The backend is used for easy over-the-air configuration of our WM-Bus converter and is used mostly by integrators with their own frontend application. Backend currently supports integration to the NB-IoT provider M2MC - www.miotiq.com.
The backend is currently running at https://backend.wmbus.acrios.com/docs
For data exchange interface descripton, please check: - Wireless M-Bus backend - data exchange interface
The backend is divided into the 2 main groups - units and user group. Within the units group you can modify anything regarding the specific unit, its settings and WMBUS ID's. Within the user group can modify global settings, such are default unit configuration, list of the WMBUS ID's, reading out all of the units or setting the data endpoints.
Unit - Wireless M-Bus converter
WMBUS ID - Specific radio modul with its ID. For example a single water meter.
User - Usually a company or a specific person using the backend
Currently only the NB-IoT converter is supported. Support for the LoRaWAN version of the converter will follow.
The backend communicates with a frontend via REST API and data are in JSON format. The integration can be done via POST and GET requests or events can be captured using WebSocket API. For the request, bearer tokens are used.
The backend is provided to the customer.
For the integration with other NB-IoT providers please reach out to us at smetana@acrios.com
Within the User group, there are followoing subgroups that enable you to set the global atttributes:
GET /units will return you the list of units that are registered in backend application. With the POST you can enter a new unit with its unique IMSI. While entering a new unit, there is a possibility to enter a configuration which will overwrite the default configuration entered at the /default-config.
Allows you to add a new unit to the backend
Any of the field can be left empty by inserting [ ].
{
"gatherTimeSeconds": {
"sMode": 0,
"tMode": 120
},
"timePerDeviceSeconds": 120,
"wakeUpPeriod": {
"days": 0,
"hours": 8,
"minutes": 0
},
"url": [],
"uplinkDataAction": "posting-and-logging",
"ids": []
}
{
"units": [
{
"IMSI": "901288002328171"
},
{
"IMSI": "901288002328178"
},
{
"IMSI": "901288002328179"
}
],
"action": "add"
}
GET /wmbus-ids will return you the list of WMBUS ID's that are needed to be read remotely. POST /wmbus-ids add a new ID's. This function is being used when there are no specific ID's set directly to the converter and you want to use the automatic allocation instead.
Allows you to add a new WMBUS ID
{
"ids": [
"12345678, 98765432"
],
"action": "add"
}
{
"ids": [
"12345678, 98765432"
],
"action": "remove"
}
GET /default-config will return you the current default global configuration. POST /default-config will alow you to manipulate a new global configuration.
Allows you to manipulate a new global configuration
{
"gatherTimeSeconds": {
"sMode": 0,
"tMode": 120
},
"timePerDeviceSeconds": 120,
"wakeUpPeriod": {
"days": 0,
"hours": 8,
"minutes": 0
},
"url": [],
"uplinkDataAction": "posting-and-logging",
"ids": []
}
GET /debug will show you all messages from all units. POST /debug allows you to clear the log.
Allows you to see a NB log for debugging purpose
{
"owner": "ACRIOS",
"msg": "scan: {\"deviceType\": 128, \"id\": \"40876203\", \"manufacturerId\": \"0x5068\", \"RSSI\": -88}",
"timestamp": "2021-08-11T11:35:25.023219"
},
{
"owner": "ACRIOS",
"msg": "scan: {\"deviceType\": 128, \"id\": \"40876490\", \"manufacturerId\": \"0x5068\", \"RSSI\": -71}",
"timestamp": "2021-08-11T11:35:25.033827"
},
{
"owner": "ACRIOS",
"msg": "scan: {\"deviceType\": 128, \"id\": \"24714874\", \"manufacturerId\": \"0x5068\", \"RSSI\": -85}",
"timestamp": "2021-08-11T11:35:25.045174"
},
{
"owner": "ACRIOS",
"msg": "scan: {\"deviceType\": 55, \"id\": \"83816928\", \"manufacturerId\": \"0x5068\", \"RSSI\": -101}",
"timestamp": "2021-08-11T11:35:25.057938"
}
Same function as the /debug but this one will give you the debug log in txt form.
2021-08-11T11:31:52.216353 (ACRIOS): upload: Received 1 bytes from unit 901288002328171
2021-08-11T11:31:52.221150 (ACRIOS): gather: {"idsReceived": [], "idsNotFound": []}
2021-08-11T11:34:09.543372 (ACRIOS): upload: Received 244 bytes from unit 901288002328171
2021-08-11T11:34:09.549394 (ACRIOS): scan: {"deviceType": 128, "id": "40876594", "manufacturerId": "0x5068", "RSSI": -95}
2021-08-11T11:34:09.578163 (ACRIOS): scan: {"deviceType": 128, "id": "40879989", "manufacturerId": "0x5068", "RSSI": -82}
2021-08-11T11:34:09.591836 (ACRIOS): scan: {"deviceType": 128, "id": "31674215", "manufacturerId": "0x5068", "RSSI": -97}
2021-08-11T11:34:09.606577 (ACRIOS): scan: {"deviceType": 114, "id": "80860999", "manufacturerId": "0x5068", "RSSI": -99}
The /log will give you the data obtained when reading the wanted WMBUS ID's. GET /log will return you the data, POST /log allows you to remove data or download them in the .csv, .xls or JSON file.
Allows you to see a data from wanted WMBUS ID's
The /allocation allows you to allocate a WMBUS ID's that you want to read to the specific unit based on the RSSI as well as read the current allocation. This command is crucial after the /{identification}/scan is done to allocate a scanned WMBUS ID's to the specific unit. Please do see an example below as well.
Allows you to apply an allocation based on the scan result
Allows you to see an allocation
{
"owner": "ACRIOS",
"allocation": {},
"unseen": [
"20048418",
"20088917",
"20055329",
"20054790",
"20054807",
"20055297",
"20054808",
"20055296",
]
}
Within the Unit group, there are followoing subgroups that enable you to set the global atttributes:
Allows you to get information about the specific unit. As the identification IMSI is being used.
Provide you with the unit information
{
"unit": "901288002328171",
"config-state": "synchronized",
"last-activity": "2021-08-18T06:15:33.663599",
"owner": "ACRIOS",
"scan-request": {
"config": {
"sMode": 0,
"tMode": 120
},
"pending": true
}
}
Allows you to read the current configuration of the unit or set a new configuration to the specific unit.
Provide you with the unit configuration
{
"unit": "901288002328171",
"gatherTimeSeconds": {
"sMode": 0,
"tMode": 120
},
"ids": [],
"owner": "ACRIOS",
"timePerDeviceSeconds": 120,
"uplinkDataAction": "posting-and-logging",
"url": [],
"wakeUpPeriod": {
"days": 0,
"hours": 8,
"minutes": 0
}
}
Allows you to set the unit configuration
{
"unit": "901288002328171",
"gatherTimeSeconds": {
"sMode": 0,
"tMode": 120
},
"ids": [],
"owner": "ACRIOS",
"timePerDeviceSeconds": 120,
"uplinkDataAction": "posting-and-logging",
"url": [],
"wakeUpPeriod": {
"days": 0,
"hours": 8,
"minutes": 0
}
}
Shows you the log of WMBUS ID's that were read.
Provide you with the unit log
Allows you to delete the log
Allows you to read the unit's scan results and write a new scan request.
Shows you the log of last scan
{
"unit": "901288002328171",
"wmbusId": "40876594",
"deviceType": 128,
"manufacturerId": "0x5068",
"owner": "ACRIOS",
"rssi": -53,
"timestamp": "2021-08-11T11:37:16.104821"
},
{
"unit": "901288002328171",
"wmbusId": "40879989",
"deviceType": 128,
"manufacturerId": "0x5068",
"owner": "ACRIOS",
"rssi": -47,
"timestamp": "2021-08-11T11:38:16.802723"
},
{
"unit": "901288002328171",
"wmbusId": "31674215",
"deviceType": 128,
"manufacturerId": "0x5068",
"owner": "ACRIOS",
"rssi": -56,
"timestamp": "2021-08-11T11:37:16.142899"
},
{
"unit": "901288002328171",
"wmbusId": "80860999",
"deviceType": 114,
"manufacturerId": "0x5068",
"owner": "ACRIOS",
"rssi": -99,
"timestamp": "2021-08-11T11:34:09.610929"
},
{
"unit": "901288002328171",
"wmbusId": "44426436",
"deviceType": 128,
"manufacturerId": "0x5068",
"owner": "ACRIOS",
"rssi": -100,
"timestamp": "2021-08-11T11:34:09.623968"
}
Allows you to set a new scan request
{
"sMode": 0,
"tMode": 120
}
The endpoint can be used via the URL address where HTTP or HTTPS can be used together with an optional API key. The data are then being published via POST method.
In case more endpoints are needed, you can do so by using the column between URL addresses.
The endpoint can be set to the specific units or globally.
URL example:
https://wmbus.com/apikey=OptionalApiKeyInsertHere, http://wmbusAddressNumberTwo.com
The backend has an ability to do allocation automatically based on the result of scan. The unit does scan for surrounding WMBUS ID's and sends its device ID, RSSI and manufacturer ID to the server / backend. The user must insert the list of required WMBUS ID's to the backend, where after scan is complete the 2 lists are being compared and based on the RSSI the WMBUS ID's are being asssigned to the specific unit. If any WMBUS ID is not being received by any unit, it will show up as the unseen WMBUS ID and you can manually allocate this ID to the specific unit.
By using the POST /user/wmbus-ids manipulate a WMBUS ID's you want to read. This can be for example done by importing your WMBUS ID database in case you are an manufacturer or if you have a list of ID's.
ID needs to be in format "00112233".
Execute
Install the unit in the place of installation. Don't forget to insert the SIM card and connect the battery. Then manipulate the unit to the backend by using the POST /user/units. Leave the "ID" field empty by inserting "[ ]"
Leave the ID field within the unit configuration empty - "ids": []
Execute
Use POST /unit/{identification}/scan by setting the identification as an IMSI of the unit, select the "start" and in request body specify how long and in which mode should the scanning be done. We suggest to use minimum of 2 hours (120 minutes) in one mode, but this can depend on the specific setting of the WMBUS slave. For example, if the slave transmits every 4 hours you want to scan ideally for 8 hours.
Execute
Confirm that the scan did find a WMBUS ID's you were expecting. This can be done by GET /unit/{identification}/scan for each unit.
You can also check the unseen WMBUS ID's from the pool by using the GET /user/allocation. The non-scanned WMBUS ID's will show up as "unseen".
Confirm allocation by POST /user/allocation. Select apply and execute.
You can see the unit configuration by using GET /unit/{identification}/config
If you find any WMBUS ID as unseen you can manually allocate it to the specific unit. For this, you want to use GET /unit/{identification}/config, copy the current setting and insert it to the POST /unit/{identification}/config body. Do not forget to add the missing ID. If you add only the WMBUS ID itself and delete rest of the WMBUS ID's, you will loose the setting from automatic allocation and you need to repeat the steps 3 to 5.
The WMBUS ID's allocation based on scanning is preffered way of configuring the device as it minimize the risk of faulty human input. In some cases however, the firm setup of the WMBUS ID's might be preffered. This can be in the installation where there is less than 128 devices (the unit limit) and you want to use 2 - 3 units. This installation is for example 6-story appartment building with 3 doorways.
Install the unit in the place of installation. Don't forget to insert the SIM card and connect the battery. Then manipulate the unit to the backend by using the POST /user/units. Fill the "ID" field by WMBUS ID's you want to read.
Option 2 allows you to manipulate multiple units at once and leave the configuration for later. This can be the case if you have multiple units which will be placed in multiple locations and you do not know where each unit will be.
Manipulate the unit to the backend by using the POST /user/units. Leave the "ID" field empty by inserting "[ ]". By doing so, you can manipulate multiple units at once.
Use POST /unit/{identification}/config to manipulate required WMBUS ID's to the each unit.