# okalachev/flix architecture

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

- Interactive diagram: https://gitdiagram.com/okalachev/flix
- Repository: https://github.com/okalachev/flix

## Overview

Flix is an ESP32 quadcopter flight-control product with firmware, MAVLink control, a Gazebo simulation that runs the Arduino firmware, and Python automation and log-analysis tools. The principal workflow is pilot or script input over Wi-Fi/ESP-NOW, firmware state estimation and control, then motor actuation; telemetry and logs flow back to operators. The tree and README establish the major capabilities, while sampled source confirms the simulator and Python message handling; some firmware wiring is represented only at subsystem level.

Main entry points: [`flix/flix.ino`](https://github.com/okalachev/flix/blob/master/flix/flix.ino) (Firmware entry), [`gazebo/simulator.cpp`](https://github.com/okalachev/flix/blob/master/gazebo/simulator.cpp) (Gazebo plugin), [`tools/pyflix/flix.py`](https://github.com/okalachev/flix/blob/master/tools/pyflix/flix.py) (Python flight API), [`flix/mavlink.ino`](https://github.com/okalachev/flix/blob/master/flix/mavlink.ino) (MAVLink protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flight["Flight firmware"]
  node_firmware["Firmware entry<br/>[flix.ino]"]
  node_rc["RC input<br/>[rc.ino]"]
  node_wifi["Wireless link<br/>[wifi.ino]"]
  node_mavlink["MAVLink protocol<br/>[mavlink.ino]"]
  node_imu["IMU acquisition<br/>[imu.ino]"]
  node_estimate["State estimation<br/>[estimate.ino]"]
  node_control["Flight control<br/>[control.ino]"]
  node_safety["Flight safety<br/>[safety.ino]"]
  node_motors["Motor output<br/>[motors.ino]"]
  node_power["Power monitoring<br/>[power.ino]"]
  node_console["Wireless CLI<br/>[console.ino]"]
  node_logging["Flight logging<br/>[log.ino]"]
  node_parameters["Parameters<br/>[parameters.ino]"]
end

subgraph group_simulation["Gazebo simulation"]
  node_simulator["Gazebo plugin<br/>[simulator.cpp]"]
  node_simworld["Drone world model<br/>[flix.world]"]
  node_arduino["Arduino compatibility<br/>[Arduino.h]"]
end

subgraph group_operator["Control and analysis"]
  node_python["Python flight API<br/>[flix.py]"]
  node_proxy["MAVLink proxy<br/>[proxy.py]"]
  node_logtool["Log download<br/>[log.py]"]
  node_converter["CSV to ULog<br/>[csv_to_ulog.cpp]"]
end

subgraph group_math["Flight primitives"]
  node_vectors["Vector math<br/>[vector.h]"]
  node_quaternion["Quaternion math<br/>[quaternion.h]"]
end

node_pilot(("Pilot / QGroundControl"))
node_motors_ext{{"Motors / ESCs"}}
node_imu_ext{{"IMU sensor"}}
node_flightlog["CSV flight log"]

node_pilot -.->|"pilot input"| node_rc
node_pilot -->|"MAVLink control"| node_wifi
node_wifi -->|"transports"| node_mavlink
node_rc -->|"control input"| node_firmware
node_mavlink -->|"commands"| node_firmware
node_firmware -->|"samples"| node_imu
node_firmware -->|"updates"| node_estimate
node_firmware -->|"runs control"| node_control
node_firmware -->|"checks safety"| node_safety
node_firmware -->|"sets outputs"| node_motors
node_motors -->|"drives"| node_motors_ext
node_imu_ext -->|"sensor data"| node_imu
node_firmware -->|"monitors voltage"| node_power
node_firmware -->|"serves commands"| node_console
node_firmware -->|"records state"| node_logging
node_firmware -->|"uses settings"| node_parameters
node_estimate -->|"uses math"| node_vectors
node_estimate -->|"uses rotations"| node_quaternion
node_simulator -->|"uses compatibility"| node_arduino
node_simulator -->|"runs flight code"| node_firmware
node_simworld -->|"loads model"| node_simulator
node_simulator -->|"supplies virtual IMU"| node_imu
node_simulator -->|"applies forces"| node_motors
node_python -.->|"scripted control"| node_pilot
node_python -->|"sends commands"| node_mavlink
node_mavlink -->|"telemetry"| node_python
node_proxy -->|"forwards packets"| node_python
node_logtool -->|"downloads log"| node_python
node_logtool -->|"writes CSV"| node_flightlog
node_converter -->|"reads CSV"| node_flightlog

click node_firmware "https://github.com/okalachev/flix/blob/master/flix/flix.ino"
click node_rc "https://github.com/okalachev/flix/blob/master/flix/rc.ino"
click node_wifi "https://github.com/okalachev/flix/blob/master/flix/wifi.ino"
click node_mavlink "https://github.com/okalachev/flix/blob/master/flix/mavlink.ino"
click node_imu "https://github.com/okalachev/flix/blob/master/flix/imu.ino"
click node_estimate "https://github.com/okalachev/flix/blob/master/flix/estimate.ino"
click node_control "https://github.com/okalachev/flix/blob/master/flix/control.ino"
click node_safety "https://github.com/okalachev/flix/blob/master/flix/safety.ino"
click node_motors "https://github.com/okalachev/flix/blob/master/flix/motors.ino"
click node_power "https://github.com/okalachev/flix/blob/master/flix/power.ino"
click node_console "https://github.com/okalachev/flix/blob/master/flix/console.ino"
click node_logging "https://github.com/okalachev/flix/blob/master/flix/log.ino"
click node_parameters "https://github.com/okalachev/flix/blob/master/flix/parameters.ino"
click node_simulator "https://github.com/okalachev/flix/blob/master/gazebo/simulator.cpp"
click node_simworld "https://github.com/okalachev/flix/blob/master/gazebo/flix.world"
click node_arduino "https://github.com/okalachev/flix/blob/master/gazebo/Arduino.h"
click node_python "https://github.com/okalachev/flix/blob/master/tools/pyflix/flix.py"
click node_proxy "https://github.com/okalachev/flix/blob/master/tools/pyflix/proxy.py"
click node_logtool "https://github.com/okalachev/flix/blob/master/tools/log.py"
click node_converter "https://github.com/okalachev/flix/blob/master/tools/csv_to_ulog/csv_to_ulog.cpp"
click node_vectors "https://github.com/okalachev/flix/blob/master/flix/vector.h"
click node_quaternion "https://github.com/okalachev/flix/blob/master/flix/quaternion.h"

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,node_rc,node_wifi,node_mavlink,node_imu,node_estimate,node_control,node_safety,node_motors,node_power,node_console,node_logging,node_parameters toneBlue
class node_simulator,node_simworld,node_arduino toneAmber
class node_python,node_proxy,node_logtool,node_converter toneMint
class node_vectors,node_quaternion toneRose
class node_pilot,node_motors_ext,node_imu_ext,node_flightlog toneIndigo
```

## Components

### Flight firmware

- [Firmware entry](https://github.com/okalachev/flix/blob/master/flix/flix.ino): `flix/flix.ino`
- [RC input](https://github.com/okalachev/flix/blob/master/flix/rc.ino): `flix/rc.ino`
- [Wireless link](https://github.com/okalachev/flix/blob/master/flix/wifi.ino): `flix/wifi.ino`
- [MAVLink protocol](https://github.com/okalachev/flix/blob/master/flix/mavlink.ino): `flix/mavlink.ino`
- [IMU acquisition](https://github.com/okalachev/flix/blob/master/flix/imu.ino): `flix/imu.ino`
- [State estimation](https://github.com/okalachev/flix/blob/master/flix/estimate.ino): `flix/estimate.ino`
- [Flight control](https://github.com/okalachev/flix/blob/master/flix/control.ino): `flix/control.ino`
- [Flight safety](https://github.com/okalachev/flix/blob/master/flix/safety.ino): `flix/safety.ino`
- [Motor output](https://github.com/okalachev/flix/blob/master/flix/motors.ino): `flix/motors.ino`
- [Power monitoring](https://github.com/okalachev/flix/blob/master/flix/power.ino): `flix/power.ino`
- [Wireless CLI](https://github.com/okalachev/flix/blob/master/flix/console.ino): `flix/console.ino`
- [Flight logging](https://github.com/okalachev/flix/blob/master/flix/log.ino): `flix/log.ino`
- [Parameters](https://github.com/okalachev/flix/blob/master/flix/parameters.ino): `flix/parameters.ino`

### Gazebo simulation

- [Gazebo plugin](https://github.com/okalachev/flix/blob/master/gazebo/simulator.cpp): `gazebo/simulator.cpp`
- [Drone world model](https://github.com/okalachev/flix/blob/master/gazebo/flix.world): `gazebo/flix.world`
- [Arduino compatibility](https://github.com/okalachev/flix/blob/master/gazebo/Arduino.h): `gazebo/Arduino.h`

### Control and analysis

- [Python flight API](https://github.com/okalachev/flix/blob/master/tools/pyflix/flix.py): `tools/pyflix/flix.py`
- [MAVLink proxy](https://github.com/okalachev/flix/blob/master/tools/pyflix/proxy.py): `tools/pyflix/proxy.py`
- [Log download](https://github.com/okalachev/flix/blob/master/tools/log.py): `tools/log.py`
- [CSV to ULog](https://github.com/okalachev/flix/blob/master/tools/csv_to_ulog/csv_to_ulog.cpp): `tools/csv_to_ulog/csv_to_ulog.cpp`

### Flight primitives

- [Vector math](https://github.com/okalachev/flix/blob/master/flix/vector.h): `flix/vector.h`
- [Quaternion math](https://github.com/okalachev/flix/blob/master/flix/quaternion.h): `flix/quaternion.h`

### Other components

- **Pilot / QGroundControl**
- **Motors / ESCs**
- **IMU sensor**
- **CSV flight log**

## Connections

- Pilot / QGroundControl → RC input: pilot input
- Pilot / QGroundControl → Wireless link: MAVLink control
- Wireless link → MAVLink protocol: transports
- RC input → Firmware entry: control input
- MAVLink protocol → Firmware entry: commands
- Firmware entry → IMU acquisition: samples
- Firmware entry → State estimation: updates
- Firmware entry → Flight control: runs control
- Firmware entry → Flight safety: checks safety
- Firmware entry → Motor output: sets outputs
- Motor output → Motors / ESCs: drives
- IMU sensor → IMU acquisition: sensor data
- Firmware entry → Power monitoring: monitors voltage
- Firmware entry → Wireless CLI: serves commands
- Firmware entry → Flight logging: records state
- Firmware entry → Parameters: uses settings
- State estimation → Vector math: uses math
- State estimation → Quaternion math: uses rotations
- Gazebo plugin → Arduino compatibility: uses compatibility
- Gazebo plugin → Firmware entry: runs flight code
- Drone world model → Gazebo plugin: loads model
- Gazebo plugin → IMU acquisition: supplies virtual IMU
- Gazebo plugin → Motor output: applies forces
- Python flight API → Pilot / QGroundControl: scripted control
- Python flight API → MAVLink protocol: sends commands
- MAVLink protocol → Python flight API: telemetry
- MAVLink proxy → Python flight API: forwards packets
- Log download → Python flight API: downloads log
- Log download → CSV flight log: writes CSV
- CSV to ULog → CSV flight log: reads CSV
