# truesense-it/stellauwb architecture

> Architecture diagram of the GitHub repository truesense-it/stellauwb, 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/truesense-it/stellauwb
- Repository: https://github.com/truesense-it/stellauwb

## Overview

StellaUWB is an Arduino-facing UWB library for configuring the radio stack, managing sessions, and exposing ranging and device-role APIs. A typical user starts through the public header and UWB API, configures and starts a session, then receives ranging or data notifications; Nearby Interaction adds BLE-based peer/session coordination. The source index supports the public API, session, HAL, and parameter relationships. The README is empty and examples were not excerpted, so their runtime wiring is not asserted.

Main entry points: [`src/uwbapps/UWB.hpp`](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWB.hpp) (UWB API), [`src/hal/uwb_hal.hpp`](https://github.com/truesense-it/stellauwb/blob/main/src/hal/uwb_hal.hpp) (UWB HAL), [`src/StellaUWB.h`](https://github.com/truesense-it/stellauwb/blob/main/src/StellaUWB.h) (Library header), [`src/uwbapps/UWBSession.hpp`](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBSession.hpp) (UWB session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_umbrella["Library header<br/>[StellaUWB.h]"]
  node_uwb_api["UWB API<br/>[UWB.hpp]"]
  node_role_apis["Ranging role APIs"]
end

subgraph group_sessions["Session Management"]
  node_session["UWB session<br/>[UWBSession.hpp]"]
  node_session_mgr["Session manager"]
end

subgraph group_uwb["UWB Runtime"]
  node_hal["UWB HAL<br/>[uwb_hal.hpp]"]
  node_types["Protocol types<br/>[uwb_types.hpp]"]
  node_params["Session parameters"]
  node_param_values["Parameter values"]
  node_vendor_params["Vendor parameters"]
  node_mac["MAC addresses<br/>[UWBMacAddress.hpp]"]
  node_mac_list["MAC address lists"]
  node_ranging_params["Ranging parameters"]
  node_ranging_data["Ranging results<br/>[UWBRangingData.hpp]"]
  node_notifications["Notifications"]
  node_inband["In-band data"]
end

subgraph group_nearby["Nearby Interaction"]
  node_nearby_sess["Nearby session<br/>[NearbySession.hpp]"]
  node_nearby_mgr["Nearby manager"]
  node_ble_notify["BLE peer notify"]
end

node_user(("Arduino application"))

node_user -->|"includes"| node_umbrella
node_umbrella -->|"exposes"| node_uwb_api
node_umbrella -->|"exposes"| node_role_apis
node_umbrella -->|"exposes"| node_nearby_sess
node_umbrella -->|"exposes"| node_nearby_mgr
node_uwb_api -->|"uses"| node_hal
node_uwb_api -->|"uses"| node_session_mgr
node_uwb_api -->|"uses"| node_nearby_mgr
node_uwb_api -->|"registers"| node_notifications
node_uwb_api -->|"reports"| node_ranging_data
node_session_mgr -->|"manages"| node_session
node_session_mgr -->|"supports"| node_nearby_sess
node_nearby_mgr -->|"extends"| node_session_mgr
node_nearby_mgr -->|"manages"| node_nearby_sess
node_nearby_mgr -->|"uses"| node_ble_notify
node_nearby_sess -->|"uses"| node_session
node_session -->|"configures"| node_hal
node_session -->|"uses"| node_ranging_params
node_session -->|"uses"| node_params
node_hal -->|"uses"| node_types
node_hal -->|"accepts"| node_params
node_hal -->|"accepts"| node_vendor_params
node_hal -->|"accepts"| node_ranging_params
node_params -->|"uses"| node_param_values
node_params -->|"uses"| node_mac
node_params -->|"uses"| node_mac_list
node_vendor_params -->|"uses"| node_param_values
node_vendor_params -->|"uses"| node_hal
node_notifications -->|"carries"| node_ranging_data
node_ranging_data -->|"decodes"| node_types
node_inband -->|"uses"| node_uwb_api

click node_umbrella "https://github.com/truesense-it/stellauwb/blob/main/src/StellaUWB.h"
click node_uwb_api "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWB.hpp"
click node_session "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBSession.hpp"
click node_session_mgr "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBSessionManager.hpp"
click node_nearby_sess "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/NearbySession.hpp"
click node_nearby_mgr "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/NearbySessionManager.hpp"
click node_ble_notify "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/NearbyBlePeerNotify.cpp"
click node_hal "https://github.com/truesense-it/stellauwb/blob/main/src/hal/uwb_hal.hpp"
click node_types "https://github.com/truesense-it/stellauwb/blob/main/src/hal/uwb_types.hpp"
click node_params "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBAppParamList.hpp"
click node_param_values "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBAppParamsList.hpp"
click node_vendor_params "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBVendorParamList.hpp"
click node_mac "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBMacAddress.hpp"
click node_mac_list "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBMacAddressList.hpp"
click node_ranging_params "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBRangingParams.hpp"
click node_ranging_data "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBRangingData.hpp"
click node_notifications "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBNotification.hpp"
click node_role_apis "https://github.com/truesense-it/stellauwb/tree/main/src/uwbapps"
click node_inband "https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBInbandDataTx.hpp"

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_umbrella,node_uwb_api,node_role_apis toneBlue
class node_session,node_session_mgr toneAmber
class node_hal,node_types,node_params,node_param_values,node_vendor_params,node_mac,node_mac_list,node_ranging_params,node_ranging_data,node_notifications,node_inband toneMint
class node_nearby_sess,node_nearby_mgr,node_ble_notify toneRose
class node_user toneIndigo
```

## Components

### Public API

- [Library header](https://github.com/truesense-it/stellauwb/blob/main/src/StellaUWB.h): `src/StellaUWB.h`
- [UWB API](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWB.hpp): `src/uwbapps/UWB.hpp`
- [Ranging role APIs](https://github.com/truesense-it/stellauwb/tree/main/src/uwbapps): `src/uwbapps`

### Session Management

- [UWB session](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBSession.hpp): `src/uwbapps/UWBSession.hpp`
- [Session manager](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBSessionManager.hpp): `src/uwbapps/UWBSessionManager.hpp`

### UWB Runtime

- [UWB HAL](https://github.com/truesense-it/stellauwb/blob/main/src/hal/uwb_hal.hpp): `src/hal/uwb_hal.hpp`
- [Protocol types](https://github.com/truesense-it/stellauwb/blob/main/src/hal/uwb_types.hpp): `src/hal/uwb_types.hpp`
- [Session parameters](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBAppParamList.hpp): `src/uwbapps/UWBAppParamList.hpp`
- [Parameter values](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBAppParamsList.hpp): `src/uwbapps/UWBAppParamsList.hpp`
- [Vendor parameters](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBVendorParamList.hpp): `src/uwbapps/UWBVendorParamList.hpp`
- [MAC addresses](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBMacAddress.hpp): `src/uwbapps/UWBMacAddress.hpp`
- [MAC address lists](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBMacAddressList.hpp): `src/uwbapps/UWBMacAddressList.hpp`
- [Ranging parameters](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBRangingParams.hpp): `src/uwbapps/UWBRangingParams.hpp`
- [Ranging results](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBRangingData.hpp): `src/uwbapps/UWBRangingData.hpp`
- [Notifications](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBNotification.hpp): `src/uwbapps/UWBNotification.hpp`
- [In-band data](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/UWBInbandDataTx.hpp): `src/uwbapps/UWBInbandDataTx.hpp`

### Nearby Interaction

- [Nearby session](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/NearbySession.hpp): `src/uwbapps/NearbySession.hpp`
- [Nearby manager](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/NearbySessionManager.hpp): `src/uwbapps/NearbySessionManager.hpp`
- [BLE peer notify](https://github.com/truesense-it/stellauwb/blob/main/src/uwbapps/NearbyBlePeerNotify.cpp): `src/uwbapps/NearbyBlePeerNotify.cpp`

### Other components

- **Arduino application**

## Connections

- Arduino application → Library header: includes (evidence: `src/StellaUWB.h`)
- Library header → UWB API: exposes (evidence: `src/StellaUWB.h`)
- Library header → Ranging role APIs: exposes (evidence: `src/StellaUWB.h`)
- Library header → Nearby session: exposes (evidence: `src/StellaUWB.h`)
- Library header → Nearby manager: exposes (evidence: `src/StellaUWB.h`)
- UWB API → UWB HAL: uses (evidence: `src/uwbapps/UWB.hpp`)
- UWB API → Session manager: uses (evidence: `src/uwbapps/UWB.hpp`)
- UWB API → Nearby manager: uses (evidence: `src/uwbapps/UWB.hpp`)
- UWB API → Notifications: registers (evidence: `src/uwbapps/UWB.hpp`)
- UWB API → Ranging results: reports (evidence: `src/uwbapps/UWB.hpp`)
- Session manager → UWB session: manages (evidence: `src/uwbapps/UWBSessionManager.hpp`)
- Session manager → Nearby session: supports (evidence: `src/uwbapps/UWBSessionManager.hpp`)
- Nearby manager → Session manager: extends (evidence: `src/uwbapps/NearbySessionManager.hpp`)
- Nearby manager → Nearby session: manages (evidence: `src/uwbapps/NearbySessionManager.hpp`)
- Nearby manager → BLE peer notify: uses
- Nearby session → UWB session: uses (evidence: `src/uwbapps/NearbySession.hpp`)
- UWB session → UWB HAL: configures (evidence: `src/uwbapps/UWBSession.hpp`)
- UWB session → Ranging parameters: uses (evidence: `src/uwbapps/UWBSession.hpp`)
- UWB session → Session parameters: uses (evidence: `src/uwbapps/UWBSession.hpp`)
- UWB HAL → Protocol types: uses (evidence: `src/hal/uwb_hal.hpp`)
- UWB HAL → Session parameters: accepts (evidence: `src/hal/uwb_hal.hpp`)
- UWB HAL → Vendor parameters: accepts (evidence: `src/hal/uwb_hal.hpp`)
- UWB HAL → Ranging parameters: accepts (evidence: `src/hal/uwb_hal.hpp`)
- Session parameters → Parameter values: uses (evidence: `src/uwbapps/UWBAppParamList.hpp`)
- Session parameters → MAC addresses: uses (evidence: `src/uwbapps/UWBAppParamList.hpp`)
- Session parameters → MAC address lists: uses (evidence: `src/uwbapps/UWBAppParamList.hpp`)
- Vendor parameters → Parameter values: uses (evidence: `src/uwbapps/UWBVendorParamList.hpp`)
- Vendor parameters → UWB HAL: uses (evidence: `src/uwbapps/UWBVendorParamList.hpp`)
- Notifications → Ranging results: carries (evidence: `src/uwbapps/UWBNotification.hpp`)
- Ranging results → Protocol types: decodes (evidence: `src/uwbapps/UWBRangingData.hpp`)
- In-band data → UWB API: uses (evidence: `src/uwbapps/UWBInbandDataTx.hpp`)
