# joeearlam/fatal-deviation architecture

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

- Interactive diagram: https://gitdiagram.com/joeearlam/fatal-deviation
- Repository: https://github.com/joeearlam/fatal-deviation

## Overview

Fatal Deviation is a beetleweight robot combining an RP2040 firmware stack, custom control electronics, and mechanical CAD. Its main runtime path is RC input through IBUS decoding and drive control, with IMU feedback supporting electronic stability control, followed by four motor outputs. The board also integrates current sensing, servo connections, and RGB lighting. The README documents asynchronous task scheduling and packet-triggered drive calculations; sampled source shows the drive, IMU, IBUS, and motor abstractions, but not the task callback implementations or their full wiring.

Main entry points: [`Code/bot_software/bot_software.ino`](https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/bot_software.ino) (Task callbacks), [`Electronics/botctrl-rev2/botctrl.kicad_pcb`](https://github.com/joeearlam/fatal-deviation/blob/main/Electronics/botctrl-rev2/botctrl.kicad_pcb) (Controller PCB), [`Code/bot_software/src/drive.h`](https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/src/drive.h) (Drive controller), [`Code/bot_software/src/motor.h`](https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/src/motor.h) (Motor drivers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_firmware["Firmware runtime"]
  node_scheduler["Task callbacks<br/>[bot_software.ino]"]
  node_ibus["IBUS decoder<br/>[ibus.cpp]"]
  node_channel_map["Radio mapping<br/>[bot_software.ino]"]
end

subgraph group_control["Motion control"]
  node_imu["IMU acquisition<br/>[IMU.h]"]
  node_drive["Drive controller<br/>[drive.h]"]
  node_motor["Motor drivers<br/>[motor.h]"]
end

subgraph group_electronics["Robot electronics"]
  node_board["Controller PCB<br/>[botctrl.kicad_pcb]"]
  node_drive_circuit["Drive circuitry<br/>[drive.kicad_sch]"]
  node_main_circuit["Board circuitry<br/>[botctrl.kicad_sch]"]
  node_servo["Lifter servo<br/>[botctrl.kicad_sch]"]
  node_lighting["RGB lighting<br/>[botctrl.kicad_sch]"]
end

subgraph group_mechanical["Mechanical design"]
  node_chassis["Robot chassis"]
  node_backup_cad["CAD backup"]
end

node_operator(("RC operator"))
node_receiver["IBUS receiver"]

node_operator -->|"sends commands"| node_receiver
node_receiver -->|"sends packets"| node_ibus
node_scheduler -->|"reads packets"| node_ibus
node_scheduler -->|"maps channels"| node_channel_map
node_channel_map -->|"sets inputs"| node_drive
node_scheduler -->|"triggers calculations"| node_drive
node_scheduler -->|"updates readings"| node_imu
node_drive -->|"uses gyro data"| node_imu
node_drive -->|"computes commands"| node_motor
node_motor -.->|"drives motors"| node_drive_circuit
node_board -.->|"implements"| node_main_circuit
node_board -.->|"integrates"| node_drive_circuit
node_board -->|"provides pads"| node_servo
node_board -->|"integrates LEDs"| node_lighting
node_chassis -.->|"has backup"| node_backup_cad

click node_scheduler "https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/bot_software.ino"
click node_ibus "https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/src/ibus.cpp"
click node_channel_map "https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/bot_software.ino"
click node_imu "https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/src/IMU.h"
click node_drive "https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/src/drive.h"
click node_motor "https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/src/motor.h"
click node_board "https://github.com/joeearlam/fatal-deviation/blob/main/Electronics/botctrl-rev2/botctrl.kicad_pcb"
click node_drive_circuit "https://github.com/joeearlam/fatal-deviation/blob/main/Electronics/botctrl-rev2/drive.kicad_sch"
click node_main_circuit "https://github.com/joeearlam/fatal-deviation/blob/main/Electronics/botctrl-rev2/botctrl.kicad_sch"
click node_servo "https://github.com/joeearlam/fatal-deviation/blob/main/Electronics/botctrl-rev2/botctrl.kicad_sch"
click node_lighting "https://github.com/joeearlam/fatal-deviation/blob/main/Electronics/botctrl-rev2/botctrl.kicad_sch"
click node_chassis "https://github.com/joeearlam/fatal-deviation/blob/main/CAD/fatalDeviation.FCStd"
click node_backup_cad "https://github.com/joeearlam/fatal-deviation/blob/main/CAD/fatalDeviation.20250727-103208.FCBak"

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_scheduler,node_ibus,node_channel_map toneBlue
class node_imu,node_drive,node_motor toneAmber
class node_board,node_drive_circuit,node_main_circuit,node_servo,node_lighting toneMint
class node_chassis,node_backup_cad toneRose
class node_operator,node_receiver toneIndigo
```

## Components

### Firmware runtime

- [Task callbacks](https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/bot_software.ino): `Code/bot_software/bot_software.ino`
- [IBUS decoder](https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/src/ibus.cpp): `Code/bot_software/src/ibus.cpp`
- [Radio mapping](https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/bot_software.ino): `Code/bot_software/bot_software.ino`

### Motion control

- [IMU acquisition](https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/src/IMU.h): `Code/bot_software/src/IMU.h`
- [Drive controller](https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/src/drive.h): `Code/bot_software/src/drive.h`
- [Motor drivers](https://github.com/joeearlam/fatal-deviation/blob/main/Code/bot_software/src/motor.h): `Code/bot_software/src/motor.h`

### Robot electronics

- [Controller PCB](https://github.com/joeearlam/fatal-deviation/blob/main/Electronics/botctrl-rev2/botctrl.kicad_pcb): `Electronics/botctrl-rev2/botctrl.kicad_pcb`
- [Drive circuitry](https://github.com/joeearlam/fatal-deviation/blob/main/Electronics/botctrl-rev2/drive.kicad_sch): `Electronics/botctrl-rev2/drive.kicad_sch`
- [Board circuitry](https://github.com/joeearlam/fatal-deviation/blob/main/Electronics/botctrl-rev2/botctrl.kicad_sch): `Electronics/botctrl-rev2/botctrl.kicad_sch`
- [Lifter servo](https://github.com/joeearlam/fatal-deviation/blob/main/Electronics/botctrl-rev2/botctrl.kicad_sch): `Electronics/botctrl-rev2/botctrl.kicad_sch`
- [RGB lighting](https://github.com/joeearlam/fatal-deviation/blob/main/Electronics/botctrl-rev2/botctrl.kicad_sch): `Electronics/botctrl-rev2/botctrl.kicad_sch`

### Mechanical design

- [Robot chassis](https://github.com/joeearlam/fatal-deviation/blob/main/CAD/fatalDeviation.FCStd): `CAD/fatalDeviation.FCStd`
- [CAD backup](https://github.com/joeearlam/fatal-deviation/blob/main/CAD/fatalDeviation.20250727-103208.FCBak): `CAD/fatalDeviation.20250727-103208.FCBak`

### Other components

- **RC operator**
- **IBUS receiver**

## Connections

- RC operator → IBUS receiver: sends commands (evidence: `README.md`)
- IBUS receiver → IBUS decoder: sends packets (evidence: `README.md`)
- Task callbacks → IBUS decoder: reads packets (evidence: `Code/bot_software/src/ibus.cpp`)
- Task callbacks → Radio mapping: maps channels (evidence: `README.md`)
- Radio mapping → Drive controller: sets inputs (evidence: `README.md`)
- Task callbacks → Drive controller: triggers calculations (evidence: `README.md`)
- Task callbacks → IMU acquisition: updates readings (evidence: `README.md`)
- Drive controller → IMU acquisition: uses gyro data (evidence: `Code/bot_software/src/drive.h`)
- Drive controller → Motor drivers: computes commands (evidence: `Code/bot_software/src/drive.h`)
- Motor drivers → Drive circuitry: drives motors
- Controller PCB → Board circuitry: implements
- Controller PCB → Drive circuitry: integrates
- Controller PCB → Lifter servo: provides pads (evidence: `README.md`)
- Controller PCB → RGB lighting: integrates LEDs (evidence: `README.md`)
- Robot chassis → CAD backup: has backup