ESP32 motion-sensing prototype with a local dashboard for tremor-signal visualization and exploratory analysis.
Tremor-Pro combines an ESP32 and MPU6050 accelerometer/gyroscope with a browser dashboard and a local FastAPI service. The firmware samples motion, filters the signal, estimates energy in frequency bands and streams data over server-sent events (SSE). The dashboard records sessions and visualizes summary metrics. The backend stores session history in a local SQLite database and generates rule-based summaries; an optional MedGemma integration and a Random Forest classifier are also present in the codebase.
Research prototype only. This project is not a medical device and does not diagnose or screen for a condition. The reported labels and narrative summaries are exploratory signal interpretations, not clinically validated outputs. Do not use them for treatment or care decisions.
flowchart LR
IMU[MPU6050 motion sensor] --> MCU[ESP32 sampling and filtering]
MCU --> DSP[Frequency-band features and heuristic labels]
DSP --> SSE[SSE stream + device web endpoints]
SSE --> UI[Browser dashboard]
UI --> API[Local FastAPI service]
API --> DB[(SQLite session history)]
API --> RULES[Rule-based biomarker report]
API -. optional configured service .-> AI[MedGemma endpoint]
| Component | Status |
|---|---|
| ESP32 firmware | Sampling, calibration, band power features, Wi-Fi and SSE endpoints are implemented |
| Browser dashboard | Vite-based live dashboard and profile/trend screens are included |
| Local API | FastAPI endpoints for analysis, classification and session history |
| Session storage | Local SQLite database, created at runtime |
| ML classifier | Random Forest path and training script included; data/model provenance should be reviewed before interpreting predictions |
| Clinical validation | Not present; outputs are not diagnostic |
The bundled firmware reports frequency-band features and heuristic class names. They should not be interpreted as diagnoses or validated clinical classification. The optional model and AI report paths also require independent evaluation before any accuracy claims.
- ESP32 development board
- MPU6050 IMU module
- Push button on GPIO 16 and status LED on GPIO 2 (as configured in firmware)
- USB cable and a computer on the same local network for dashboard use
The firmware uses a 50 Hz sample rate and computes features from 128-sample windows. Confirm sensor orientation and wiring against your board/module before powering the device.
Credentials are loaded from a local, ignored header so secrets are not stored in source control.
- Copy
include/TremorSecrets.example.htoinclude/TremorSecrets.h. - Set
STA_SSIDandSTA_PASSfor your local network. - If station credentials are blank, or station mode cannot connect, firmware starts an open access point named
TremorDevice; connect only in a controlled environment and avoid exposing it to untrusted networks. - Never commit
include/TremorSecrets.h.
The fallback access point is open and has no password; use it only in a trusted, isolated setting. Device endpoints currently have no authentication.
cd ai_dashboard/backend
python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1
# macOS/Linux: source .venv/bin/activate
python -m pip install -r requirements.txt
python -m uvicorn main:app --host 127.0.0.1 --port 8000API docs are at http://localhost:8000/docs; health is /health.
In a second terminal:
cd ai_dashboard
npm install
npm run devOpen the URL printed by Vite (typically http://localhost:5173). Enter the ESP32 address, connect, record a session, stop, and generate its local report. The profile view is available at /profiles.html.
For firmware, open the repository root in PlatformIO, build/upload the esp32dev environment, and upload the SPIFFS filesystem image containing the dashboard assets. PlatformIO Core CLI is available as pio run, pio run -t upload, and pio run -t uploadfs.
Session history is stored locally in SQLite. Set TREMOR_PROFILE_DB_PATH to choose a database path. The optional MedGemma integration can send session summaries to a configured external endpoint (KAGGLE_MEDGEMMA_URL); leave it unset for the local rule-based report path. Do not enter identifiable health information, and do not expose the API or ESP32 endpoints to a public network.
- Firmware project:
platformio.ini,src/main.cpp - Dashboard setup:
ai_dashboard/USAGE.md - Backend dependencies:
ai_dashboard/backend/requirements.txt - ML feature extraction and training:
ai_dashboard/backend/ml/
Please include the board, sensor wiring, firmware build output and reproducible dashboard steps when reporting bugs. Do not present synthetic or weakly labeled training metrics as clinical performance.
No license is currently declared. Unless a license is added, reuse and redistribution are not granted by default.