SmartDB

SmartDB is a household electrical fault detection and protection system spanning ESP32 firmware, KiCad hardware, a device-ingestion gateway, API examples, and engineering reference material.

Repository map

Path

Contents

backend/

Python CoAP/CBOR ingestion gateway and tests

cloud/

Implemented Firebase HTTP API, emulator launcher and frontend integration guide

dashboard/

Optional developer console; user dashboard belongs to the frontend team

esp_idf/smartdb_fusion/

PlatformIO ESP-IDF v2 system firmware and separate ESP32-CAM firmware; build/flash guide

smart_db/

Earlier KiCad design and historical manufacturing outputs

smart_db_v2/

Selected hardware revision; review findings and ESP32-S3 module decision

postman/

User-facing HTTP API requests, OpenAPI contract, and collection guide

docs/

System architecture and engineering references

Run the backend locally

Run sh system.sh from this folder (Node.js 22 LTS and Java 21+ required). It starts Firebase emulators and the optional developer console, prints a local administrator login, and preserves local data on clean shutdown. The API is at http://127.0.0.1:5000/api/v1. See the team API handoff for integration, Postman, device provisioning, configuration commands and deployment. The frontend team owns the user dashboard.

Set up the two boards

The web documentation source includes the setup guide, hardware notes, API guide and architecture. Rebuild it with ./docs/build.sh and open docs/_build/html/index.html; see website maintenance.

Open esp_idf/smartdb_fusion as the VS Code project folder, then choose Terminal → Run Task → SmartDB: Setup. Alternatively, launch the menu from that folder:

./setup.sh

Choose 1 to enter Wi-Fi settings, 2 to set up the ESP32-CAM, then 3 to set up the SmartDB main board. The menu selects ports, offers the initial firmware flash, saves settings and checks Wi-Fi. Use 4 for protection limits. Later connection changes are saved over USB without rebuilding. The camera and main board each need their own firmware; PlatformIO combines their source files automatically.

Connect each board directly to the computer for setup. The main board’s J6 camera socket supplies power only and cannot program the camera. See the firmware guide for connections, configuration, recovery and calibration. The full architecture separates implemented bench behavior from production requirements; the backend guide covers the separate CoAP ingestion gateway.

Current hardware

SmartDB v2 is being corrected for an ESP32-S3-WROOM-1-N16R8 module supplied and assembled by JLCPCB. The existing ESP32-WROOM-32 development board is separate test hardware, not the selected PCB module. The module replacement is applied in the KiCad schematic and PCB, with corrected reset/boot wiring and an updated pin map. The current revision targets a low-voltage bench load, with corrected 5 V logic power, USB, CT input and a separate normally-open relay contact connector. The permanent v2 project now contains the 95 × 78 mm compact redesign with an AP63203 buck supply, four copper layers, and the SmartDB logo and connector labels. All PCB connections are routed, with wider signal and power traces and continuous inner ground planes. ERC, DRC, connectivity and schematic parity checks report zero issues. See the v2 review for current validation results, previews and the archived previous board. It is not a mains protection board.

Project maturity

The v2 bench firmware now covers SCT-013 isolated low-voltage AC monitoring, MLX90640 thermal sensing, local relay protection with physical re-arm, persistent configuration/events, registered RGB–thermal fusion and optional HTTPS diagnostic telemetry using the Postman contract. Build smartdb_s3 for the main board and esp32cam for the separate camera. See the firmware guide for configuration, flashing, calibration and implementation limits. Source/build verification is complete; physical bench validation remains pending. The PCB logic supply is DC; the CT measurement is AC-only.

This is an engineering-stage repository, not a production-certified safety device. The backend’s secure transport integration and several firmware/hardware validation activities remain explicit pre-production work. Do not use it as the sole protective mechanism for a live electrical installation.

Code style

Maintained application code uses two-space indentation for JavaScript, CSS, and shell, four spaces for Python and C, and a 100-column target. Prettier handles the web/API code, Ruff formats and checks Python, clang-format handles the current firmware, and shfmt formats shell scripts. Editor defaults are in .editorconfig.

C code uses an open, Python-like layout: one statement per line, spaces around operators, braced control-flow blocks, and blank lines between functions and logical steps.

Install the development tools with npm ci and, inside a Python virtual environment, python -m pip install -r requirements-dev.txt. Install clang-format and shfmt separately; the formatting baseline uses clang-format 23.1.0 and shfmt 3.13.1.

npm run format        # Apply formatting
npm run format:check  # Check formatting and Python imports/errors without rewriting files
npm run build        # Build the developer console
npm test             # Run the cloud API tests using local Firebase emulators
python -m pytest backend/tests
sh esp_idf/smartdb_fusion/tools/check.sh

The formatting commands cover backend, cloud, dashboard, documentation support scripts/styles, launchers, and first-party code in esp_idf/smartdb_fusion. They exclude generated outputs, local firmware configuration, upstream sensor drivers, legacy firmware examples, hardware design files, archives, and Postman exports.