Terremoto is one local-first footstep sensing product: production firmware for an ESP32-S3 with an ADXL345 and INMP441, plus one Docker-served browser Console. The browser manages and flashes the board over local Web Serial. The Docker server receives full-resolution sensor telemetry over Wi-Fi/TCP, draws bounded live views, and records unchanged samples to HDF5.
Browser -- Web Serial --> ESP32-S3 <-- ADXL345 + INMP441
|
| HTTP / WebSocket Wi-Fi / FSTP v2
v |
Docker Console <---------------------------------------+
|
+-- bounded display copies
+-- HDF5 recordings, JSON annotations, and logs
Requirements are Docker with Compose and a desktop Chromium browser with Web Serial support, such as current Chrome or Edge.
-
From the repository root, start the product:
docker compose up --build -
Open http://localhost:8080.
-
Open USB Setup, select the ESP32-S3, and verify its
TMGM/1 INFOidentity. -
If needed, open Firmware and install the bundled production image.
-
Scan for Wi-Fi, enter credentials, test the connection, and save only after the device reports success. Credentials travel directly between the browser and device; they never enter Docker, URLs, logs, or browser storage.
-
Register the tested node/IP handoff, open the node workspace, connect TCP, choose stream representations, and view the ADXL345 and INMP441 graphs.
-
Start a recording only after the selected sensors are calibrated and the firmware has acknowledged the stream configuration.
Stop the server with docker compose down. Named Docker volumes retain the
node registry, logs, and recordings.
| Responsibility | Authoritative owner |
|---|---|
| Firmware composition | src/app/main.cpp |
| Hardware and acquisition settings | include/device_config.h |
| ADXL345 / INMP441 drivers | src/sensors/ |
| Calibration and derived representations | src/streaming/ and include/sensors/background_estimator.h |
| USB management protocol | src/platform/serial_management.cpp and static/browser_usb.mjs |
| TCP framing and acquisition | src/protocol/network_protocol.cpp and the Console FSTP client |
| Browser UI and server | console/src/terremoto_console/ |
| Runtime packaging | compose.yaml and console/Dockerfile |
USB is management-only after normal boot. Sensor telemetry has one path: FSTP v2 over TCP. Raw sensor batches are offered to recording before separate, bounded display copies are made. Derived data never replaces raw data.
| Device signal | ESP32-S3 GPIO |
|---|---|
| ADXL345 SDA | 9 |
| ADXL345 SCL | 8 |
| INMP441 DATA | 5 |
| INMP441 WS | 7 |
| INMP441 BCLK | 6 |
See hardware wiring and configuration before connecting components.
Use the native tools directly:
pio test -e native
pio run -e esp32-s3-supermini
python -m pytest console/tests -q
python scripts/check_markdown_links.py
docker compose build
Do not upload firmware unless physical flashing is explicitly intended. The
browser production artifact is an intentional merged release image with pinned
metadata; ordinary .pio output is ignored. Its update procedure is in the
browser flashing guide.
Software builds, fakes, and browser route tests do not prove physical USB,
sensor, Wi-Fi, TCP, or recording behavior. Unobserved physical checks are
NOT RUN.