A lightweight, intuitive and well tested communication protocol

24 Feb 2016

For all people struggling to achieve efficient communication between any Mbed device and a computer, or annoyed to always reimplement a serial protocol for each new project, I just wanted to share a nice library I wrote (For the same exact reasons).

Telemetry

https://github.com/Overdrivr/Telemetry

The syntax is super clean :

#include "telemetry/Telemetry.hpp"

int main()
{
   Telemetry TM;

   for( ; ; )
   {
       TM.pub("someTopic","Hello, World !");
   }
}

Of course it also possible to send numbers in all portable datatypes

#include "telemetry/Telemetry.hpp"

int main()
{
   Telemetry TM;
   int8_t i;
   uint16_t j; 
   float f;
   for( ; ; )
   {
       i++;    j = i * 10;   f = i / 100.0;
       TM.pub_i8("foo",i);
       TM.pub_u16("bar",j);
       TM.pub_f32("qux",f);
       // also i16, i32, u16, u32, etc...
   }
}

Data is exchanged on named channels called topics. Data can be also be received easily and in a safe manner on the device (without the need for ugly hacks such as global variables):

struct TM_state {
   int8_t myParameter;
};

void process(TM_state * state, TM_msg * msg)
{
    int8_t received;
    if(emplace_i8(mgs, &received)) // Write on any received topic if datatype matches uint8
    {
        state->myParameter = (received <= 5) ? received : 5 ; // Only write if safe (e.g. < 5)
    }
}

int main()
{
   Telemetry TM;
   TM_state state;
   Tm.subscribe(process, &state); // Pass `state` data to the process function 

   for( ; ; )
   {
       TM.update(); // state.myParameter updated in process(..) and also accessible in main
   }
}

Parameters that needs to be written remotely just need to be stored in a TM_state data structure, so that they can be passed safely to the called-back function called process here. This function is implemented by you and is called everytime a frame is received.

On the desktop

The power of this library also comes from the desktop command line interface Pytelemetrycli

https://github.com/Overdrivr/pytelemetrycli https://badge.fury.io/py/pytelemetrycli.svg

/media/uploads/Overdrivr/console.png

This command line interface (CLI) allows you to type a few commands to communicate and check the state of your device. You can write any type of data from the CLI to the device, see all available reception channels and even... open realtime plots

/media/uploads/Overdrivr/graph.png Output in live of the NXP Freedom KL25Z capacitive slider

It is also possible to write scripts with the underlying python implementation of the C protocol, called Pytelemetry:

https://github.com/Overdrivr/pytelemetry https://badge.fury.io/py/pytelemetrycli.svg

It allows for very clean and linear syntax for scripting the behavior of a remotely controlled device

from pytelemetry import Pytelemetry
from pytelemetry.transports.serialtransport import *

transport = SerialTransport()
tlm = Pytelemetry(transport)

transport.connect({'port': 'com20', 'baudrate': 9600})
tlm.publish('sometopicWhatever',4,'int8')

transport.disconnect()

Even if you don't speak the Python, I feel it is very readable and easy to understand.

Summary

Enjoy and don't hesitate to post your feedback !