Aqua-Meter Clamp with Wi-Fi

Developers Manual

SKU: AQMWIE01
Version: 1.0

Product Description

The water sensor clamp measures the flow and temperature in a water pipe using a "Time of Flight" measurement method and transmits the data wirelessly. By analyzing the flow internally, water leaks and other anomalies are detected, and the owner is alerted.

The device is clamped onto the outside of the water pipe without interrupting the water supply. Its flexible design and innovative software allow it to be used on water pipes between 16 and 50 mm, with all currently available materials on the market such as PEX, PEX AL, copper, PE, or steel. It meets all requirements of the European Community's Measuring Instruments Directive (MID). With only 60 mm of space required above the water pipe and a length of 110 mm, the device is very flat and short, making it easy to install.

The device can be powered either via USB-C or two AA alkaline cells. Whenever an external power source is available, it is used independently of the inserted batteries.

The system communicates via Wi-Fi and is controlled by an app on a mobile phone. Additionally, data can be sent to an MQTT server or an HTTP 'webhook' to be integrated into a smart home system.

JSON Cloud Interface

By default, the devices communicate directly with the Aqua-Scope Cloud via an IP connection. The data is encoded as a JSON object and then encrypted using the XXTEA encryption algorithm with a private key stored in the device. The encrypted data is transmitted as ASCII hexadecimal values in the POST field of an HTTP request. In the data field of the HTTP request, the downlink data is also sent as a JSON object and encrypted using XXTEA.

The very same JSON encoding is used for the MQTT and the JSON Webservice interface. The following downlink commands are understood by the devices as JSON objects:

Downlink Command: 'conf': {a:b,c:d}

Changing configuration parameter 'a' resp. 'c' to the value of 'b' resp 'd'. A maximum of 32 parameters can be changed simultaneously. The parameters are modified in the order they are specified. For the explanation of the parameters and its values please refer to the section 'Configuration parameters' in this manual.

Downlink Command: 'system': x

System commands are:

Downlink Command: 'shell': 'aaa'

Execute a command on the serial shell. The commands are described in the BLE interface. Note that if a command requires a space, use the underscore character ('_').

Downlink Command: 'ota': 'xxx'

Firmware Update Over the Air. XXX represents a transaction number used to request the required firmware from the OTA server.

Downlink Command: 'webs': { 'enable': '1', 'url': 'https://io.aqua-scope.com/be3/test.php', 'token': '12345', 'raw': 1, 'xxtea': 1 }

The 'webs' object configures the use of a JSON Web Service. When enabled (enable = 1), all JSON reports are encoded and transmitted in the POST field of an HTTP request. Optionally, a private token can be provided, which is appended to the URL as a GET parameter. With 'raw' set to 1, detailed raw data is also sent to this service when the device collects such data. The 'xxtea' switch allows the JSON object to be encrypted with the device's private key. More information on this is available in the JSON Web Services section of this manual.

Downlink Command: 'clear': x

Clears an alarm of type X in the device. Using X = 0 will clear all alarms in the device. The alarm will also be reset even if the cause of the alarm, such as a temperature drop, has not been resolved. When an alarm is cleared with this command, the alarm will not be triggered again until the next reboot (via command or power-on).

Downlink Command: 'mqtt': :{'debug':'1','enable':'1','server':'aaa.bbb.com', 'port':789,'login':'abcdef','password':'abcdef'}

Configures the use of an MQTT service. When enabled (enable=1), all reports and alarms from the device are sent to the MQTT service specified as 'server' in parallel with other communication channels, using the IP port 'port'. Depending on the configuration of the MQTT service, an optional user login and password may need to be provided. The values can be subscribed to on the MQTT broker via the string '/AQS-XXXXXX', where XXXXXX is the 6-digit ID of the device.

Downlink Command: 'list': 0

Transmits all configuration parameters of the device as an array.

Downlink Command: 'msp': 'xxx'

This command sends a ASCI-encoded command right to the MSP coprocessor. For details on the MSP coprocessors ASCII UART interface please contact support.

Downlink Command: 'valve': x

Sets a motor registered with the Aqua-Scope Monitor to the value X, which can be either 0 (closed) or > 0 (open). If more than one motor (device types 1 or 3) is registered, these motors are closed or opened together. If this is not desired, the type of a motor can be changed to a value other than 1 or 3. This motor must then be controlled directly using the 'svalve' command.

Downlink Command: 'svalve': {c: X,s: Y}

Sends a command to open or close a motor with a value Y to a sub-device in communication channel X, regardless of its device type. This command is needed when a motor is separated from the common control of all motors with the command 3. If the device in communication channel X is battery-operated and in deep sleep, this command will be executed when the device wakes up next. Pressing a button on the sub-device will wake it up.

Downlink Command: 'sconf': {c: X,p: Y,v: Z}

Sets a configuration parameter 'Y' of a sub-device in communication channel 'X' to the value 'Z'. If the device in communication channel X is battery-operated and in deep sleep, this command will be executed when the device wakes up next. Pressing a button on the sub-device will wake it up.

Downlink Command: '_': {"eid":"12345678","sensor_x":XXXX,"sensor_y":YYYY, }

The status report of a device is typically sent every 15 minutes and contains the names and current values of device-specific sensors. A status report is also sent for battery-operated devices. The interval (time between two reports) is defined in configuration parameter 29 (default 900 seconds). This does not apply to Aqua-Scope devices with a water pressure sensor (AQS*, PRE*, AQE*, ...) where the status is sent along with the raw data depending on the chosen sampling interval. The sensor types are provided in the device manual.

Downlink Command: 'sub': {X: {'c': cmd,'d': channel,'I': deveui,'k': key,'t': type},Y: {// ...}}

This configures sub-devices of an Aqua-Scope Monitor, whose functionality can only be used through the Aqua-Scope Monitor. Communication between these sub-devices and the Aqua-Scope main device occurs through a specially secured private LoRa Point-2-Point connection. Various commands are supported and are processed in the order they are specified in the JSON object. The command number X is not considered, but it's used to separate different commands.

Uplink Command: 'list': [1, 2, 3, 4, , 30]

Sends an array with all configuration parameters of a device in response to the downlink command 'list'.

Uplink Command: 'sub': {"c":X,"pay":YYY}

This is raw data from a sub-device in channel 'X'. Decoding the raw data can be done on the server. The encoding corresponds to the LoRaWAN communication channel encoding. The main device will also decode the received payload to execute commands intended for the main device (e.g., alarms that lead to motor shutdown).

Uplink Command: 'flow': {'event':'1|2', 'dur': XXX, 'cons': YYYY, 'reason': ZZZ }

This is a notification for the start and end of detected water consumption. 'event' = '1' indicates the start of a water consumption event with information about the reason for the event, and 'event' = '2' marks the end. It includes the event duration ('t'), the amount of water consumed ('l'), and, for debugging purposes, a possible reason for the termination of water flow. The duration is in seconds, and the amount is in milliliters.

Uplink Command: 'alarm': {"state":X,"type":Y,'val':Z,"map":AA}

This alarm object notifies active (state=1) or completed (status=0) alarm states. 'type' specifies the alarm type, and depending on the alarm type, an additional value may be provided if applicable (e.g., the current temperature value for a temperature alarm). The complete alarm vector 'map' can also be transmitted, where each bit corresponds to an alarm type.

Uplink Command: 'uptime': 'xxxx'

The heartbeat of a device transmits the uptime in seconds plus a device-specific status. If a meaningful status cannot be transmitted for a device, this object is omitted. A heartbeat is only sent for devices that are not battery-operated. The interval (time between two heartbeats) is defined in configuration parameter 30 (default 20 seconds).

Uplink Command: 'arr': xxxxx

If available on the device, this object transmits the raw data from the main sensor as a continuous string of hexadecimal characters of length 4. For example, "arr": "035403560350..." for 0x0354 = 852, 0x0356 = 854, 0x30350 = 848.

Local Web Server

HTTPD Dienst

The local web server of Aqua-Scope WLAN devices is active by default on Port 80 (HTTP service) and can be used for the initial configuration of WLAN, among other functions. Once the WLAN interface is successfully configured, the web server is deactivated. However, it can be reactivated from any communication channel. The web server allows for enabling and disabling, as well as configuring other communication channels like MQTT or JSON web service. It also provides easy access to the current sensor values of the device. Accessing the web server when the device is in sleep mode is challenging as there is a very limited time available for querying or setting values.

The web server interface is self-explanatory.

JSON-Web-Service

To use this communication channel, you need an HTTP server with a communication endpoint to which the device can send its data in JSON format via the POST field. The communication options are defined in the Aqua-Scope Cloud Interface description.

If encryption via XXTEA (https://en.wikipedia.org/wiki/XXTEA) is chosen, you must have a device-specific 128-bit encryption key. This key is securely embedded in the device and cannot be extracted or read. You can obtain this key directly from Aqua-Scope upon request, providing the 8-byte ID. The 8 bytes of the ID follow the format specified by Aqua-Scope.

AA BB BB BB CC CC CC CC

When no encryption is selected, data transmission occurs as an HTML POST with a content type of 'application/json.' With encryption, 'application/raw' is used, and the JSON object is encrypted with XXTEA and then encoded as HEX ASCII.

The transmitted JSON object corresponds to the Aqua-Scope Cloud Interface description. As a response or command to the device, a downlink object can be sent in the HTTP text, the format of which also complies with the Aqua-Scope Cloud Interface.

The transmission of sensor raw data (using the 'arr' object) must be explicitly enabled, for example, in the app. This data is generally not encrypted.

The following small example demonstrates the reception of a JSON object from the Aqua-Scope device, exemplified as PHP code.

If you have any further questions or need assistance with anything specific, feel free to ask.

require_once __DIR__ . 'xxtea-php.php'; 
// from https://github.com/xxtea/xxtea-php

#define EID 060000001
#define KEY 06000000123456780600000012345678


error_reporting(0);
$json  = json_decode(file_get_contents('php://input'), true);
if(!$json) {
	$key = hex2bin(KEY);	
	$jd = xxtea_decrypt(base64_decode(file_get_contents('php://input')),$key);
	$json  = json_decode(jd, true);
	if(!$json) die(”wrong key or wrong id”);
}
var_dump($json); 

MQTT Service

All data (except for the raw data from the main sensor) can be sent in parallel to both the JSON web service and the Aqua-Scope Cloud to an MQTT broker. To do this, the server, port, and optionally an access login and password are provided. To retrieve data, you must subscribe to:

With '12345678' as the 8-digit device ID. It is also possible to send downlink commands as JSON objects via the MQTT service. The notation of these commands is identical to those of the Aqua-Scope Cloud.

Bluetooth Low Energy

The Bluetooth interface of Aqua-Scope WLAN devices is active by default and is used for the initial configuration of WLAN through the Aqua-Scope app. Once the WLAN interface is successfully configured, the Bluetooth interface is deactivated. However, it can be reactivated from any communication channel. Please note that reactivating the Bluetooth interface on battery-operated devices will block their sleep mode and quickly deplete the battery.

The Bluetooth interface implements the UART profile in BLE 5. It can be used with all serial Bluetooth applications. It's even more convenient when using a PC or an Android mobile phone with Bluetooth capabilities. You can open the Chrome browser, navigate to the website 'https://ble.aqua-scope.com,' and connect to the Bluetooth device 'AQS-XXXXXX' (where XX is the device's ID).

Once the Bluetooth connection is established, you have direct access to the internal serial console of the device. You can view all debug messages and execute commands, seeing their results on the console. The following commands are supported:

Alarms

Alarm messages consist of an alarm type, the alarm status ( 1 = on, 0 = off) and an optional value that is associated ot the alarm.

Alarm 1 (0x01): No water flow

Description: If no water is needed over a longer period (threshold is 30 days), the water should be turned off and the pipes drained or used regularly, e.g., by flushing the toilet, to prevent the pipes from being damaged and destroyed by standing water. The alarm is cleared when either water usage is detected again or no water is detected in the pipe.

Optional Alarm Value: Always zero

Alarm 2 (0x02): Temperature outside of allowed range

Description: The alarm is triggered if the water temperature moves outside an allowable range. The factory setting is assumed to be 5 to 40 degrees Celsius. The threshold values can be adjusted in the app.

Optional Alarm Value: Current Temperature in 1/10 degree celsius

Alarm 3 (0x03): Prolonged water usage

Description: The water flows for a very long time. The threshold is set at 15 minutes from the factory and can be adjusted in the app under 'Configuration'. The alarm is automatically cleared when the water usage stops.

Optional Alarm Value: Seconds of Water Flow

Alarm 5 (0x05): Stuck toilet

Description: A stuck toilet will not cause damage but will unnecessarily consume water. A stuck toilet creates a very characteristic usage pattern and is therefore easily recognized. The problem is usually resolved by pressing the toilet flush button. The alarm is also cleared when no sticking is detected anymore.

Optional Alarm Value: Time in Seconds between 8 events

Alarm 6 (0x06): Excessive water flow

Description: This usually indicates a pipe burst. The water flow is consistently higher than the threshold allows over a period of one minute. The threshold is set at 28 liters per minute from the factory and can be adjusted in the app under 'Configuration'. If the usage intensity drops below the threshold or stops, this alarm is automatically cleared.

Optional Alarm Value: Velocity of Water Flow in ps

Alarm 7 (0x07): Dripping faucet

Description: Any water usage above the measurement inaccuracy and below normal water usage is recognized as a dripping faucet. If the water flows minimally over a period of at least one hour, an alarm is triggered. The cause of such an alarm can also be a small leak in a water pipe (micro-leakage). Therefore, the matter should be investigated and the cause rectified.

Optional Alarm Value: Velocity of Water Flow in ps

Alarm 8 (0x08): Backwards Water Flow

Description: Due to modern installations, such as legally required backflow preventers, it is actually impossible for water to flow back into the supply line in the opposite direction. If this happens, a plumber needs to investigate the issue. The alarm is triggered if water flows in the wrong direction for 30 seconds continuously. The alarm is cleared when no abnormal flow is detected or when normal water flow is restored.

Optional Alarm Value: Velocity of Water Flow in ps

Alarm 12 (0x0c): Low Battery

Description: The battery is running low and needs to be replaced.

Optional Alarm Value: Battery voltage in mV

Alarm 14 (0x0e): Attempted tampering with the device

Description: This alarm is always triggered when the electronics capsule is removed from the base unit. Please note that changing the batteries will always trigger a corresponding tampering alarm.

Optional Alarm Value: Always zero

Alarm 15 (0x0f): No water in the pipe

Description: This is possible when the water is turned off, e.g., during repair work. The sensor can no longer operate then. Permanent air bubbles in the pipe are also conceivable. Observe the installation conditions.

Optional Alarm Value: Always zero

Configuration Parameters

This list of configuration parameters is supported by this device. All configuration parameters are 32 bit values but - with the exception of Parameter 3 only the lower 16 bits are used

Parameter 1 (0x01): System Register (Default: 0x0be4 = dec 3044)

The bitmap defines the general behavior of the device. Bit = 1 means function enabled, and Bit = 0 means function disabled.

Parameter 3 (0x03): LoRaWAN Register (Default: 0x0ffd = dec 4093)


The bitmap defines which commands are accepted on the LoRaWAN communication channel. Bit = 1 means function enabled, bit = 0 disables function

The upper 16 Bit of the register are not accessible via LoRaWAN but from serial console or WIFI only (whatever is available):

Parameter 5 (0x05): Ultrasonic Transducer Signal Strength (Default: 0x0000 = dec 0)

This value defines the signal amplification needed to achieve good sensor results. This value depends on the quality of the acoustic coupling and the pipe material. It will be set during calibration C01 resp. C0B. Do not touch this value unless you know what you do.

Parameter 6 (0x06): Ultrasonic ADC RX Delay (Default: 0x0000 = dec 0)

This value defines the delay between sending out the USS signal and receiving it back. The value depends on the size and the material of the pipe and will be set during calibration C02 resp C0C. Do not touch this value unless you know what you do.

Parameter 7 (0x07): Ultrasonic Total Time of Flight (Default: 0x0000 = dec 0)

This value defines the total time of flight in ns for a USS signal. This is an indicator for the pipe diameter and to a lesser extent the pipe material. The value is set during calibration C02 resp. C0C

Parameter 8 (0x08): Liter Translation (Default: 0x03e8 = dec 1000)

The value of 1000 is an arbitrary value to translate the measured velocity of water into liters. Ths translation depends on the inner pipe diameter and this value can correct the translation.

Parameter 9 (0x09): Jamming Toilet (Default: 0x00c8 = dec 200)

This parameter defines the max time in seconds for 10 consecutive small water consumption event typical for jamming toilet flap. The default value of 200 means that the 11th event with a given 200 seconds time interval will cause a jamming alarm sent as uplink message. If your home has heavy water usage in general you may want to increase this value to avoid false alarms but keep in mind that the system will be less sensitive to find possible malfunctions.

Parameter 10 (0x0a): Max. Water Take Time (Default: 0x0384 = dec 900)

A Water Flow longer than this value will cause a Usage Alarm The value needs to be defined in 0,43 * seconds. This means a desired cut-off of 15 minutes results in a value of 2093.

Parameter 11 (0x0b): Frost Warn Threshold (Default: 0x0028 = dec 40)

A frost alarm is sent as uplink message when the current temperature falls below the threshold. The threshold value is accepted in 1/10 degree Celsius. The default value is set to 4 degree Celsius.

Parameter 12 (0x0c): Minimum Flow time to report (Default: 0x0002 = dec 2)

Any value above zero will suppress any explicit EOF report even when EOF reporting is enabled in the systems register.

Parameter 13 (0x0d): Ultrasonic Measurement Interval (Default: 0x0008 = dec 8)

This value defines how often the USS sub-system will detect a flow. More measurements per second means more power consumption but more measurement precision too.

Parameter 14 (0x0e): Ultrasonic Noise Threshold (Default: 0x0000 = dec 0)

This value defines the minimal threshold between noise and drip detection as dTOF in ps. The lower this value the better because the more sensitive the device operates. Compared to the Leakage mode the device will be less sensitive in meter mode. This value be be set during calibration C03 resp. C0D.

Parameter 15 (0x0f): Flow Detection Threshold (Default: 0x0fa0 = dec 4000)

This value determined the minimum velocity of a water flow to be recognized as valid water flow. For metering purposed even flow below this threshold will be counted but no explicit BOF or EOF report is generated.

Parameter 16 (0x10): High Threshold for Temperature Alarm (Default: 0x01f4 = dec 500)

If the measured temperature rises beyond this level a temperature alarm is issued. Dropping below the level clears the alarm

Parameter 17 (0x11): Drip Length Threshold (Default: 0x001e = dec 30)

Once the DTOF rises above the noise threshold (Parameter 14) but remains below the flow threshold (Parameter 15) there is a delay defined with this parameter. After this time a Drip Alarm is sent. The drip alarm is cleared either when a real water flow is detected or the dTOF falls below the noise threshold.

Parameter 18 (0x12): Zero Drift Offset (Default: 0x0000 = dec 0)

Zero Drift is an effect of USS measurement sensors. Over time the dTOF on still water moves away. The zero drift offset compensates this error increasing the accuracy and sensitivity of the device. This read-only value shows the current offset in ps to reach the zero line and its constantly updated.

Parameter 19 (0x13): Alarm Enable/Disable (Default: 0xd806 = dec 55302)

The bitmap defines which alarm type is active and will cause an alarm status command 0x0b. Bit = 1 means function enabled, bit = 0 disables the function. The different alarm types are shown in the section 'LoRaWAN Alarm Types'.

Parameter 21 (0x15): Time Delay in Transducer (Default: 0x0000 = dec 0)

This parameter represents the assumed time delay of the USS signal outside water. It depends on the geometry of the transducers, the geometry and material constants of the pipe, and its inner and outer coating. This value is used for the estimation of the pipe diameter and pipe material after calibration and can be changed to align with user-provided information on these constants. The value is device-specific.

Parameter 22 (0x16): Threshold for Intense Flow Alarm (Default: 0x0096 = dec 150)

If the Velocity of the water stream rises above this level for a time defined in config parameter 23, an intense flow alarm will be issued. The value is given in 1000 * ps.

Parameter 23 (0x17): Duration for Intense Flow Alarm (Default: 0x001e = dec 30)

If the Velocity of the water stream rises above the level defined in config parameter 22 for a time period defined in this configuration parameter, an intense flow alarm will be issued. The value is given in seconds.

Parameter 24 (0x18): Threshold for Negative Flow Alarm (Default: 0x03e8 = dec 1000)

If the Velocity of the water stream rises above a negative level for a time defined in config parameter 25, an intense flow alarm will be issued. The value is given in 1000 * ps.

Parameter 25 (0x19): Duration for Negative Flow Alarm (Default: 0x001e = dec 30)

If the Velocity of the water stream rises above the level defined in config parameter 24 for a time period defined in this configuration parameter, an negative flow alarm will be issued. The value is given in seconds.

Parameter 26 (0x1a): Correction Factor No-PRV Algorithm (Default: 0x03e8 = dec 1000)

This correction factor translates the measures water flow of the No-PRV algorithm to a liter value. Can be changed to adapt to different pipe diameters or pipe system layouts.

Parameter 28 (0x1c): Active Communication Channels (Default: 0x0000 = dec 0)

This register is bit-mapped and defines which communication channels of the device are active. Te following bits are recognized:

Parameter 29 (0x1d): Reporting Interval (Default: 0x0384 = dec 900)

This parameter defines the interval in seconds the device automatically reports sensor values and heartbeat as an uplink message.

Parameter 30 (0x1e): Heartbeat Interval (Default: 0x003c = dec 60)

This parameter defines the interval in seconds the device automatically reports sensor values and heartbeat as an uplink message.