Steam Community :: Guide :: Liftoff

Store Page

Liftoff

All Discussions Screenshots Artwork Broadcasts Videos Workshop News Guides Reviews

Liftoff > Guides > JuniorDiscart's Guides

Not enough ratings

Liftoff - Drone Telemetry

By JuniorDiscart and 2 collaborators

Liftoff: FPV Drone Racing allows you to stream drone telemetry data to external locations. That way, you can analyze flights, or diagnose issues with external programs that interface with Liftoff.

Award

Created by

JuniorDiscart
Offline

Kasper
Offline

LuGus Studios
Offline

Category: Modding or Configuration

Languages: English

Posted

Updated

14 Feb @ 3:07am

14 Mar @ 3:56am

1,379	Unique Visitors
14	Current Favorites

Guide Index

Overview

Introduction

Who is this for?

Setup

Configuring the telemetry data

Modifying the configuration while in-game

Example configurations

Comments

Introduction

Liftoff: FPV Drone Racing allows you to stream drone telemetry data to external locations. This way you can analyze flights or diagnose issues with external programs that interface with Liftoff.

Who is this for?

The Drone Telemetry feature is not something the average Liftoff: FPV player will find a use for. It is however, useful to players wanting some extremely detailed feedback or researchers interested in analyzing a drone's behavior, to plot out data in other software, or to train certain data models for A.I.

Setup

The Drone Telemetry feature can be enabled by placing a file in a specific directory. This location depends on the operating system running Liftoff:

Windows:
C:\Users\%userprofile%\AppData\LocalLow\LuGus Studios\Liftoff\
macOS:
~/Library/Application Support/LuGus Studios/Liftoff/
Linux:
~/.config/unity3d/LuGus Studios/Liftoff/

Within this directory, create a new file named TelemetryConfiguration.json to enable the drone telemetry.

Currently there is no way to enable or configure this feature from within Liftoff itself. This might be added in a future update.

Configuring the telemetry data

The Drone Telemetry data stream is configured using the TelemetryConfiguration.json file. We'll go over each of the parameters in this section. The example configurations section below provides a few practical examples.

Before diving into the different configuration possibilities, first let's define the types of data you can expect to receive on the data stream. Each component will state what type of value it will be. This will be important for when you parse the data on your end. So let's sum them up below:

float - a single precision floating point number, 4 bytes long.
int - an integral number, 4 bytes long.
byte - a single byte.

There are two main parameters that can be configured:

The data end point: all telemetry data are sent over a UDP packet stream. The EndPoint value allows you to configure where it is sent to. This value is formatted in IP end point notation, e.g. 127.0.0.1:9001, where you specify the intended IP address and port number.
The stream format: you can configure which telemetry data points you're interested in, as well as the sequence in which they are sent. The StreamFormat string array defines the sequence. The supported data points and their data layout are listed below:
- Timestamp (1 float) - current timestamp of the drone's flight. The unit scale is in seconds. This value is reset to zero when the drone is reset.
- Position (3 floats) - the drone's world position as a 3D coordinate. The unit scale is in meters. Each position component can be addressed individually as PositionX, PositionY, or PositionZ.
- Attitude (4 floats) - the drone's world attitude as a quaternion. Each quaternion component can be addressed individually as AttitudeX, AttitudeY, AttitudeZ and AttitudeW.
- Gyro (3 floats) - the drone's angular velocity rates, represented with three components in the order: pitch, roll and yaw. The unit scale is in degrees/second. Each component can also be addressed individually as GyroPitch, GyroRoll and GyroYaw.
- Input (4 floats) - the drone's input at that time, represented with four components in the following order: throttle, yaw, pitch and roll. Each input can be addressed individually as InputThrottle, InputYaw, InputPitch and InputRoll.
- Battery (2 floats) - the drone's current battery state, represented by the remaining voltage, and the charge percentage. Each of these two can be addressed individually with the BatteryPercentage and BatteryVoltage keys. Note - these values will only make sense when battery simulation is enabled in the game's options.
- MotorRPM (1 byte + (1 float * number of motors)) - the rotations per minute for each motor. The byte at the front of this piece of data defines the amount of motors on the drone, and thus how many floats you can expect to find next. The sequence of motors for a quadcopter in Liftoff is as follows: left front, right front, left back, right back.

Note that this data stream is only available for drones that are actively being simulated by Liftoff. It won't work for drones being spectated in multiplayer or during a replay session.

Modifying the configuration while in-game

Each time the drone is reset, Liftoff will check whether the telemetry configuration file has been changed, and reload it if so. This allows you to tweak and change parameters without restarting Liftoff.

If the configuration file contains an error, Liftoff will display a popup message after the drone has been reset. Fix the error, reset the drone again, and the new telemetry configuration will be loaded.

Example configurations

Some example configurations of the TelemetryConfiguration.json file.

Everything

A configuration that will send over all telemetry data to a local end point.

{ "EndPoint": "127.0.0.1:9001", "StreamFormat": [ "Timestamp", "Position", "Attitude", "Gyro", "Input", "Battery", "MotorRPM" ] }

The total size of each data frame being sent would be 85 bytes.

Horizontal position over time

A configuration that will only send the position of the drone in the XZ-plane, along with the timestamp, to an end point in the local network.

{ "EndPoint": "192.168.1.6:6808", "StreamFormat": [ "Timestamp", "PositionX", "PositionZ" ] }

The total size of each data frame being sent would be 12 bytes.

From input to gyroscope

A configuration that correlates input axes to the drone's gyroscope, without a timestamp.

{ "EndPoint": "127.0.0.1:9001", "StreamFormat": [ "InputPitch", "GyroPitch", "InputRoll", "GyroRoll", "InputYaw", "GyroYaw" ] }

The total size of each data frame being sent would be 24 bytes.

24 Comments

< >

o7ur 4 hours ago

Hey!

I'm on my Windows 11 computer, running the game in Windows through steam.

When I place the .json file in the correct location and named correctly, i'm not getting any telemetry out from the udp port... I have checked the Player.log file and Player-prev.log, and I can see that it's not finding the .json file.. I have double and triple checked the location of the file and the structure of the .json file itself, and its according to the instruction in this thread...

What i'm concerned about is that the path to the .json file in the .log file is using a "\"(backslash) to look for the .json file, instead of using "/"(forwardslash) in the path..

"Could not find a drone telemetry configuration file at C:/Users/magnu/AppData/LocalLow/LuGus Studios/Liftoff\TelemetryConfiguration.json"

Any thoughts on what might be the problem?

Kudo 21 Nov @ 5:37pm

@JuniorDiscart

Couldn't get it to work locally due to my isp but I set up a server and it works! Thanks for the help

JuniorDiscart [author] 19 Nov @ 12:35am

@Kudo

I only tested with local host and on a local network. If you traverse a router with NAT enabled, things might be more complicated.
Furthermore, is the configuration file placed in the right directory, and the file has the correct spelling/capitalization? If not, it will not read the file and send out any data.

Kudo 18 Nov @ 1:09pm

I have the endpoint field connected to my IP and the correct port. but when I set up a local socket with the same IP and endpoint. I get no data from liftoff, any clue how to fix this?
I tested the socket and it can receive data so I think the issue is with liftoff?

JuniorDiscart [author] 5 Oct @ 4:51pm

It doesn't yet. There are plans to port a lot of the features over to Micro Drones, and possibly the Telemetry feature will be available there as well by then.

friend0 5 Oct @ 3:12pm

does the telemetry feature work on micro drones?

tifoha 22 Apr @ 10:19am

Maybe it worth to mention such feature of Unity in documentation above? Cause it is not obvious, that attitude axis has different interpretation

JuniorDiscart [author] 17 Apr @ 8:02am

@tifoha

The quaternion values are written out as delivered by the physics system. Please note that the Unity engine does not use the Z-axis as its up-axis. It uses the primary axes as follows:

[list]
[*] -/+X: left/right
[*] -/+Y: down/up
[*] -/+Z: backwards/forwards
[/list]

So I think you need to take into account the type of rotation system the engine works in as well in order to get the right values in Euler angles.

tifoha 17 Apr @ 7:34am

I found one strange thing:
According to documentation "Attitude (4 floats) - the drone's world attitude as a quaternion. Each quaternion component can be addressed individually as AttitudeX, AttitudeY, AttitudeZ and AttitudeW." but it seems that the order of attitude components is wrong. For example I'm using "The Drawing Board" map, my drone respawn at the ground, and initial quaterion is (-0.0000118161, 0.0000152106, 0.0004023837, 1.0000000000), but when I make a turn by Z axis (Yaw) clockwise I got this quaterion (0.0002670673, 0.6556074023, 0.0003331938, 0.7551018000) The second quaterion element was changed instead of third. What is the actual mapping of attitude quaterion?

Isopodus 2 Apr @ 10:12am

@JuniorDiscart

Thanks, please let me know if there will be any updates. I'll subscribe to this thread!

< >