# alanbjohnston/cubesatsim architecture

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

- Interactive diagram: https://gitdiagram.com/alanbjohnston/cubesatsim
- Repository: https://github.com/alanbjohnston/cubesatsim

## Overview

CubeSatSim is a Raspberry Pi-based satellite emulator that samples onboard telemetry and transmits it over UHF; the README also describes multiple radio formats, camera/SSTV transmission, and sensor extensions. The main runtime entry point is `main.c`, with sensor acquisition and telemetry preparation feeding radio transmission. Separate groundstation scripts support reception and telemetry decoding. Some connections below are documented or visible in the excerpts; dashed, uncited links mark relationships that the available excerpts do not verify.

Main entry points: [`main.c`](https://github.com/alanbjohnston/cubesatsim/blob/master/main.c) (Simulator loop), [`ax5043/spi/ax5043spi.c`](https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/spi/ax5043spi.c) (SPI interface), [`ax5043/axradio/axradioinit.c`](https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/axradio/axradioinit.c) (Radio initialization), [`ax5043/axradio/axradiotx.c`](https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/axradio/axradiotx.c) (Packet transmitter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Simulator runtime"]
  node_main["Simulator loop<br/>[main.c]"]
  node_sensors["Sensor sampling<br/>[sensor_extension.c]"]
  node_telemetry["Telemetry encoding<br/>[TelemEncoding.c]"]
  node_codec["AO-40 codec<br/>[codecAO40.c]"]
  node_python_tx["Alternate transmitter<br/>[transmit.py]"]
  node_frequency["Frequency utilities<br/>[frequency.py]"]
end

subgraph group_radio["Radio stack"]
  node_ax25["AX.25 framing<br/>[ax25.c]"]
  node_afsk["AFSK radio driver<br/>[ax5043.c]"]
  node_radio_init["Radio initialization<br/>[axradioinit.c]"]
  node_radio_mode["Radio modes<br/>[axradiomode.c]"]
  node_radio_tx["Packet transmitter<br/>[axradiotx.c]"]
  node_radio_rx["Packet receiver<br/>[axradiorx.c]"]
  node_chip_support["Chip support"]
  node_crc["CRC and PN9<br/>[crc.c]"]
  node_spi["SPI interface<br/>[ax5043spi.c]"]
end

subgraph group_ground["Groundstation tools"]
  node_ground_rx["Ground reception<br/>[config_webrx.py]"]
  node_decoder["Telemetry decoder<br/>[fc_block_decode.py]"]
  node_ground_tune["Receiver tuning<br/>[auto-tune.py]"]
  node_aprs["APRS location tools"]
end

subgraph group_extensions["Sensor extensions"]
  node_stem_extensions["STEM payloads"]
end

node_operator(("Operator"))
node_transceiver{{"AX5043 transceiver"}}

node_operator -->|"starts"| node_main
node_main -->|"reads sensors"| node_sensors
node_main -.->|"prepares telemetry"| node_telemetry
node_main -.->|"encodes frames"| node_codec
node_main -.->|"frames packets"| node_ax25
node_main -.->|"transmits radio"| node_afsk
node_main -.->|"configures radio"| node_radio_init
node_ax25 -->|"submits frames"| node_afsk
node_afsk -->|"accesses registers"| node_spi
node_radio_init -->|"initializes chip"| node_chip_support
node_radio_init -->|"uses CRC"| node_crc
node_radio_tx -->|"uses TX support"| node_chip_support
node_radio_tx -->|"appends CRC"| node_crc
node_radio_tx -->|"selects mode"| node_radio_mode
node_radio_init -->|"configures registers"| node_spi
node_radio_mode -->|"sets mode"| node_spi
node_radio_rx -.->|"reads radio"| node_spi
node_chip_support -->|"uses interface"| node_spi
node_spi -->|"reads and writes"| node_transceiver
node_transceiver -.->|"emits RF"| node_ground_rx
node_ground_rx -.->|"provides signal"| node_decoder
node_ground_tune -.->|"tunes receiver"| node_ground_rx
node_aprs -.->|"supports telemetry"| node_decoder
node_stem_extensions -.->|"extends payload"| node_sensors
node_python_tx -.->|"transmits RF"| node_transceiver
node_frequency -.->|"supports tuning"| node_python_tx

click node_main "https://github.com/alanbjohnston/cubesatsim/blob/master/main.c"
click node_sensors "https://github.com/alanbjohnston/cubesatsim/blob/master/sensor_extension.c"
click node_telemetry "https://github.com/alanbjohnston/cubesatsim/blob/master/TelemEncoding.c"
click node_codec "https://github.com/alanbjohnston/cubesatsim/blob/master/codecAO40.c"
click node_ax25 "https://github.com/alanbjohnston/cubesatsim/blob/master/afsk/ax25.c"
click node_afsk "https://github.com/alanbjohnston/cubesatsim/blob/master/afsk/ax5043.c"
click node_radio_init "https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/axradio/axradioinit.c"
click node_radio_mode "https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/axradio/axradiomode.c"
click node_radio_tx "https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/axradio/axradiotx.c"
click node_radio_rx "https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/axradio/axradiorx.c"
click node_chip_support "https://github.com/alanbjohnston/cubesatsim/tree/master/ax5043/ax5043support"
click node_crc "https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/crc/crc.c"
click node_spi "https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/spi/ax5043spi.c"
click node_ground_rx "https://github.com/alanbjohnston/cubesatsim/blob/master/groundstation/config_webrx.py"
click node_decoder "https://github.com/alanbjohnston/cubesatsim/blob/master/groundstation/fc_block_decode.py"
click node_ground_tune "https://github.com/alanbjohnston/cubesatsim/blob/master/groundstation/auto-tune.py"
click node_aprs "https://github.com/alanbjohnston/cubesatsim/blob/master/groundstation/loc-add-foxtelem.py"
click node_stem_extensions "https://github.com/alanbjohnston/cubesatsim/tree/master/stempayload"
click node_python_tx "https://github.com/alanbjohnston/cubesatsim/blob/master/transmit.py"
click node_frequency "https://github.com/alanbjohnston/cubesatsim/blob/master/frequency.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_main,node_sensors,node_telemetry,node_codec,node_python_tx,node_frequency toneBlue
class node_ax25,node_afsk,node_radio_init,node_radio_mode,node_radio_tx,node_radio_rx,node_chip_support,node_crc,node_spi toneAmber
class node_ground_rx,node_decoder,node_ground_tune,node_aprs toneMint
class node_stem_extensions toneRose
class node_operator,node_transceiver toneIndigo
```

## Components

### Simulator runtime

- [Simulator loop](https://github.com/alanbjohnston/cubesatsim/blob/master/main.c): `main.c`
- [Sensor sampling](https://github.com/alanbjohnston/cubesatsim/blob/master/sensor_extension.c): `sensor_extension.c`
- [Telemetry encoding](https://github.com/alanbjohnston/cubesatsim/blob/master/TelemEncoding.c): `TelemEncoding.c`
- [AO-40 codec](https://github.com/alanbjohnston/cubesatsim/blob/master/codecAO40.c): `codecAO40.c`
- [Alternate transmitter](https://github.com/alanbjohnston/cubesatsim/blob/master/transmit.py): `transmit.py`
- [Frequency utilities](https://github.com/alanbjohnston/cubesatsim/blob/master/frequency.py): `frequency.py`

### Radio stack

- [AX.25 framing](https://github.com/alanbjohnston/cubesatsim/blob/master/afsk/ax25.c): `afsk/ax25.c`
- [AFSK radio driver](https://github.com/alanbjohnston/cubesatsim/blob/master/afsk/ax5043.c): `afsk/ax5043.c`
- [Radio initialization](https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/axradio/axradioinit.c): `ax5043/axradio/axradioinit.c`
- [Radio modes](https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/axradio/axradiomode.c): `ax5043/axradio/axradiomode.c`
- [Packet transmitter](https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/axradio/axradiotx.c): `ax5043/axradio/axradiotx.c`
- [Packet receiver](https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/axradio/axradiorx.c): `ax5043/axradio/axradiorx.c`
- [Chip support](https://github.com/alanbjohnston/cubesatsim/tree/master/ax5043/ax5043support): `ax5043/ax5043support`
- [CRC and PN9](https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/crc/crc.c): `ax5043/crc/crc.c`
- [SPI interface](https://github.com/alanbjohnston/cubesatsim/blob/master/ax5043/spi/ax5043spi.c): `ax5043/spi/ax5043spi.c`

### Groundstation tools

- [Ground reception](https://github.com/alanbjohnston/cubesatsim/blob/master/groundstation/config_webrx.py): `groundstation/config_webrx.py`
- [Telemetry decoder](https://github.com/alanbjohnston/cubesatsim/blob/master/groundstation/fc_block_decode.py): `groundstation/fc_block_decode.py`
- [Receiver tuning](https://github.com/alanbjohnston/cubesatsim/blob/master/groundstation/auto-tune.py): `groundstation/auto-tune.py`
- [APRS location tools](https://github.com/alanbjohnston/cubesatsim/blob/master/groundstation/loc-add-foxtelem.py): `groundstation/loc-add-foxtelem.py`

### Sensor extensions

- [STEM payloads](https://github.com/alanbjohnston/cubesatsim/tree/master/stempayload): `stempayload`

### Other components

- **Operator**
- **AX5043 transceiver**

## Connections

- Operator → Simulator loop: starts (evidence: `README.md`)
- Simulator loop → Sensor sampling: reads sensors (evidence: `main.c`)
- Simulator loop → Telemetry encoding: prepares telemetry
- Simulator loop → AO-40 codec: encodes frames
- Simulator loop → AX.25 framing: frames packets
- Simulator loop → AFSK radio driver: transmits radio
- Simulator loop → Radio initialization: configures radio
- AX.25 framing → AFSK radio driver: submits frames (evidence: `afsk/ax25.c`)
- AFSK radio driver → SPI interface: accesses registers (evidence: `afsk/ax5043.c`)
- Radio initialization → Chip support: initializes chip (evidence: `ax5043/axradio/axradioinit.c`)
- Radio initialization → CRC and PN9: uses CRC (evidence: `ax5043/axradio/axradioinit.c`)
- Packet transmitter → Chip support: uses TX support (evidence: `ax5043/axradio/axradiotx.c`)
- Packet transmitter → CRC and PN9: appends CRC (evidence: `ax5043/axradio/axradiotx.c`)
- Packet transmitter → Radio modes: selects mode (evidence: `ax5043/axradio/axradiotx.c`)
- Radio initialization → SPI interface: configures registers (evidence: `ax5043/axradio/axradioinit.c`)
- Radio modes → SPI interface: sets mode (evidence: `ax5043/axradio/axradiomode.c`)
- Packet receiver → SPI interface: reads radio
- Chip support → SPI interface: uses interface (evidence: `ax5043/ax5043support/ax5043init.c`)
- SPI interface → AX5043 transceiver: reads and writes
- AX5043 transceiver → Ground reception: emits RF
- Ground reception → Telemetry decoder: provides signal
- Receiver tuning → Ground reception: tunes receiver
- APRS location tools → Telemetry decoder: supports telemetry
- STEM payloads → Sensor sampling: extends payload
- Alternate transmitter → AX5043 transceiver: transmits RF
- Frequency utilities → Alternate transmitter: supports tuning
