Decoding OpenAMR payloads for Maddalena LoRaWAN water sensors

Maddalena IoT-enabled water meters

Maddalena s.p.a. is an Italian company providing water readers that are frequently used in Belgium and across Europe. Water meters such as the PR-MWM can detect the lowest flow rates (from 0.5 liters / hour). So this makes them, according to this company, “the ideal meter for billing cold water consumption in collective housing”.

Maddalena understood the market’s need for connected meters quite well. So they teamed up with Kerlink to create a LoRaWAN™ add-on radio module. This module makes it possible to collect water consumption data over long distances. Its battery life can last up to 15 years thanks to the low power requirements of LoRaWAN and an optimization in the way this module works.


Payload challenges

As you may know, there is no unique or universal payload format definition when it comes to LoRaWAN. Every vendor uses the protocol’s payload capacity to his own liking. Some use it adhering to format such as Cayenne LPP, but most implement their own format. When it comes to utility meters (such as for water or electricity), vendors tend to adopt mostly the Wireless M-Bus (Wireless Meter-Bus) protocol and adapt it over LoRa MAC in our case. The Maddalena LoRaWAN add-on module for the MWM water meters has taken this approach and uses Kerlink’s OpenAMR-MBUS payload formatting.

Proximus MyThings can offer payload decoding for many known LoRa device vendors such as Ascoel, eWattch, Adeunis, Sagemcom, etc. But when it comes to Maddalena connected meters over LoRaWAN, there is some additional payload deciphering to deal with.

On top of the standard LoRaWAN network and application encryptions, the Kerlink OpenAMR format implies that data coming from the same meter will be further enciphered. You can use a set of different encryption keys for each device. This means that each message coming from the same device may be using a different encryption key. Obviously, the set of keys is different for each device. This extra encryption/decryption raises the complexity on the end-to-end flow. Meaning that either your LoRaWAN provider has quite advanced payload decoding capabilities to offer or you need an extra application stack on your side to decode the data payload before injecting it in your metering or reporting solution.

EnCo CloudEngine Maddalena module

In April, we’ve added a Maddalena decoder module in the Proximus EnCo CloudEngine*. Resulting from our continuous effort to facilitate the integration of IoT data coming out of our LoRaWAN, M2M and soon NBIoT networks.

*As a reminder: the CloudEngine (CloE) is an event hub with an Integrated Development Environment (IDE). CloE ingests events from multiple sources, routes to multiple external sources and allows data transformation via advanced scripting in the middle.


Step 1: Maddalena decoding

For Maddalena decoding, we need to provide the module with:

  • the DevEUI from the LoRa network (64-bit unique device identifier on LoRaWAN networks)
  • the hexadecimal message to be decoded
  • the LoRa port to which this message was sent or FPort. Because it will be required for the Initialization Vector to decrypt the ciphered payload
  • an array of the keys that can be used to decode payloads from the device

The CloudEngine’s Configuration Store is used to store a text file associating the DevEUI with the multiple device-specific encryption keys. This file’s content just needs some structure, such as comma or semi-column separated fields.


Step 2: CloE script

The second step is to create a CloudEngine script that ingests data coming from Proximus’ LoRaWAN network (ie “Proximus MyThings”). For each incoming Maddalena message, the script needs to:

  1. Extract the necessary data from the incoming message: DevEUI, FPort and hexadecimal undecoded payload
  2. Parse the stored text file containing the device decoding keys to fetch this device’s specific keys
  3. Decode the payload using the CloudEngine Maddalena module. This is most probably the simplest part of the script, just a single line like this:
    object valueArray = maddalena.decode(deveui, payloadObject, port, keysForDevice);
    The script returns an array with all decoded values contained in the message, like the example below:
    [2019-04-29T00:00:00=259, 2019-04-30T00:00:00=259, 2019-04-28T00:00:00=259]
  4. Send each of the decoded readings to the desired platform using the CloudEngine outbound modules. Outbound modules such as Microsoft Azure Event Hub or IoT Hub, SAP IoT Leonardo, HTTP, MQTT, sFTP, etc.

You can find a complete example script in the inline documentation of the Maddalena module in the Proximus EnCo CloudEngine.

Do you work with LoRaWAN devices coming with complex payload decoding requirements? And would you like to have a standard module in our CloudEngine? Reach out and let us know by dropping a note to !

Author: API Solutions Team

Biographical Info