Advanced usage

Access variables between notification function and main

So far in the basic examples, only global variables were modified from the subscribed function.

static uint8_t myInc;

void myCustomFunction(TM_state * state, TM_msg * msg)
{
    myInc++;
}

struct TM_state {
};

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

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

While this is easy to understand, it is usually better to avoid using global variables. This is where the TM_state data structure becomes useful.

TM_state can be seen as a shared space where you will store writeable parameters. Shared, because it will be possible to access it from the main function, but also from the subscribed function.

This is an equivalent of the previous code using TM_state instead of global variables.

void myCustomFunction(TM_state * state, TM_msg * msg)
{
    state->myInc++;
}

struct TM_state {
    uint8_t myInc; // myInc is no longer a global variable
};

void main()
{
    TM_state state; // the shared space for writeable parameters
    state.myInc = 0;

    init_telemetry();
    
    // Pass the shared state by pointer so we can access it inside myCustomFunction(..)
    subscribe(myCustomFunction, &state); 

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

Of course, you can add as many parameters to the TM_state structure.

Send complex data

Sometimes, you will need to send from the embedded device some more complex data than just plain numbers. Telemetry offers some support for several complex structures by inserting extra indentifiers inside the topic character string.

Groups

Special character : / (slash)

foo/bar, somedata

foo/qux, 123

Indexed topics (arrays, sparse arrays)

Special character : : (two-points)

foo:1, myArray[1]

foo:2, myArray[2]

foo:5, myArray[5]

Hash-tagged topics (spatial coordinates and matrix)

Special character : # (hashtag)

foo#xy, 0.1, 0.5

foo#xyz , 0.1, 0.5, 0.8

foo#m22 , 11, 12, 21, 22