¶ Standard exchange format for ACRIOS wMBus backend
¶ Introduction
This document provides example payloads, which are forwarded to the customer's backend or application. ACRIOS wMBus backend executes an HTTP POST request to provided URL. It is possible to set up a repetition strategy and authentication method while providing the URL. The data are forwarded at the end of the meters read-out cycle (when the gathering cycle ended or was given up having some meters unavailable).
¶ Endpoint URL
The endpoint URL can consist of up to three space-separated parts consisting of the following:
- the standard URL
- the authentication method
- the repetition strategy
An example of such a URL is provided here:
https://api.customersite.hu/api/data-input/post-data REPEAT:100:1000 X-AUTH-TOKEN:80856c4197c45120aafe6064c7a8a6886117302cb98a705de67d2cc966411f54
This configuration string means the following:
- POST is executed to: https://api.customersite.hu/api/data-input/post-data
- if other than 200 HTTP answer is received, then the send is repeated twice, once after 100 seconds and then after 1000 seconds
- X-AUTH-TOKEN with the value of 80856c4197c45120aafe6064c7a8a6886117302cb98a705de67d2cc966411f54 is used for authentication
The number of REPEATs is unlimited, but will be validated by an ACRIOS representative before being applied. Reasonable values are provided above in the example. The authentication type can be:
- X-AUTH-TOKEN:AABBCCDDEE
- bearer:eyJhbrciOiJIUzI1NiIsInR5cCI6IkptCJ9.eyJzdWIiOiyXJlayJ9.HudRUPghSabnRWOGIXyBQsdHdYwd32xG36fIvXw
- basic:somebase64valueEncodingNameAndPassword
- basic-in-header-base64:somebase64value
- basic-in-header-name-pass:name:password
- NOTHING - no authorization is done, but you can have HTTPS + unique URL for verification on your side.
The payload follows a common scheme, which is best defined by the examples below, for respective "parsers" settings used for meter devices. Some fields are always present, some are facultative.
¶ Parsers
In the server system, there are multiple parsing services, which are available for processing of received meter data. For development of a new user parser, it is possible to query existing "basic" parsers and then modify or "normalize" their output. It is also possible to write the meter data parser from scratch.
A custom parsers are written in python containing the parserEntrypoint() function, where the backend passed the received data (data), the representation of a registered meter from database meterFromDb and in the last argument, there is a generic backend context passed in.
Here is an example/template of a parser script containing query to wmbusmeters (https://github.com/weetmuts/wmbusmeters) based parser being run on the server and then modifying/normalizing the result:
import parser
import json
import asyncio
async def parserEntrypoint(data, meterFromDb, out):
print("--- Starting parser ---")
parsed = {}
# No data were received - abort parsing
if len(data) == 0:
out["parsed"] = parsed
return out
try:
# parser to JSON received raw data using wmbusmeters
entry = await parser.parserWmbus(data, meterFromDb, {}, analyze=False)
# example of "normalizing" the result of parsing to desired structure
if "meter" in entry and "media" in entry and \
entry["meter"] == "metername" and entry["media"] == "heat cost allocation":
print("ITN device")
parsed["type"] = "ITN"
parsed["value"] = entry["current_consumption_hca"]
# no error info..
# elif ...
# if no known parsed result detected - provide error instead
if not ("type" in parsed):
parsed["type"] = "error"
# if includeMeterInfo flag is set in meter metadata, then
# include meter information from DB to the parsed output
if "metadata" in meterFromDb:
if "includeMeterInfo" in meterFromDb["metadata"]:
if meterFromDb["metadata"]["includeMeterInfo"]:
parsed["meterFromDb"] = meterFromDb
out["parsed"] = parsed
return out
except Exception as ex:
# in case any exception occurs, return error
print("Exception occured!")
print(str(ex))
parsed["type"] = "error"
out["parsed"] = parsed
return out
# this line create an awaitable object for the backend to await
toawait = asyncio.ensure_future(parserEntrypoint(data, meterFromDb, {}))
Here are output examples of existing parsers, which work using a similar principle as shown above:
¶ 'maddalena_arrow'
{
owner: 'OWNER', /*Owner*/
unit: '901288000001234', /*IMSI*/
timestamp: '2023-01-29T14:35:49.987Z' /*Timestamp*/
data: [ /*Array of meters by unit*/
{
timestamp: '2023-01-29T14:35:09.896Z', /*Timestamp*/
unit: '901288000001234', /*IMSI*/
meterId: '12345678', /*ID of the meter*/
found: true, /*Variable true/false if meter was found*/
data: 'GUQkNIEHFCiEGaHtFg8Us8EebhsyfZ1wD9s=', /*Data before parsing in base64 format*/
parsed: {
type: 'water', /*Type 'water', or 'error' if exception occurs while parsing*/
value: 11.89, /*Value in m3*/
flags: [ /*Manufacturer specific flags*/
'Mechanical Fraud Is',
'Magnetic Fraud Is',
'Mechanical Fraud Was',
'Magnetic Fraud Was'
]
}
},
],
}
¶ 'metra_maddalena_engelmann_qundis_techem'
{
owner: 'OWNER', /*Owner*/
unit: '901288000001234', /*IMSI*/
timestamp: '2023-01-31T08:59:51.170Z', /*Timestamp*/
data: [
{
timestamp: '2023-01-31T08:52:54.755Z', /*Timestamp*/
unit: '901288000001234', /*IMSI*/
meterId: '12345678', /*ID of the meter*/
found: true, /*Variable true/false if meter was found*/
data: 'EX6yXmPuBQ7mLmCeAGKEAF2ozm8=', /*Data in base64 format before parsing*/
parsed: {
/*These two keys are mandatory (type and value)*/
type: 'ITN', /*Types(values): 'water' (m3),'heat'(kwh),'ITN'(-),'error'(-)*/
value: 106, /*Dimensionless quantity in parts*/
/*Keys below are optional*/
meterFromDb: {
id: '00BC614E', /*meter ID in hex format*/
owner: 'OWNER',
'added-date': '2022-12-16T09:38:31.183250',
endpoints: [],
groups: [
'group_name' /*Name of the group to which the meter is assigned*/
],
key: '',
metadata: {
device_type: 'HCA',
device_installation_date: '16.12.2022',
state: 'CR',
city: 'City',
street: 'Street',
entrance: '123',
floor: '0',
flat_number: '1',
owner_email: '',
surname: '',
name: '',
owner_address: '',
owner_contact: '',
datalogger_code: '',
description: '',
'Building_unique code': '',
Name_SVJ: 'SVJ',
Address_SVJ: '',
Web_SVJ: '',
Contact_mail_SVJ: '',
Contact_phone_SVJ: '',
parser_id: 'metra_maddalena_engelmann_qundis_techem',
tarif: 'tarif',
includeMeterInfo: true
},
parser_id: 'metra_maddalena_engelmann_qundis_techem',
'last-seen': '2023-01-31T08:52:54.753Z'
}
}
}
]
}
¶ 'kamstrup'
{
owner: 'OWNER', /*Owner*/
unit: '901288000001234', /*IMSI*/
timestamp: '2023-01-31T08:25:40.479Z', /*Timestamp*/
data: [
{
timestamp: '2023-01-31T08:09:53.372Z', /*Timestamp*/
unit: '901288000001234', /*IMSI*/
meterId: '72298841', /*ID of the meter*/
found: true, /*Variable true/false if meter was found*/
/*Data in base64 format before parsing*/
data: 'jEQtLEGIKXI0BI0gTdJW5yAMaX0ix/WZqqz9c9iMdQ+Ph3jF/TSKBQKwzQGEelzPly4CngI11W60mUcnVCfuQBxukK2x5+q6Y0aQ+7sKBxy9iP1oN7uaapQLEigBWbzlyD9tORcmcfAGHB+liS/f+iYVedgP76vGkX+RwA9Q7+bJGBK0AdLGQEI=',
/*Parsed data from meter*/
parsed: {
type: 'multical',
value: {
SlaveInformation: {
Id: '72298841',
Manufacturer: 'KAM',
Version: '1',
ProductName: 'Kamstrup 382 (6850-005)',
Medium: 'Heat: Outlet',
AccessNumber: '77',
Status: '00',
Signature: '0000'
},
DataRecord: [
{
'@id': '0',
Function: 'Instantaneous value',
StorageNumber: '0',
Unit: 'Wh',
Quantity: 'Energy',
Value: '16669000.000000'
},
{
'@id': '1',
Function: 'Instantaneous value',
StorageNumber: '0',
Unit: null,
Quantity: 'Manufacturer specific',
Value: '52245.000000'
},
{
'@id': '2',
Function: 'Instantaneous value',
StorageNumber: '0',
Unit: null,
Quantity: 'Manufacturer specific',
Value: '37816.000000'
},
{
'@id': '3',
Function: 'Instantaneous value',
StorageNumber: '0',
Unit: 'm^3',
Quantity: 'Volume',
Value: '785.850000'
},
{
'@id': '4',
Function: 'Instantaneous value',
StorageNumber: '0',
Tariff: '0',
Device: '1',
Unit: 'm^3',
Quantity: 'Volume',
Value: '56.000000'
},
{
'@id': '5',
Function: 'Instantaneous value',
StorageNumber: '0',
Tariff: '0',
Device: '2',
Unit: 'm^3',
Quantity: 'Volume',
Value: '0.000000'
},
{
'@id': '6',
Function: 'Instantaneous value',
StorageNumber: '0',
Unit: 'm^3/h',
Quantity: 'Volume flow',
Value: '0.009000'
},
{
'@id': '7',
Function: 'Instantaneous value',
StorageNumber: '0',
Unit: '°C',
Quantity: 'Flow temperature',
Value: '74.810000'
},
{
'@id': '8',
Function: 'Instantaneous value',
StorageNumber: '0',
Unit: '°C',
Quantity: 'Return temperature',
Value: '34.300000'
},
{
'@id': '9',
Function: 'Maximum value',
StorageNumber: '0',
Unit: 'W',
Quantity: 'Power',
Value: '11200.000000'
},
{
'@id': '10',
Function: 'Instantaneous value',
StorageNumber: '0',
Tariff: '1',
Device: '0',
Unit: 'Wh',
Quantity: 'Energy',
Value: '0.000000'
},
{
'@id': '11',
Function: 'Instantaneous value',
StorageNumber: '0',
Tariff: '2',
Device: '0',
Unit: 'Wh',
Quantity: 'Energy',
Value: '0.000000'
},
{
'@id': '12',
Function: 'Instantaneous value',
StorageNumber: '0',
Unit: null,
Quantity: 'Manufacturer specific',
Value: '0.000000'
},
{
'@id': '13',
Function: 'Instantaneous value',
StorageNumber: '0',
Unit: '-',
Quantity: 'Time point (date)',
Value: '2023-01-31'
},
{
'@id': '14',
Function: 'Instantaneous value',
StorageNumber: '1',
Unit: 'Wh',
Quantity: 'Energy',
Value: '15263000.000000'
},
{
'@id': '15',
Function: 'Instantaneous value',
StorageNumber: '1',
Unit: 'm^3',
Quantity: 'Volume',
Value: '743.340000'
},
{
'@id': '16',
Function: 'Instantaneous value',
StorageNumber: '1',
Tariff: '0',
Device: '1',
Unit: 'm^3',
Quantity: 'Volume',
Value: '51.400000'
},
{
'@id': '17',
Function: 'Instantaneous value',
StorageNumber: '1',
Tariff: '0',
Device: '2',
Unit: 'm^3',
Quantity: 'Volume',
Value: '0.000000'
},
{
'@id': '18',
Function: 'Instantaneous value',
StorageNumber: '1',
Unit: '-',
Quantity: 'Time point (date)',
Value: '2023-01-01'
}
]
},
flags: [
'OK'
]
}
}
]
}