voxl-elrs

Overview

voxl-elrs source code ExpressLRS Project Page

What is ExpressLRS?

ExpressLRS (ELRS) aims to provide the best completely open, high refresh radio control link while maintaining a maximum achievable range at that rate with low latency. Vast support of hardware in both 900 MHz and 2.4 GHz frequencies using the crossfire protocol.

What is voxl-elrs?

voxl-elrs is an application introduced in VOXL SDK 1.0.0 which gives a user the ability to flash a receiver or transmitter, put a receiver into bind mode, and get device information from a receiver.

There is a large array of ELRS compatible receivers and transmitters on the market and we haven’t tested them all, but below is a list of some that we know voxl-elrs supports.

In theory, voxl-elrs supports any receiver that is compatible with ELRS, however some functionalities such as setting a receiver into bind mode or assigning pwm channels depends on ModalAI firmware modifications. Here is a list of currently supported receivers and transmitters:

Installation

voxl-elrs can be installed on the VOXL platform or on any Debian distribution with access to the ModalAI package repository.

voxl2:/$ sudo apt install voxl-elrs

Binding Procedure

Note: Ensure that voxl-elrs version is 0.0.8+ and that both the receiver and transmitter are on ELRS version 3.0.0+!

Usage

Currently, voxl-elrs does not require any configuration in order to get started. Usage is as follows:

voxl2:/$ voxl-elrs -h
Description: Flash a RX or TX with ELRS firmware.

usage: voxl-elrs [-h] [-d DEVICE] [-w] [-q] [-b] [-B] [-u] [-l] [-v] [-s] [-p SETID] [-n] [command ...]

positional arguments:
  command               Command to run (optional) [help, bind, unbind, update, info, setid, configure]

options:
  -h, --help            Show this help message and exit
  -d DEVICE, --device DEVICE
                        Serial port
  -w, --wizard          Activate interactive wizard
  -q, --quiet           Quiet mode, don't print debug msgs
  -b, --bind            Put receiver into bind mode
  -B, --betaflight      Put betaflight flight controller into passthrough mode
  -u, --unbind          Unbind a bound transmitter
  -l, --bootloader      Put receiver into bootloader mode
  -v, --version         Get receiver version info
  -s, --scan            Scan current firmware and update if <=3.2.1
  -p SETID, --setid SETID
                        Sets the binding phrase of a connected receiver
  -n, --noscan          Disables auto-detection of the connected receiver

If you run voxl-elrs without any commands (or flags which are aliases for commands such as “–bind”) the wizard will start automatically and attempt to auto-detect a connected receiver.

Wiring Guide

BetaFPV Nano RX

FrSky R9MM/Mini-OTA

Manually flashing a receiver

• In order to manually flash an ELRS receiver, make sure that the receiver is not in bootloader mode and that it is not connected to a transmitter. These conditions are necessary so we can get device information from the receiver.

• On host computer adb shell onto the voxl2 or ssh:

adb shell
OR
ssh root@<voxl2 ip> 

Note: The default ssh password is oelinux123

• Now, on the voxl2 use the voxl-elrs wizard and select the “Flash Receiver” option:

voxl2:/$ voxl-elrs -w
Please choose an option below

==============================

 1.	Bind Receiver
 2.	Unbind Receiver
 3.	Set Receiver ID
 4.	Modify PWM Settings
 5.	Restart Receiver
 6.	Recover Receiver
 7.	Flash Receiver
 8.	Flash Transmitter
 9.	Start Configuration Wizard
> 7

• Choose auto-update if you want to use the latest version and the wizard auto-detected your receiver in the first step.

• Otherwise, manually choose your receiver and firmware version for the first installation.

Please choose an option below

==============================

 1.	Auto-Update
 2.	Choose Version

 0.	Back
> 2

• Select which firmware binary to flash:

Select the firmware to flash:

 1.	ModalAI : M0193 | ELRS v3.5.3.3 | Local: True
 2.	ModalAI : M0184 | ELRS v3.5.3.3 | Local: True
 3.	betafpv : BETAFPV 900MHz RX | ELRS v3.2.1.2 | Local: True
 4.	frsky : FrSky R9 Mini | ELRS v3.3.2.1 | Local: True
 5.	ModalAI : M0184 | ELRS v3.3.2.1 | Local: True
 6.	ModalAI : M0184 | ELRS v3.5.3.2 | Local: True

 0.	Back
> 2

• The receiver you selected will now be flashed with the latest firmware!

Recovering a bricked receiver

• Manually place the receiver into bootloader mode by holding down the boot button while power cycling the receiver.
  
• On host computer adb shell onto the voxl2 or ssh:

adb shell
OR
ssh root@<voxl2 ip> 

• Now, on the voxl2 use the voxl-elrs wizard and select the “Recover Receiver” option:

voxl2:/$ voxl-elrs -w
Please choose an option below

==============================

 1.	Bind Receiver
 2.	Unbind Receiver
 3.	Set Receiver ID
 4.	Modify PWM Settings
 5.	Restart Receiver
 6.	Recover Receiver
 7.	Flash Receiver
 8.	Flash Transmitter
 9.	Start Configuration Wizard
> 6

• This only works for ESP-32 and ESP-8266 based receivers, please confirm that your receiver meets these criteria:

Receiver recovery is only for ESP-based receivers which are unable to be flashed normally.
This will wipe all data from your receiver before prompting you to flash new software.
Enter 'y' to confirm.
> y

• Follow the instructions given and if the recovery is successful you should see an output like the image below
  

• If the recovery process fails, double check that the receiver is actually in bootloader mode. Make sure that you hold the bootloader button down for a couple seconds after power cycling the receiver.

PWM Configuration

PWM Capable Receivers

The R9MM/Mini-OTA is used as an example of enabling PWM on an STM32 based ELRS receiver (there is no native ELRS support for PWM on STM32 based receivers in ELRS firmware version 3.2.1.X). This receiver is supported by voxl-elrs but not necessarily sold by ModalAI.

FrSky R9MM/Mini-OTA PWM outputs

Setting up PWM Channels

In the voxl-elrs wizard, there is an option to Modify PWM Settings. After choosing this option, the following prompt appears:

Please choose an option below

==============================

 1.	Set PWM Value
 2.	Set PWM Channel Mapping

 0.	Back
> 2

To set up PWM channels, choose option 2. The next option will prompt you for the pin to set on your receiver. The pins are numbered from 0 to 3 on receivers with 4 PWM pins.

Set the PWM parameters:
Pin to set (0-3) > 0

Then it will prompt you for the input channel from the transmitter. The channels are numbered from 1 to 255 (though no transmitters actually send that many channels, the number of available channels depends on your handset and ELRS configuration).

Set the PWM parameters:
Pin to set (0-3) > 0
Input Channel (1-255) > 7

It will then take you back to the previous screen so you can continue assigning all of the pins.

Binding phrase

The menu item Set Receiver ID can be used to set a unique binding phrase for the connected receiver. After selecting that option, you will see the following prompt:

Enter the binding phrase or press enter to cancel
> 

Press enter after entering your binding phrase and it will assign that phrase to your receiver.

Manage ELRS from Ubuntu host

As noted in the Installation section, voxl-elrs can be installed on any Debian/Ubuntu machine. By default it will attempt to use the serial port /dev/ttyUSB0. If your receiver is connected to a different port, use the optional flag -d {port} to specify it. Otherwise, voxl-elrs on Ubuntu will perform identically to voxl-elrs on a Voxl.

Betaflight Passthrough

For receivers connected to a Betaflight flight controller, voxl-elrs can still be used to manage the receiver through the use of Betaflight passthrough. The flag -B or --betaflight will attept to setup betaflight passthrough on the port specified with -d. In order for this to be successful, the betaflight configurator tool must be disconnected from the flight controller. The passthrough setup will persist until the flight controller is power cycled, so subsequent calls to voxl-elrs do not need the -B flag, though it is still recommended in case the flight controller reboots.

Configuration Wizard

To make managing a fleet of voxl-connected ELRS receivers easier, the voxl-elrs configuration wizard can be used to declare the desired firmware version, PWM mappings, and binding phrase of the connected receiver and apply these settings all at once. The configuration wizard provides an interface for editing the file /etc/modalai/voxl-elrs.conf, which can be manually edited and copied across devices.

Configuration Fields

PWM

The PWM pins can be mapped to channels or disabled in the configuration menu.

Set all values below:

 1.	PWM 0 : Enabled, Ch 7, Mode Default, Failsafe 50
 2.	PWM 1 : Enabled, Ch 8, Mode Default, Failsafe 50
 3.	PWM 2 : Enabled, Ch 9, Mode Default, Failsafe 50
 4.	PWM 3 : Disabled

 0.	Back
> 

Binding Phrase

A binding phrase can be specified or left empty if traditional binding is preferred.

Receiver Model

A configuration can also specify the receiver type. If the receiver specified in this field isn’t detected when uploading a configuration, the configuration procedure will fail.

Multiple Configurations

Multiple configurations can exist in this file, but the one marked as “default” is the one which will be uploaded when running voxl-elrs configure.

Applying the default configuration

A quick command is available to apply the selected default configuration voxl-elrs configure will ensure that your receiver firmware, PWM, and binding phrase match your configured values.

Setting up the systemd service

To keep a fleet of ELRS receivers up to date and configured correctly, a systemd service script is included in voxl-elrs which will automatically run voxl-elrs configure on a system startup. This will keep your ELRS receivers up to date automatically (if configured to use the latest version), and ensure the correct binding phrase and PWM mappings are always set. Make sure not to enable this script if you make any manual changes to your receiver without changing the default configuration; otherwise, your changes will be overridden.

To enable the startup script, run the command systemctl enable voxl-elrs-startup.service.

Tips

• In order for a receiver and transmitter to bind, they need to be on the same major version of ELRS. For voxl-elrs, this means that both the transmitter and receiver need to be on ELRS version 3.0.0+.
• The recommended usage of this tool is to use the interactive wizard, by either using voxl-elrs -w or voxl-elrs --wizard and then following the prompt.
• If making your own custom modifications to the receiver firmware, be careful using the voxl-elrs --scan function. If voxl-elrs detects a firmware version that doesn’t match the latest for that version of voxl-elrs, it will overwrite the firmware you have currently loaded.
• You can determine the state of the receiver by inspecting the LED on your receiver and comparing to the information on the ELRS LED Status page.
• Useful information regarding all things ExpressLRS (ELRS) can be found on the ELRS quickstart page.

Table of contents

• M0184 Gemini 915MHz ELRS- ModalAI's M0184 Gemini 915MHz ELRS