Example Code

Table of contents

1. Overview
2. Start a New Application: voxl-cross-template
3. MPA Pipe Basics: libmodal-pipe Examples
4. Reference Clients: Reading Each Pipe Type
5. Configuration Files: libmodal-json Examples
6. Offboard Control
7. Bridges

Overview

The VOXL SDK ships working example code at several levels, from a complete buildable package template down to single-file pipe readers. This page catalogs the examples that exist today and what each one demonstrates, so you can start from running code instead of a blank file.

Start a New Application: voxl-cross-template

voxl-cross-template is the starting point for a new VOXL application. It is a complete, buildable package that reads IMU data from MPA and prints it, and it carries the standard ModalAI project structure: clean.sh, build.sh, make_package.sh, and deploy_to_voxl.sh, producing a deb you install on VOXL.

The Developer Bootcamp walkthrough covers the full workflow: cloning the template, building it inside the voxl-cross docker image, and deploying it to a VOXL. Start there, then rename and extend the template into your own package following the packaging standards.

MPA Pipe Basics: libmodal-pipe Examples

The libmodal-pipe examples directory contains minimal single-file programs for the core pipe patterns. Read these to understand servers, clients, and control pipes before writing your own:

The core of a pipe client is small. Condensed from modal-hello-client.c:

// called whenever the simple helper has data for us to process
static void _simple_cb(int ch, char* data, int bytes, __attribute__((unused)) void* context)
{
    printf("received %d bytes on channel %d: %s\n", bytes, ch, data);
    return;
}

int main(int argc, char* argv[])
{
    int flags = CLIENT_FLAG_EN_SIMPLE_HELPER;

    // assign callbacks for data, connection, and disconnect
    pipe_client_set_simple_helper_cb(CLIENT_CH, _simple_cb, NULL);
    pipe_client_set_connect_cb(CLIENT_CH, _connect_cb, NULL);
    pipe_client_set_disconnect_cb(CLIENT_CH, _disconnect_cb, NULL);

    // init connection to server. In auto-reconnect mode this will "succeed"
    // even if the server is offline, but it will connect later on automatically
    ret = pipe_client_open(CLIENT_CH, PIPE_NAME, CLIENT_NAME, flags, PIPE_READ_BUF_SIZE);

    // keep going until signal handler sets the main_running flag to 0
    while(main_running) usleep(500000);

    pipe_client_close_all();
    return 0;
}

See Developing in MPA for the concepts behind these, and libmodal-pipe for the library reference.

Reference Clients: Reading Each Pipe Type

The inspect tools are small, readable programs, most one file each, that subscribe to a specific pipe type and print it. When you need to consume a particular data stream, the matching inspect tool source is a working reference for that pipe’s data format and helper functions:

The full set covers every standard pipe type; browse the voxl-mpa-tools tools directory for the rest, and the inspect tools overview for what each prints.

Configuration Files: libmodal-json Examples

ModalAI services read and write their /etc/modalai/*.conf files through libmodal-json. The libmodal-json examples show the read-modify-write pattern services use, which is also the right pattern for your own application’s config file. See libmodal-json for the library reference.

Offboard Control

fixed_frame_pipe_example.c in voxl-vision-hub shows how to feed fixed-frame poses into the vision hub from your own process. The Figure 8 demo documents the built-in offboard trajectory modes, and MAVSDK covers commanding the vehicle from an external program over MAVLink.

Bridges

To consume MPA data in other ecosystems, voxl-mpa-to-ros and voxl-mpa-to-ros2 republish pipes as topics; setup is covered in the ROS and ROS 2 installation guides.