# ur8us/astra918sdr architecture

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

- Interactive diagram: https://gitdiagram.com/ur8us/astra918sdr
- Repository: https://github.com/ur8us/astra918sdr

## Overview

Astra918 is receive-only RP2350 firmware for a CMX918-based radio, with a Rust host library providing a simulator and CLI. The primary workflow is to accept control or CAT tuning, configure the receiver, capture I/Q, produce channelized audio and I/Q streams, and expose them over composite USB. Persistence and recovery support reliable operation. README statements establish the advertised interfaces and capabilities; source excerpts and the SOURCE INDEX establish several internal modules and calls, but some runtime wiring is unsampled, so those connections are left out.

Main entry points: [`firmware/src/main.rs`](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/main.rs) (Firmware runtime), [`firmware/src/chip.rs`](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/chip.rs) (CMX918 control), [`firmware/src/astra.rs`](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/astra.rs) (AST1 control), [`firmware/src/capture.rs`](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/capture.rs) (I/Q capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control and tuning"]
  node_firmware_entry["Firmware runtime<br/>[main.rs]"]
  node_control_protocol["AST1 control<br/>[astra.rs]"]
  node_command_records["Control records<br/>[control_v2.rs]"]
  node_cat_parser["CAT commands<br/>[cat.rs]"]
  node_receiver_controls["Receiver settings<br/>[controls.rs]"]
  node_config_protocol["Protocol helpers<br/>[protocol.rs]"]
end

subgraph group_radio["Receiver hardware"]
  node_chip_control["CMX918 control<br/>[chip.rs]"]
  node_i2c["I²C bus<br/>[i2c_bus.rs]"]
  node_bus_recovery["Bus recovery<br/>[recovery.rs]"]
  node_saved_settings[("Saved settings<br/>[persistence.rs]")]
end

subgraph group_streams["Capture and streams"]
  node_capture["I/Q capture<br/>[capture.rs]"]
  node_dsp["Channel DSP<br/>[dsp.rs]"]
  node_dsp_tables["DSP coefficients<br/>[dsp_tables.rs]"]
  node_wide_fir["Wide FIR mode<br/>[wide_fir.rs]"]
  node_wide_fir_tables["Wide FIR tables<br/>[wide_fir_tables.rs]"]
  node_audio["Audio handling<br/>[audio.rs]"]
  node_usb_audio["USB audio<br/>[usb_audio.rs]"]
  node_usb_vendor["USB vendor interface<br/>[usb_vendor.rs]"]
end

subgraph group_host["Host tools"]
  node_host_library["Host library<br/>[lib.rs]"]
  node_simulator["Hardware simulator<br/>[simulator.rs]"]
  node_cli["Controller CLI<br/>[cli.rs]"]
end

node_operator(("Operator / client"))

node_operator -->|"connects USB"| node_firmware_entry
node_operator -->|"sends CAT"| node_cat_parser
node_operator -->|"runs simulator"| node_simulator
node_operator -->|"runs controller"| node_cli
node_firmware_entry -->|"starts capture"| node_capture
node_firmware_entry -->|"exposes audio"| node_usb_audio
node_firmware_entry -->|"exposes vendor control"| node_usb_vendor
node_firmware_entry -->|"loads settings"| node_saved_settings
node_control_protocol -->|"uses records"| node_command_records
node_firmware_entry -.->|"dispatches control"| node_control_protocol
node_firmware_entry -.->|"dispatches CAT"| node_cat_parser
node_control_protocol -->|"updates settings"| node_receiver_controls
node_chip_control -->|"applies controls"| node_receiver_controls
node_chip_control -->|"uses bus"| node_i2c
node_chip_control -->|"recovers bus"| node_bus_recovery
node_capture -.->|"processes I/Q"| node_dsp
node_dsp -->|"reads coefficients"| node_dsp_tables
node_chip_control -->|"selects FIR"| node_wide_fir
node_wide_fir -->|"selects tables"| node_wide_fir_tables
node_dsp -.->|"produces audio"| node_audio
node_audio -.->|"streams audio"| node_usb_audio
node_capture -.->|"streams I/Q"| node_usb_vendor
node_host_library -.->|"provides simulator"| node_simulator
node_host_library -.->|"provides CLI"| node_cli

click node_firmware_entry "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/main.rs"
click node_control_protocol "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/astra.rs"
click node_command_records "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/control_v2.rs"
click node_cat_parser "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/cat.rs"
click node_receiver_controls "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/controls.rs"
click node_config_protocol "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/protocol.rs"
click node_chip_control "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/chip.rs"
click node_i2c "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/i2c_bus.rs"
click node_bus_recovery "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/recovery.rs"
click node_saved_settings "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/persistence.rs"
click node_capture "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/capture.rs"
click node_dsp "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/dsp.rs"
click node_dsp_tables "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/dsp_tables.rs"
click node_wide_fir "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/wide_fir.rs"
click node_wide_fir_tables "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/wide_fir_tables.rs"
click node_audio "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/audio.rs"
click node_usb_audio "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/usb_audio.rs"
click node_usb_vendor "https://github.com/ur8us/astra918sdr/blob/main/firmware/src/usb_vendor.rs"
click node_host_library "https://github.com/ur8us/astra918sdr/blob/main/host/src/lib.rs"
click node_simulator "https://github.com/ur8us/astra918sdr/blob/main/host/src/simulator.rs"
click node_cli "https://github.com/ur8us/astra918sdr/blob/main/host/src/cli.rs"

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_entry,node_control_protocol,node_command_records,node_cat_parser,node_receiver_controls,node_config_protocol,node_operator toneBlue
class node_chip_control,node_i2c,node_bus_recovery,node_saved_settings toneAmber
class node_capture,node_dsp,node_dsp_tables,node_wide_fir,node_wide_fir_tables,node_audio,node_usb_audio,node_usb_vendor toneMint
class node_host_library,node_simulator,node_cli toneRose
```

## Components

### Control and tuning

- [Firmware runtime](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/main.rs): `firmware/src/main.rs`
- [AST1 control](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/astra.rs): `firmware/src/astra.rs`
- [Control records](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/control_v2.rs): `firmware/src/control_v2.rs`
- [CAT commands](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/cat.rs): `firmware/src/cat.rs`
- [Receiver settings](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/controls.rs): `firmware/src/controls.rs`
- [Protocol helpers](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/protocol.rs): `firmware/src/protocol.rs`

### Receiver hardware

- [CMX918 control](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/chip.rs): `firmware/src/chip.rs`
- [I²C bus](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/i2c_bus.rs): `firmware/src/i2c_bus.rs`
- [Bus recovery](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/recovery.rs): `firmware/src/recovery.rs`
- [Saved settings](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/persistence.rs): `firmware/src/persistence.rs`

### Capture and streams

- [I/Q capture](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/capture.rs): `firmware/src/capture.rs`
- [Channel DSP](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/dsp.rs): `firmware/src/dsp.rs`
- [DSP coefficients](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/dsp_tables.rs): `firmware/src/dsp_tables.rs`
- [Wide FIR mode](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/wide_fir.rs): `firmware/src/wide_fir.rs`
- [Wide FIR tables](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/wide_fir_tables.rs): `firmware/src/wide_fir_tables.rs`
- [Audio handling](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/audio.rs): `firmware/src/audio.rs`
- [USB audio](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/usb_audio.rs): `firmware/src/usb_audio.rs`
- [USB vendor interface](https://github.com/ur8us/astra918sdr/blob/main/firmware/src/usb_vendor.rs): `firmware/src/usb_vendor.rs`

### Host tools

- [Host library](https://github.com/ur8us/astra918sdr/blob/main/host/src/lib.rs): `host/src/lib.rs`
- [Hardware simulator](https://github.com/ur8us/astra918sdr/blob/main/host/src/simulator.rs): `host/src/simulator.rs`
- [Controller CLI](https://github.com/ur8us/astra918sdr/blob/main/host/src/cli.rs): `host/src/cli.rs`

### Other components

- **Operator / client**

## Connections

- Operator / client → Firmware runtime: connects USB (evidence: `README.md`)
- Operator / client → CAT commands: sends CAT (evidence: `README.md`)
- Operator / client → Hardware simulator: runs simulator (evidence: `README.md`)
- Operator / client → Controller CLI: runs controller (evidence: `README.md`)
- Firmware runtime → I/Q capture: starts capture (evidence: `firmware/src/main.rs`)
- Firmware runtime → USB audio: exposes audio (evidence: `README.md`)
- Firmware runtime → USB vendor interface: exposes vendor control (evidence: `README.md`)
- Firmware runtime → Saved settings: loads settings (evidence: `firmware/src/main.rs`)
- AST1 control → Control records: uses records (evidence: `firmware/src/astra.rs`)
- Firmware runtime → AST1 control: dispatches control
- Firmware runtime → CAT commands: dispatches CAT
- AST1 control → Receiver settings: updates settings (evidence: `firmware/src/astra.rs`)
- CMX918 control → Receiver settings: applies controls (evidence: `firmware/src/chip.rs`)
- CMX918 control → I²C bus: uses bus (evidence: `firmware/src/chip.rs`)
- CMX918 control → Bus recovery: recovers bus (evidence: `firmware/src/chip.rs`)
- I/Q capture → Channel DSP: processes I/Q
- Channel DSP → DSP coefficients: reads coefficients (evidence: `firmware/src/dsp.rs`)
- CMX918 control → Wide FIR mode: selects FIR (evidence: `firmware/src/chip.rs`)
- Wide FIR mode → Wide FIR tables: selects tables (evidence: `firmware/src/wide_fir.rs`)
- Channel DSP → Audio handling: produces audio
- Audio handling → USB audio: streams audio
- I/Q capture → USB vendor interface: streams I/Q
- Host library → Hardware simulator: provides simulator
- Host library → Controller CLI: provides CLI
