[TerkinTelemetry] Renovations to improve the library interface, and to make things work

[amotl]

About

In order to do the right thing, this patch renovates the TerkinTelemetry library a bit. It also adds a README, and runnable example programs, aiming to make it a first citizen of the library code provided by this repository, alongside the BERadio C++ and TerkinData C++ libraries.

Synopsis

Transmit sensor measurement readings from Arduino and libc environments, for humans. ¹

telemetry->transmit(measurement);

Details

The library is still in its infancy, being very much work in progress, but at least this patch is another iteration which actually makes a few things work, where they did not work beforehand. While working on this iteration, I've adjusted a few class names, and removed one layer of indirection.

Now, there are three classes you will use to configure a telemetry client instance, each with a specific subset of connectivity parameters. This design aims to make the library as modular as intended, without overcomplicating it.

• ChannelAddress: You will use it to define the data acquisition channel your device will submit data to. It reflects the venerable quadruple hierarchic addressing scheme we are using for connecting, addressing, and mapping individual sensor node devices in a wide-area scenario.
• XyzTransmitter: You can select one of the available transmitter components, in order to define which kind of outbound transport you are intending to use. There are different kinds of transmitter components included into TerkinTelemetry, but it is possible to bring your own.
• TelemetryClient: The telemetry client instance your code will interact with, in order to actually submit measurement/metric values, after reading your sensors.

I am not sure this will turn out well, but it is worth to explore. More details are available on our discussion forum at ².

Usage

Setup

// The address of the data acquisition channel.
ChannelAddress* address = new ChannelAddress(CHANNEL_REALM, CHANNEL_OWNER, CHANNEL_SITE, CHANNEL_DEVICE);

// The actual transmitter element.
// Choose and configure a suitable transmitter, and that's it.
JsonHttpTransmitter* transmitter = new JsonHttpTransmitter(KOTORI_URL);
JsonMqttTransmitter* transmitter = new JsonMqttTransmitter(MQTT_TOPIC);
CrateDBTransmitter* transmitter = new CrateDBTransmitter(CRATEDB_URL, CRATEDB_USERNAME, CRATEDB_PASSWORD);
InfluxDBTransmitter* transmitter = new InfluxDBTransmitter(INFLUXDB_URL, INFLUXDB_USERNAME, INFLUXDB_PASSWORD);

// The telemetry client you will use for transmitting, see below.
telemetry = new TelemetryClient(transmitter, address);

Collect and transmit

// Collect sensor data.
TerkinData::Measurement measurement;
measurement.data["temperature"] = 42.42;
measurement.data["humidity"] = 80;

// Transmit measurement to telemetry data collection server.
telemetry->transmit(measurement);

/cc @msweef, @einsiedlerkrebs, @wetterfrosch, @Tonkenfo, @thiasB, @ClemensGruber, @marcelgasser, @rohlan

Footnotes

1. The idea of TerkinTelemetry is to bring the flexibility of the telemetry subsystem of the Terkin MicroPython Datalogger on behalf of the self.device.telemetry.transmit(dataframe) within its transmit_readings() method, to the Arduino ecosystem. ↩

2. https://community.hiveeyes.org/t/telemetriesubsystem-fur-arduino-firmwares-generalisieren/181/14 ↩