Contributing & Development Guide

Thank you for contributing to ESP32 Service Uptime Monitor. This guide covers the local development setup, build targets, Web UI packaging, OpenAPI/Swagger documentation generation, and testing workflows.

For architectural conventions and AI agent coding rules, also see AGENTS.md.


Prerequisites


Building Firmware

Standard Builds

# Build all default board environments
pio run

# Build for a specific target board
pio run -e esp32-s3-cam   # ESP32-S3-CAM (MicroSD)
pio run -e esp32-s3       # ESP32-S3 DevKit (LittleFS, 16MB)
pio run -e esp32          # Classic ESP32-WROOM-32 (LittleFS, 4MB)
pio run -e esp32-c3       # ESP32-C3 SuperMini (LittleFS, 4MB)
pio run -e esp32-c6       # ESP32-C6 DevKit (LittleFS, 4MB)
pio run -e esp32-c5       # ESP32-C5 DevKit (LittleFS, 4MB)

# Build with File Manager excluded for release (omits fileManager.html, saves ~15 KB flash)
DISABLE_FILE_MANAGER=1 pio run

# Build with periodic memory statistics logging excluded
DISABLE_MEM_STATS_LOGGING=1 pio run

# Build release versions (disables File Manager and memory stats logging, sets log level to INFO)
RELEASE=1 pio run

# Flash via USB and monitor serial output (115200 8N1)
pio run -e esp32-s3-cam --target upload
pio device monitor

# Clean build artifacts
pio run --target clean

Release Binaries & ESP Web Tools Manifest

# Export standalone OTA binaries, merged factory-*.bin images, web.zip, and manifest.json to dist/
pio run -t dist

Wireless OTA Firmware Upload

# Upload over OTA (default target: esp32-service-uptime-monitor.local)
pio run -e esp32-s3-cam-ota --target upload
pio run -e esp32-s3-ota --target upload
pio run -e esp32-ota --target upload
pio run -e esp32-c3-ota --target upload
pio run -e esp32-c6-ota --target upload
pio run -e esp32-c5-ota --target upload

# Override target IP or mDNS hostname
ESP_IP=192.168.0.118 pio run -e esp32-s3-cam-ota --target upload
ESP_HOST=my-device.local pio run -e esp32-s3-cam-ota --target upload
pio run -e esp32-s3-ota --target upload --upload-port 192.168.0.118

# Provide OTA token when configuration mode is locked on the device
ESP_OTA_TOKEN=your-ota-token pio run -e esp32-s3-cam-ota --target upload

OTA Target Resolution Order: 1. ESP_HOST / ESP_IP environment variables 2. upload_port in platformio.ini (or --upload-port CLI flag) 3. hostname in local config.json or data/config.json (if present) 4. Fallback: esp32-service-uptime-monitor.local

OTA Token Resolution Order (X-PlatformIO-Upload header): 1. ESP_OTA_TOKEN / OTA_TOKEN environment variables 2. otaToken in local config.json or data/config.json (if present)


Web UI Asset Pipeline

Web UI sources live in web/ and are minified and packed into web.zip and src/EmbeddedWebArchive.cpp (PROGMEM) automatically before firmware compilation (pre:scripts/generate_web_embed.py). The archive also embeds docs/api/index.html (api-docs.html), docs/api/openapi.yaml (openapi.yaml), and LICENSE.

# Package, minify, and upload Web UI directly to a running device over HTTP
pio run --target uploadweb

# Upload to a custom device IP or hostname
ESP_IP=192.168.0.118 pio run --target uploadweb
ESP_HOST=my-device.local pio run --target uploadweb

# Generate web.zip locally without uploading
pio run --target packweb

API Documentation (OpenAPI & Swagger UI)

The REST API specification is generated directly from @openapi JSDoc-style YAML blocks inside the C++ source files (include/Api.h, src/Api.cpp, lib/FileManager/src/FileManager.cpp).

How It Works

Generator CLI & Flags

# Generate docs/api/openapi.yaml (excludes x-internal: true endpoints, warns on missing routes)
python3 scripts/openapi_generator.py

# Fail with exit code 1 if any server.on(...) route is missing an @openapi block (recommended for CI)
python3 scripts/openapi_generator.py --strict

# Include internal/dev-only endpoints (e.g. File Manager) in the generated YAML
python3 scripts/openapi_generator.py --include-internal

# Custom output path or project root
python3 scripts/openapi_generator.py --output docs/api/openapi-dev.yaml --include-internal
python3 scripts/openapi_generator.py --project-dir /path/to/repo

Local Swagger UI Preview

python3 -m http.server 8000 --directory docs/api

Open http://localhost:8000/ in your browser and enter your ESP32 IP or mDNS hostname in the Servers → host field.

Static Site Building & Local Preview

Documentation Markdown files (README.md, CONTRIBUTING.md, LICENSE, CHANGELOG.md) are pre-rendered into static HTML (readme.html, contributing.html, license.html) for deployment on esp32-service-uptime-monitor.com. Shared layout components (header, navigation, footer, analytics) are maintained centrally in templates/ and automatically synchronized across both the landing page (docs/index.html) and documentation pages.

# Assembles the full site in _site/ and serves at http://localhost:8765/ with live reload
python3 scripts/preview_site.py

# Custom port or disable automatic browser opening
python3 scripts/preview_site.py --port 8080 --no-browser

# Disable file watching and live reload
python3 scripts/preview_site.py --no-watch

# Build/assemble the site only without starting the HTTP preview server
python3 scripts/preview_site.py --build-only

# Or pre-render documentation and synchronize templates into docs/ directly
python3 scripts/render_docs.py docs/

Features of preview_site.py: - File Watcher: Automatically monitors docs/, templates/, and root Markdown files for changes. - Browser Live Reload: Injects a lightweight Server-Sent Events (SSE) listener into HTML pages to automatically refresh open browser tabs upon save. - Zero Cache Latency: Disables browser caching (Cache-Control: no-cache) during preview so styling and template updates appear immediately.


Testing & Quality Assurance

# Run all native C++ unit tests (Unity + ArduinoFake)
pio test -e native

# Run native tests and generate code coverage report (Custom task: "Generate Coverage Report")
pio run -t coverage

# Run a single C++ test suite
pio test -e native -f test_api

# Run Web UI frontend unit tests (Vitest)
npm --prefix web test

# Run Web UI tests with coverage
npm --prefix web run test:coverage

# Run PlatformIO static analysis
pio check

Coding & Commit Guidelines


Contributor License Agreement (CLA)

Because this project is dual-licensed (free for personal use, paid commercial license for businesses and organizations), by submitting a Pull Request, patch, or other contribution to this repository, you agree that:

  1. Your contribution is your original work and you have the legal right to submit it.
  2. You retain copyright to your contribution, and you grant the project author (gyengus) a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license to use, reproduce, modify, distribute, and relicense your contribution under both the Personal & Non-Commercial License in LICENSE and any Commercial Licenses offered by the author.