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
- PlatformIO Core (CLI) or PlatformIO IDE
- Python 3 with PyYAML, markdown, and beautifulsoup4 (
pip install pyyaml markdown beautifulsoup4) — required for OpenAPI specification generation and documentation pre-rendering - Node.js & npm — required for Web UI unit tests and
terserJS minification (npm --prefix web install)
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
- Top-level metadata,
serversvariables,tags, and reusablecomponents.schemaslive ininclude/Api.h. - Each endpoint's OpenAPI block sits directly above its
server.on(...)registration insrc/Api.cpporlib/FileManager/src/FileManager.cpp. info.versionis automatically populated fromFIRMWARE_VERSIONininclude/version.h.- Endpoints marked with
x-internal: true(such as the File Manager endpoints) are excluded from the publicdocs/api/openapi.yamlby default, along with any orphaned tags and schemas. - During
pio run,pre:scripts/generate_openapi.pyruns beforepre:scripts/generate_web_embed.pyso the updateddocs/api/openapi.yamlis always embedded into the firmware as well.
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
- Follow all architectural and thread-safety rules in AGENTS.md.
- Keep device hostnames RFC 1123 compliant (
a-z,0-9,-only; sanitize user input viaHostnameUtils::cleanHostname()). - Write clear, descriptive commit messages in English without Conventional Commits prefixes (
feat:,fix:,chore:, etc.) and without sign-off lines. - Sign all commits with GPG/SSH (
git commit -S).
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:
- Your contribution is your original work and you have the legal right to submit it.
- 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 inLICENSEand any Commercial Licenses offered by the author.