From 344835cba80efbd101de379b74ad79a528573589 Mon Sep 17 00:00:00 2001
From: Oleg Kalachev <okalachev@gmail.com>
Date: Sat, 13 Jan 2024 14:08:02 +0300
Subject: [PATCH] Add firmware overview article

---
 README.md        |  6 +++---
 docs/build.md    |  4 ++++
 docs/firmware.md | 36 ++++++++++++++++++++++++++++++++++++
 3 files changed, 43 insertions(+), 3 deletions(-)
 create mode 100644 docs/firmware.md

diff --git a/README.md b/README.md
index 1cc1a60..551f63e 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 **flix** (*flight + X*) — making an open source ESP32-based quadcopter from scratch.
 
-<img src="docs/img/flix.jpg" width=500>
+<img src="docs/img/flix.jpg" width=500 alt="Flix quadcopter">
 
 ## Features
 
@@ -31,11 +31,11 @@ See YouTube demo video: https://youtu.be/8GzzIQ3C6DQ.
 
 Simulation in Gazebo using a plugin that runs original Arduino code is implemented:
 
-<img src="docs/img/simulator.png" width=500>
+<img src="docs/img/simulator.png" width=500 alt="Flix simulator">
 
 ## Schematics
 
-<img src="docs/img/schematics.svg" width=800>
+<img src="docs/img/schematics.svg" width=800 alt="Flix schematics">
 
 You can also check a user contributed [variant of complete circuit diagram](https://github.com/okalachev/flix/issues/3#issue-2066079898) of the drone.
 
diff --git a/docs/build.md b/docs/build.md
index 846ab2d..af697a4 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -98,6 +98,10 @@ Dependencies are [Gazebo Classic simulator](https://classic.gazebosim.org) and [
 
 See other available Make commands in the [Makefile](../Makefile).
 
+### Firmware code structure
+
+See [firmware overview](firmware.md) for more details.
+
 ## Setup
 
 Before flight in simulation and on the real drone, you need to calibrate your remote control. Use drone's command line interface (`make monitor` on the real drone) and type `cr` command. Copy calibration results to the source code (`flix/rc.ino` and/or `gazebo/joystick.h`).
diff --git a/docs/firmware.md b/docs/firmware.md
new file mode 100644
index 0000000..47312b6
--- /dev/null
+++ b/docs/firmware.md
@@ -0,0 +1,36 @@
+# Firmware overview
+
+## Dataflow
+
+<img src="img/dataflow.svg" width=800 alt="Firmware dataflow diagram">
+
+The main loop is running at 1000 Hz. All the dataflow is happening through global variables (for simplicity):
+
+* `t` *(float)* — current step time, *s*.
+* `dt` *(float)* — time delta between the current and previous steps, *s*.
+* `rates` *(Vector)* — angular rates from the gyroscope, *rad/s*.
+* `acc` *(Vector)* — acceleration data from the accelerometer, *m/s<sup>2</sup>*.
+* `attitude` *(Quaternion)* — current estimated attitude (orientation) of drone.
+* `controls` *(float[])* — user control inputs from the RC, normalized to [-1, 1] range.
+* `motors` *(float[])* — motor outputs, normalized to [-1, 1] range; reverse rotation is possible.
+
+## Source files
+
+Firmware source files are located in `flix` directory. The key files are:
+
+* [`flix.ino`](../flix/flix.ino) — main entry point, Arduino sketch. Include global variables definition and the main loop.
+* [`imu.ino`](../flix/imu.ino) — reading data from the IMU sensor (gyroscope and accelerometer), IMU calibration.
+* [`rc.ino`](../flix/rc.ino) — reading data from the RC receiver, RC calibration.
+* [`estimate.ino`](../flix/estimate.ino) — drone's attitude estimation, complementary filter.
+* [`control.ino`](../flix/control.ino) — drone's attitude and rates control, three-dimensional two-level cascade PID controller.
+* [`motors.ino`](../flix/motors.ino) — PWM motor outputs control.
+
+Utility files include:
+
+* [`vector.h`](../flix/vector.h), [`quaternion.h`](../flix/quaternion.h) — project's vector and quaternion libraries implementation.
+* [`pid.h`](../flix/pid.h) — generic PID controller implementation.
+* [`lpf.h`](../flix/lpf.h) — generic low-pass filter implementation.
+
+## Building
+
+See build instructions in [build.md](build.md).