search

mstrens / oXs_on_RP2040

version of openXsensor to be used on raspberry pi pico RP2040 (more protocols, more functionalities)
83 stars 22 forks source link

readme

openXsensor (oXs) on RP2040 board

For rc protocols : expressLRS / FRSKY (sport + Fbus) / HOTT / JETI Ex / JETI EXBUS/ MPX / FLYSKY / Futaba (SBUS2) / Spektrum (SRXL2)

This project can be interfaced with 1 or 2 ELRS, FRSKY , HOTT , MPX, FLYSKY , Futaba, Spektrum or Jeti receiver(s) (protocol has to be selected accordingly).

This project is foreseen to generate:

It can also provide up to 16 PWM RC channels to drive servos from a CRSF/ELRS or from 1 or 2 Sbus/Fbus/Exbus/Ibus/SRXL2 signal (e.g Frsky,Jeti,Flysky,Spektrum). The refresh rate can be set between 50Hz(default) and 333Hz.

It can also provide SBUS signal (e.g. from 1 or 2 ELRS receivers).

When connected to 2 receivers, the output signals (e.g. PWM or Sbus) will be issued from the last received Rc channels. So this provides a kind of redundancy/diversity.

It can stabilize the plane (gyro). This requires

- to use a mp6050 device
- to configure oXs in order to get Rc channels and to generate PWM signals for the servos controling the camera
- to get from the handset the "original" (not mixed) sticks positions in 3 additional RC channels
- to get from the handset the gyro mode and general gain in 1 additional RC channels

It can stabilize a camera. This requires

- to use a mp6050 device
- to configure oXs in order to get Rc channels and to generate PWM signals for the servos controling the camera
- to edit the camera parameters in the config.h file and to compile the edited project.

It can generates some sequences on servos or e.g. led. This requires to configure oXs in order to get Rc channels.

It can log data's on a SD card. This require to build also another module with another RP2040: see oXs_logger project

It can transmit some localisation data on a separate rf link to another module in order to retrieve a model that has been lost.

Each function (telemetry/PWM/SBUS/gyro/logger/sequencer/localisation) can be used alone or combined with the others.

Note: when a mpu6050 is used (to improve vario reactivity, stabilize the plane and/or a camera), it is important to calibrate the mp6050 horizontally and vertically (see section below)

------- Hardware -----------------

This project requires a board with a RP2040 processor (like the rapsberry pi pico).

A better alternative is the RP2040-Zero or the RP2040-TINY (both have the same processor but smaller board)

This board can be connected to:

About the SDP31, SDP32, SDP33 , SDP810: Those sensors are probably better than MS4525. They do not requires calibration (and reset) and are more accurate at low speed. Those sensors exists in 3 versions which differs by the maximum differential pressure (and so the max speed) they can measure SDP31 (or SDP810-500) can measure up to 500 Pa = 105 km/h SDP32 (or SDP810-125) can measure up to 125 Pa = 52 km/h SDP33 can measure up to 1500 Pa = 189 km/h The difference between SDP3x and SDP800 series is mainly the size of the sensor. SDP3x are very small (5mm) and require soldering on small pin SDP810 are bigger (25 mm) and have a 4 pin connector Currently oXs code is written for SDP3x serie but using a SDP810 requires only to change the I2C address in the config.h file.

--------- Wiring --------------------

FRSKY/ELRS/JETI/... receiver, MS5611, GPS and other sensors must share the same Gnd
Connect a 5V source to the Vcc pin of RP2040 board ( RP2040-zero or RP2040-TINY boards do not accept more than 5.5V on Vcc pin !! )
There is no default affectation of the RP2040 pins so user has to specify it with some parameters after flashing the firmware (see below)

Depending on the protocol, the pins used for PRIMARY/SECONDARY RC Channels and for Telemetry (TLM) varies protocol PRI pin is connectected to SEC pin is connected to TLM pin is connected to Comment
C(ELRS) (TX from Rx1) (TX from Rx2) (RX from RX1)
S(Frsky sport) (Sbus from Rx1) (Sbus from Rx2) (Sport from RX1 or Rx2) (1)
F(Frsky Fbus) Fbus from Rx1 (Sbus from Rx2) Not used (2)
J(Jeti ex) (Sbus from Rx1) (Sbus from Rx2) (Ex from Rx1 or Rx2)
E(Jeti Exbus) Exbus from Rx1 (Sbus from Rx2) Not used (2)
H(Hott) (Sbus from Rx1) (Sbus from Rx2) ???(tlm from RX1 or Rx2) (1)
M(Multiplex) (Sbus from Rx1) (Sbus from Rx2) ???(tlm from RX1 or Rx2) (1)
I(Flysky Ibus) (Sbus from Rx1) (Sbus from Rx2) ( Ibus from RX1 or Rx2) (1)
L(Spektrum Srxl2) Srxl from Rx1 Not used Not used (2)
2(Futaba Sbus2) Sbus2 from Rx1 (Sbus2 from Rx2) Sbus2 from Rx1 via 1Kohm (3)

Note: pins between () means that they are optional.

(1) for safety, insert a 1 kOhm resistor between TLM pin and Rx

(2) for safety, insert a 1 kOhm resistor between PRI pin and Rx

(3) For Futaba, TLM pin must be equal to PRI pin - 1 and insert 1 kOhm resistor between PRI and TLM

Up to 16 PWM signals can be generated on pin gpio 0...15 (to select in setup parameters).

Voltages 1, 2, 3, 4 can be measured on gpio 26...29. Take care to use a voltage divider (2 resistances) in order to limit the voltage on those pins to 3V max. V2 is normally used to measure a current (based on the analog voltage). V3 and V4 can be used to measure or a voltage or a temperature (based on a voltage provided by a sensor like TMP36 or a CTN/thermistor). For each voltage being measured, you probably have to specify the offset and scale to be applied.

One RPM (Hz) can be measured

When a MS5611/SPL06/BMP280 (baro sensor) and/or MP6050 is used:

When a differential pressure sensor is used, you should connect SCL/SDA like for a baro sensor.

When a GPS is used:

When a Hobbywing, ZWT, Kontronik, Jeti or BlHeli ESC is used:

About sequencers and locator, see below.

The affectation of the pins has to be defined by the user.
Here are the command codes and the pins that can be used are:
Note: pin 16 is reserved for an internal LED on RP2040-zero or RP2040-TINY and so should not be used with this board.		 Command used for:
C1 = 0/15 ... C16 = 0/15 PWM output
GPS_TX = 0/29 getting GPS data
GPS_RX = 0/29 sending configuration to GPS
PRI = 5 ,9, 21 ,25 primary RC channel input
SEC = 1, 13 , 17 ,29 secondary RC channel input
SBUS_OUT = 0/29 Sbus output
TLM = 0/29 telemetry data (! for futaba Sbus2, this pin must be equal to PRI pin - 1)
V1= 26/29 ... V4= 26/29 voltage (or current/temperatue) measurements

|RPM = 0/29 | RPM| |LED = 16 | internal led of RP2040-zero or RP2040-TINY|
|LOG = 0/29 | data to be logged |
|ESC_PIN = 0/29 | data provided by ESC (rpm, volt, current, temp)| |SPI_CS = 0/29 | Chip Select (=NSS) pin from E220-900M22S (locator)| |SPI_SCK = 10, 14, 26 | SCK pin from E220-900M22S (locator)| |SPI_MOSI = 11, 15, 27 | MOSI pin from E220-900M22S (locator)| |SPI_MISO = 8, 12, 24, 28 | MISO pin from E220-900M22S (locator)| |SPI_BUSY = 0/29 | Busy pin from E220-900M22S (locator)| |HIGH = 0/29 | set the voltage level to 3V; can be used as Vcc for some sensors| |LOW = 0/29 | set the voltage level to 0V; can be used as Ground for some sensors|

--------- Software -------------------

This software has been developped using the RP2040 SDK provided by Rapsberry.

If you just want to use it, there is (in most cases) no need to install/use any tool.

Developers can change the firmware, compile and flash it with VScode and Rapsberry SDK tools.
An easy way to install those tools is to follow the tutorials provided by Rapsberry.
In particular for Windows there is currently an installer. See : https://github.com/raspberrypi/pico-setup-windows/blob/master/docs/tutorial.md

Once the tools are installed, copy all files provided on github on you PC (keeping the same structure).
Open VScode and then select menu "File" + item "Open Folder". Select the folder where you copied the files.
In VScode, press CTRL+SHIFT+P and in the input line that appears, enter (select) CMake: Configure + ENTER
This will create some files needed for the compilation.
To compile, select the "CMake" icon on the left vertical pannel (rectangle with a triangle inside).
Move the cursor on the line oXs [oXs.elf]; an icon that look like an open box with some dots apears; click on it.
Compilation should start. When done a new file oXs.uf2 should be created.
For more info on VScode and SDK look at tutorials on internet.

Note : the file config.h contains some #define that can easily be changed to change some advanced parameters.

Note for ELRS:
The RP2040 send the telemetry data to the ELRS receiver at some speed.
This speed (=baud rate) must be the same as the baudrate defined on the receiver.
Usually ELRS receiver uses a baudrate of 420000 to transmit the CRSF channels signal to the flight controller and to get the telemetry data.
Still, ELRS receivers can be configured to use another baud rate. In this case, change the baudrate in parameters accordingly.

You have to compile your self the firmware if you want to change some less usual values in the config.h file in order e.g. to:

------------ Failsafe---------------

For the 2 last options, the handset must be on and generating the channels values that you want to save in oXs.

--- Telemetry fields being measured and transmitted ---

oXs tries to detect automatically which sensors are connected (based on the parameters being fill in the setup). It can display on the PC (on a serial terminal getting the messages via usb ) the current setup and the sensors that have been discovered.

oXs measures different fields depending on the sensors being detected.

Please note that the data being transmitted depends also on the protocol being used (Sport, ELRS, ...).

For more information, please look at document "fields per protocol.txt" in folder "doc"

When a baro sensor and an airspeed sensor are both used, oXs calculates 2 vertical speeds:

You can use a channel to control the way airspeed compensated Vspeed is calculated and/or transmitted.

First you have to send a command ACC (via the PC) to specify the channel being used (1...16).

You must use a protocol/wiring (like Sbus, Fbus, Exbus, ...) that allows the Rx to communicate the RC channel values to oXs.

Then, depending on the value sent by the Tx on the selected channel, oXs manages the airspeed compensated Vspeed in different ways:

Note: you can use the FV command to know the current coefficient. This allow you to check that your Tx sent a Rc channel value that match the expected goal and indeed required, adjust your Tx settings.

---------------- Calibration and orientation of MP6050 ---------------

When MP6050 (=MPU) is used, oXs must know his orientation in the model. There are many possible orientations.

Furthermore, for best result, each MP6050 must be calibrated (accelerometer and gyro). This is just optional when MP650 is used to improve vario reactivity (so not to know roll/pitch, stabilize camera and/or model).

Best is to start with calibration of the accelerometer, then calibration of the gyro and finaly to set up the orientation of the MPU in the model.

Note: Once the MP6050 calibration process has been done and saved, it is normally not required to do it again. Take care that, if you change the orientation of the M6050 in a model, you have to update the orientation parameters in oXs (not the calibration).

1 Calibration of the accelerometer

To calibrate the MP6050, oXs must be conected to the PC (via usb) and the PC must be running a serial montitor (to enter commands and display the oXs messages). It requires to make several measurements while the sensor remains fix in many different orientations.

In the doc folder, you can also find word document explaining again the process and a link to a video about accelerometer calibration. It shows the principle even if it is not done with an oXs device.

2 Calibration of the gyro

The gyro calibration is quite easy because it only requires that the sensor does not move at all.

It is normally done automatically at each power on but it requires that the model stay still the first 2 sec. If oXs detects that the sensor moves during the first 2 sec, the process will fail and oXs will reuse parameters that have been saved.

Note: It is possible to disable this automatic calibration with a parameter in file config.h.

So, it is not bad practice to save gyro calibration offsets. To do so, oXs must be conected to the PC (via usb) and the PC must be running a serial montitor (to enter commands and display the oXs messages).

3 Set up the gyro orientation.

The mpu must be installed in the model in such a way that one axis of MPU6050 is vertical and that another axis is aligned with main axis of the model (nose-queue). There are 24 possible orientations to match this. Most commercial gyro's require that the user declares the orientation of the MP6050 in the model. oXs does it automatically.

There are 2 ways to let oXs know the MPU orientation:

Process with USB command:

Notes:

------------------ Gyro ------------------

Important note: at this stage, this is still experimental. It has not been intensively tested. So used it at you own risk.

Principle.

Setup on the handset.

Required oXs parameters to set up the gyro.

oXs has to know:

Optional oXs parameters to fine tune the settings: to get the list of commands to use, enter the USB command ? (=help)

Note: as usual with oXs:

Gyro learning process = mixer calibration = discovering the orientation/mixers and limits

The general principle is to let the mixers + servo centers/min/max being defined only on the handset. Still oXs must take care of those mixers and limits when it applies gyro corrections. To achieve this, oXs has to capture the positions of all Rc channels when sticks are in several specific positions. That is the reason why you had to add 3 channels on the handset (see above).

The process to let oXs discover the mixers/limits to apply is named the "gyro learning" process (also named "mixer calibration"). It is mandatory. This process is not the same as the calibration of the MP6050.

This process also let oXs find automatically the orientation of the MP6050 in the model. That is the reason why you don't need to use usb commands (MPUORI=..) to setup the orirentation of the MP6050 when gyro is used.

Important note: the learning process must be done again if the orientation of the MPU in the model change and/or if the mixers/servo directions change on the handset.

The learning process consist of several steps.

1 Starting the process

To start the mixer calibration, the user has to put the model HORIZONTAL and, on the handset, simultaneously:

When oXs detect this situation, It will try to find the MP6050 axis that measures gravity. If oXs can't, it stops moving the servos and sending telemetry. The user has to make a power off. So it is clear that the process did not ended properly.

If "horizontal" orientation is found, oXs will set the led on RED and register the "horizontal" orientation and the 3 stick positions. It then goes to the next step (discovering the mixers)

2 First Phase : discovering the mixers.

oXs will then analyse the positions of sticks expecting to detect 7 cases:

Each time a case is detected, oXs will register the positions of all Rc channels. This wil help to apply the gyro corrections with the right proportions on the rigth servos.

During this phase, to avoid side effect on the discovered mixers, it is VERY IMPORTANT that :

The 7 cases can be done in any order and any number of times.

When all cases have been detected at least once, LED will become BLUE (saying that it allowed to switch to next step).

The user can still continue to move the sticks as previous as long as he want.

3 Switching to phase 2:

When all cases have been detected (led is blue),next step must be activated.

To do so, SET THE MODEL VERTICAL with the NOSE UP and then change (1X is enough) the position of the gyro switch.

Note: switch changes during the first 5 sec of phase 1 are just discarded (so it does not matter if user changed more than 5 X the switch when it was starting the process).

oXs tries to detect the new orientation (vertical nose up) and checks that it is different from the "Horizontal".

In case of error (wrong orientation or at least one of the 7 cases not detected -LED still RED), oXs stops moving the servos and sending telemetry. The user has to make a power off. So it is clear that the process did not ended properly.

If gyro switch is valid, LED becomes GREEN (= second phase (discovering the limits) is running).

4 Second phase: dicovering the limits

User can now move all sticks, sliders, switches(except gyro switch) simultaneously in all positions in order to let each servo reaches his min and max allowed positions.

oXs registers those limits. They will be used to limit the movements when oXs applies gyro corrections on top of the Rc channel received from the handset. User can make this step as long he want (but must be at least 2sec). During this phase, orientation of the model does not matter (it can be set e.g. horizontally in order to easily move the stick).

Ending the learning process

To close the mixer calibration process, user has to change once more the gyro switch.

oXs saves then all parameters in flash so the calibration does not have to be repeated (except if mixers/mechanical limits are modified on the handset).

Note: switch changes during the first 2 sec of phase 2 are just discarded (so it does not matter if user changed to often the switch when it was switching to phase 2).

Notes:

At each power on, oXs uploads saved parameters and uses them.

Outside of the learning process process, end points of each servo (=min/max limits) are automatically updated based on the Rc channel values received from the receiver (so before gyro corrections). This allows oXs to apply gyro corrections that exceed the limits registered during the cabration but without exceeding the limits defined in the handset. The drawback of skipping step 2 of learning process is that some gyro corrections could be more restricted than really required in the first minutes after a power on.

Checks.

when the learning process has been done, it is important to check that every thing is OK. So without moving the model, first check that the servos move as expected.

---------------- Sequencers ---------------

With oXs, one single channel on the handset can control one or several SERVOS in sequences defined by the user (e.g. for landing gears with doors and wheels).

It can also generate one or several ANALOG signals in sequences (e.g. to blink leds or to start/stop motors).

One output is controlled by only one Rc channel.

You can use several Rc channels; each channel controls one or serveral outputs (SERVO and/or ANALOG).

oXs uses 3 concepts : sequencer, sequence and step.

------------------ Logging -------------------

If the LOG Gpio is defined, all telemetry data and all PWM Rc channel values (usec) captured by oXs are transmitted on the LOG pin in a compressed format.

Each time a set of data is ready, oXs generates a packet (with only the newly generated data).

The packet is generated with an UART 8N1 (8 bits, no parity, 1 stop bit) at the defined logger baudrate.

Each packet starts with 0X7E (= synchro byte) followed by 4 bytes (number of milli sec since RP2040 start up) and by

There is some stuffing mecanism (like in Frsky Sport protocol) in order to ensure that the value 0X7E can only be present at the begining of a packet. \ \ This format allows to compress the data transmitted via the (quite slow) UART to the logger. \ \ The logger will remove the stuff bytes, uncompress the data, combine the new data with previous one to create an "actual" set of data's, convert it in CSV format and finally store it on a SD card.

------------------ Model Locator ----------------------------------------

oXs can be used to locate a lost model if you add a LORA module Ebyte E220-900M22S (or a RFM95 - depreciated).

The model is normally connected to the handset but when the model is on the ground, the range is quite limitted. So if a model is lost at more than a few hundreed meters, the handset will not get any telemetry data anymore. oXs allows to use a separate connection (with LORA modules) in order to have an extended range and have a chance to find back a lost model. This is possible because those modules use a lower frequency, a lower transmitting speed and a special protocol for long range. The LORA modules are E220-900M22S that are small, cheap and easily available (e.g. Aliexpress, ebay, amazon) \ \ The principle is the following:

Note: the range of communication between two Ebyte modules is normally several time bigger then the common RC 2.4G link.
If oXs and locator receiver are both on the ground, it can be that there are to far away to communicate with each other. But there are 2 ways to extend the range:

An oXs device with an Ebyte does not perturb the 2.4G link (it uses another frequency range - default 868mHz) and consumes only a few milliAmp because it remains normally in listening mode and when sending it is just a few % of the time. So, in order to increase the reliability of the system, it is possible to power oXs with a separate 1S lipo battery of e.g. 200/500 mAh. This should allow the system to work for several hours.

Cabling : The Ebyte module must be connected to the Rp2040 in the following way

Do not forget to install an antenna on the E220 module (or solder a wire of about 8.5 cm on the pin named ANT)

To build the locator receiver, please check this link https://github.com/mstrens/oXs_locator_receiver_on_ESP8266

Note: oXs (=transmitter) stay in sleep mode most of the time. Once every X (see config.h) sec, it starts listening to the receiver for e.g. 5 sec. If the receiver is not powered on, oXs never get a request and so never sent data. When powered on, the receiver sent a request every 1 sec. At least X sec later (when entering listening mode), oXs should get this request and then reply immediately. oXs will then reply to each new request (so every 1 sec). oXs goes back to sleep mode for X sec if it does not get a request within 60 sec.

Note: this version of oXs is foreseen to work with E220-900M22S modules and with the version of locator receiver from main branch of oXs_loacator_on_ESP8266. Still it is possible to use depreciated RFM95 module (less performant, more expensive) but it requires to edit the config.h file to activate the option "#define USE_RFM95". In this case, you have to use the locator receiver from oXs_locator_on_RP2040 (uses a rp2040 and an oled display) or from the rfm95 branch from oXs_locator_receiver_on_ESP8266 (uses a ESP8266 and wifi to communicate with a GSM or PC).When a RFM95 is used, SPI_BUSY pin must be defined but is not cnnected to the RFM95.

------------------ Led -------------------

When a RP2040-Zero or RP2040-TINY is used, the firmware will handle a RGB led (internally connected to gpio16).

Note: some users got a RP2040-zero or RP2040-TINY where red and green colors are inverted. If you got such a device and want to get the "normal" colors, you can enter a command LED=I to invert the 2 colors.

Please note that other boards do not have a RGB led on gpio16 and so this does not applies.