# rongyishuaige7/esp32-c3-smart-band architecture

> Architecture diagram of the GitHub repository rongyishuaige7/esp32-c3-smart-band, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rongyishuaige7/esp32-c3-smart-band
- Repository: https://github.com/rongyishuaige7/esp32-c3-smart-band

## Overview

This is an ESP32-C3 health-data teaching prototype: firmware samples sensors, updates the local OLED, and sends compact BLE telemetry to a Flutter Android client that scans for the project service and displays availability-aware readings. Separate branches cover optical estimates, temperature, motion, GPS availability, and the optional bench-only vibration experiment. Firmware control flow and estimator calls are visible in sampled source; app behavior and protocol capabilities are based on the README, since app implementation files were not sampled. These are uncalibrated demonstrations, not medical or safety functions.

Main entry points: [`firmware/src/main.cpp`](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/main.cpp) (ESP32-C3 band), [`firmware/src/sensors.cpp`](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/sensors.cpp) (Sensor sampling), [`app/lib/band_ble_controller.dart`](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/band_ble_controller.dart) (Band BLE controller), [`app/lib/pages/scan_page.dart`](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/pages/scan_page.dart) (BLE scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Band firmware"]
  node_band["ESP32-C3 band<br/>[main.cpp]"]
  node_ble["BLE telemetry<br/>[ble.cpp]"]
  node_oled["OLED display<br/>[display.cpp]"]
  node_vibration["Optional vibration<br/>[main.cpp]"]
end

subgraph group_sensing["Sensing and estimates"]
  node_sensors["Sensor sampling<br/>[sensors.cpp]"]
  node_pulse["Pulse detector<br/>[heartRate.h]"]
  node_spo2["SpO2 estimator<br/>[spo2_calc.cpp]"]
  node_temperature["Temperature sampling<br/>[sensors.cpp]"]
  node_motion["Acceleration event<br/>[sensors.cpp]"]
  node_gps["GPS availability<br/>[gps.cpp]"]
end

subgraph group_client["Android client"]
  node_app["Flutter app<br/>[main.dart]"]
  node_scan["BLE scan<br/>[scan_page.dart]"]
  node_controller["Band BLE controller"]
  node_model["Band data model<br/>[band_data.dart]"]
  node_home["Live readings<br/>[home_page.dart]"]
end

subgraph group_hardware["Hardware reference"]
  node_board["Board and wiring<br/>[wiring.md]"]
  node_bom["Parts list<br/>[BOM.csv]"]
end

node_wearer(("Band wearer"))

node_wearer -->|"starts scan"| node_scan
node_scan -.->|"uses"| node_controller
node_controller -->|"scans and receives"| node_band
node_controller -.->|"decodes"| node_model
node_model -.->|"supplies readings"| node_home
node_home -->|"shows status"| node_wearer
node_band -->|"samples and reads"| node_sensors
node_band -->|"feeds and reads status"| node_gps
node_sensors -->|"detects beats"| node_pulse
node_sensors -->|"pushes samples; estimates"| node_spo2
node_band -->|"notifies telemetry"| node_ble
node_band -->|"updates readings"| node_oled
node_band -->|"optionally pulses"| node_vibration
node_wearer -.->|"views locally"| node_oled
node_board -.->|"lists components"| node_bom

click node_app "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/main.dart"
click node_scan "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/pages/scan_page.dart"
click node_controller "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/band_ble_controller.dart"
click node_model "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/models/band_data.dart"
click node_home "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/pages/home_page.dart"
click node_band "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/main.cpp"
click node_sensors "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/sensors.cpp"
click node_pulse "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/heartRate.h"
click node_spo2 "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/spo2_calc.cpp"
click node_temperature "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/sensors.cpp"
click node_motion "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/sensors.cpp"
click node_gps "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/gps.cpp"
click node_ble "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/ble.cpp"
click node_oled "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/display.cpp"
click node_vibration "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/main.cpp"
click node_board "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/hardware/wiring.md"
click node_bom "https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/hardware/BOM.csv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_band,node_ble,node_oled,node_vibration toneBlue
class node_sensors,node_pulse,node_spo2,node_temperature,node_motion,node_gps toneAmber
class node_app,node_scan,node_controller,node_model,node_home toneMint
class node_board,node_bom toneRose
class node_wearer toneIndigo
```

## Components

### Band firmware

- [ESP32-C3 band](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`
- [BLE telemetry](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/ble.cpp): `firmware/src/ble.cpp`
- [OLED display](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/display.cpp): `firmware/src/display.cpp`
- [Optional vibration](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`

### Sensing and estimates

- [Sensor sampling](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/sensors.cpp): `firmware/src/sensors.cpp`
- [Pulse detector](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/heartRate.h): `firmware/src/heartRate.h`
- [SpO2 estimator](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/spo2_calc.cpp): `firmware/src/spo2_calc.cpp`
- [Temperature sampling](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/sensors.cpp): `firmware/src/sensors.cpp`
- [Acceleration event](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/sensors.cpp): `firmware/src/sensors.cpp`
- [GPS availability](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/firmware/src/gps.cpp): `firmware/src/gps.cpp`

### Android client

- [Flutter app](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/main.dart): `app/lib/main.dart`
- [BLE scan](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/pages/scan_page.dart): `app/lib/pages/scan_page.dart`
- [Band BLE controller](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/band_ble_controller.dart): `app/lib/band_ble_controller.dart`
- [Band data model](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/models/band_data.dart): `app/lib/models/band_data.dart`
- [Live readings](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/app/lib/pages/home_page.dart): `app/lib/pages/home_page.dart`

### Hardware reference

- [Board and wiring](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/hardware/wiring.md): `hardware/wiring.md`
- [Parts list](https://github.com/rongyishuaige7/esp32-c3-smart-band/blob/main/hardware/BOM.csv): `hardware/BOM.csv`

### Other components

- **Band wearer**

## Connections

- Band wearer → BLE scan: starts scan (evidence: `README.md`)
- BLE scan → Band BLE controller: uses
- Band BLE controller → ESP32-C3 band: scans and receives (evidence: `README.md`)
- Band BLE controller → Band data model: decodes
- Band data model → Live readings: supplies readings
- Live readings → Band wearer: shows status (evidence: `README.md`)
- ESP32-C3 band → Sensor sampling: samples and reads (evidence: `firmware/src/main.cpp`)
- ESP32-C3 band → GPS availability: feeds and reads status (evidence: `firmware/src/main.cpp`)
- Sensor sampling → Pulse detector: detects beats (evidence: `firmware/src/sensors.cpp`)
- Sensor sampling → SpO2 estimator: pushes samples; estimates (evidence: `firmware/src/sensors.cpp`)
- ESP32-C3 band → BLE telemetry: notifies telemetry (evidence: `firmware/src/main.cpp`)
- ESP32-C3 band → OLED display: updates readings (evidence: `firmware/src/main.cpp`)
- ESP32-C3 band → Optional vibration: optionally pulses (evidence: `firmware/src/main.cpp`)
- Band wearer → OLED display: views locally
- Board and wiring → Parts list: lists components
