diff --git a/README.md b/README.md index ef07d2f..8933fab 100644 --- a/README.md +++ b/README.md @@ -54,15 +54,17 @@ The simulator is implemented using Gazebo and runs the original Arduino code: ## Documentation -* [Assembly instructions](docs/assembly.md). -* [Usage: build, setup and flight](docs/usage.md). -* [Troubleshooting](docs/troubleshooting.md). -* [Simulation](gazebo/README.md). -* [Firmware architectural overview](docs/firmware.md). -* [Python library](tools/pyflix/README.md). -* [Log analysis](docs/log.md). +1. [Assembly instructions](docs/assembly.md). +2. [Usage: build, setup and flight](docs/usage.md). +3. [Simulation](gazebo/README.md). +4. [Python library](tools/pyflix/README.md). + +Additional articles: + * [User builds gallery](docs/user.md). -* [Version 0 (obsolete)](docs/version0.md). +* [Firmware architectural overview](docs/firmware.md). +* [Troubleshooting](docs/troubleshooting.md). +* [Log analysis](docs/log.md). ## Components @@ -80,9 +82,9 @@ The simulator is implemented using Gazebo and runs the original Arduino code: |Li-Po Battery charger|Any||1| |Screws for IMU board mounting|M3x5||2| |Screws for frame assembly|M1.4x5||4| -|Frame main part|3D printed²:
[`flix-frame-1.1.stl`](docs/assets/flix-frame-1.1.stl) [`flix-frame-1.1.step`](docs/assets/flix-frame-1.1.step)
Recommended settings: layer 0.2 mm, line 0.4 mm, infill 100%.||1| -|Frame top part|3D printed:
[`esp32-holder.stl`](docs/assets/esp32-holder.stl) [`esp32-holder.step`](docs/assets/esp32-holder.step)||1| -|Washer for IMU board mounting|3D printed:
[`washer-m3.stl`](docs/assets/washer-m3.stl) [`washer-m3.step`](docs/assets/washer-m3.step)||2| +|Frame main part|3D printed²: [`stl`](docs/assets/flix-frame-1.1.stl) [`step`](docs/assets/flix-frame-1.1.step)
Recommended settings: layer 0.2 mm, line 0.4 mm, infill 100%.||1| +|Frame top part|3D printed: [`stl`](docs/assets/esp32-holder.stl) [`step`](docs/assets/esp32-holder.step)||1| +|Washer for IMU board mounting|3D printed: [`stl`](docs/assets/washer-m3.stl) [`step`](docs/assets/washer-m3.step)||2| |Controller (recommended)|CC2500 transmitter, like BetaFPV LiteRadio CC2500 (RC receiver/Wi-Fi).
Two-sticks gamepad (Wi-Fi only) — see [recommended gamepads](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/setup_view/joystick.html#supported-joysticks).
Other⁵||1| |*RC receiver (optional)*|*DF500 or other³*||1| |Wires|28 AWG recommended||| @@ -116,8 +118,6 @@ Motor connection scheme: You can see a user-contributed [variant of complete circuit diagram](https://miro.com/app/board/uXjVN-dTjoo=/?moveToWidget=3458764612338222067&cot=14) of the drone. -See [assembly guide](docs/assembly.md) for instructions on assembling the drone. - ### Notes * Power ESP32 Mini with Li-Po battery using VCC (+) and GND (-) pins. @@ -151,9 +151,9 @@ See [assembly guide](docs/assembly.md) for instructions on assembling the drone. |-|-| |GND|GND| |VIN|VCC (or 3.3V depending on the receiver)| - |Signal (TX)|GPIO4⁶| + |Signal (TX)|GPIO4¹| -*⁶ — UART2 RX pin was [changed](https://docs.espressif.com/projects/arduino-esp32/en/latest/migration_guides/2.x_to_3.0.html#id14) to GPIO4 in Arduino ESP32 core 3.0.* +*¹ — UART2 RX pin was [changed](https://docs.espressif.com/projects/arduino-esp32/en/latest/migration_guides/2.x_to_3.0.html#id14) to GPIO4 in Arduino ESP32 core 3.0.* ## Resources diff --git a/docs/img/arduino-ide.png b/docs/img/arduino-ide.png new file mode 100644 index 0000000..24eb6e3 Binary files /dev/null and b/docs/img/arduino-ide.png differ diff --git a/docs/img/drone-axes-rotate.svg b/docs/img/drone-axes-rotate.svg new file mode 100644 index 0000000..05a66e4 --- /dev/null +++ b/docs/img/drone-axes-rotate.svg @@ -0,0 +1,136 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + y/left + z/up + x/forward + + + + + + + + + + + + + + + + + + + + diff --git a/docs/img/drone-axes.svg b/docs/img/drone-axes.svg new file mode 100644 index 0000000..716ad66 --- /dev/null +++ b/docs/img/drone-axes.svg @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + y/left + z/up + x/forward + + diff --git a/docs/img/mosfet-connection.png b/docs/img/mosfet-connection.png index 28e088c..3c432b6 100644 Binary files a/docs/img/mosfet-connection.png and b/docs/img/mosfet-connection.png differ diff --git a/docs/img/motors.svg b/docs/img/motors.svg index 949736f..a89f419 100644 --- a/docs/img/motors.svg +++ b/docs/img/motors.svg @@ -1,4 +1,4 @@ - + - - - - - - - + + + + + - + - - + + - - + + + 3 + 2 + prop A + prop B + - - + + + 1 + prop A + - - + + - 3 - 0 - 1 - 2 - prop A - prop A - prop B - prop B + 0 + prop B diff --git a/docs/usage.md b/docs/usage.md index 437cc37..6fee791 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -16,6 +16,8 @@ You can build and upload the firmware using either **Arduino IDE** (easier for b ### Arduino IDE (Windows, Linux, macOS) +Flix firmware open in Arduino IDE + 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).* 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. @@ -73,9 +75,11 @@ 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.** +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. + + +See various [IMU boards 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 @@ -93,44 +97,51 @@ The console is a command line interface (CLI) that allows to interact with the d 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). +2. Open Serial Monitor in Arduino IDE (or use `make monitor` in the command line). 3. In Arduino IDE, make sure the baudrate is set to 115200. -To access the console wirelessly using QGroundControl: +To access the console using QGroundControl: 1. Connect to the drone using QGroundControl app. 2. Go to the QGroundControl menu ⇒ *Vehicle Setup* ⇒ *Analyze Tools* ⇒ *MAVLink Console*. -Use `help` command to see the list of available commands. +> [!TIP] +> Use `help` command to see the list of available commands. ### Calibrate accelerometer Before flight you need to calibrate the accelerometer: -1. Access the console using QGroundControl (more convenient) or Serial Monitor. +1. Access the console using QGroundControl (recommended) or Serial Monitor. 2. Type `ca` command there and follow the instructions. ### 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. + * The `landed` field should be `1` when the drone is still on the ground and `0` when you lift it up. 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: -3. Perform motor tests in the console. **Remove the propellers before this!** Use the following commands: +3. Perform motor tests in the console. Use the following commands **— remove the propellers before running the tests!** + * `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). +> [!WARNING] +> Never run the motors when powering the drone from USB, always use the battery for that. + ## 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). +There are several ways to control the drone's flight: using **smartphone** (Wi-Fi), using **SBUS remote control**, or using **USB remote control** (Wi-Fi). ### Control with smartphone @@ -146,10 +157,10 @@ There are several ways to control the drone's flight: using **smartphone** (Wi-F ### Control with remote control -Before flight using remote control, you need to calibrate it: +Before using remote SBUS-connected remote control, you need to calibrate it: -1. Open Serial Monitor in Arduino IDE (or use `make monitor` command in the command line). -2. Type `cr` command there and follow the instructions. +1. Access the console using QGroundControl (recommended) or Serial Monitor. +2. Type `cr` command and follow the instructions. 3. Use the remote control to fly the drone! ### Control with USB remote control diff --git a/docs/version0.md b/docs/version0.md index d8dd9c4..d2e43d1 100644 --- a/docs/version0.md +++ b/docs/version0.md @@ -14,7 +14,7 @@ Flix version 0 (obsolete): |Motor|8520 3.7V brushed motor (**shaft 0.8mm!**)||4| |Propeller|Hubsan 55 mm||4| |Motor ESC|2.7A 1S Dual Way Micro Brush ESC||4| -|RC transmitter|KINGKONG TINY X8||1| +|RC transmitter|KINGKONG TINY X8||1| |RC receiver|DF500 (SBUS)||1| |~~SBUS inverter~~*|||~~1~~| |Battery|3.7 Li-Po 850 MaH 60C||| diff --git a/gazebo/README.md b/gazebo/README.md index bce4980..eebc27b 100644 --- a/gazebo/README.md +++ b/gazebo/README.md @@ -4,7 +4,7 @@ The Flix drone simulator is based on Gazebo 11 and runs the firmware code in vir Gazebo 11 works on **Ubuntu 20.04** and used to work on macOS. However, on the recent macOS versions it seems to be broken, so Ubuntu 20.04 is recommended. -Flix simulator +Flix simulator running on macOS ## Installation diff --git a/tools/pyflix/README.md b/tools/pyflix/README.md index 47d5633..c10c00f 100644 --- a/tools/pyflix/README.md +++ b/tools/pyflix/README.md @@ -46,8 +46,11 @@ print(flix.acc) # accelerometer output (list) print(flix.gyro) # gyroscope output (list) ``` -> [!NOTE] -> The library uses the Front-Left-Up coordinate system — the same as in the firmware. All angles are in radians. +The library uses the Front-Left-Up coordinate system — the same as the firmware: + + + +All angles are in radians. ### Events @@ -107,7 +110,7 @@ Full list of events: |`value.`|Specific named value update (see bellow)|Value| > [!NOTE] -> Update events trigger on every new data from the drone, and do not mean the value is changed. +> Update events trigger on every new data from the drone, and do not mean the value has changed. ### Common methods @@ -118,7 +121,7 @@ pitch_p = flix.get_param('PITCH_P') # get parameter value flix.set_param('PITCH_P', 5) # set parameter value ``` -Execute CLI commands using `cli` method. This method returns command response: +Execute console commands using `cli` method. This method returns command response: ```python imu = flix.cli('imu') # get detailed IMU data @@ -136,7 +139,7 @@ flix.set_armed(True) # arm the drone flix.set_armed(False) # disarm the drone ``` -You can imitate pilot's controls using `set_controls` method: +You can pass pilot's controls using `set_controls` method: ```python flix.set_controls(roll=0, pitch=0, yaw=0, throttle=0.6)