# adamzembrzuski/sensorsuite architecture

> Architecture diagram of the GitHub repository adamzembrzuski/sensorsuite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adamzembrzuski/sensorsuite
- Repository: https://github.com/adamzembrzuski/sensorsuite
- Video tour (about a minute): https://gitdiagram.com/adamzembrzuski/sensorsuite/video

## Overview

AZSensorSuite is an ultra-low-power sensing and data-acquisition platform. Its example workflow samples the ToF and environmental sensors, turns detections into timestamped counts, buffers and persists readings, and exposes live data and historical downloads over BLE to a Python client that writes CSV files. The graph also shows the timekeeping and sensor-driver layers supporting that workflow. The README documents the platform capabilities; the sampled source excerpts are partial, so links for unsampled behavior are limited to explicit documentation and visible interfaces.

Main entry points: [`firmware/src/main.c`](https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/main.c) (Firmware lifecycle), [`firmware/src/services/log_service.c`](https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/log_service.c) (Log service), [`firmware/src/services/sense_service.c`](https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/sense_service.c) (BLE GATT service), [`software/azss_client.py`](https://github.com/adamzembrzuski/sensorsuite/blob/main/software/azss_client.py) (Python CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_board["Sensor board"]
  node_board_hw["SensorSuite PCB<br/>[azss.kicad_sch]"]
  node_tof["VL53L4CD ToF"]
  node_sht["SHT30 sensor"]
end

subgraph group_firmware["Firmware sensing"]
  node_app["Firmware lifecycle<br/>[main.c]"]
  node_tof_api["ToF driver<br/>[VL53L4CD_ULP_api.c]"]
  node_tof_platform["ToF platform I/O"]
  node_time["Wall-clock service<br/>[time_service.h]"]
  node_errors["Fatal diagnostics<br/>[error_service.c]"]
end

subgraph group_data_ble["Logging and BLE"]
  node_logger["Log service<br/>[log_service.c]"]
  node_storage[("Persistent log<br/>[log_service.c]")]
  node_gatt["BLE GATT service<br/>[sense_service.c]"]
end

subgraph group_host["Python client"]
  node_user["Python CLI<br/>[azss_client.py]"]
  node_session["BLE session<br/>[azss_client.py]"]
  node_download["Bulk downloader<br/>[azss_client.py]"]
  node_csv["CSV writer<br/>[azss_client.py]"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_user
node_board_hw -->|"hosts sensor"| node_tof
node_board_hw -->|"hosts sensor"| node_sht
node_app -->|"configures and reads"| node_tof_api
node_tof_api -->|"uses I/O"| node_tof_platform
node_tof -->|"ranging data"| node_app
node_sht -->|"ambient readings"| node_app
node_app -->|"gets timestamps"| node_time
node_app -->|"records readings"| node_logger
node_logger -->|"persists log"| node_storage
node_app -->|"initializes and notifies"| node_gatt
node_gatt -->|"starts bulk stream"| node_logger
node_logger -->|"sends packets"| node_gatt
node_app -->|"reports fatal faults"| node_errors
node_user -->|"scans and connects"| node_session
node_user -->|"requests download"| node_download
node_download -->|"reads BLE data"| node_session
node_session -->|"exchanges GATT data"| node_gatt
node_download -->|"writes records"| node_csv

click node_board_hw "https://github.com/adamzembrzuski/sensorsuite/blob/main/hardware/azss.kicad_sch"
click node_app "https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/main.c"
click node_tof_api "https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/vl53l4cd_ulp_api/VL53L4CD_ULP_api.c"
click node_tof_platform "https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/vl53l4cd_ulp_api/VL53L4CD_ULP_platform.c"
click node_time "https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/time_service.h"
click node_errors "https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/error_service.c"
click node_logger "https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/log_service.c"
click node_storage "https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/log_service.c"
click node_gatt "https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/sense_service.c"
click node_user "https://github.com/adamzembrzuski/sensorsuite/blob/main/software/azss_client.py"
click node_session "https://github.com/adamzembrzuski/sensorsuite/blob/main/software/azss_client.py"
click node_download "https://github.com/adamzembrzuski/sensorsuite/blob/main/software/azss_client.py"
click node_csv "https://github.com/adamzembrzuski/sensorsuite/blob/main/software/azss_client.py"

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_board_hw,node_tof,node_sht toneBlue
class node_app,node_tof_api,node_tof_platform,node_time,node_errors toneAmber
class node_logger,node_storage,node_gatt toneMint
class node_user,node_session,node_download,node_csv toneRose
class node_operator toneIndigo
```

## Components

### Sensor board

- [SensorSuite PCB](https://github.com/adamzembrzuski/sensorsuite/blob/main/hardware/azss.kicad_sch): `hardware/azss.kicad_sch`
- **VL53L4CD ToF**
- **SHT30 sensor**

### Firmware sensing

- [Firmware lifecycle](https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/main.c): `firmware/src/main.c`
- [ToF driver](https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/vl53l4cd_ulp_api/VL53L4CD_ULP_api.c): `firmware/src/vl53l4cd_ulp_api/VL53L4CD_ULP_api.c`
- [ToF platform I/O](https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/vl53l4cd_ulp_api/VL53L4CD_ULP_platform.c): `firmware/src/vl53l4cd_ulp_api/VL53L4CD_ULP_platform.c`
- [Wall-clock service](https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/time_service.h): `firmware/src/services/time_service.h`
- [Fatal diagnostics](https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/error_service.c): `firmware/src/services/error_service.c`

### Logging and BLE

- [Log service](https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/log_service.c): `firmware/src/services/log_service.c`
- [Persistent log](https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/log_service.c): `firmware/src/services/log_service.c`
- [BLE GATT service](https://github.com/adamzembrzuski/sensorsuite/blob/main/firmware/src/services/sense_service.c): `firmware/src/services/sense_service.c`

### Python client

- [Python CLI](https://github.com/adamzembrzuski/sensorsuite/blob/main/software/azss_client.py): `software/azss_client.py`
- [BLE session](https://github.com/adamzembrzuski/sensorsuite/blob/main/software/azss_client.py): `software/azss_client.py`
- [Bulk downloader](https://github.com/adamzembrzuski/sensorsuite/blob/main/software/azss_client.py): `software/azss_client.py`
- [CSV writer](https://github.com/adamzembrzuski/sensorsuite/blob/main/software/azss_client.py): `software/azss_client.py`

### Other components

- **Operator**

## Connections

- Operator → Python CLI: runs commands
- SensorSuite PCB → VL53L4CD ToF: hosts sensor
- SensorSuite PCB → SHT30 sensor: hosts sensor
- Firmware lifecycle → ToF driver: configures and reads
- ToF driver → ToF platform I/O: uses I/O
- VL53L4CD ToF → Firmware lifecycle: ranging data
- SHT30 sensor → Firmware lifecycle: ambient readings
- Firmware lifecycle → Wall-clock service: gets timestamps
- Firmware lifecycle → Log service: records readings
- Log service → Persistent log: persists log
- Firmware lifecycle → BLE GATT service: initializes and notifies
- BLE GATT service → Log service: starts bulk stream
- Log service → BLE GATT service: sends packets
- Firmware lifecycle → Fatal diagnostics: reports fatal faults
- Python CLI → BLE session: scans and connects
- Python CLI → Bulk downloader: requests download
- Bulk downloader → BLE session: reads BLE data
- BLE session → BLE GATT service: exchanges GATT data
- Bulk downloader → CSV writer: writes records