Many updates to documentation

Updates to main readme. Add much more info to usage article. Move simulator building to simulation's readme. Improve assembly article. Many fixes. Updates in diagrams.
2026-01-11 05:26:53 +00:00 · 2025-11-06 13:46:25 +03:00
parent 0e6651ab82
commit 774144c430
14 changed files with 344 additions and 186 deletions
--- a/docs/assembly.md
+++ b/docs/assembly.md
@@ -27,3 +27,27 @@ Soldered components ([schematics variant](https://miro.com/app/board/uXjVN-dTjoo
 <br>Assembled drone:

 <img src="img/assembly/7.jpg" width=600>
+
+## Motor directions
+
+> [!WARNING]
+> The drone above is an early build, and it has **inversed** motor directions scheme. The photos only illustrate the assembly process in general.
+
+Use standard motor directions scheme:
+
+<img src="img/motors.svg" width=200>
+
+Motors connection table:
+
+|Motor|Position|Direction|Prop type|Motor wires|GPIO|
+|-|-|-|-|-|-|
+|Motor 0|Rear left|Counter-clockwise|B|Black & White|GPIO12 (*TDI*)|
+|Motor 1|Rear right|Clockwise|A|Blue & Red|GPIO13 (*TCK*)|
+|Motor 2|Front right|Counter-clockwise|B|Black & White|GPIO14 (*TMS*)|
+|Motor 3|Front left|Clockwise|A|Blue & Red|GPIO15 (*TD0*)|
+
+## Motors tightening
+
+Motors should be installed very tightly — any vibration may lead to bad attitude estimation and unstable flight. If motors are loose, use tiny tape pieces to fix them tightly as shown below:
+
+<img src="img/motor-tape.jpg" width=600>
--- a/docs/book/firmware.md
+++ b/docs/book/firmware.md
@@ -12,8 +12,8 @@
 * `acc` *(Vector)* — данные с акселерометра, *м/с<sup>2</sup>*.
 * `rates` *(Vector)* — отфильтрованные угловые скорости, *рад/с*.
 * `attitude` *(Quaternion)* — оценка ориентации (положения) дрона.
-* `controlRoll`, `controlPitch`, ... *(float[])* — команды управления от пилота, в диапазоне [-1, 1].
-* `motors` *(float[])* — выходные сигналы на моторы, в диапазоне [0, 1].
+* `controlRoll`, `controlPitch`, `controlYaw`, `controlThrottle`, `controlMode` *(float)* — команды управления от пилота, в диапазоне [-1, 1].
+* `motors` *(float[4])* — выходные сигналы на моторы, в диапазоне [0, 1].

 ## Исходные файлы

--- a/docs/build.md
+++ b/docs/build.md
@@ -1 +0,0 @@
-usage.md
--- a/docs/build.md
+++ b/docs/build.md
@@ -0,0 +1,2 @@
+<!-- markdownlint-disable MD041 -->
+Build instructions are moved to [usage article](usage.md).
--- a/docs/firmware.md
+++ b/docs/firmware.md
@@ -6,7 +6,7 @@ The firmware is a regular Arduino sketch, and it follows the classic Arduino one

 <img src="img/dataflow.svg" width=600 alt="Firmware dataflow diagram">

-The main loop is running at 1000 Hz. All the dataflow goes through global variables (for simplicity):
+The main loop is running at 1000 Hz. The dataflow goes through global variables, including:

 * `t` *(float)* — current step time, *s*.
 * `dt` *(float)* — time delta between the current and previous steps, *s*.
@@ -14,12 +14,12 @@ The main loop is running at 1000 Hz. All the dataflow goes through global variab
 * `acc` *(Vector)* — acceleration data from the accelerometer, *m/s<sup>2</sup>*.
 * `rates` *(Vector)* — filtered angular rates, *rad/s*.
 * `attitude` *(Quaternion)* — estimated attitude (orientation) of drone.
-* `controlRoll`, `controlPitch`, ... *(float[])* — pilot control inputs, range [-1, 1].
-* `motors` *(float[])* — motor outputs, range [0, 1].
+* `controlRoll`, `controlPitch`, `controlYaw`, `controlThrottle`, `controlMode` *(float)* — pilot control inputs, range [-1, 1].
+* `motors` *(float[4])* — motor outputs, range [0, 1].

 ## Source files

-Firmware source files are located in `flix` directory. The core files are:
+Firmware source files are located in `flix` directory.

 * [`flix.ino`](../flix/flix.ino) — Arduino sketch main file, entry point.Includes some global variable definitions and the main loop.
 * [`imu.ino`](../flix/imu.ino) — reading data from the IMU sensor (gyroscope and accelerometer), IMU calibration.
@@ -28,6 +28,7 @@ Firmware source files are located in `flix` directory. The core files are:
 * [`control.ino`](../flix/control.ino) — control subsystem, three-dimensional two-level cascade PID controller.
 * [`motors.ino`](../flix/motors.ino) — PWM motor output control.
 * [`mavlink.ino`](../flix/mavlink.ino) — interaction with QGroundControl or [pyflix](../tools/pyflix) via MAVLink protocol.
+* [`cli.ino`](../flix/cli.ino) — serial and MAVLink console.

 Utility files:

@@ -45,12 +46,22 @@ Pilot inputs are interpreted in `interpretControls()`, and then converted to the
 * `torqueTarget` *(Vector)* — target torque, range [-1, 1].
 * `thrustTarget` *(float)* — collective thrust target, range [0, 1].

-Control command is processed in `controlAttitude()`, `controlRates()`, `controlTorque()` functions. Each function may be skipped if the corresponding target is set to `NAN`.
+Control command is handled in `controlAttitude()`, `controlRates()`, `controlTorque()` functions. Each function may be skipped if the corresponding control target is set to `NAN`.

 <img src="img/control.svg" width=300 alt="Control subsystem diagram">

 Armed state is stored in `armed` variable, and current mode is stored in `mode` variable.

-## Building
+### Console
+
+To write into the console, `print()` function is used. This function sends data both to the Serial console and to the MAVLink console (which can be accessed wirelessly in QGroundControl). The function supports formatting:
+
+```cpp
+print("Test value: %.2f\n", testValue);
+```
+
+In order to add a console command, modify the `doCommand()` function in `cli.ino` file.
+
+## Building the firmware

 See build instructions in [usage.md](usage.md).
--- a/docs/img/control.svg
+++ b/docs/img/control.svg
--- a/docs/img/dataflow.svg
+++ b/docs/img/dataflow.svg
--- a/docs/img/motor-tape.jpg
+++ b/docs/img/motor-tape.jpg
--- a/docs/img/motors.svg
+++ b/docs/img/motors.svg
@@ -0,0 +1,89 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 355.49 357.47">
+  <defs>
+    <style>
+      .a, .e {
+        fill: none;
+        stroke-miterlimit: 10;
+      }
+
+      .a {
+        stroke: #d5d5d5;
+        stroke-width: 31px;
+      }
+
+      .b {
+        fill: #c1c1c1;
+      }
+
+      .c {
+        fill: #ff9400;
+      }
+
+      .d {
+        opacity: 0.12;
+      }
+
+      .e {
+        stroke: #cc5200;
+        stroke-width: 8px;
+      }
+
+      .f {
+        fill: #cc5200;
+      }
+
+      .g {
+        font-size: 50px;
+        fill: #fff;
+      }
+
+      .g, .h {
+        font-family: Tahoma;
+      }
+
+      .h {
+        font-size: 20px;
+      }
+
+      .i {
+        letter-spacing: 0em;
+      }
+    </style>
+  </defs>
+  <g>
+    <g>
+      <line class="a" x1="77" y1="279.14" x2="277" y2="78.14"/>
+      <line class="a" x1="78" y1="79.14" x2="278" y2="280.14"/>
+      <circle class="b" cx="177.5" cy="178.64" r="41.5"/>
+      <circle class="c" cx="77.57" cy="78.64" r="77.95"/>
+      <circle class="c" cx="277.13" cy="78.42" r="77.95"/>
+      <circle class="c" cx="276.13" cy="279.42" r="77.95"/>
+      <circle class="c" cx="77.13" cy="279.42" r="77.95"/>
+    </g>
+    <path class="d" d="M173.89,164.07l-8.44,26.05a4.31,4.31,0,0,0,4.1,5.65h16.9a4.32,4.32,0,0,0,4.11-5.65l-8.45-26.05A4.32,4.32,0,0,0,173.89,164.07Z"/>
+    <g>
+      <path class="e" d="M307.07,123A52.66,52.66,0,1,0,235,47"/>
+      <polygon class="f" points="228.28 38.98 227.04 59.68 245.59 50.41 228.28 38.98"/>
+    </g>
+    <g>
+      <path class="e" d="M42.57,237.58a52.66,52.66,0,1,0,72.08,76"/>
+      <polygon class="f" points="121.36 321.6 122.6 300.9 104.05 310.17 121.36 321.6"/>
+    </g>
+    <g>
+      <path class="e" d="M311.89,237.58a52.66,52.66,0,1,1-72.08,76"/>
+      <polygon class="f" points="250.41 310.17 231.86 300.9 233.1 321.6 250.41 310.17"/>
+    </g>
+    <g>
+      <path class="e" d="M47.71,122.69a52.66,52.66,0,1,1,72.08-75.95"/>
+      <polygon class="f" points="109.19 50.1 127.74 59.38 126.5 38.67 109.19 50.1"/>
+    </g>
+    <text class="g" transform="translate(64.5 99.24)">3</text>
+    <text class="g" transform="translate(63.52 297.27)">0</text>
+    <text class="g" transform="translate(263.52 298.27)">1</text>
+    <text class="g" transform="translate(260.52 99.27)">2</text>
+    <text class="h" transform="translate(65.66 129.73)">p<tspan class="i" x="11.05" y="0">r</tspan><tspan x="18.16" y="0">op A</tspan></text>
+    <text class="h" transform="translate(233.66 245.73)">p<tspan class="i" x="11.05" y="0">r</tspan><tspan x="18.16" y="0">op A</tspan></text>
+    <text class="h" transform="translate(232.15 129.42)">p<tspan class="i" x="11.05" y="0">r</tspan><tspan x="18.16" y="0">op B</tspan></text>
+    <text class="h" transform="translate(67.15 245.42)">p<tspan class="i" x="11.05" y="0">r</tspan><tspan x="18.16" y="0">op B</tspan></text>
+  </g>
+</svg>
--- a/docs/img/qgc-attitude.png
+++ b/docs/img/qgc-attitude.png
--- a/docs/img/schematics1.svg
+++ b/docs/img/schematics1.svg
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -32,6 +32,8 @@ Do the following:
  * `mfl` — should rotate front left motor (clockwise).
  * `mrl` — should rotate rear left motor (counter-clockwise).
  * `mrr` — should rotate rear right motor (clockwise).
+* **Check the propeller directions are correct**. Make sure your propeller types (A or B) are installed as on the picture:
+  <img src="img/user/peter_ukhov-2/1.jpg" width="200">
 * **Check the remote control**. Using `rc` command, check the control values reflect your sticks movement. All the controls should change between -1 and 1, and throttle between 0 and 1.
 * If using SBUS receiver, **calibrate the RC**. Type `cr` command in Serial Monitor and follow the instructions.
 * **Check the IMU output using QGroundControl**. Connect to the drone using QGroundControl on your computer. Go to the *Analyze* tab, *MAVLINK Inspector*. Plot the data from the `SCALED_IMU` message. The gyroscope and accelerometer data should change according to the drone movement.
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -1,130 +1,36 @@
 # Usage: build, setup and flight

-To use Flix, you need to build the firmware and upload it to the ESP32 board. For simulation, you need to build and run the simulator.
+To fly Flix quadcopter, you need to build the firmware, upload it to the ESP32 board, and set up the drone for flight.

-For the start, clone the repository using git:
+To get the firmware sources, clone the repository using git:

 ```bash
-git clone https://github.com/okalachev/flix.git
-cd flix
+git clone https://github.com/okalachev/flix.git && cd flix
 ```

-## Simulation
+Beginners can [download the source code as a ZIP archive](https://github.com/okalachev/flix/archive/refs/heads/master.zip).

-### Ubuntu
+## Building the firmware

-The latest version of Ubuntu supported by Gazebo 11 simulator is 20.04. If you have a newer version, consider using a virtual machine.
-
-1. Install Arduino CLI:
-
-   ```bash
-   curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/.local/bin sh
-   ```
-
-2. Install Gazebo 11:
-
-   ```bash
-   sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list'
-   wget https://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add -
-   sudo apt-get update
-   sudo apt-get install -y gazebo11 libgazebo11-dev
-   ```
-
-   Set up your Gazebo environment variables:
-
-   ```bash
-   echo "source /usr/share/gazebo/setup.sh" >> ~/.bashrc
-   source ~/.bashrc
-   ```
-
-3. Install SDL2 and other dependencies:
-
-   ```bash
-   sudo apt-get update && sudo apt-get install build-essential libsdl2-dev
-   ```
-
-4. Add your user to the `input` group to enable joystick support (you need to re-login after this command):
-
-   ```bash
-   sudo usermod -a -G input $USER
-   ```
-
-5. Run the simulation:
-
-   ```bash
-   make simulator
-   ```
-
-### macOS
-
-1. Install Homebrew package manager, if you don't have it installed:
-
-   ```bash
-   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-   ```
-
-2. Install Arduino CLI, Gazebo 11 and SDL2:
-
-   ```bash
-   brew tap osrf/simulation
-   brew install arduino-cli
-   brew install gazebo11
-   brew install sdl2
-   ```
-
-   Set up your Gazebo environment variables:
-
-   ```bash
-   echo "source /opt/homebrew/share/gazebo/setup.sh" >> ~/.zshrc
-   source ~/.zshrc
-   ```
-
-3. Run the simulation:
-
-   ```bash
-   make simulator
-   ```
-
-### Setup
-
-#### Control with smartphone
-
-1. Install [QGroundControl mobile app](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html#android) on your smartphone. For **iOS**, use [QGroundControl build from TAJISOFT](https://apps.apple.com/ru/app/qgc-from-tajisoft/id1618653051).
-2. Connect your smartphone to the same Wi-Fi network as the machine running the simulator.
-3. If you're using a virtual machine, make sure that its network is set to the **bridged** mode with Wi-Fi adapter selected.
-4. Run the simulation.
-5. Open QGroundControl app. It should connect and begin showing the virtual drone's telemetry automatically.
-6. Go to the settings and enable *Virtual Joystick*. *Auto-Center Throttle* setting **should be disabled**.
-7. Use the virtual joystick to fly the drone!
-
-#### Control with USB remote control
-
-1. Connect your USB remote control to the machine running the simulator.
-2. Run the simulation.
-3. Calibrate the RC using `cr` command in the command line interface.
-4. Run the simulation again.
-5. Use the USB remote control to fly the drone!
-
-## Firmware
+You can build and upload the firmware using either **Arduino IDE** (easier for beginners) or a **command line**.

 ### Arduino IDE (Windows, Linux, macOS)

 1. Install [Arduino IDE](https://www.arduino.cc/en/software) (version 2 is recommended).
-2. Windows users might need to install [USB to UART bridge driver from Silicon Labs](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers).
+2. *Windows users might need to install [USB to UART bridge driver from Silicon Labs](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers).*
 3. Install ESP32 core, version 3.2.0. See the [official Espressif's instructions](https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html#installing-using-arduino-ide) on installing ESP32 Core in Arduino IDE.
 4. Install the following libraries using [Library Manager](https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-installing-a-library):
   * `FlixPeriph`, the latest version.
   * `MAVLink`, version 2.0.16.
-5. Clone the project using git or [download the source code as a ZIP archive](https://codeload.github.com/okalachev/flix/zip/refs/heads/master).
-6. Open the downloaded Arduino sketch `flix/flix.ino` in Arduino IDE.
-7. Connect your ESP32 board to the computer and choose correct board type in Arduino IDE (*WEMOS D1 MINI ESP32* for ESP32 Mini) and the port.
-8. [Build and upload](https://docs.arduino.cc/software/ide-v2/tutorials/getting-started/ide-v2-uploading-a-sketch) the firmware using Arduino IDE.
+5. Open the `flix/flix.ino` sketch from downloaded firmware sources in Arduino IDE.
+6. Connect your ESP32 board to the computer and choose correct board type in Arduino IDE (*WEMOS D1 MINI ESP32* for ESP32 Mini) and the port.
+7. [Build and upload](https://docs.arduino.cc/software/ide-v2/tutorials/getting-started/ide-v2-uploading-a-sketch) the firmware using Arduino IDE.

 ### Command line (Windows, Linux, macOS)

 1. [Install Arduino CLI](https://arduino.github.io/arduino-cli/installation/).

-   On Linux, use:
+   On Linux, install it like this:

   ```bash
   curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR=~/.local/bin sh
@@ -149,19 +55,84 @@ The latest version of Ubuntu supported by Gazebo 11 simulator is 20.04. If you h
   make upload monitor
   ```

-See other available Make commands in the [Makefile](../Makefile).
+See other available Make commands in [Makefile](../Makefile).

 > [!TIP]
-> You can test the firmware on a bare ESP32 board without connecting IMU and other peripherals. The Wi-Fi network `flix` should appear and all the basic functionality including CLI and QGroundControl connection should work.
+> You can test the firmware on a bare ESP32 board without connecting IMU and other peripherals. The Wi-Fi network `flix` should appear and all the basic functionality including console and QGroundControl connection should work.

-### Setup
+## Before first flight
+
+### Choose the IMU model
+
+In case if using different IMU model than MPU9250, change `imu` variable declaration in the `imu.ino`:
+
+```cpp
+ICM20948 imu(SPI);  // For ICM-20948
+MPU6050 imu(Wire);  // For MPU-6050
+```
+
+### Setup the IMU orientation
+
+The IMU orientation is defined in `rotateIMU` function in the `imu.ino` file. Change it so it converts the IMU axes to the drone's axes correctly. **Drone axes are X forward, Y left, Z up.**
+
+See various [IMU axes orientations table](https://github.com/okalachev/flixperiph/?tab=readme-ov-file#imu-axes-orientation) to help you set up the correct orientation.
+
+### Connect using QGroundControl
+
+QGroundControl is a ground control station software that can be used to monitor and control the drone.
+
+1. Install mobile or desktop version of [QGroundControl](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html).
+2. Power up the drone.
+3. Connect your computer or smartphone to the appeared `flix` Wi-Fi network (password: `flixwifi`).
+4. Launch QGroundControl app. It should connect and begin showing the drone's telemetry automatically
+
+### Access console
+
+The console is a command line interface (CLI) that allows to interact with the drone, change parameters, and perform various actions. There are two ways of accessing the console: using **serial port** or using **QGroundControl (wirelessly)**.
+
+To access the console using serial port:
+
+1. Connect the ESP32 board to the computer using USB cable.
+2. Open Serial Monitor in Arduino IDE (or use `make monitor` command in the command line).
+3. In Arduino IDE, make sure the baudrate is set to 115200.
+
+To access the console wirelessly using QGroundControl:
+
+1. Connect to the drone using QGroundControl app.
+2. Go to the QGroundControl menu ⇒ *Vehicle Setup* ⇒ *Analyze Tools* ⇒ *MAVLink Console*.
+   <img src="img/cli.png" width="400">
+
+Use `help` command to see the list of available commands.
+
+### Calibrate accelerometer

 Before flight you need to calibrate the accelerometer:

-1. Open Serial Monitor in Arduino IDE (or use `make monitor` command in the command line).
+1. Access the console using QGroundControl (more convenient) or Serial Monitor.
 2. Type `ca` command there and follow the instructions.

-#### Control with smartphone
+### Check everything works
+
+1. Check the IMU is working: perform `imu` command and check its output:
+   * The `status` field should be `OK`.
+   * The `rate` field should be about 1000 (Hz).
+   * The `accel` and `gyro` fields should change as you move the drone.
+
+2. Check the attitude estimation: connect to the drone using QGroundControl, rotate the drone in different orientations and check if the attitude estimation shown in QGroundControl is correct. Attitude indicator in QGroundControl is shown below:
+
+   <img src="img/qgc-attitude.png" height="200">
+
+3. Perform motor tests in the console. **Remove the propellers before this!** Use the following commands:
+   * `mfr` — should rotate front right motor (counter-clockwise).
+   * `mfl` — should rotate front left motor (clockwise).
+   * `mrl` — should rotate rear left motor (counter-clockwise).
+   * `mrr` — should rotate rear right motor (clockwise).
+
+## Setup remote control
+
+There are several ways to control the drone's flight: using **smartphone** (Wi-Fi), using **standard radio remote control**, or using **USB remote control** (Wi-Fi).
+
+### Control with smartphone

 1. Install [QGroundControl mobile app](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html#android) on your smartphone.
 2. Power the drone using the battery.
@@ -173,7 +144,7 @@ Before flight you need to calibrate the accelerometer:
 > [!TIP]
 > Decrease `TILT_MAX` parameter when flying using the smartphone to make the controls less sensitive.

-#### Control with remote control
+### Control with remote control

 Before flight using remote control, you need to calibrate it:

@@ -181,7 +152,7 @@ Before flight using remote control, you need to calibrate it:
 2. Type `cr` command there and follow the instructions.
 3. Use the remote control to fly the drone!

-#### Control with USB remote control (Wi-Fi)
+### Control with USB remote control

 If your drone doesn't have RC receiver installed, you can use USB remote control and QGroundControl app to fly it.

@@ -193,9 +164,6 @@ If your drone doesn't have RC receiver installed, you can use USB remote control
 6. Go the the QGroundControl menu ⇒ *Vehicle Setup* ⇒ *Joystick*. Calibrate you USB remote control there.
 7. Use the USB remote control to fly the drone!

-> [!NOTE]
-> If something goes wrong, go to the [Troubleshooting](troubleshooting.md) article.
-
 ## Flight

 For both virtual sticks and a physical joystick, the default control scheme is left stick for throttle and yaw and right stick for pitch and roll:
@@ -214,6 +182,9 @@ When finished flying, **disarm** the drone, moving the left stick to the bottom

 <img src="img/disarming.svg" width="150">

+> [!NOTE]
+> If something goes wrong, go to the [Troubleshooting](troubleshooting.md) article.
+
 ### Flight modes

 Flight mode is changed using mode switch on the remote control or using the command line.
@@ -241,12 +212,6 @@ If the pilot moves the control sticks, the drone will switch back to *STAB* mode

 ## Adjusting parameters

-You can adjust some of the drone's parameters (include PID coefficients) in QGroundControl app. In order to do that, go to the QGroundControl menu ⇒ *Vehicle Setup* ⇒ *Parameters*.
+You can adjust some of the drone's parameters (include PID coefficients) in QGroundControl. In order to do that, go to the QGroundControl menu ⇒ *Vehicle Setup* ⇒ *Parameters*.

 <img src="img/parameters.png" width="400">
-
-## CLI access
-
-In addition to accessing the drone's command line interface (CLI) using the serial port, you can also access it with QGroundControl using Wi-Fi connection. To do that, go to the QGroundControl menu ⇒ *Vehicle Setup* ⇒ *Analyze Tools* ⇒ *MAVLink Console*.
-
-<img src="img/cli.png" width="400">