# gilboash/tinytimer-rf architecture

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

- Interactive diagram: https://gitdiagram.com/gilboash/tinytimer-rf
- Repository: https://github.com/gilboash/tinytimer-rf

## Overview

tinytimer is an analog FPV lap-timing system: the gate scans pilot video channels, detects and timestamps crossings, then reports them over LoRa; the base aggregates race state and serves a phone interface over Wi-Fi. The optional USB server supports tuning and debugging. Edges are limited to README relationships and source references or calls visible in the supplied excerpts/index; unsampled details are not assumed.

Main entry points: [`gate/src/scan/scanner.c`](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/scan/scanner.c) (Channel scanner), [`gate/src/gate/gate.c`](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/gate/gate.c) (Gate state), [`base/src/main.cpp`](https://github.com/gilboash/tinytimer-rf/blob/main/base/src/main.cpp) (Base radio), [`gate/src/proto/commands.c`](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/proto/commands.c) (Gate commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gate["Gate firmware"]
  node_gate_boot["Gate runtime<br/>[main.c]"]
  node_commands["Gate commands<br/>[commands.c]"]
  node_scanner["Channel scanner<br/>[scanner.c]"]
  node_radio_rx["Radio backend<br/>[radio_c5.c]"]
  node_spectrum["Signal analysis<br/>[psd.c]"]
  node_metrics["Signal metrics<br/>[metrics.c]"]
  node_crossings["Lap detection<br/>[lap.c]"]
  node_gate_state["Gate state<br/>[gate.c]"]
  node_gate_link["LoRa link<br/>[lora_link.cpp]"]
  node_wire["Packet format<br/>[lap_link.h]"]
end

subgraph group_base["Base station"]
  node_base_radio["Base radio<br/>[main.cpp]"]
  node_race_engine["Race engine<br/>[app.cpp]"]
  node_web_service["Web service<br/>[web.cpp]"]
end

subgraph group_phone["Race interface"]
  node_race_page["Race page<br/>[race.js]"]
  node_browser_app["Browser app<br/>[app.js]"]
  node_announcer["Voice call-outs<br/>[announcer.js]"]
  node_lap_sounds["Lap beeps<br/>[beep.js]"]
end

subgraph group_debug["Tuning and debug"]
  node_usb_server["USB debug server<br/>[lapserver.py]"]
end

node_pilot(("FPV pilots"))
node_phone_user(("Phone racer"))
node_computer(("Tuning computer"))

node_pilot -->|"transmit video"| node_radio_rx
node_gate_boot -->|"starts task"| node_commands
node_gate_boot -->|"initializes"| node_scanner
node_scanner -->|"tunes and captures"| node_radio_rx
node_scanner -->|"processes samples"| node_spectrum
node_scanner -->|"computes metrics"| node_metrics
node_scanner -->|"feeds levels"| node_gate_state
node_gate_state -->|"detects passes"| node_crossings
node_commands -->|"configures scan"| node_scanner
node_commands -->|"configures pilots"| node_gate_state
node_gate_state -->|"queues passes"| node_gate_link
node_gate_link -->|"encodes packets"| node_wire
node_wire -->|"transfers LoRa packets"| node_base_radio
node_base_radio -->|"delivers radio events"| node_race_engine
node_race_engine -->|"requests gate config"| node_base_radio
node_race_engine -->|"publishes race updates"| node_web_service
node_phone_user -->|"joins hotspot"| node_web_service
node_web_service -->|"serves race interface"| node_browser_app
node_browser_app -->|"runs race view"| node_race_page
node_race_page -->|"plays call-outs"| node_announcer
node_race_page -->|"plays lap beeps"| node_lap_sounds
node_computer -.->|"connects over USB"| node_usb_server
node_usb_server -.->|"reads gate telemetry"| node_gate_boot
node_usb_server -.->|"reads base telemetry"| node_base_radio

click node_gate_boot "https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/main.c"
click node_commands "https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/proto/commands.c"
click node_scanner "https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/scan/scanner.c"
click node_radio_rx "https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/radio/c5/radio_c5.c"
click node_spectrum "https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/dsp/psd.c"
click node_metrics "https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/scan/metrics.c"
click node_crossings "https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/scan/lap.c"
click node_gate_state "https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/gate/gate.c"
click node_gate_link "https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/gate/lora_link.cpp"
click node_wire "https://github.com/gilboash/tinytimer-rf/blob/main/common/lap_link.h"
click node_base_radio "https://github.com/gilboash/tinytimer-rf/blob/main/base/src/main.cpp"
click node_race_engine "https://github.com/gilboash/tinytimer-rf/blob/main/base/src/app.cpp"
click node_web_service "https://github.com/gilboash/tinytimer-rf/blob/main/base/src/web.cpp"
click node_race_page "https://github.com/gilboash/tinytimer-rf/blob/main/web/race.js"
click node_browser_app "https://github.com/gilboash/tinytimer-rf/blob/main/web/app.js"
click node_announcer "https://github.com/gilboash/tinytimer-rf/blob/main/web/announcer.js"
click node_lap_sounds "https://github.com/gilboash/tinytimer-rf/blob/main/web/beep.js"
click node_usb_server "https://github.com/gilboash/tinytimer-rf/blob/main/server/lapserver.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_gate_boot,node_commands,node_scanner,node_radio_rx,node_spectrum,node_metrics,node_crossings,node_gate_state,node_gate_link,node_wire toneBlue
class node_base_radio,node_race_engine,node_web_service toneAmber
class node_race_page,node_browser_app,node_announcer,node_lap_sounds toneMint
class node_usb_server toneRose
class node_pilot,node_phone_user,node_computer toneIndigo
```

## Components

### Gate firmware

- [Gate runtime](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/main.c): `gate/src/main.c`
- [Gate commands](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/proto/commands.c): `gate/src/proto/commands.c`
- [Channel scanner](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/scan/scanner.c): `gate/src/scan/scanner.c`
- [Radio backend](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/radio/c5/radio_c5.c): `gate/src/radio/c5/radio_c5.c`
- [Signal analysis](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/dsp/psd.c): `gate/src/dsp/psd.c`
- [Signal metrics](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/scan/metrics.c): `gate/src/scan/metrics.c`
- [Lap detection](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/scan/lap.c): `gate/src/scan/lap.c`
- [Gate state](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/gate/gate.c): `gate/src/gate/gate.c`
- [LoRa link](https://github.com/gilboash/tinytimer-rf/blob/main/gate/src/gate/lora_link.cpp): `gate/src/gate/lora_link.cpp`
- [Packet format](https://github.com/gilboash/tinytimer-rf/blob/main/common/lap_link.h): `common/lap_link.h`

### Base station

- [Base radio](https://github.com/gilboash/tinytimer-rf/blob/main/base/src/main.cpp): `base/src/main.cpp`
- [Race engine](https://github.com/gilboash/tinytimer-rf/blob/main/base/src/app.cpp): `base/src/app.cpp`
- [Web service](https://github.com/gilboash/tinytimer-rf/blob/main/base/src/web.cpp): `base/src/web.cpp`

### Race interface

- [Race page](https://github.com/gilboash/tinytimer-rf/blob/main/web/race.js): `web/race.js`
- [Browser app](https://github.com/gilboash/tinytimer-rf/blob/main/web/app.js): `web/app.js`
- [Voice call-outs](https://github.com/gilboash/tinytimer-rf/blob/main/web/announcer.js): `web/announcer.js`
- [Lap beeps](https://github.com/gilboash/tinytimer-rf/blob/main/web/beep.js): `web/beep.js`

### Tuning and debug

- [USB debug server](https://github.com/gilboash/tinytimer-rf/blob/main/server/lapserver.py): `server/lapserver.py`

### Other components

- **FPV pilots**
- **Phone racer**
- **Tuning computer**

## Connections

- FPV pilots → Radio backend: transmit video (evidence: `README.md`)
- Gate runtime → Gate commands: starts task (evidence: `gate/src/main.c`)
- Gate runtime → Channel scanner: initializes (evidence: `gate/src/main.c`)
- Channel scanner → Radio backend: tunes and captures (evidence: `gate/src/scan/scanner.c`)
- Channel scanner → Signal analysis: processes samples (evidence: `gate/src/scan/scanner.c`)
- Channel scanner → Signal metrics: computes metrics (evidence: `gate/src/scan/scanner.c`)
- Channel scanner → Gate state: feeds levels
- Gate state → Lap detection: detects passes
- Gate commands → Channel scanner: configures scan (evidence: `gate/src/proto/commands.c`)
- Gate commands → Gate state: configures pilots (evidence: `gate/src/proto/commands.c`)
- Gate state → LoRa link: queues passes
- LoRa link → Packet format: encodes packets (evidence: `gate/src/gate/lora_link.cpp`)
- Packet format → Base radio: transfers LoRa packets (evidence: `README.md`)
- Base radio → Race engine: delivers radio events
- Race engine → Base radio: requests gate config
- Race engine → Web service: publishes race updates
- Phone racer → Web service: joins hotspot (evidence: `README.md`)
- Web service → Browser app: serves race interface (evidence: `README.md`)
- Browser app → Race page: runs race view (evidence: `README.md`)
- Race page → Voice call-outs: plays call-outs (evidence: `README.md`)
- Race page → Lap beeps: plays lap beeps (evidence: `README.md`)
- Tuning computer → USB debug server: connects over USB (evidence: `README.md`)
- USB debug server → Gate runtime: reads gate telemetry (evidence: `README.md`)
- USB debug server → Base radio: reads base telemetry (evidence: `README.md`)
