Loading...
 

Teensy Telemetry Project

This howto provides steps required to setup Taranis telemetry with an APM or Pixhawk when the Taranis is running OpenTx 2.1. It also includes precompiled firmware for a Teensy 3.1. The firmware is compatible with the FrSky stock telemetry screens and some Lua telemetry scripts that already exist.

Downloads, Support and Community

There is an active blog for this project at http://www.rcgroups.com/forums/showthread.php?t=2529072 .  The pre compiled firmware can be downloaded there.

Extensions

There are two extensions to this project

LEDs

Teensy Telemetry LED Extension

Sound Extension

Teensy Telemetry Sound Extension

 

Why would you do this?

One of the greatest features of an APM based system is it's ability to provide data to other devices using a protocol called MAVLink http://en.wikipedia.org/wiki/MAVLink. Most people know MAVLink as the protocol for sending telemetry information to OSD's and ground stations. For this project, we intercept the MAVLink data and translate it to FrSky's telemetry protocol. FrSky's telemetry protocol is not public, but there is enough information available to simulate FrSky's sensor devices. In other words, the Taranis radio thinks it's receiving data from a FrSky sensor, but in reality, it is receiving data from the converter we are going to build that just simulates the FrSky sensor using MAVLink data.

Taranis HUD Thumbnail  

This focus of this project was to make a fully featured MAVLINK to FrSky S.Port converter that could be setup by almost anyone.  A lot of the time on this project went into diagnostics and a configuration console so that changes wouldn't require a software developer or recompilation. I believe that this project is still very unique. The FrSky to S.Port module was originally derived from the work by Rolf Blomgren at http://diydrones.com/forum/topics/amp-to-frsky-x8r-sport-converter.  

Advantages of this Firmware

  • The Teensy's LED is used to display coded diagnostic messages which simplify connecting and debugging
  • USB console for advanced debugging and configuration changes
  • Full text messages are streamed through the FrSky telemetry channel to reduce the chance of missing or misinterpreting MAVLink messages. This is very useful to resolve issues when you don't have a computer or telemetry based telemetry running. eg. Copter won't arm and you don't know why
  • Compatible with other telemetry scripts that use the FrSky defined telemetry properties. This does not mean that this is compatible with other telemetry projects that use custom telemetry extensions. Many other MAVLINK telemetry use FrSky properties such as RPM and temperatures to pass MAVLINK information. This is typically done differently in each project
  • No dependency on the telemetry RX line which simplifies wiring. The RX line can optionally be connected which eliminates the need to set ArduCopter's SRn_ parameters.
  • You can disable MAVLink voltage and current monitoring and use the official FrSky power monitor. This is useful if you don't have an APM Power Monitor and need a solid plug and play solution for power monitoring.
  • Supports X4R, X6R and X8R receivers
  • The current consumed value (mah) does not clear if the the Taranis is turned off and on. The value is only set to zero when the copter is connected to a battery
  • Precise floating point ground distance and HUD calculations from the position where you armed the vehicle
  • Direction arrow gives you the intuitive orientation that the vehicle is heading relative to the direction the pilot is facing
  • Course over ground (COG) line that indicates the actual direction that the vehicle is moving
  • All functionality is implemented on both APM and Pixhawk compatible platforms since the Teensy's 32 bit processor offloads the flight controller from complex 32 bit calculations

Support for external LEDs which display complex patterns

  • Support for NeoPixel LED strips to get LED patterns triggered by MAVLINK data
  • Each NeoPixel LED is capable of displaying 24 bit color
  • Supports 8 LED strips with up to 16 indiviually controlled LEDs per strip
  • Configure complex LED patterns triggered from MAVLINK data without coding.  See the LED extension for more details

 

Instructions

Things That You'll Need

 

  1. A Teensy 3.1 or 3.2. The Teensy is a tiny 32 bit microprocessor board that is extremely capable. I considered supporting 8 bit Arduino boards but was far to restricted by the limited code space. Here's a list of official distributors https://forum.pjrc.com/threads/23601-Official-Distributors . The Teensy 3.1/3.2 is programmed with a standard USB micro cable. No FTDI required.
  2. A cable to connect the Telemetry TX pin from the APM to the Teensy. Just like OSD, you don't need to connect RX. We'll configure the APM to regularly send data packets. The wires will just be soldered to the Teensy RX. You can also connect GND but it's not important since the Teensy is grounded from the receiver.
  3. A cable to connect the Teensy 3.1 to the receiver's SPort. This is just a standard servo connector. SPort is a single wire protocol so RX and TX are the same thing. The three wires are Data, VCC and GND.
  4. Heat shrink or equivalent to protect the Teensy when it is mounted to the vehicle. I used the thin clear stuff so I can see the LED.
  5. A micro USB cable to connect the Teensy to your computer for programming and configuring.

 

Programming the Teensy 3.1

Here's a link right to the loader program that you'll need to download https://www.pjrc.com/teensy/loader_vista.html. You just need to click the picture for the OS that you are using. (Windows, Mac, Linux, etc). The next page that will come up will show you how to download and run the loader. There is even a sample .hex file on that page that you can flash to the Teensy to verify that you know how to load firmware.

Once you have that going, just do the same procedure to flash the Teensy with the attached mavsky hex file. When the mavsky firmware runs, it will start flashing LED diagnostic codes immediately. Probably telling you that you need to hook it into your APM and receiver.

  • One thing to remember: If you are following these steps in order, you haven't gotten to the first step in the next section "Cut the tiny VIN from VUSB trace". That's okay since the USB will supply power to the Teensy and it won't have to be connected to the copter to program. However, if you have already wired your Teensy to your receiver and have cut the trace, you'll need to power the Teensy from the receiver while you flash it. You can just put a battery in the copter or attach the copter's USB port while you are programming the Teensy.


If you are interested in compiling the source code you'll need to download the Arduino software and Teensyduino, then grab the source from github https://github.com/scottflys/mavsky

Preparing the Teensy

Image  

  1. Cut the tiny VIN from VUSB trace on the back of the Teensy/U/B. This is a feature and is not wrecking your Teensy, it's designed for this. You can always put a blob of solder on the pads beside the trace later if you want it connected again, but cutting it is important to make sure USB 5V does not get connected to the Receiver VCC. Test that your cut broke the connection with an ohm meter or by powering the Teensy by USB and verifying that it's not powered
  2. Prepare a 3 pin female connector for the SPort (Smart Port) by cutting the wire at about 5 inches and tinning the wire. Make sure you are connecting to the SPort and not the SBUS on the receiver.
  3. Solder negative (-) to a Teensy GND pad
  4. Solder positive (+) to the Vin pad
  5. Solder the signal (S) to TX1 . The Teensy's serial chip is capable of transmit and receive on the TX line (single wire data)
  6. Prepare a connector for the flight controller. The connector you are using depends on your existing configuration. The Teensy only needs to receive MAVLink so you just need to connect TX from the flight controller and GND. This is the same way MinimOSD is wired in, so you can google MinimOSD wiring for lots of information. You can connect the Teensy TX2 to Flight Controllers telemetry RX to avoid needing to set the SR0_ parameters to have the FC autosend mavlink.
    • If you are using a 3DR radio, you have to tap into the TX line from the flight controller going to the RX of the radio.
    • If you don't have telemetry already setup, you will have to connect TX and GND from the flight controller
    • If you have a CX-20 or Nova, you'll have to add a wire inside the flight controller (see resistor hack urlhttp://www.rcgroups.com/forums/showpost.php?p=28340346&postcount=428/url). You only need a wire connected to the microprocessor TX side of telemetry and GND. (Pin 3 on the micro is TX and that is the yellow wire in the picture)
  7. Wire GND from the flight controller to a GND pin on the Teensy
  8. Wire the telemetry TX from the APM to RX2 on the Teensy
  9. Apply the shrink wrap. If you are using clear you'll be able to see the LED, but if you use black you might to make a small hole to see the LED.

 

Flight Controller Parameters

As of version 2.1.4, you can connect an additional wire connecting the Teensy's TX2 port to the flight controllers RX. This way, the Teensy will request data and you won't have to set any of the SR0_ parameters (or SR1_, SR2_).

If you don't connect the data request wire you'll need to tell the APM to automatically send MAVLink data out the serial port so it can get read by the Teensy. This is done the same way it's done for minim OSD. With APM hardware, serial port 0 is used for telemetry. The parameters that control serial port 0 are SR0. Pixhawk uses SR1_ for telem1 and SR2_ for telem2.

To set these, go to the Full Parameter List and use the Find function and search for SR0 to get them all to show up. Set them and click Write Params

ParameterValueControlled MAV Packets
SR0_EXT_STAT3SYS_STATUS, MEMINFO, MISSION_CURRENT_GPS_RAW_INT, NAV_CONTROLLER_OUTPUT, LIMITS_STATUS
SR0_EXTRA15ATTITUDE, SIMSTATE
SR0_EXTRA22VFR_HUD
SR0_EXTRA33AHRS, HWSTATUS, SYSTEM_TIME
SR0_PARAMS10PARAM_VALUE
SR0_POSITION3GLOBAL_POSITION_INT
SR0_RAW_CTRL0RC_CHANNELS_SCALED
SR0_RAW_SENS2RAW_IMU, SCALED_IMU2, SCALED_PRESSURE, SENSOR_OFFSETS
SR0_RC_CHAN3SERVO_OUTPUT_RAW, RC_CHANNELS_RAW

If you are using APM, the serial port is shared with the USB. So, if you make changes in Mission Planner while connected through USB, you'll have to unplug the USB and boot up the APM before MAVLINK data gets sent out the telemetry TX line.

Issue Setting SR0 Parameters on APM

You may notice an issue trying to write SR0_ values consistently.  It's related to a bug in Arducopter with APM.  Pixhawk will not have this problem.  In APM, SR0 is multiplexed with USB so when you connect with USB, the values displayed in the SR0 parameters are not the values that are stored in NVRAM.  

The following procedure will consistently set the SR0 parameters correctly.

  1. Connect to the APM in Mission Planner
  2. Click Config/Tuning->Full Parameter List
  3. Click Find and enter SR0_
  4. Change each value to 9 (value box turns green) and Write Params
  5. Change the values as shown above (value box turns green) and Write Params
  6. Reboot the APM and the correct values will be used by Arducopter

Programming the Taranis

The Taranis runs opensource software called OpenTX (urlhttp://www.open-tx.org//url). OpenTX supports a programming language called Lua.  Lua is used to draw the telemetry data on the Taranis LCD display. Lua is an interpretted language meaning that you don't need to compile it. You just have to copy the Lua files into the right place on the Taranis and your new Telemetry screen will be available. I tried to keep this project simple so that it's easier to understand and modify.

  1. Install OpenTX Companion on your PC
  2. In Settings->Settings->Radio Profile tab, make sure Lua is selected. I have Lua and noheli checked
  3. To install the Lua telemetry scripts, you just have to start up your Taranis in bootloader mode (hold the two trim buttons towards each other and turn it on), then connect the USB port. The Taranis SD card should show up as a new Windows/Mac/Linux drive.
  4. With Windows explorer, navigate to the Taranis SD card and change to a directory named \SCRIPTS. In this directory you should see a subdirectory named TELEMETRY. If you don't, create one so that you have a directory named \SCRIPTS\TELEMETRY. You don't need to have a directory with the model name like you did in OpenTx 2.0. In OpenTx 2.1, all telemetry scripts go into a single directory.
  5. Copy the telemetry script(s) located in the Lua directory of the zip of this project into the \SCRIPTS\TELEMETRY directory.
  6. If you want telemetry to be reported in SAE units (ft and mi/hr) instead of Metric, edit the telemetry file named sfthud1.lua and change the line at the top to read local imperialUnits = 1
  7. Unplug USB and restart your radio
  8. Press Menu quickly then Page for one second (long press). This will show you the Telemetry configuration page for your current model. ("long press" is just a shortcut that goes back one page so you don't have to hit page 11 times to get to the Telemetry configuration page which is the last page)
  9. Scroll down to Screen 1 and change it to "Scripts" and set the script name to sfthud1. There are three other diagnostic screens you can optionally add to Screen 2-3 that are called sfdiag1-2
  10. Scroll down to "Discover new sensors" and hit the "ENT" button. Turn on your vehicle so that telemetry data starts getting pushed down to the Taranis. Make sure your Taranis is several feet away and you should see several "sensors" show up. If you are using an X8R you should see about 13 sensors. Click "Stop discovery".
  11. Hit EXIT a few times to get back to the OpenTx start page and you should be able to get into the telemetry screens by long-holding the Page button. To get to the second telemetry screen, short hold the Page button. You can use short-hold to cycle through all all telemetry screens including the stock screen. Long-hold cycles backwards.

Testing

Before closing up the case, you should test to make sure telemetry is getting sent to the transmitter. You should also make sure you make any configuration changes. The default configuration will probably be all you need, but if for some reason you have special requirements, you may want to have access to the firmware configuration console through the Teensy's USB.

1) Turn the transmitter on and long-press the Page button. This should show the first telemetry Lua script

2) Connect a battery to the copter.

3) Look at the LED on the Teensy. If it's a solid red, then data is correctly being passed to the FrSky telemetry channel. If the LED is flashing, you need to count the flashing to determine the numeric code. See the LED codes section for a summary of the diagnostic codes

4) You should now see telemetry data changing on the Transmitter telemetry screen.

LED Diagnostic Codes

If the LED is flashing, count the number of flashes to determine a numeric code(s). The code is repeated continuously as long as the fault continues to exist. i.e. If the faults clear, the LED will be solid.

1 - No MAVLink data is being received (possible faulty connection to APM)
2 - No Telemetry packets are being requested (possible faulty connection to receiver)
3 - Missing MAVLink SYS_STATUS data. (Check APM Parameters)
4 - Missing MAVLink GPS data. (Check APM Parameters)
5 - Missing MAVLink VFR_HUD data. (Check APM Parameters)
6 - Missing MAVLink RAW_IMU data. (Check APM Parameters)
7 - Missing MAVLink ATTITUDE data. (Check APM Parameters)

Advanced Configuration and Diagnostics

The console can be accessed by a terminal emulator. Windows used to include HyperTerminal but doesn't anymore.

1) Plug the Teensy into a computer with a USB port.

2) Since the Teensy is not powered by the receiver, you'll have to connect a battery to the copter

3) The Teensy's COM port should show up in Windows Device Manager. If you don't see the Teensy's COM port, you may need a device driver. TeensyDuino ( urlhttps://www.pjrc.com/teensy/td_download.html/url ) will install one, then just replug the Teensy after the installation completes.

4) Start up a terminal emulator (Putty) and connect to the Teensy's COM port at 57,600 baud. If you are using Putty, click the Serial radio button, Type in the COM port name (i.e. COM5) an set the baud to 57600

5) Hit a few enter keys and you should notice a ] prompt

6) Type help to see a list of diagnostic and configuration commands available

Notes About Console Commands

dump
This command will dump out the most recent data in the converter

map current
This sets what is sent to the current (battery current) value. You can send the direct current measurement or averages over the past 10 or 50 samples. The averages make the display more stable than direct. This defaults to map current average10

mav heartbeat
This is an example of one of the enabling one of the mav debug filters. After running this you'll see each heartbeat message on the console until you turn it back off. All debug filter commands are reset by restarting the Teensy. This prevents you from getting flooded with messages when you first connect

frsky vfas disable
Use this to disable MAVLink voltage and current monitoring. This is useful if you are using an official FrSky VFAS.

factory
Puts all settings back to factory defaults

Included telemetry screens

sfthud1.lua
This is the screen with the big arrow in the center. Battery information is at the left, velocity, altitude, and distance is at the right. The GPS status is shown at the bottom. There are options for this screen, but you'll have to use a simple text editor like Notepad to change them. Just edit the sfthud1.lua and look at the options near the top of the file. Just change them to whatever you prefer. For example, if you prefer imperial, set that option to 1.

If you have two copters, one with current monitoring and one without, you can make a copy of sfthud1.lua for the copter without current monitoring. Keep the first part of the filename less than 8 characters, so sfthudnc.lua would work. (nc stands for no current). Then, edit sfthudnc.lua and set the option for no current monitoring. Then, all you have to do is go into the Taranis telemetry page for your model and set the page to sfthudnc.lua instead of sfthud1.lua.

i) Once you have a GPS lock and you arm, the arrow in the center points in the direction that the copter is facing Urelative to you/U.

ii) The black bar at the bottom shows the last text status messages that was emitted from MAVLink. This is useful if you run into problems such as the copter not arming. Since this is an exact MAVLink text message it makes it much easier to troubleshoot any copter issues.

sfttext1.lua
This shows the last 5 text messages that were received from the flight controller if there were any

sdtdiag1.lua
This screens is a diagnostic screen which can help you sort out issues if you add or modify the existing lua scripts. The names of most Lua values is shown, in some cases a short form, along with the raw data value.

Downloads, Support and Community

There is an active blog for this project at http://www.rcgroups.com/forums/showthread.php?t=2529072