Utility translators
The utility group is what is left once the other categories have taken what they describe: translators that configure another translator, decode a generic format, correct an upstream one, or exist to be read as worked examples.
Decoding Modbus
Modbus is not a self-describing format. The same bytes are a temperature, a flow rate or a serial number depending on a register layout that only the installer knows, so a generic decoder needs that layout supplied to it.
| Translator | Role |
|---|---|
modbus | The generic decoder. Takes a hex-encoded Modbus payload and decodes it according to the register layout in contextMap.modbusRegisters. Chained, typically behind a Watteco or Enginko Modbus-over-LoRaWAN bridge, but it works with any source producing a contiguous hex payload |
Each register in modbusRegisters is described by a fieldName, a dataType of float, int or uint, a length of 1 for a 16-bit register or 2 for 32-bit, a scale multiplier, and an encoding of BE or LE. The endianness matters and is not guessable: getting it wrong produces numbers rather than errors.
Unlike the rest of the platform, modbus reads its layout from contextual parameters rather than translator parameters, because the layout is a list of register descriptions rather than a set of named values.
If you are bringing a common meter onto the platform, check the A–Z catalogue first. Several vendors have dedicated presets, such as the Kamstrup Multical and Ambiductor decoders, which already carry the correct register configuration.
Correcting an upstream translator
| Translator | Role |
|---|---|
xovis-field-inverter | Swaps the in and out direction on the output of xovis-pc2se-people-line-counter, across every count it produces: live, daily, total, and the long and short variants. For a sensor mounted facing the opposite way to the one the counter assumes |
Mounting a counter the other way round is a physical fact you often cannot change after installation. Inverting in software keeps the data correct without anyone having to remember that this one device counts backwards.
Examples for translator developers
These three exist to be read. They are working translators, and they are the shortest path to understanding the shape of one before you write your own.
| Translator | Demonstrates |
|---|---|
example-regular | The basic shape: decoding a hex payload into a temperature, a status and a timestamp, reading several data types out of binary and returning them in the result |
example-parameterized | The parameters feature, applying a scaleFactor and an offset supplied by the user |
example-timeseries | Returning a timeseries rather than a single reading, taking a payload where each byte is a temperature one minute further into the past |
For writing your own, see Translator Development.
For the full A–Z index of every translator, see the translators overview.