Droneforge SDK

Because telemetry is provided via shared memory, you should validate the age of the data using the timestamp_us field (microseconds since epoch) provided in every data structure. This ensures you are not acting on stale data if the service or hardware stops updating.

Example logic to check if data is less than 100ms old:

auto battery = client.getBattery();
if (battery) {
    auto age_ms = (getCurrentTimestamp() - battery->timestamp_us) / 1000;
    if (age_ms < 100) {
        // Data is fresh
    }
}

auto battery = client.getBattery();
if (battery) {
    auto age_ms = (getCurrentTimestamp() - battery->timestamp_us) / 1000;
    if (age_ms < 100) {  // Data is fresh (< 100ms old)
        // Use battery data
    }
}

Expressions are the primary way to define agent behavior by connecting inputs (sensors/parameters) to outputs (controls).

Workflow:

1. Create a node (building block).
2. Connect nodes via lines (connecting an output of one block to an input of another).
3. Write an expression in the block to describe the logic.

Syntax Rules:

• Single Formulas: An expression can be a simple math formula like input * 0.5.
• Multiple Assignments: Use semicolons to assign multiple outputs in one block, e.g., roll = 992; throttle = 200.
• Order of Operations: Use parentheses to control evaluation, e.g., (a + b) * 2.
• Operators: Supports math (+, -, *, /), comparisons (==, !=, <, <=, >, >=), and logic (&&, ||).

// Example: Multiple assignments
roll = 992; pitch = 992; yaw = 992; throttle = 200

The service requires a serial port and a baud rate as command line arguments.

Common Baud Rates:

• 420000 (ExpressLRS/ELRS)
• 400000 (ELRS alternative)
• 115200 (Standard CRSF)

Execution Examples:

Linux:

./droneforge-crsf-service /dev/ttyUSB0 420000

Windows:

droneforge-crsf-service.exe COM3 420000

# Linux
./droneforge-crsf-service /dev/ttyUSB0 420000

# Windows
droneforge-crsf-service.exe COM3 420000

To build the service from source, you need a C++17 compatible compiler (GCC 8+, Clang 7+, or MSVC 2019+), CMake 3.16+, and the fmt library.

Linux/macOS

# Clone and enter directory
git clone https://github.com/your-org/droneforge-crsf-service.git
cd droneforge-crsf-service

# Build
mkdir build && cd build
cmake ..
make -j$(nproc)

Windows (Visual Studio)

# Clone and enter directory
git clone https://github.com/your-org/droneforge-crsf-service.git
cd droneforge-crsf-service

# Build
mkdir build && cd build
cmake .. -G "Visual Studio 16 2019"
cmake --build . --config Release

To run your agent on a drone:

1. Select Agent: In the Build Tab, ensure the correct agent is selected in the left sidebar.
2. Connect (VRX Controls):
   • Bind: Put your drone into bind mode (unplug/plug 3 times until flashes change from quick to single). Click Bind in the Deploy tab.
   • Scan: If the video feed is black, use Scan to cycle 5.8 GHz bands until the transmission is found.
3. Configure Profile: In the Deploy Tab, set the drone's mass and KV for accurate physics.
4. Execute: Click Play to deploy the agent. Click Pause to stop it.

Warning: Always keep a hand on your safety switch or emergency stop when playing.

For most applications, use the TelemetryStore singleton to access real-time telemetry data. It provides a convenient, globally accessible interface that manages an internal TelemetryClient instance.

To use it, call getInstance() to get the singleton reference, then call connect() to establish the shared memory connection before attempting to read data.

#include "telemetry_client.h"

void monitor_drone() {
    auto& telemetry = droneforge::telemetry::TelemetryStore::getInstance();

    if (telemetry.connect()) {
        while (telemetry.isConnected()) {
            if (telemetry.hasNewData()) {
                auto attitude = telemetry.getAttitude();
                if (attitude) {
                    // Use attitude->pitch, attitude->roll, etc.
                }
            }
        }
    }
}

Service fails to start

• Linux Permissions: Ensure the user has serial port access: sudo usermod -a -G dialout $USER.
• Device Path: Verify the device exists using ls /dev/ttyUSB* or ls /dev/ttyACM*.
• Baud Rate: Ensure the baud rate matches your CRSF device configuration (e.g., 420000 for ELRS).

No telemetry data

• Verify the CRSF device is actually transmitting telemetry.
• Check flight controller CRSF telemetry settings.
• Monitor the service output for CRSF frame reception messages.

Client connection fails

• Service Status: Ensure the service is running before starting your client application.
• Shared Memory Permissions: On Linux, check access to /dev/shm/.
• Conflicts: Ensure no other processes are using the shared memory segment.

Practical expression snippets for common tasks:

PID Control for Yaw: Center on a target when it is visible:

yaw = pid(320, target_x, 0.8, 0.0, 0.1, 300)

Smooth Ramping: Smoothly ramp throttle over 2 seconds:

throttle = lin(172, 600, 2.0)

Latching/Memory: Latch a flag (aux1) the first time a target appears:

aux1 = mem(1800, target_visible, 0, 1)

One-time Randomization: Apply a randomized hover nudge that is evaluated only once:

roll = once(randrange(50)) - 25

// Center on a target when it is visible
yaw = pid(320, target_x, 0.8, 0.0, 0.1, 300)

The TelemetryClient class provides the primary interface for accessing telemetry via shared memory IPC.