Tutorial (C API)

This tutorial will guide you on how to publish some data from an embedded platform, to your computer, in just a few lines of code. Then, you will learn how to write, from the computer, parameters on the embedded platform.

Publishing

In the main.c file, start off by initializing the library.

If you are on a supported platform:

void main()
{
   init_telemetry();

On non officially supported platforms (see Setup on a new platform)

void main()
{
   TM_transport transport;
   // [..] transport initialization
   init_telemetry(&transport);

Now, publishing on a topic called "foo" every hundred milliseconds can be done simply with

   for( ; ; )
   {
       publish_i32("foo",123);
       sleep(0.1); // sleep to avoid overflowing UART
   }

If you connect to the device with pytelemetrycli, you can run a few commands to observe the result desktop-side: todo : animated ttty gif

 >: ls
foo
 >: print foo
123

Overview of the complete script

Subscribing

Minimal code

At this point, you know how to send the data from the device to the computer. But what about the other way? What about sending data from the computer so you can control the device at distance?

telemetry can notify you by calling one of your own custom function every time a frame is received. This is called subscribing. Here is how you do it.

First, declare a function with the following signature. It must return void, and have two arguments TM_state and TM_data. You will understand later the reason behind it and the flexibility it provides.

void myCustomFunction(TM_state * state, TM_data * data)
{
    // For now, do nothing
}

As said previously, in the main function, myCustomFunction must be subscribed. This way, each time data is received from the computer (= a topic + a value), telemetry will notify you by calling myCustomFunction from update_telemetry.

Let's see a practical example with the following code.

static uint8_t myInc;

void myCustomFunction(TM_state * state, TM_data * data)
{
    myInc++;
}

void main()
{
    myInc = 0;
    init_telemetry();
    subscribe(myCustomFunction); // Subscribe our function to be notified 

    for( ; ; )
    {
        update_telemetry();
    }
}

In this code, what happens ? Well, each time a new frame is received, myCustomFunction is called and the variable myInc is incremented.

Filtering by topic

What if you wanted to increment only if the received topic was foofoo ? Just a couple of modifications are required.

#include "string.h"
static uint8_t myInc;

void myCustomFunction(TM_state * state, TM_data * data)
{
   // See http://www.cplusplus.com/reference/cstring/strcmp/
   if(strcmp("foofoo",data->topic) == 0)
   {
      // topic matches foo, so increment
      myInc++;
   }
}
// no change in main()

Filtering by topic and received data type

Even better, what if you wanted to increment myInc only if the received data was of type uint8_t ? Again, just a couple of modifications are required to myCustomFunction.

#include "string.h"
static uint8_t myInc;

void myCustomFunction(TM_state * state, TM_data * data)
{
   if(strcmp("foofoo",data->topic) == 0)
   {
      if(data->type == TM_uint8) // Filter by datatype
      {
          myInc++;
      }
   }
}
// no change in main()

This way of specifying behavior is extremely flexible. You build your application with the protocol, and it doesn't get in the way. What if, on topic booyaa you wanted to start a function, but on topic PID you need to register values somewhere ? Using telemetry, there is nothing preventing you to do so.

Now, you may have noticed that, to store received values in a variable, a global variable (myInc) was used. There is a better way to make data accessible from myCustomFunction and the main function. This is covered in the next tutorial called Advanced usage.

You may also want to check at this point the list of examples.