# truesense-it/portentauwbshield architecture

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

- Interactive diagram: https://gitdiagram.com/truesense-it/portentauwbshield
- Repository: https://github.com/truesense-it/portentauwbshield

## Overview

This is an Arduino library for using the Portenta UWB Shield. A sketch calls the public UWB API, configures and manages ranging sessions, then receives ranging or data notifications; the HAL abstracts the underlying UWB stack. README capabilities include TWR, TDoA, and Apple Nearby Interaction. The graph includes the distinct role and data-transfer APIs; several are linked only where the source index establishes references, so unsampled runtime behavior is not inferred.

Main entry points: [`src/uwbapps/UWBSession.hpp`](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBSession.hpp) (UWB session), [`src/uwbapps/UWB.hpp`](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWB.hpp) (UWB engine), [`src/hal/uwb_hal.hpp`](https://github.com/truesense-it/portentauwbshield/blob/main/src/hal/uwb_hal.hpp) (UWB HAL), [`src/uwbapps/UWBAppParamList.hpp`](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBAppParamList.hpp) (App parameters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_public["Shield API"]
  node_uwb["UWB engine<br/>[UWB.hpp]"]
end

subgraph group_sessions["Sessions and Nearby"]
  node_session["UWB session<br/>[UWBSession.hpp]"]
  node_session_mgr["Session manager"]
  node_nearby_session["Nearby session<br/>[NearbySession.hpp]"]
  node_nearby_mgr["Nearby manager"]
end

subgraph group_ranging["Ranging and Data"]
  node_twr["TWR roles"]
  node_controlee["Controlee role"]
  node_one_many["One-to-many"]
  node_multi_anchor["Multi-session anchor"]
  node_multi_tag["Multi-session tag"]
  node_tdoa["TDoA roles"]
  node_tdoa_responder["TDoA responder"]
  node_tdoa_tag["TDoA tag<br/>[UWBDltdoaTag.hpp]"]
  node_tdoa_anchor["TDoA anchors"]
  node_sync_anchor["Sync anchor"]
  node_inband_tx["In-band transmit"]
  node_inband_rx["In-band receive"]
  node_result["Ranging results<br/>[UWBRangingData.hpp]"]
  node_notifications["Notifications"]
  node_coordinates["Anchor coordinates"]
  node_active_rounds["Active rounds"]
end

subgraph group_hal["HAL and Parameters"]
  node_hal_api["UWB HAL<br/>[uwb_hal.hpp]"]
  node_types["UWB types<br/>[uwb_types.hpp]"]
  node_app_params["App parameters"]
  node_params_list["Parameter values"]
  node_vendor_params["Vendor parameters"]
  node_ranging_params["Ranging parameters"]
  node_mac["MAC address<br/>[UWBMacAddress.hpp]"]
  node_mac_list["MAC list"]
end

node_sketch(("Arduino sketch"))
node_nearby_ble(("BLE peer"))

node_sketch -->|"uses"| node_public
node_public -->|"exposes"| node_uwb
node_uwb -->|"manages sessions"| node_session_mgr
node_uwb -->|"references"| node_nearby_mgr
node_nearby_ble -->|"connects"| node_nearby_mgr
node_nearby_mgr -->|"finds sessions"| node_nearby_session
node_session_mgr -->|"stores sessions"| node_session
node_nearby_session -->|"extends"| node_session
node_session -->|"controls sessions"| node_hal_api
node_twr -->|"uses engine"| node_uwb
node_twr -->|"uses session"| node_session
node_controlee -->|"uses engine"| node_uwb
node_controlee -->|"uses session"| node_session
node_one_many -->|"uses session"| node_session
node_multi_anchor -->|"uses engine"| node_uwb
node_multi_anchor -->|"uses session"| node_session
node_multi_tag -->|"uses engine"| node_uwb
node_multi_tag -->|"uses session"| node_session
node_tdoa -->|"uses engine"| node_uwb
node_tdoa -->|"uses session"| node_session
node_tdoa -->|"uses coordinates"| node_coordinates
node_tdoa -->|"tracks rounds"| node_active_rounds
node_tdoa_responder -->|"uses engine"| node_uwb
node_tdoa_responder -->|"uses session"| node_session
node_tdoa_tag -->|"uses engine"| node_uwb
node_tdoa_tag -->|"uses session"| node_session
node_tdoa_anchor -->|"uses engine"| node_uwb
node_tdoa_anchor -->|"uses session"| node_session
node_sync_anchor -->|"uses engine"| node_uwb
node_sync_anchor -->|"uses session"| node_session
node_inband_tx -->|"uses engine"| node_uwb
node_inband_tx -->|"sends through"| node_session
node_inband_rx -->|"uses engine"| node_uwb
node_inband_rx -->|"uses session"| node_session
node_uwb -->|"registers callbacks"| node_notifications
node_uwb -->|"reports ranging"| node_result
node_result -->|"decodes measurements"| node_types
node_session -->|"configures with"| node_ranging_params
node_session -->|"uses parameters"| node_app_params
node_session -->|"uses parameters"| node_vendor_params
node_hal_api -->|"uses types"| node_types
node_hal_api -->|"uses parameters"| node_app_params
node_hal_api -->|"uses parameters"| node_vendor_params
node_hal_api -->|"uses parameters"| node_ranging_params
node_app_params -->|"uses values"| node_params_list
node_app_params -->|"uses addresses"| node_mac
node_app_params -->|"uses address lists"| node_mac_list
node_vendor_params -->|"uses values"| node_params_list

click node_public "https://github.com/truesense-it/portentauwbshield/blob/main/src/PortentaUWBShield.h"
click node_uwb "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWB.hpp"
click node_session "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBSession.hpp"
click node_session_mgr "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBSessionManager.hpp"
click node_nearby_session "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/NearbySession.hpp"
click node_nearby_mgr "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/NearbySessionManager.hpp"
click node_twr "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBRangingController.hpp"
click node_controlee "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBRangingControlee.hpp"
click node_one_many "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBRangingOneToMany.hpp"
click node_multi_anchor "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBMultiSessionAnchor.hpp"
click node_multi_tag "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBMultiSessionTag.hpp"
click node_tdoa "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBDltdoaInitiator.hpp"
click node_tdoa_responder "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBDltdoaResponder.hpp"
click node_tdoa_tag "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBDltdoaTag.hpp"
click node_tdoa_anchor "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBUltdoaAnchor.hpp"
click node_sync_anchor "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBUltdoaSyncAnchor.hpp"
click node_inband_tx "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBInbandDataTx.hpp"
click node_inband_rx "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBInbandDataRx.hpp"
click node_result "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBRangingData.hpp"
click node_notifications "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBNotification.hpp"
click node_hal_api "https://github.com/truesense-it/portentauwbshield/blob/main/src/hal/uwb_hal.hpp"
click node_types "https://github.com/truesense-it/portentauwbshield/blob/main/src/hal/uwb_types.hpp"
click node_app_params "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBAppParamList.hpp"
click node_params_list "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBAppParamsList.hpp"
click node_vendor_params "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBVendorParamList.hpp"
click node_ranging_params "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBRangingParams.hpp"
click node_mac "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBMacAddress.hpp"
click node_mac_list "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBMacAddressList.hpp"
click node_coordinates "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBAnchorCoordinates.hpp"
click node_active_rounds "https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBActiveRounds.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_public,node_uwb toneBlue
class node_session,node_session_mgr,node_nearby_session,node_nearby_mgr toneAmber
class node_twr,node_controlee,node_one_many,node_multi_anchor,node_multi_tag,node_tdoa,node_tdoa_responder,node_tdoa_tag,node_tdoa_anchor,node_sync_anchor,node_inband_tx,node_inband_rx,node_result,node_notifications,node_coordinates,node_active_rounds toneMint
class node_hal_api,node_types,node_app_params,node_params_list,node_vendor_params,node_ranging_params,node_mac,node_mac_list toneRose
class node_sketch,node_nearby_ble toneIndigo
```

## Components

### Public API

- [Shield API](https://github.com/truesense-it/portentauwbshield/blob/main/src/PortentaUWBShield.h): `src/PortentaUWBShield.h`
- [UWB engine](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWB.hpp): `src/uwbapps/UWB.hpp`

### Sessions and Nearby

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

### Ranging and Data

- [TWR roles](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBRangingController.hpp): `src/uwbapps/UWBRangingController.hpp`
- [Controlee role](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBRangingControlee.hpp): `src/uwbapps/UWBRangingControlee.hpp`
- [One-to-many](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBRangingOneToMany.hpp): `src/uwbapps/UWBRangingOneToMany.hpp`
- [Multi-session anchor](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBMultiSessionAnchor.hpp): `src/uwbapps/UWBMultiSessionAnchor.hpp`
- [Multi-session tag](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBMultiSessionTag.hpp): `src/uwbapps/UWBMultiSessionTag.hpp`
- [TDoA roles](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBDltdoaInitiator.hpp): `src/uwbapps/UWBDltdoaInitiator.hpp`
- [TDoA responder](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBDltdoaResponder.hpp): `src/uwbapps/UWBDltdoaResponder.hpp`
- [TDoA tag](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBDltdoaTag.hpp): `src/uwbapps/UWBDltdoaTag.hpp`
- [TDoA anchors](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBUltdoaAnchor.hpp): `src/uwbapps/UWBUltdoaAnchor.hpp`
- [Sync anchor](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBUltdoaSyncAnchor.hpp): `src/uwbapps/UWBUltdoaSyncAnchor.hpp`
- [In-band transmit](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBInbandDataTx.hpp): `src/uwbapps/UWBInbandDataTx.hpp`
- [In-band receive](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBInbandDataRx.hpp): `src/uwbapps/UWBInbandDataRx.hpp`
- [Ranging results](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBRangingData.hpp): `src/uwbapps/UWBRangingData.hpp`
- [Notifications](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBNotification.hpp): `src/uwbapps/UWBNotification.hpp`
- [Anchor coordinates](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBAnchorCoordinates.hpp): `src/uwbapps/UWBAnchorCoordinates.hpp`
- [Active rounds](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBActiveRounds.hpp): `src/uwbapps/UWBActiveRounds.hpp`

### HAL and Parameters

- [UWB HAL](https://github.com/truesense-it/portentauwbshield/blob/main/src/hal/uwb_hal.hpp): `src/hal/uwb_hal.hpp`
- [UWB types](https://github.com/truesense-it/portentauwbshield/blob/main/src/hal/uwb_types.hpp): `src/hal/uwb_types.hpp`
- [App parameters](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBAppParamList.hpp): `src/uwbapps/UWBAppParamList.hpp`
- [Parameter values](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBAppParamsList.hpp): `src/uwbapps/UWBAppParamsList.hpp`
- [Vendor parameters](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBVendorParamList.hpp): `src/uwbapps/UWBVendorParamList.hpp`
- [Ranging parameters](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBRangingParams.hpp): `src/uwbapps/UWBRangingParams.hpp`
- [MAC address](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBMacAddress.hpp): `src/uwbapps/UWBMacAddress.hpp`
- [MAC list](https://github.com/truesense-it/portentauwbshield/blob/main/src/uwbapps/UWBMacAddressList.hpp): `src/uwbapps/UWBMacAddressList.hpp`

### Other components

- **Arduino sketch**
- **BLE peer**

## Connections

- Arduino sketch → Shield API: uses (evidence: `README.md`)
- Shield API → UWB engine: exposes (evidence: `src/PortentaUWBShield.h`)
- UWB engine → Session manager: manages sessions (evidence: `src/uwbapps/UWB.cpp`)
- UWB engine → Nearby manager: references (evidence: `src/uwbapps/UWB.hpp`)
- BLE peer → Nearby manager: connects (evidence: `src/uwbapps/NearbySessionManager.hpp`)
- Nearby manager → Nearby session: finds sessions (evidence: `src/uwbapps/NearbySessionManager.hpp`)
- Session manager → UWB session: stores sessions (evidence: `src/uwbapps/UWBSessionManager.hpp`)
- Nearby session → UWB session: extends (evidence: `src/uwbapps/NearbySession.hpp`)
- UWB session → UWB HAL: controls sessions (evidence: `src/uwbapps/UWBSession.hpp`)
- TWR roles → UWB engine: uses engine (evidence: `src/uwbapps/UWBRangingController.hpp`)
- TWR roles → UWB session: uses session (evidence: `src/uwbapps/UWBRangingController.hpp`)
- Controlee role → UWB engine: uses engine (evidence: `src/uwbapps/UWBRangingControlee.hpp`)
- Controlee role → UWB session: uses session (evidence: `src/uwbapps/UWBRangingControlee.hpp`)
- One-to-many → UWB session: uses session (evidence: `src/uwbapps/UWBRangingOneToMany.hpp`)
- Multi-session anchor → UWB engine: uses engine (evidence: `src/uwbapps/UWBMultiSessionAnchor.hpp`)
- Multi-session anchor → UWB session: uses session (evidence: `src/uwbapps/UWBMultiSessionAnchor.hpp`)
- Multi-session tag → UWB engine: uses engine (evidence: `src/uwbapps/UWBMultiSessionTag.hpp`)
- Multi-session tag → UWB session: uses session (evidence: `src/uwbapps/UWBMultiSessionTag.hpp`)
- TDoA roles → UWB engine: uses engine (evidence: `src/uwbapps/UWBDltdoaInitiator.hpp`)
- TDoA roles → UWB session: uses session (evidence: `src/uwbapps/UWBDltdoaInitiator.hpp`)
- TDoA roles → Anchor coordinates: uses coordinates (evidence: `src/uwbapps/UWBDltdoaInitiator.hpp`)
- TDoA roles → Active rounds: tracks rounds (evidence: `src/uwbapps/UWBDltdoaInitiator.hpp`)
- TDoA responder → UWB engine: uses engine (evidence: `src/uwbapps/UWBDltdoaResponder.hpp`)
- TDoA responder → UWB session: uses session (evidence: `src/uwbapps/UWBDltdoaResponder.hpp`)
- TDoA tag → UWB engine: uses engine (evidence: `src/uwbapps/UWBDltdoaTag.hpp`)
- TDoA tag → UWB session: uses session (evidence: `src/uwbapps/UWBDltdoaTag.hpp`)
- TDoA anchors → UWB engine: uses engine (evidence: `src/uwbapps/UWBUltdoaAnchor.hpp`)
- TDoA anchors → UWB session: uses session (evidence: `src/uwbapps/UWBUltdoaAnchor.hpp`)
- Sync anchor → UWB engine: uses engine (evidence: `src/uwbapps/UWBUltdoaSyncAnchor.hpp`)
- Sync anchor → UWB session: uses session (evidence: `src/uwbapps/UWBUltdoaSyncAnchor.hpp`)
- In-band transmit → UWB engine: uses engine (evidence: `src/uwbapps/UWBInbandDataTx.hpp`)
- In-band transmit → UWB session: sends through (evidence: `src/uwbapps/UWBInbandDataTx.hpp`)
- In-band receive → UWB engine: uses engine (evidence: `src/uwbapps/UWBInbandDataRx.hpp`)
- In-band receive → UWB session: uses session (evidence: `src/uwbapps/UWBInbandDataRx.hpp`)
- UWB engine → Notifications: registers callbacks (evidence: `src/uwbapps/UWB.hpp`)
- UWB engine → Ranging results: reports ranging (evidence: `src/uwbapps/UWB.hpp`)
- Ranging results → UWB types: decodes measurements (evidence: `src/uwbapps/UWBRangingData.hpp`)
- UWB session → Ranging parameters: configures with (evidence: `src/uwbapps/UWBSession.hpp`)
- UWB session → App parameters: uses parameters (evidence: `src/uwbapps/UWBSession.hpp`)
- UWB session → Vendor parameters: uses parameters (evidence: `src/uwbapps/UWBSession.hpp`)
- UWB HAL → UWB types: uses types (evidence: `src/hal/uwb_hal.hpp`)
- UWB HAL → App parameters: uses parameters (evidence: `src/hal/uwb_hal.hpp`)
- UWB HAL → Vendor parameters: uses parameters (evidence: `src/hal/uwb_hal.hpp`)
- UWB HAL → Ranging parameters: uses parameters (evidence: `src/hal/uwb_hal.hpp`)
- App parameters → Parameter values: uses values (evidence: `src/uwbapps/UWBAppParamList.hpp`)
- App parameters → MAC address: uses addresses (evidence: `src/uwbapps/UWBAppParamList.hpp`)
- App parameters → MAC list: uses address lists (evidence: `src/uwbapps/UWBAppParamList.hpp`)
- Vendor parameters → Parameter values: uses values (evidence: `src/uwbapps/UWBVendorParamList.hpp`)
