Apps Aqua-Scope App User Manual

: June 4, 2024
: APPs

Table of Contents

Connecting the Aqua-Scope Monitor (AQS) to your local Internet
Using WIFI
Using Bluetooth (experimental)
Accessing values using the local web server
Home
Menu Item Config
Menu Item Net
Menu Item Data
Menu Item Setup
Reporting all value to a MQTT server of choice
LoRaWan Payload Commands
References
Read User Manual Online (PDF format)
Download This Manual (PDF format)

**Apps Aqua-Scope App User Manual

**

The Aqua-Scope Monitor comes with a convenient app connecting the device to the AquaScope Cloud and accessing all its functions and data.

However, if you want to stay independent of third-party clouds such as the Aqua Scope cloud you are welcome to do so. This little tutorial explains you what to do and what to expect.

Connecting the Aqua-Scope Monitor (AQS) to your local Internet

When in factory default the device blinks red/green. You can always reset the device into factory default by unplugging / remove battery, wait for 20 seconds and re plug/insert battery.
Then you will hear a short beep. Now push the button and keep it pushed for 5 seconds. 5 short beeps will guide you. After the 5 seconds you will hear a low frequency noise. Now release the button – the device is in factory default settings.

Using WIFI

The device will act as open WIFI access point with the SSID ‘Scope’. You need to connect your mobile device or PC to this SSID. Start a web browser and open the page: http://192.168.1.4.

You will now see this dialog. There is a list of WIFI networks the AquaScope Monitor can see with the signal strength seen from the AquaScope Monitor in braces. Please select your desired WIFI network and add your WIFI WPA key.

If you still like to connect your Aqua-Scope Monitor to the Aqua-Scope cloud, you need to have an Aqua-Scope user account identified by your email address. You can sign up to the Aqua-Scope cloud using the Aqua-Scope mobile apps or simply open the webpage http://io.aqua-scope.com and follow the instructions.

If you don’t provide a valid email address signed up at the Aqua-Scope Cloud, you will never be able to access any values over the cloud or the apps!

If you want to use the local web server for direct access OR if you want to enable MQTT communication, you need to keep the webserver active for further communication.

Keeping the webserver active (check the box on section web server) allows accessing values right from device and changing the value. If you want to protect this access you can define an access token (max 64 Byte, any chars) that need to be provided for every subsequent access to the web servers pages as ‘GET’ parameter. Leaving this field empty means everybody with access to your local WIFI can access the AQS data and change this setting (!!).

Press ‘save’ to store and activate the values. If the values were correct the red/green blinking will stop. Otherwise, you will have to repeat the process with correct SSID and WPA key.

Using Bluetooth (experimental)

Web BLE

In factory default state the device operates as Bluetooth device operating as UART Service. The device name is AQS_XX with XX as unique ID of the device. This ID consists of the 8 least significant chars of the LoRaWAN EUI printed on the device.

The most convenient way to use Bluetooth is a simple webpage accessed by a browser supporting Web-BLE. (Use Chrome of Firefox. Apple Safari users should connect to their hardware vendor and convince them to finally support open web standards such as web BLE -sorry).
Go to the URL: https://io.aqua-scope.com/ble. You find a simple and self- explaining dialog. Type in your SSID and your WPA key and hit enter and you are done!

Plain Bluetooth UART

If you conclude using such a simple interface insulting your genius, here is the traditional way.
You will need a Bluetooth capable device plus a mobile app supporting standard Bluetooth UART service. For Android devices we recommend “SerialBluetooth”. First you need to pair the Bluetooth device using the system dialog of your mobile phone. Then you open the serial Bluetooth app and connect to the device you just paired. If successful you have direct access to the serial console of the Aqua-Scope Monitor. This serial console will also show internal debug messages, so don’t be irritated. You need three commands to setup WIFI:

wl: List all SSIDs in proximity
ws SSID: set SSID to given values (will not work ifSSID contains white space!)
ww WPA: set WPA and connect. This requires that the SSID was set before

Accessing values using the local web server

If the local webserver is active, you can continue to access this webserver but after connecting to your local WIFI the IP address of the device has changed to an address fitting into the address range of your local router.

Hence, the first step is to find the new IP address assigned. The best way for this depends on
the configuration of your local network and your router. Please refer to Internet resources for
help (as a true hacker you know anyway).
Once you have the correct IP, you connect to the local webserver again using the URL

http://YOUR_LOCAL_IP resp.
http://YOUR_LOCAL_IP?token=YOURACCESSTOKEN

You will see a nice overview of the Aqua-Scopes sensor data and a menu to access further information:

Home

The homepage shows all sensor data available. Please note that the Water consumption measures total consumption since last retrieval of the data.
This means that this value is always set back to zero once the page was loaded.

Menu Item Config
Here you can access the complete set of AQS configuration values plus you have the chance to change them. Changing configuration values without proper knowledge about its meaning and function may screw up the device.
The manual gives some guidance on config parameters to change bit please handle this with care. If you did something wrong the process back to factory default values will rescue you.

This menu item sends the complete set of WIFI networks detected in proximity as JSON object
{“eid”: “54457e3c”,
“ssids”: [
{“name”:”tc”,”rssi”:”-37″,”encryption”:”4″}, {“name”:”CPAP”,”rssi”:”-59″,”encryption”:”4″},
{“name”:”tcu”,”rssi”:”-59″,”encryption”:”4″}, {“name”:”CPAP”,”rssi”:”-75″,”encryption”:”4″}

The format is self-explaining. Encryption = 4 is the Wi-Fi-internal meaning for “WPA key required”

This menu item provided all the sensor data of the homepage but in JSON format. The JSON format is self-explaining. Please note that the Water consumption measures total consumption since last retrieval of the data. This means that this value is always set back to zero once the page was loaded.
{ “eid”: “54457e3c”,
“Uptime”: “132”,
“FlowState”: “0”,
“Water Cons”: “0”,
“Pressure”: “3401”,
“Ext Water”: “0”,
“Battery Voltage”: “0”,
“Water Temperature”: “268”}

The setup page allows to change the state and security token of the webserver plus enable MQTT Settings. If MQTT is enabled, you need to provide the MQTT Server address as domain name or IP address plus the server port as decimal number. If your MQTT server required authentication you can provide this info too.
For testing purposed we recommend using one of the free and public (and unsecure) servers such as www.hivemq.com or other

Reporting all value to a MQTT server of choice

If enabled in the setup dialog of the local webserver you can feed all sensor data to a MQTT server of choice.

The built-in MQTT Client uses the domain /AQS-XXXXXXXX with XX as the 8-digit EID of the system (The device shows the 16-character LoRaWAN EUI. The 8 least significant chars equal to this value).

The following sensor values are reported:

Uptime
Pressure
Consumption
Temperature

LoRaWan Payload Commands

LoRaWAN commands can be daisy chained into the payload up to the defined maximum payload size of 51 bytes. This mean that for all commands sent to defined number of bytes in the payload is required to avoid misinterpretation of command and/or command values in the receiver side. All uplink and downlink commands use FPort=1.

Uplink Command Hardware Version Report: 0x03 – HW – CAP_MSB CAP_LSB (4 Byte)

This command reports the hardware version and a bitmap of the capabilities of the device. It is sent unsolicited as the first command during boot-up and as replying command to downlink command Hardware Version Get. HW is a single byte indicating the version of the hardware. The bitmap indicates the different capabilities of the device.

Uplink Command Configuration Report: 0x04 – IDX – VAL_MSB – VAL_LSB (4 Byte)

This command reports a configuration parameter of the device: IDX is the number of the configuration parameter. The 16 Bit VAL is the parameter itself. Configuration parameters are always 16 Bit values. The table below describes the configuration parameters and their values.

Uplink Command Sensor Report: 0x06 – ID – VAL_MSB – VAL_LSB (4 Byte)

This command reports sensor values. The ID indicates the sensor type and defines the format of the 16-Bit VAL. Possible sensor types are:

0x01: Temperature: VAL is temperature in 1/10 Degree Celsius. Example: 0x06 0x11 0x20
0x20 => Temperature 0x00CD = 205 = 20.5 C.
0x03: Uptime: VAL is the number of seconds after last boot
0x10: Water Pressure: VAL is unsigned water pressure in mBar. Example: 0x10 0x011 0x0D
0x48 => Pressure 0x0D48 = 3400 = 3.4 Bar.
0x11: Water Consumption: VAL is water consumption in liters since last report 0x13: Battery status (if applicable)

Uplink Command Device Status Report: 0x07 – STATE – VAL1_MSB – VAL1_LSB – VAL2_MSB – VAL2_LSB (6 Byte)

This command reports every single water flow event and the result of a Pipe Check. STATE contains the status of the operation and defines the meaning of the two 16-bit values.

0x00: Valve closed, YY/ZZ set to zero
0x01: Water Stop, YY flow time/sec, ZZ consumption in ml
0x02: Pipe-Check is ok
0x03: Pipe-Check alarm, YY = pressure diff in mBar, ZZ = elevation in cm
0x04: Pipe-Check aborted due to normal water take, YY/ZZ set to zero
0x05: Pipe-Check aborted due to water heats up, YY/ZZ set to zero
0x06: Pipe-Check aborted due to blocking valve, YY/ZZ set to zero
0x07: Pipe-Check not started, water currently flowing, YY/ZZ set to zero
0x08: Pipe-Check has started, YY/ZZ set to zero
0x0f: Water Flow Start, YY/ZZ set to zero
0x64: Valve Open, YY/ZZ set to zero

Uplink Command Logging: 0x08 – LEVEL LEN X1…XN (51 Byte)

This command is used to send certain logs to the server for debugging purposes. LEVEL is the severity level of the log, LEN defines the number of bytes containing the message

Uplink Command Firmware Version Report: 0x0a – VER_MSB VER_2 VER_3 VER LSB (5 Byte)

This command reports the 32-bit value of the current firmware. It is sent unsolicited as the first command during boot-up and as replying command to downlink command ‘Hardware Version Get’.

Uplink Command Alarm Report: 0x0b – STATE – TYPE – VAL_MSB – VAL_LSB (5 Byte)

This command reports start and end of alarms. The STATE-Byte indicate the status of the alarm (0x01 = active, 0x00 = inactive). The TYPE Byte indicates the type of alarm and defines the content of the 16 Bit VAL.

0x0001 (Bit 00) : All Alarms
0x0002 (Bit 01) : Flood Sensor Tripped, VAL is 0x01 or 0x00.
0x0004 (Bit 02) : Freeze/Frost Danger, VAL is actual temperature.
0x0008 (Bit 03) : Too Long Water Flow, VAL is the time in s.
0x0010 (Bit 04) : Heavy Flow – Pipe Break ? Value is actual water pressure.
0x0020 (Bit 05) : Jamming Toilet Flap
0x0040 (Bit 06) : Water Overpressure. Value is actual water pressure.
0x0100 (Bit 08) : Pipe-Check Alarm
0x0800 (Bit 11) : WIFI RSSI Value too low. Value is actual rssi value.
0x1000 (Bit 12) : Battery Low
0x2000 (Bit 13) : Lost Mains Power
0x4000 (Bit 14) : No external sensor head connected.
0x8000 (Bit 15) : External sensor head is not in contact with water.

The configuration parameter #19 defines which parameter is active. Inactive alarms will not be reported and will not cause any other indications (buzzer, led).

Downlink Command System Commands: 0x01 – CMD (2 Byte)

This command sends a system command to the devices. CMD defines the type of command:

CMD = 0x01: System restart
CMD = 0x02: System Reset – back to factory default
CMD = 0x03: Start Pipe-Check. The behavior of the Pipe-Check can be defined in configuration parameters.

Downlink Command Hardware Version Get: 0x03 – (1 Byte)

This command calls for a Hardware Version Report sent upstream

Downlink Command Configuration Set: 0x04 – IDX – VAL_MSB – VAL_LSB (4 Byte)

This command allows setting configuration parameters of the device: IDX is the number of the configuration parameter. The 16 Bit VAL is the parameter itself. Configuration parameters are always 16 Bit Values. The table below describes the configuration parameters and its values.

Downlink Command Sensor Get: 0x06 – ID (2 Byte)

This command requests the report of a sensor values. The ID indicates the sensor type Possible sensor types are:

0x01: Temperature: VAL is temperature in 1/10 Degree Celsius. Example: 0x06 0x11 0x20
0x20 => Temperature 0x00CD = 205 = 20.5 C.
0x03: Uptime: VAL is the number of seconds after last boot
0x10: Water Pressure (1) : VAL is unsigned water pressure in mBar. Example: 0x10 0x011 0x0D
0x48 => Pressure 0x0D48 = 3400 = 3.4 Bar.
0x11: Water Consumption: VAL is water consumption in Liters since last report 0x13: Battery status (if applicable)

Downlink Command Valve Position: 0x07 – STATE (2 Byte)

This command turns the water valve – if associated – into OPEN (state = 1) or CLOSE (state = 0) position

Downlink Command Firmware Version Get: 0x0a – (1 Byte)

This command calls for a firmware version report.

Downlink Command Alarm Clear: 0x0b – TYPE (2 Byte)

This command clears an alarm. TYPE is the type of alarm to be cleared. Type = 0 clears all active alarms. For other types of alarms to be cleared please refer to the uplink command 0x0b.

Downlink Command Configuration Get: 0x14 – IDX (2 Byte)

This command allows reading the configuration value IDX. The device will respond with an upstream command Configuration Report

Downlink Command Valve Status Get: 0x17 – (1 Byte)

This command requests a command “Device Status Report” sent upstreams.

Configuration Parameters

All Configuration Parameters are 2 Byte values that can be set and read out using LoRaWAN ‘config get’ and ‘config set’ commands.

Here is an overview of the configuration parameters currently used:

01: System Register
02: Water Algorithm control Register
03: LoRaWAN configuration Register
04: Valve Actions on Alarms
05: Target (Norm) Water Pressure (set and updated by device)
06: Upper Water Pressure Threshold
07: Upper Water Pressure Threshold
08: Translation factor from internal water meter to external water meter
09: Time threshold for “Jamming Toilet detection”
10: max Flowtime to trigger “long flow” alarm
11: Threshold to trigger frost alarm
12: Min Flow to report
13: Pipecheck duration
14: Pipecheck abort Threshold
15: Pipecheck alarm Threshold
16: n.n.
17: n.n.
18: n.n.
19: Alarm reporting mask
20: n.n.
21: n.n.
22: n.n.
23: n.n.
24: T-Algorithm: Flow Pressure (don’t change)
25: T-Algorithm: Threshold (don’t change)
26: M-Algorithm: Accu Sub (don’t change)
27: M-Algorithm: Threshold (don’t change)
28: M-Algorithm: key (don’t change)
29: Status Reporting Interval
30: Heartbeat Interval
31: End Flag (fix, don’t change)

Parameter 1 (0x1): System Register (Default: 0x5bfe = dec 23550)

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

0x0001 (Bit 00) : Main Processor in Sleep Mode
0x0002 (Bit 01) : LoRaWAN communication
0x0004 (Bit 02) : WIFI communication
0x0008 (Bit 03) : Serial communication
0x0010 (Bit 04) : Ubilink (Device-2-Device) Communication
0x0020 (Bit 05) : Buzzer active
0x0040 (Bit 06) : LED active
0x0080 (Bit 07) : BOF (Begin of Flow) reported
0x0100 (Bit 08) : EOF (End of Flow) reported
0x0200 (Bit 09) : Buffers reported
0x0400 (Bit 10) : Enforce LoRaWAN Rejoin process
0x0800 (Bit 11) : high frequency (1) versus low frequency(0)
0x1000 (Bit 12) : base operation interval msb
0x2000 (Bit 13) : base operation interval
0x4000 (Bit 14) : base operation interval
0x8000 (Bit 15) : base operation interval lsb

When High-Frequency Bit set to 1: 4 MSB defines interval in 2 * ms from 2 -32 ms (val 1 – 16).
When High-Frequency Bit set to 0: 4 MSB defines interval as 125 ms power of x, ranging from x = 1 =
125 ms to x = 14 = 2048 sec = 34 min , x=15 is not allowed.

Parameter 2 (0x2): Flow and Flood Detection Register (Default: 0x004c = dec 76)

The bitmap defines which water flow algorithm is used and what kind of water pressure data is reported if corresponding bits for buffer reporting in system register are enabled. Bit = 1 means function enabled, bit = 0.

0x0001 (Bit 00) : Initial Auto-Calibration done (set and updated by device)
0x0002 (Bit 01) : 24 Hour Auto-Calibration done (set and updated by device)
0x0004 (Bit 02) : T algorithm active (set and updated by device)
0x0008 (Bit 03) : M algorithm active (set and updated by device)
0x0010 (Bit 04) : R algorithm active (set and updated by device)
0x0020 (Bit 05) : Accu Mode in M Algorithm
0x0040 (Bit 06) : T data buffered and reported
0x0080 (Bit 07) : M data buffered and reported
0x0100 (Bit 08) : n.n.
0x0200 (Bit 09) : Water Tank detected (set and updated by device)
0x0400 (Bit 10) : Source Identification active
0x0800 (Bit 11) : n.n.
0x1000 (Bit 12) : t-calib counter
0x2000 (Bit 13) : t-calib counter
0x4000 (Bit 14) : t-calib counter
0x8000 (Bit 15) : t-calib counter

Parameter 3 (0x3): LoRa Register (Default: 0x0ffd = dec 4093)

The bitmap defines which commands are accepted on the LORAWAN communication channel.

Please note that disabling bit 4 will essentially lock this function against further changes from the

LORAWAN channel. Changes via Wifi are still possible. Bit = 1 means function enabled, bit = 0 disables function

0x0001 (Bit 00) : CLASS C (default = Class A)
0x0002 (Bit 01) : Alarm Reporting
0x0004 (Bit 02) : Alarm Clearing
0x0008 (Bit 03) : Heartbeat Reporting
0x0010 (Bit 04) : Config Parameter Changes
0x0020 (Bit 05) : BOF
0x0040 (Bit 06) : EOF
0x0080 (Bit 07) : Water Consumption Report
0x0100 (Bit 08) : Temperature Report
0x0200 (Bit 09) : Calibration
0x0400 (Bit 10) : Pipe-Check
0x0800 (Bit 11) : Pressure
0x1000 (Bit 12) : Periodic Config Parameter Reporting
0x2000 (Bit 13) : n.n.
0x4000 (Bit 14) : Frequency msb, 0x00 = EU, 0x01 = US, 0x02 = nn., 0x03 = nn.
0x8000 (Bit 15) : Frequency lsb

Parameter 4 (0x4): Valve Close Action on Alarm (Default: 0x0001 = dec 1)

The bitmap defines which alarm type causes an associated valve to close. Bit = 1 means function enabled, bit = 0 disables function.

0x0001 (Bit 00) : All Alarms
0x0002 (Bit 01) : Flood Sensor Tripped
0x0004 (Bit 02) : Freeze/Frost Danger
0x0008 (Bit 03) : Too Long Water Flow
0x0010 (Bit 04) : Heavy Flow – Pipe Break ?
0x0020 (Bit 05) : Jamming Toilet Flap
0x0040 (Bit 06) : Water Overpressure
0x0080 (Bit 07) : n.n.
0x0100 (Bit 08) : Pipe-Check Alarm
0x0200 (Bit 09) : n.n.
0x0400 (Bit 10) : n.n.
0x0800 (Bit 11) : WIFI RSSI Value too low
0x1000 (Bit 12) : Battery Low
0x2000 (Bit 13) : Lost Mains Power
0x4000 (Bit 14) : No external Sensor found
0x8000 (Bit 15) : External Sensor not in contact with water

Parameter 5 (0x5): Water Standard Pressure (Default: 0x0dac = dec 3500)

This parameter is for information only. The pressure value is automatically set at initial calibration and may change from time to time as a result of ongoing calibration. The value is provided in mBar.

Parameter 6 (0x6): Over-Pressure Alarm threshold (Default: 0x1f40 = dec 8000)

An overpressure alarm is sent as an uplink message when the current pressure exceeds this threshold. The threshold value is automatically set 24 hours after initial setup during calibration and may change from time to time as a result of ongoing calibration. The value is accepted in mBar.

Parameter 7 (0x7): Under-Pressure Warm threshold (Default: 0x07d0 = dec 2000)

A heavy flow alarm is sent as an uplink message when the current pressure falls below this threshold for a certain time. The threshold value is automatically set 24 hours after initial setup during calibration and may change from time to time as a result of ongoing calibration.
The value is accepted in mBar.

Parameter 9 (0x9): 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 (0x10): Max. Water Take Time (Default: 0x0258 = dec 600)

A Water Flow longer then this value (in seconds) will cause a Usage Alarm.

Parameter 11 (0x11): 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 regardless of the scale settings in parameter 21.
The default value is set to 4 degree Celsius.

Parameter 13 (0x13): Pipe-Check Duration (Default: 0x0258 = dec 600)

This value defines how long (in seconds) a pipe check process shall take.

Parameter 14 (0x14): Pipe-Check Abort Drop (Default: 0x00c8 = dec 200)

This value defines the maximum sudden loss in pressure during Pipe-Check to indicate water consumption. When hit, the Pipe-Check is aborted immediately and the valve is reopened. The value is provided in mBar regardless of the scale settings in parameter #21.

Parameter 15 (0x15): Pipe-Check Alarm Drop (Default: 0x001e = dec 30)

This value defines the maximum loss in pressure per minute during Pipe-Check in mBar. When hit, the Pipe-Check will continue for several more minutes to determine the elevation and the orifice size of the detected leak.

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

The bitmap defines which alarm type is active and will cause a alarm status command 0x0b. Bit = 1 means function enabled, bit = 0 disables function.