# daltoncox/supertooth architecture

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

- Interactive diagram: https://gitdiagram.com/daltoncox/supertooth
- Repository: https://github.com/daltoncox/supertooth

## Overview

Supertooth captures HackRF IQ and turns it into BLE advertising or BR/EDR frames, decoded packets, and tracked device/piconet views. The shared session coordinates tuning, channel workers, protocol-specific collectors, and callbacks; CLI binaries provide summary/full/device output, while the Qt GUI bridges session events into its presentation models. The README documents live spectrum and packet-log capabilities, but the supplied tree has no QML paths, so those UI details are represented only at the GUI level. Some internal wiring is based on the documented architecture because source excerpts are partial.

Main entry points: [`src/core/service/session.c`](https://github.com/daltoncox/supertooth/blob/main/src/core/service/session.c) (Session coordinator), [`src/apps/gui/backend/backend_api.c`](https://github.com/daltoncox/supertooth/blob/main/src/apps/gui/backend/backend_api.c) (GUI backend), [`src/core/service`](https://github.com/daltoncox/supertooth/tree/main/src/core/service) (Channel processors), [`src/apps/gui/controllers/receiver_controller.cpp`](https://github.com/daltoncox/supertooth/blob/main/src/apps/gui/controllers/receiver_controller.cpp) (Receiver controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Runtime apps"]
  node_cli_ble["BLE CLI<br/>[supertooth-ble.c]"]
  node_cli_bredr["BR/EDR CLI<br/>[supertooth-bredr.c]"]
  node_cli_hybrid["Hybrid CLI"]
  node_gui_app["Qt GUI<br/>[main.cpp]"]
  node_gui_controller["Receiver controller"]
  node_gui_backend["GUI backend<br/>[backend_api.c]"]
  node_gui_models["GUI models"]
  node_cli_views["CLI views<br/>[app_summary_view.c]"]
end

subgraph group_service["Capture service"]
  node_session["Session coordinator<br/>[session.c]"]
  node_collector["Event collectors<br/>[collector.c]"]
  node_processors["Channel processors"]
end

subgraph group_radio["Radio and DSP"]
  node_radio_driver["HackRF driver<br/>[hackrf.c]"]
  node_dispatcher["Sample dispatcher"]
  node_channelizer["Channelizer"]
  node_dsp["DSP utilities"]
end

subgraph group_ble["BLE protocol"]
  node_ble_decoder["BLE framing"]
  node_ble_codec["BLE codec<br/>[ble_codec.c]"]
  node_ble_tracker["BLE tracker<br/>[ble_tracker.c]"]
  node_ble_display["BLE display<br/>[ble_display.c]"]
end

subgraph group_bredr["BR/EDR protocol"]
  node_bredr_decoder["BR/EDR framing"]
  node_bredr_codec["BR/EDR codec<br/>[bredr_codec.c]"]
  node_bredr_tracker["BR/EDR tracker<br/>[bredr_tracker.c]"]
  node_piconet_store["Piconet store"]
  node_bredr_display["BR/EDR display<br/>[bredr_display.c]"]
end

node_operator(("Operator"))
node_hackrf_device["HackRF"]

node_operator -->|"selects capture"| node_cli_ble
node_operator -->|"selects capture"| node_cli_bredr
node_operator -->|"selects capture"| node_cli_hybrid
node_operator -->|"starts capture"| node_gui_app
node_cli_ble -->|"runs BLE session"| node_session
node_cli_bredr -->|"runs BR/EDR session"| node_session
node_cli_hybrid -->|"runs hybrid session"| node_session
node_gui_app -->|"loads interface"| node_gui_controller
node_gui_controller -->|"starts and stops"| node_gui_backend
node_gui_backend -->|"creates session"| node_session
node_session -->|"starts receiver"| node_radio_driver
node_hackrf_device -->|"provides IQ"| node_radio_driver
node_radio_driver -->|"pushes samples"| node_dispatcher
node_session -->|"configures channels"| node_channelizer
node_dispatcher -->|"delivers samples"| node_channelizer
node_channelizer -->|"uses DSP"| node_dsp
node_session -->|"starts workers"| node_processors
node_processors -->|"frames BLE bits"| node_ble_decoder
node_processors -->|"frames BR/EDR bits"| node_bredr_decoder
node_processors -->|"submits events"| node_collector
node_collector -->|"dispatches events"| node_session
node_session -->|"processes BLE events"| node_ble_tracker
node_session -->|"processes BR/EDR events"| node_bredr_tracker
node_ble_decoder -->|"decodes frames"| node_ble_codec
node_bredr_decoder -->|"decodes frames"| node_bredr_codec
node_bredr_tracker -->|"updates piconets"| node_piconet_store
node_session -->|"delivers callbacks"| node_gui_backend
node_gui_backend -->|"decodes BLE frames"| node_ble_codec
node_gui_controller -->|"updates views"| node_gui_models
node_gui_backend -->|"emits frame rows"| node_gui_controller
node_session -->|"delivers events"| node_cli_views
node_cli_views -->|"formats BLE output"| node_ble_display
node_cli_views -->|"formats BR/EDR output"| node_bredr_display
node_session -->|"provides BLE events"| node_ble_display
node_session -->|"provides BR/EDR events"| node_bredr_display

click node_cli_ble "https://github.com/daltoncox/supertooth/blob/main/src/apps/cli/supertooth-ble.c"
click node_cli_bredr "https://github.com/daltoncox/supertooth/blob/main/src/apps/cli/supertooth-bredr.c"
click node_cli_hybrid "https://github.com/daltoncox/supertooth/blob/main/src/apps/cli/supertooth-hybrid.c"
click node_gui_app "https://github.com/daltoncox/supertooth/blob/main/src/apps/gui/main.cpp"
click node_gui_controller "https://github.com/daltoncox/supertooth/blob/main/src/apps/gui/controllers/receiver_controller.cpp"
click node_gui_backend "https://github.com/daltoncox/supertooth/blob/main/src/apps/gui/backend/backend_api.c"
click node_gui_models "https://github.com/daltoncox/supertooth/tree/main/src/apps/gui/models"
click node_cli_views "https://github.com/daltoncox/supertooth/blob/main/src/apps/cli/app_summary_view.c"
click node_session "https://github.com/daltoncox/supertooth/blob/main/src/core/service/session.c"
click node_collector "https://github.com/daltoncox/supertooth/blob/main/src/core/service/collector.c"
click node_processors "https://github.com/daltoncox/supertooth/tree/main/src/core/service"
click node_radio_driver "https://github.com/daltoncox/supertooth/blob/main/src/core/radio/hackrf.c"
click node_dispatcher "https://github.com/daltoncox/supertooth/blob/main/src/core/radio/sample_dispatcher.c"
click node_channelizer "https://github.com/daltoncox/supertooth/blob/main/src/core/service/channelizer_thread.c"
click node_dsp "https://github.com/daltoncox/supertooth/tree/main/src/core/dsp"
click node_ble_decoder "https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/ble/ble_bitstream_decoder.c"
click node_ble_codec "https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/ble/ble_codec.c"
click node_ble_tracker "https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/ble/ble_tracker.c"
click node_ble_display "https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/ble/ble_display.c"
click node_bredr_decoder "https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/bredr/bredr_bitstream_decoder.c"
click node_bredr_codec "https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/bredr/bredr_codec.c"
click node_bredr_tracker "https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/bredr/bredr_tracker.c"
click node_piconet_store "https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/bredr/bredr_piconet_store.c"
click node_bredr_display "https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/bredr/bredr_display.c"

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_cli_ble,node_cli_bredr,node_cli_hybrid,node_gui_app,node_gui_controller,node_gui_backend,node_gui_models,node_cli_views toneBlue
class node_session,node_collector,node_processors toneAmber
class node_radio_driver,node_dispatcher,node_channelizer,node_dsp toneMint
class node_ble_decoder,node_ble_codec,node_ble_tracker,node_ble_display toneRose
class node_bredr_decoder,node_bredr_codec,node_bredr_tracker,node_piconet_store,node_bredr_display,node_operator,node_hackrf_device toneIndigo
```

## Components

### Runtime apps

- [BLE CLI](https://github.com/daltoncox/supertooth/blob/main/src/apps/cli/supertooth-ble.c): `src/apps/cli/supertooth-ble.c`
- [BR/EDR CLI](https://github.com/daltoncox/supertooth/blob/main/src/apps/cli/supertooth-bredr.c): `src/apps/cli/supertooth-bredr.c`
- [Hybrid CLI](https://github.com/daltoncox/supertooth/blob/main/src/apps/cli/supertooth-hybrid.c): `src/apps/cli/supertooth-hybrid.c`
- [Qt GUI](https://github.com/daltoncox/supertooth/blob/main/src/apps/gui/main.cpp): `src/apps/gui/main.cpp`
- [Receiver controller](https://github.com/daltoncox/supertooth/blob/main/src/apps/gui/controllers/receiver_controller.cpp): `src/apps/gui/controllers/receiver_controller.cpp`
- [GUI backend](https://github.com/daltoncox/supertooth/blob/main/src/apps/gui/backend/backend_api.c): `src/apps/gui/backend/backend_api.c`
- [GUI models](https://github.com/daltoncox/supertooth/tree/main/src/apps/gui/models): `src/apps/gui/models`
- [CLI views](https://github.com/daltoncox/supertooth/blob/main/src/apps/cli/app_summary_view.c): `src/apps/cli/app_summary_view.c`

### Capture service

- [Session coordinator](https://github.com/daltoncox/supertooth/blob/main/src/core/service/session.c): `src/core/service/session.c`
- [Event collectors](https://github.com/daltoncox/supertooth/blob/main/src/core/service/collector.c): `src/core/service/collector.c`
- [Channel processors](https://github.com/daltoncox/supertooth/tree/main/src/core/service): `src/core/service`

### Radio and DSP

- [HackRF driver](https://github.com/daltoncox/supertooth/blob/main/src/core/radio/hackrf.c): `src/core/radio/hackrf.c`
- [Sample dispatcher](https://github.com/daltoncox/supertooth/blob/main/src/core/radio/sample_dispatcher.c): `src/core/radio/sample_dispatcher.c`
- [Channelizer](https://github.com/daltoncox/supertooth/blob/main/src/core/service/channelizer_thread.c): `src/core/service/channelizer_thread.c`
- [DSP utilities](https://github.com/daltoncox/supertooth/tree/main/src/core/dsp): `src/core/dsp`

### BLE protocol

- [BLE framing](https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/ble/ble_bitstream_decoder.c): `src/core/protocol/ble/ble_bitstream_decoder.c`
- [BLE codec](https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/ble/ble_codec.c): `src/core/protocol/ble/ble_codec.c`
- [BLE tracker](https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/ble/ble_tracker.c): `src/core/protocol/ble/ble_tracker.c`
- [BLE display](https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/ble/ble_display.c): `src/core/protocol/ble/ble_display.c`

### BR/EDR protocol

- [BR/EDR framing](https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/bredr/bredr_bitstream_decoder.c): `src/core/protocol/bredr/bredr_bitstream_decoder.c`
- [BR/EDR codec](https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/bredr/bredr_codec.c): `src/core/protocol/bredr/bredr_codec.c`
- [BR/EDR tracker](https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/bredr/bredr_tracker.c): `src/core/protocol/bredr/bredr_tracker.c`
- [Piconet store](https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/bredr/bredr_piconet_store.c): `src/core/protocol/bredr/bredr_piconet_store.c`
- [BR/EDR display](https://github.com/daltoncox/supertooth/blob/main/src/core/protocol/bredr/bredr_display.c): `src/core/protocol/bredr/bredr_display.c`

### Other components

- **Operator**
- **HackRF**

## Connections

- Operator → BLE CLI: selects capture
- Operator → BR/EDR CLI: selects capture
- Operator → Hybrid CLI: selects capture
- Operator → Qt GUI: starts capture
- BLE CLI → Session coordinator: runs BLE session
- BR/EDR CLI → Session coordinator: runs BR/EDR session
- Hybrid CLI → Session coordinator: runs hybrid session
- Qt GUI → Receiver controller: loads interface
- Receiver controller → GUI backend: starts and stops
- GUI backend → Session coordinator: creates session
- Session coordinator → HackRF driver: starts receiver
- HackRF → HackRF driver: provides IQ
- HackRF driver → Sample dispatcher: pushes samples
- Session coordinator → Channelizer: configures channels
- Sample dispatcher → Channelizer: delivers samples
- Channelizer → DSP utilities: uses DSP
- Session coordinator → Channel processors: starts workers
- Channel processors → BLE framing: frames BLE bits
- Channel processors → BR/EDR framing: frames BR/EDR bits
- Channel processors → Event collectors: submits events
- Event collectors → Session coordinator: dispatches events
- Session coordinator → BLE tracker: processes BLE events
- Session coordinator → BR/EDR tracker: processes BR/EDR events
- BLE framing → BLE codec: decodes frames
- BR/EDR framing → BR/EDR codec: decodes frames
- BR/EDR tracker → Piconet store: updates piconets
- Session coordinator → GUI backend: delivers callbacks
- GUI backend → BLE codec: decodes BLE frames
- Receiver controller → GUI models: updates views
- GUI backend → Receiver controller: emits frame rows
- Session coordinator → CLI views: delivers events
- CLI views → BLE display: formats BLE output
- CLI views → BR/EDR display: formats BR/EDR output
- Session coordinator → BLE display: provides BLE events
- Session coordinator → BR/EDR display: provides BR/EDR events