# astommondal16/uwb-rtls--esp architecture

> Architecture diagram of the GitHub repository astommondal16/uwb-rtls--esp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astommondal16/uwb-rtls--esp
- Repository: https://github.com/astommondal16/uwb-rtls--esp

## Overview

This repository provides ESP-IDF firmware for ESP32 UWB anchor/tag ranging, plus desktop and Android device-management clients. The firmware workflow provisions Wi-Fi, confirms device role and coordinates, synchronizes time, gathers sensor/ranging samples, and serves telemetry and control APIs; clients discover devices, visualize readings, and manage configuration. The graph preserves the documented setup, sensing, calibration, CIR, and localization capabilities. Some subsystem links rely on README statements because their implementation was not sampled.

Main entry points: [`main/main.c`](https://github.com/astommondal16/uwb-rtls--esp/blob/main/main/main.c) (Startup supervisor), [`components/telemetry/telemetry.c`](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/telemetry/telemetry.c) (Telemetry API and queue), [`dashboard/dashboard.py`](https://github.com/astommondal16/uwb-rtls--esp/blob/main/dashboard/dashboard.py) (Desktop dashboard), [`dashboard/localization_dashboard.py`](https://github.com/astommondal16/uwb-rtls--esp/blob/main/dashboard/localization_dashboard.py) (Localization dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and setup"]
  node_firmware["Startup supervisor<br/>[main.c]"]
  node_setup["Role and coordinates<br/>[device_setup.c]"]
  node_ble["BLE provisioning<br/>[ble_provisioning.c]"]
  node_coordinator["Sensor coordinator"]
end

subgraph group_sensing["Sensing and ranging"]
  node_ranging["UWB ranging<br/>[uwb_ranging.c]"]
  node_radio["DW1000 driver<br/>[dw1000.c]"]
  node_imu["MPU6050 driver<br/>[mpu6050.c]"]
  node_battery["Battery monitor<br/>[battery_monitor.c]"]
end

subgraph group_connectivity["Connectivity and telemetry"]
  node_wifi["Wi-Fi manager<br/>[wifi.c]"]
  node_clock["Time synchronization<br/>[time_sync.c]"]
  node_identity["Device identity<br/>[device_identity.c]"]
  node_telemetry["Telemetry API and queue<br/>[telemetry.c]"]
  node_rawjson["Raw UWB encoding<br/>[uwb_raw_json.c]"]
  node_discovery["Network discovery<br/>[telemetry.c]"]
end

subgraph group_clients["Management clients"]
  node_desktop["Desktop dashboard<br/>[dashboard.py]"]
  node_localization["Localization dashboard"]
  node_cirviewer["CIR viewer<br/>[cir_viewer.py]"]
  node_android["Android app<br/>[MainActivity.kt]"]
end

node_operator(("Device operator"))
node_network(("Wi-Fi network"))

node_operator -->|"starts and configures"| node_firmware
node_firmware -->|"connects through"| node_wifi
node_wifi -->|"starts fallback provisioning"| node_ble
node_operator -->|"requests setup"| node_ble
node_firmware -->|"initializes setup"| node_setup
node_firmware -->|"synchronizes time"| node_clock
node_firmware -->|"coordinates sensor pauses"| node_coordinator
node_firmware -->|"starts ranging"| node_ranging
node_ranging -->|"drives radio"| node_radio
node_firmware -->|"initializes and reads"| node_imu
node_firmware -->|"monitors voltage"| node_battery
node_firmware -->|"publishes samples"| node_telemetry
node_telemetry -->|"encodes raw data"| node_rawjson
node_telemetry -->|"uses device identity"| node_identity
node_telemetry -->|"serves discovery"| node_discovery
node_wifi -->|"joins"| node_network
node_desktop -->|"polls telemetry"| node_telemetry
node_desktop -->|"requests clock sync"| node_clock
node_desktop -->|"discovers devices"| node_discovery
node_localization -->|"fetches readings"| node_telemetry
node_localization -->|"scans devices"| node_discovery
node_localization -->|"solves from ranges"| node_ranging
node_desktop -->|"opens CIR viewer"| node_cirviewer
node_android -->|"requests device API"| node_telemetry
node_android -->|"configures device"| node_setup
node_desktop -->|"controls role and settings"| node_setup
node_android -->|"finds devices"| node_discovery

click node_firmware "https://github.com/astommondal16/uwb-rtls--esp/blob/main/main/main.c"
click node_setup "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/telemetry/device_setup.c"
click node_ble "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/ble_provisioning/ble_provisioning.c"
click node_coordinator "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/sensor_coordinator/sensor_coordinator.c"
click node_wifi "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/wifi/wifi.c"
click node_clock "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/time_sync/time_sync.c"
click node_ranging "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/uwb_ranging/uwb_ranging.c"
click node_radio "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/dw1000/dw1000.c"
click node_imu "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/mpu6050/mpu6050.c"
click node_battery "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/battery_monitor/battery_monitor.c"
click node_identity "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/device_identity/device_identity.c"
click node_telemetry "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/telemetry/telemetry.c"
click node_rawjson "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/telemetry/uwb_raw_json.c"
click node_discovery "https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/telemetry/telemetry.c"
click node_desktop "https://github.com/astommondal16/uwb-rtls--esp/blob/main/dashboard/dashboard.py"
click node_localization "https://github.com/astommondal16/uwb-rtls--esp/blob/main/dashboard/localization_dashboard.py"
click node_cirviewer "https://github.com/astommondal16/uwb-rtls--esp/blob/main/dashboard/cir_viewer.py"
click node_android "https://github.com/astommondal16/uwb-rtls--esp/blob/main/checkpoints/20261002-actions-order-before/MainActivity.kt"

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_firmware,node_setup,node_ble,node_coordinator toneBlue
class node_ranging,node_radio,node_imu,node_battery toneAmber
class node_wifi,node_clock,node_identity,node_telemetry,node_rawjson,node_discovery toneMint
class node_desktop,node_localization,node_cirviewer,node_android toneRose
class node_operator,node_network toneIndigo
```

## Components

### Startup and setup

- [Startup supervisor](https://github.com/astommondal16/uwb-rtls--esp/blob/main/main/main.c): `main/main.c`
- [Role and coordinates](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/telemetry/device_setup.c): `components/telemetry/device_setup.c`
- [BLE provisioning](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/ble_provisioning/ble_provisioning.c): `components/ble_provisioning/ble_provisioning.c`
- [Sensor coordinator](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/sensor_coordinator/sensor_coordinator.c): `components/sensor_coordinator/sensor_coordinator.c`

### Sensing and ranging

- [UWB ranging](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/uwb_ranging/uwb_ranging.c): `components/uwb_ranging/uwb_ranging.c`
- [DW1000 driver](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/dw1000/dw1000.c): `components/dw1000/dw1000.c`
- [MPU6050 driver](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/mpu6050/mpu6050.c): `components/mpu6050/mpu6050.c`
- [Battery monitor](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/battery_monitor/battery_monitor.c): `components/battery_monitor/battery_monitor.c`

### Connectivity and telemetry

- [Wi-Fi manager](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/wifi/wifi.c): `components/wifi/wifi.c`
- [Time synchronization](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/time_sync/time_sync.c): `components/time_sync/time_sync.c`
- [Device identity](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/device_identity/device_identity.c): `components/device_identity/device_identity.c`
- [Telemetry API and queue](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/telemetry/telemetry.c): `components/telemetry/telemetry.c`
- [Raw UWB encoding](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/telemetry/uwb_raw_json.c): `components/telemetry/uwb_raw_json.c`
- [Network discovery](https://github.com/astommondal16/uwb-rtls--esp/blob/main/components/telemetry/telemetry.c): `components/telemetry/telemetry.c`

### Management clients

- [Desktop dashboard](https://github.com/astommondal16/uwb-rtls--esp/blob/main/dashboard/dashboard.py): `dashboard/dashboard.py`
- [Localization dashboard](https://github.com/astommondal16/uwb-rtls--esp/blob/main/dashboard/localization_dashboard.py): `dashboard/localization_dashboard.py`
- [CIR viewer](https://github.com/astommondal16/uwb-rtls--esp/blob/main/dashboard/cir_viewer.py): `dashboard/cir_viewer.py`
- [Android app](https://github.com/astommondal16/uwb-rtls--esp/blob/main/checkpoints/20261002-actions-order-before/MainActivity.kt): `checkpoints/20261002-actions-order-before/MainActivity.kt`

### Other components

- **Device operator**
- **Wi-Fi network**

## Connections

- Device operator → Startup supervisor: starts and configures
- Startup supervisor → Wi-Fi manager: connects through
- Wi-Fi manager → BLE provisioning: starts fallback provisioning (evidence: `components/wifi/wifi.c`)
- Device operator → BLE provisioning: requests setup
- Startup supervisor → Role and coordinates: initializes setup (evidence: `main/main.c`)
- Startup supervisor → Time synchronization: synchronizes time
- Startup supervisor → Sensor coordinator: coordinates sensor pauses (evidence: `main/main.c`)
- Startup supervisor → UWB ranging: starts ranging
- UWB ranging → DW1000 driver: drives radio (evidence: `components/uwb_ranging/uwb_ranging.c`)
- Startup supervisor → MPU6050 driver: initializes and reads
- Startup supervisor → Battery monitor: monitors voltage
- Startup supervisor → Telemetry API and queue: publishes samples (evidence: `main/main.c`)
- Telemetry API and queue → Raw UWB encoding: encodes raw data (evidence: `components/telemetry/telemetry.c`)
- Telemetry API and queue → Device identity: uses device identity (evidence: `components/telemetry/telemetry.c`)
- Telemetry API and queue → Network discovery: serves discovery (evidence: `components/telemetry/telemetry.c`)
- Wi-Fi manager → Wi-Fi network: joins
- Desktop dashboard → Telemetry API and queue: polls telemetry (evidence: `dashboard/dashboard.py`)
- Desktop dashboard → Time synchronization: requests clock sync (evidence: `dashboard/dashboard.py`)
- Desktop dashboard → Network discovery: discovers devices (evidence: `dashboard/dashboard.py`)
- Localization dashboard → Telemetry API and queue: fetches readings (evidence: `dashboard/localization_dashboard.py`)
- Localization dashboard → Network discovery: scans devices (evidence: `dashboard/localization_dashboard.py`)
- Localization dashboard → UWB ranging: solves from ranges
- Desktop dashboard → CIR viewer: opens CIR viewer (evidence: `dashboard/cir_viewer.py`)
- Android app → Telemetry API and queue: requests device API
- Android app → Role and coordinates: configures device
- Desktop dashboard → Role and coordinates: controls role and settings (evidence: `dashboard/dashboard.py`)
- Android app → Network discovery: finds devices (evidence: `checkpoints/20261002-actions-order-before/MainActivity.kt`)
