YAMSPy

Yet Another Implementation of Multiwii Serial Protocol Python Interface for Betaflight, iNAV, etc.

SAFETY FIRST!

This work is EXPERIMENTAL and it has been made publicly available expecting to be used only by responsible legally capable adults, etc, etc, etc. Since it's experimental, crazy things may happen mid-flight or even after the drone has landed or, even worse, while the drone is sitting on the floor! Drones, by default, can be VERY dangerous if not handled properly. Here are some links that may help you understand what I mean:

Disclaimer (adapted from Wikipedia): None of the authors, contributors, supervisors administrators, employers, friends, family, vandals, or anyone else connected (or not) with this project, in any way whatsoever, can be made responsible for the use of the information (code) contained or linked from here.

Installation (Python3 because you should not use Python2 anymore):

Option #1: Clone the repo so you will have the examples

$ git clone https://github.com/ricardodeazambuja/YAMSPy.git
$ cd YAMSPy
$ sudo pip3 install .

Option #2: Install directly from git (the --upgrade is to make sure it will install the last commit, even if the version number didn't increase)

$ sudo pip3 install git+https://github.com/ricardodeazambuja/yamspy --upgrade

On Linux you may need to add your user to the dialout group:

$ sudo usermod -a -G dialout $USER

Examples:

The directory Examples (duh!) has some commented examples showing how to use the library.

Setting up your flight controller (FC):

Until this point you should have installed YAMSPy, but it will not magically work without some extra steps. In order to make it work, you need to set up your FC correctly.

If you are just starting with iNAV or Betaflight you will need to install one of the configurators: inav-configurator or betaflight-configurator.

How to check which firmware is installed in your flight controller

In general, the most popular flight controllers (so far I have tested Heli-nation Talon F7 Fusion and Kakute F7 mini with success) come with some version of Betaflight and if you try to use inav-configurator it will only show the CLI (Command Line Interface) tab. The other way around, iNAV installed and betaflight-configurator, it will still allow you to use the CLI. The good thing is that using the CLI you can enter DFU (Device Firmware Update) mode to reflash the firmware by simply typing dfu if iNAV firmware or bl or dfu if Betaflight. I noticed that my flight controlllers would only enter DFU mode if they were powered exclusivelly by the USB. To flash (install) a new firmware you can follow the instructions for Betaflight or iNAV. BTW, once you are using the CLI mode you can just type status to receive a lot of useful info like firmware version.

More details about how YAMSPy works

YAMSPy was designed to communicate with or control a flight controller from a Single Board Computer (SBC) like a Raspberry Pi as well as a normal PC. It works by communicating with the flight controller through a serial connection using MSP (MultiWii Serial Protocol). Therefore, you need to have a free UART (Universal asynchronous receiver-transmitter, commonly just called "serial") that has MSP enabled on it. By default (AFAIK), the micro USB connector located on the flight controller will be seen as an UART and it comes configured as MSP, so it should allow you to use YAMSPy out of the box. You can easily enable MSP on other UART using the configurator software (see "Ports" tab).

Ok, the paragraph above covers the basics, but to be able to use YAMSPy to control your drone it is necessary to configure the flight controller to use a receiver that talks MSP. This is easily done using one of the configurators mentioned above. Connect to your flight controller using the configurator (inav or betaflight) and enter the "Configuration" tab. Inside this tab there's a field somewhere called "Receiver" or "Receiver Mode". Click on the pull-down list and select "MSP RX (control via MSP port)". After any changes you always need to click on the "Save and Reboot". When the FC reboots it will be expecting to receive commands from one of the UARTs with MSP enabled, but that is NOT all. You still need to make sure your receiver is configured to use the correct channel map. AETR (Aileron, Elevator, Throttle and Rudder) is the default for YAMSPy and all RC commands will be expected to start with Roll, Pitch, Throttle and Yaw, exactly in this order. Additionally, the auxiliary channels will come just after Yaw following their own numbering (Aux1, Aux2... for Betaflight or CH5, CH6... for iNAV).

Finally, I would strongly suggest you to set, at least, a channel exclusivelly for arming / disarming the drone instead of using stick commands. This can be done using the configurator and the "Modes" tab.

Advanced stuff

CLI

There are two possible ways to change the settings: using the configurator app (inav-configurator / betaflight-configurator) or using the CLI (Command Line Interface). The configurators are very handy, but the CLI allows you to automate stuff and save the settings in an easy to read text file.

Flight controllers using Betaflight or iNAV will allow you to connect to its CLI using the default MSP enabled port (normally the one with a micro USB connector) and a simple terminal emulator like PuTTy (on Linux you have many options, but PuTTy is super easy to install on Ubuntu) and setting the baud-rate to 115200 (the default value). After connecting it is necessary to type # to start the CLI mode. The FC will NOT exit CLI mode if you disconnect your terminal session, what can be useful sometimes.

If you feel adventurous, you can try to connect using linux screen.

$ screen /dev/ttyACM0 115200

Maybe the serial port is not the ttyACM0 for you (e.g. ttyS0). You can confirm using something like dmesg | grep tty.

Screen can be as annoying as VIM sometimes, so my commands:

ctrl+a and then \ to exit.
ctrl+a and the ESC key to move around using the arrow keys (to stop this behaviour just press the ESC key again.
ctrl+a, then : and finally H to save everything printed on the screen after that point.

Forward data

It's possible to use socat to connect the local serial port, where the flight controller is physically wired, to another computer through the network. This allows the user to use a GUI (e.g. inav-configurator) from distance (e.g. wifi). Detailed instructions can be found in our inav-configurator fork.

Troubleshooting

If you can't connect (talk) to the FC:

Check if you enabled MSP in the correct UART using inav-configurator (or betaflight-configurator)
Make sure you connected the cables correctly: TX => RX and RX => TX
Verify the devices available using ls -lh /dev/serial* and change it in the Python script if needed.

Stargazers over time

TODO:

Currently the main library is made of a HUGE single file. That is just terrible, but I didn't have time to split it and test. So if you want to help, please, be my guest. Talking about testing, I haven't implemented any automated test besides the example files, again, be my guest ;)

Acknowledgments:

Many people from MISTLab helped during the development of this library. Special thanks goes to Tom and Yann.

This work was possible thanks to the financial support from IVADO.ca (postdoctoral scholarship 2019/2020).

thecognifly / YAMSPy

readme