Wavetrend Lorawan Water Temperature Monitor User Guide (+ PDF)

LoRaWAN Water Temperature Monitor

LoRaWAN Water Temperature Monitor – Integration Guide
Document Version 1.3
Produced by Wavetrend (Europe) Ltd

Wavetrend Europe Ltd
Barlavington Stud
Barlavington
Petworth
West Sussex
GU28 0LG
Phone: +44 (0) 330 223 2085
Copyright ♥ 2021 Wavetrend Europe Ltd. All rights reserved.

LoRaWAN Water Temperature Monitor – Integration Guide

Preface

Wavetrend’s LoRaWAN Water Temperature Monitor has been tested to work with the following Network Servers:

– The Things Network
– The Things Industries
– Loriot

This Guide provides message format details for the LoRaWAN Water Temperature Monitor and covers some detail of the requirements when using HTTP Push integration.

Each Network Server uses a proprietary format for the JSON payload conveyed in an HTTP Push. The critical fields for each are covered in this Guide.

LoRaWAN Water Temperature Monitor – Integration Guide

Messages

General

The following section covers each message used by the system, and details each field. Field positions assume that data is HEX encoded, so 2 HEX characters per byte.

Message Types

The current firmware release for the device is v0.6.0 which supports the following message types and versions.

Type (hex)	Version (hex)	Direction	Message Description
00	04	From device	Installation Request
01	02	To Device	Device Configuration
02	01	From device	Installation Response
03	01	From device	Temperature Report
05	00	From device	Scald
06	00	From device	Freeze
08	00	From device	Sensor Error
09	00	From device	Error

LoRaWAN Water Temperature Monitor – Integration Guide

Install Request Message

This message is sent on device activation & thereafter at the configured “downlink days” to solicit clock sync and configuration update.

Field	Offset	Length	Type	Comment
Message Type	0	2	uint8_t	‘00’
Message Version	2	2	uint8_t	‘04’ currently
Sequence #	4	2	uint8_t	Increments for each message and wraps to 0 on overflow
Device Time	6	8	uint32_t	Unix epoch time (This will be a small offset from 00:00:00 UTC on 1 January 1970 until first time sync after install)
Nonce	14	8	uint32_t	Used for tracking Device Configuration message
Battery Voltage	22	4	uint16_t	Battery voltage in mV i.e. Volts x 1000. Levels reported are: 3.30, 3.05, 2.83, 2.64, 2.44, 2.24, 2.04, 1.85. Green = OK, Orange = Warn, Red = critical.
Sensor 1 Temp	26	4	uint16_t	Max uint16_t if not fitted (0xFFFF), or if fitted temperature to 1 DP decoded as follows: Temp = (value – 270) / 10
Sensor 2 Temp	30	4	uint16_t
Sensor 3 Temp	34	4	uint16_t
App Version	38	2	uint8_t	Device firmware version
App Version Minor	40	2	uint8_t
App Version Build	42	4	uint16_t
Reset Reason	46	4	uint16_t	1 = Firewall 2 = OBL 4 = Pin 8 = Power On 12 = Pin, Power On 16 = Software 32 = Watch Dog Timer 36 = Pin, Watch Dog Timer 64 = Windowed Watch Dog Timer 128 = Low Power

Device Configuration Message

LoRaWAN Water Temperature Monitor – Integration Guide

This downlink message is sent by the application server in response to the Installation Request message. Its purpose is to convey the configuration that device should use.

Field	Offset	Length	Type	Comment
Message Type	0	2	uint8_t	‘01’
Message Version	2	2	uint8_t	‘02’ currently
Sequence #	4	2	uint8_t
Device Time	6	8	uint32_t	Unix epoch time – provided to the Device to set the real time clock
Nonce	14	8	uint32_t	Return the value provided in the Installation Request message
Downlink Days	22	2	uint8_t	Number of days between config/time sync. Valid values are >= 1 and <= 30
Message Flags	24	2	uint8_t	Bit-mapped: Bit 0 = Scald message enable Bit 1 = Freeze message enable Bit 2 = reserved – set to 0 Bit 3 = reserved – set to 0 Bit 4 = reserved – set to 0 Bit 5 = history} see Temp Report Bit 6 = history} message Bit 7 = reserved – set to 0
Scald Threshold	26	2	int8_t	Threshold above which to trigger a Scald Alert message. Valid values are >= 0 and <= 100
Freeze Threshold	28	2	int8_t	Threshold below which to trigger a Freeze Alert message. Valid values are >= -27 and <= 10
Reporting Period	30	4	uint16_t	Temperature report period. Valid values are >= 1 and <= 10080 (1 min to 1 week)
Sensor 1 Config	34	2	uint8_t	0 = Disabled (Sensors 2&3 only) 1 = Hot Outlet 2 = Hot Outlet (Healthcare) 3 = Cold Outlet 4 = Cold Unit 5 = TMV / Blended 6 = Hot Unit Outlet (60°C) 7 = Hot Unit Return (50°C) 8 = Hot Unit Return (55°C)
Sensor 2 Config	36	2	uint8_t
Sensor 3 Config	38	2	uint8_t

LoRaWAN Water Temperature Monitor – Integration Guide

Install Response Message

This message is sent in response to the Device Configuration downlink message.

Field	Offset	Length	Type	Comment
Message Type	0	2	uint8_t	‘02’
Message Version	2	2	uint8_t	‘01’ currently
Sequence #	4	2	uint8_t	Increments for each message and wraps to 0 on overflow
Device Time	6	8	uint32_t	Unix epoch time
Error	14	2	uint8_t	0 = No Error 1 = Installed Sensor Disabled in Config 2 = Configured Sensor Not Installed 3 = Downlink Out of Bounds 4 = Invalid Message Flags 5 = Scald Threshold Out of Bounds 6 = Freeze Threshold Out of Bounds 7 = Reporting Period Out of Bounds 8 = Configuration Type Out of Bounds 9 = Miscellaneous Error 10 = Downlink Received Too Late 11 = Downlink Nonce Mismatch

LoRaWAN Water Temperature Monitor – Integration Guide

Temperature Report Message

This message provides temperature & flow report at the configured frequency.

Field	Offset	Length	Type	Comment
Message Type	0	2	uint8_t	‘03’
Message Version	2	2	uint8_t	‘01’ currently
Sequence #	4	2	uint8_t	Increments for each message and wraps to 0 on overflow
Device Time	6	8	uint32_t	Unix epoch time
Sensor 1 Min Temp	14	2	int8_t	Min temp for reporting period
Sensor 1 Max Temp	16	2	int8_t	Max temp for reporting period
Sensor 1 Flow Count	18	2	uint8_t	Count of flow events for the reporting period
Sensor 1 Compliant	20	2	uint8_t	Count of compliant flow events for the reporting period
Sensor 2 Min Temp	22	2	int8_t
Sensor 2 Max Temp	24	2	int8_t
Sensor 2 Flow Count	26	2	uint8_t
Sensor 2 Compliant	28	2	uint8_t
Sensor 3 Min Temp	30	2	int8_t
Sensor 3 Max Temp	32	2	int8_t
Sensor 3 Flow Count	34	2	uint8_t
Sensor 3 Compliant	36	2	uint8_t

*Note that the fields from “Device Time” to “Sensor 3 Compliant” can be repeated for up to the last 2 historical report periods beyond the current to give an ability to recover from lost messages or WiFi network outages. This is configured using the “history” bits in the “Flags” field in the downlink message:

Bits 5/6 = ‘00’ = no history
Bits 5/6 = ‘01’ = 1 previous hour history
Bits 5/6 = ‘10’ = 2 previous hours history

Integration will need to deal with de-duplication of data when using the history feature. This can be simply achieved by creating an SQL composite unique index on device ID, message time and sequence number columns in a target table.

LoRaWAN Water Temperature Monitor – Integration Guide

Scald Message

This message is sent if enabled and the measured temperature exceeds the configured scald threshold. Message frequency is capped to 1 per hour.

Field	Offset	Length	Type	Comment
Message Type	0	2	uint8_t	‘05’
Message Version	2	2	uint8_t	‘00’ currently
Sequence #	4	2	uint8_t	Increments for each message and wraps to 0 on overflow
Device Time	6	8	uint32_t	Unix epoch time
Sensor	14	2	uint8_t	Sensor # that gave rise to the scald alert (1/2/3)
Temperature	16	2	int8_t	Temperature at the point of scald detection

Freeze Message

This message is sent if enabled and the measured temperature is less than the configured freeze threshold. Message frequency is capped to 1 per hour.

Field	Offset	Length	Type	Comment
Message Type	0	2	uint8_t	‘06’
Message Version	2	2	uint8_t	‘00’ currently
Sequence #	4	2	uint8_t	Increments for each message and wraps to 0 on overflow
Device Time	6	8	uint32_t	Unix epoch time
Sensor	14	2	uint8_t	Sensor # that gave rise to the freeze alert (1/2/3)
Temperature	16	2	int8_t	Temperature at the point of freeze detection

LoRaWAN Water Temperature Monitor – Integration Guide

Sensor Error Message

This message is sent if the Device detects a sensor error – typically if a configured sensor is removed whilst the device is in use.

Field	Offset	Length	Type	Comment
Message Type	0	2	uint8_t	‘08’
Message Version	2	2	uint8_t	‘00’ currently
Sequence #	4	2	uint8_t	Increments for each message and wraps to 0 on overflow
Device Time	6	8	uint32_t	Unix epoch time
Sensor 1	14	2	uint8_t	0 = no error, 1 = error
Sensor 2	16	2	uint8_t	0 = no error, 1 = error
Sensor 3	18	2	uint8_t	0 = no error, 1 = error

Error Message

This message is sent if the device detects an internal error.

Field	Offset	Length	Type	Comment
Message Type	0	2	uint8_t	‘09’
Message Version	2	2	uint8_t	‘00’ currently
Sequence #	4	2	uint8_t	Increments for each message and wraps to 0 on overflow
Device Time	6	8	uint32_t	Unix epoch time
Error #	14	4	uint16_t	1 = Invalid 2 = Too Big 3 = No Data 4 = Invalid Protocol 5 = Bad Message 6 = No Space 7 = Message Size 8 = Name Too Long 9 = Busy, Try Again 10 = Network Unreachable
Source File Name	18	64	uint8_t[32]
Source File Line #	82	4	uint16_t

LoRaWAN Water Temperature Monitor – Integration Guide

Network Server Integration

This section relates to the JSON payload conveyed when using HTTP Push (POST) integration.

Loriot

Typical JSON Payload

You will probably want to use the ‘rx’ record as is lower latency than the ‘gw’ record:

Key Data Fields

– ‘EUI’ – the device ID

– “data” – the device message. This is HEX encoded as per the message specifications in the previous section.

LoRaWAN Water Temperature Monitor – Integration Guide

The Things Industries

Typical JSON Payload

LoRaWAN Water Temperature Monitor – Integration Guide

Key Data Fields

– “dev_eui” – the device ID

– “frm_payload” – the device message. This is Base64 encoded and so will need conversion to HEX for the contents to be relevant to the message specifications in the previous section. This can be easily achieved, for example if using PHP the function base64_decode().

LoRaWAN Water Temperature Monitor – Integration Guide

The Things Network

Typical JSON Payload

Key Data Fields

– “hardware_serial” – the device ID– “payload_raw” – the device message. This is Base64 encoded and so will need conversion to HEX for the contents to be relevant to the message specifications in the previous section. This can be easily achieved, for example if using PHP the function base64_decode().

LoRaWAN Water Temperature Monitor – Integration Guide

Installation Message Exchange

Whilst in service the device generally originates messages and the application server does not need to provide a response, however at activation there is a message exchange between device and application server that is designed to provide the device it’s configuration. This process needs to succeed for the device to be successfully installed.

An overview of the process is as follows:

On activation the Device sends an Installation Request message (type HEX ‘00’) to the Application server.
The Application Server must respond by scheduling a Device Configuration message (type HEX ‘01’) using the Network Server downlink mechanism. The Device Configuration message will contain the specific configuration for the device together with the ‘nonce’ value provided in the Installation Request message.
The Device will respond to the Application Server with an Installation Response message (type HEX ‘02’). The Application Server should inspect the ‘error’ field of this message to determine success of the installation process.

Downlink Scheduling

The method of scheduling a downlink is different for each Network Server, so following is some guidance for each. The samples are provided in PHP using Curl.