Yoctopuce modules are components intended to be integrated into measure and automation systems. The most common method of integration is to add our library to the system control code, but we also offer the possibility to integrate them via HTTP callbacks to third party services. We have recently expanded the possibilities of this type of integration.
Technically, HTTP callbacks work on the same principle as most of the connected objects you can buy in supermarkets these days: the Yoctopuce network module sends a request to a web server that can be anywhere on the Internet to transmit its latest measures.
The big difference lies in the infrastructure used: while the most common connected objects use a proprietary web server, which will be shut down one day and render the connected object unusable, you can configure Yoctopuce modules to connect to the server of your choice, over which you have complete control. This is much more reliable in the long run, but it requires:
- on your part to choose and configure a web service that works for you
- on the part of Yoctopuce to offer enough flexibility for data transmission methods
On this last point, we have recently added a new option that allows you to better customize the way data is transmitted via HTTP callbacks.
Names associated with posted values
With the exception of Yocto-API callbacks which give access to all the information about Yoctopuce modules, HTTP callbacks are designed to transmit only the most important information to the server, associating each value with a name which enables you to easily link it to its origin.
The standard behavior is to transmit the value of the advertisedValue attribute for each function present on the Yoctopuce modules. The name automatically associated to each value follows the following logic:
- If a logical name has been defined for a function:
FUNCTION_LOGICAL_NAME = VALUE
- If a logical name has been defined for the module, but not for the function:
MODULE_NAME.HARDWARE_NAME = VALUE
- If no logical name has been assigned:
SERIAL_NUMBER.HARDWARE_NAME = VALUE
The easiest way to customize the names associated with the values is therefore to set the desired name as the logical name of the function, or otherwise as the logical name of the module itself. For example, for a system with a Yocto-Watt where each function has been given an explicit logical name (e.g. VoltageDC) and a Yocto-Meteo-V2 where the module itself has been given the logical name Ambient, the basic format used for InfluxDB looks like the example below:
CurrentAC=0,CurrentDC=0,VoltageAC=0,VoltageDC=0,Power=0,
Ambient_temperature=22.5,Ambient_pressure=948.63,Ambient_humidity=29.4
1678281649
This basic format associates all the values to a yoctopuce measure database and adds a name tag with the network name of the hub and an ip tag with its IP address. Then, each value is posted in a field whose name follows the basic convention described above. The data are transmitted by HTTP POST on a single line, but they have been put here on several lines to facilitate reading.
Advanced customization with a file
Here is the novelty: if you wish to further customize the format of the transmitted data, to specifically select which attribute of which module should be sent under which name, or to add contextual information, it is now possible... even if it is a little more complicated. You have to create a template file defining the exact format of the data to be sent. The content and name of this file is specific to each type of HTTP callback.
The content of the template file is sent as is to the server, with the exception of expressions enclosed in backquote (or backtick, the ` character, ASCII code 96) which is evaluated by the REST interface of the Yoctopuce modules. For example, if the template file contains the text:
and it is used on a YoctoHub-Ethernet, then the actual content posted is
If we take the previous example of InfluxDB, to customize the data format we need to create a format template file on the YoctoHub with the name INFLUXDB_cb.fmt (for InfluxDB v1.0), or INFLUXDB_V2_cb.fmt (for InfluxDB v2.0).
This file can have several lines if you want, which allows you to use different tags for different measures, or even to split measures over several databases. For example, to post absolute and relative humidity simultaneously, but with different tags, you could use the following format file:
humidity,type=absolute,location=Library absHum=`/byName/Ambient/api/humidity/absHum`
Attention: the InfluxDB server only accepts carriage returns in UNIX format (character \n, also called LF). If you edit the file on a Windows machine, take care to use a text editor able to not add the Windows carriage return (\r\n, also called CR LF).
Some tips
If you want to check the result produced by your template file after substitution, you can ask YoctoHub to show the result live using the built-in web server. To do this, open with a browser the URL corresponding to the name of the template file on your hub, preceded by the famous ` character:
http://w.x.y.z:4444/`INFLUXDB_V2_cb.fmt
The possibility to use a template file is not limited to the use of a YoctoHub: you can also use it with the VirtualHub software on a computer. But for that, you need to run VirtualHub with the -F container.tar option which enables you to upload files on VirtualHub as you can do on a YoctoHub.
