TeraBee LoRa Level Monitoring XL User manual

Terabee LoRa Level Monitoring XL
User manual
v1.0
Technical support: [email protected]
Sales and commercial support: [email protected]

Table of contents
Introduction 3
Symbols explanation 3
About product 4
LoRaWAN overview 5
Inside the Package 6
Onboard features and controls 7
External features 7
Internal features and controls 8
Onboard modes overview 10
Setup mode (1) 11
Autotest mode (2) 11
Sleep mode (3), Active mode (4) 12
LED notifications 13
Setup and device initiation 14
1. Connect antenna 14
2. Register device with a network server 14
3. Activate device 15
4. Connect to network 15
5. Ready for operations 16
Default device parameters 16
Using Terabee Configuration GUI 17
Connection 17
Home tab 18
Network tab 20
Application tab 23
About tab 25
Device maintenance 27
LoRa Antenna 27
Battery compatibility 27
Battery replacement 28
Battery information & handling recommendations 29
Battery lifetime 29
Device cleaning 30
LoRaWAN communication 31
General uplink payload structure 31
Error codes bit structure 31
Data output definition 31
Uplink payload decoding function (example) 34
Appendix 36
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
2/36

Introduction
The purpose of this document is to give guidelines for configuration, operation and
maintenance of the Terabee LoRa Level Monitoring XL (further in text referred as Terabee
device). The user manual also includes instructions for using the Terabee Configuration
GUI.
Symbols explanation
The following symbols are used within the document:
This symbol indicates important messages or specific recommendations in order
to operate the product in the intended manner
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
3/36

About product
Terabee’s solution is a self-powered, low-energy and wireless IoT device - providing users
with remote data on remaining material levels inside silos, tanks and vats. It integrates an
optical (LED) ToF sensor for distance measurements with up to 60 meter range, also
providing a non-intrusive way of monitoring material levels. Data from the device is sent to
the network at regular & configurable intervals, using the wireless LoRa protocol with
kilometers of coverage area. For operations, the device uses an onboard (replaceable)
battery which in combination with the low-energy LoRa protocol provides users with years
of autonomy.
Device installation is possible inside or outside selected silos or tanks. Zero cabling for
power or communication is needed, minimizing overall installation efforts and time. The
product includes a free and easy-to-use Configuration GUI for quick tests and device
parameter setup.
Contact the Terabee team at [email protected] for more information.
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
4/36

LoRaWAN overview
Terabee provides an IoT end-device which uses the standardized wireless LoRa protocol to
transmit data over the LoRaWAN network. Please note that for successful data
transmission, the user is responsible for Terabee device integration with a LoRaWAN
network. This includes a LoRa gateway; registration of the Terabee device on a LoRa
network server; and an application server of users choice.
Figure 2 illustrates the Terabee device fit in the LoRaWAN typology, and required
integration components as well as process.
During the production step, Terabee devices are assigned several unique identifiers, which
are used to securely activate the device and allow safe (encrypted) data transmission over
a private or public LoRa network. LoRaWAN gateways receive encrypted data packets from
the end-devices within reception range, and transmits the data messages to the LoRaWAN
network server via Ethernet or wireless connection.
The LoRa Network Server establishes secure connections from the Terabee end-device to
the user Application, and ensures the authenticity of each device on the network as well as
integrity of each message transmitted (without accessing the application data).
The Application server is responsible for securely receiving, managing and decrypting data
packet information transmitted from the Terabee end-device. Decrypted messages can
then be sent for display on the user dashboards or data portals (web-application).
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
5/36

Inside the Package
The following items & components are included in the standard LoRa Level Monitoring XL
product offering:
Components
Visuals
Comment
LoRa Level Monitoring XL
device
LoRa Antenna
Available in two versions :
1. 868 MHz
2. 915 MHz
Note : Terabee does not provide the
antenna as a separate accessory
Standard Type D battery,
3.6V, 19 AH (replaceable)
Shipped inside the level device
Note: The Terabee device does not
support rechargeable batteries. For
more information, see the “Device
Maintenance” section.
USB 2.0 Micro-B cable
(50cm)
Allows device connection to PC
and access to Terabee
Configuration Software
O-Ring
Ensures IP65 sealing between the
level device and installation point
(e.g Terabee flange accessory)
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
6/36

Onboard features and controls
External features
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
7/36

No.
Feature
Description
1
Screwable top lid
Provides sealed (IP65) protection to the control panel under the
lid.
2
RP-SMA Connector
External connection point to support connectivity with a LoRa
antenna.
3
Vent plug
Integrated plug to avoid condensation and water accumulation
inside the device, during exposure to outdoor weather
4
NPT 1.5" (male)
connection
Compatible with female NPT 1.5" threaded connection for screw-in
installation of the level device
5
Distance Sensor
Terabee proprietary distance sensor with long-range
measurement characteristics, based on LED Time-of-Flight
technology
6
O-ring and O-ring slot
Ensures water tight sealing between the level device and selected
mounting equipment
Important! Do not unscrew (untight) the vent plug on the level device, unless
instructed by the Terabee team. Unscrewing the vent plug will compromise the
IP65 seal.
Internal features and controls
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
8/36

No.
Feature
Description
7
Battery Compartment
Access for the onboard battery unit.
8
Activation Switch
Device power ON / OFF. During connection to the USB
interface, the switch is not responsive.
9
LED Notification
Multi-color LED for visual feedback on device operations
10
Micro-USB
Access for connection to PC, power via USB
11
O-ring and O-ring slot
Ensures water tight sealing between device and top lid.
Do not remove the O-ring.
12
M5 threaded insert
(includes plug)
Available slot for hook insert (middle of lid).
In cases when not used, please keep the provided insert
plugged to avoid accumulation of water and dirt
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
9/36

Onboard modes overview
The Terabee device includes 4 modes, explained in more detail below:
1. Setup mode
2. Autotest mode
3. Sleep mode
4. Active mode
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
10/36

Setup mode (1)
Mode entered as soon as the device is connected to a PC via the USB 2.0 Micro-B interface.
The mode is used mainly for device connection to the Terabee Configuration GUI, which
allows users to perform distance measurement tests, network connection tests, and device
parameter configuration/saving on device.
During Setup mode, power to the device is provided via USB interface from the connected
PC, without affecting (draining) the onboard battery.
Please ensure that the onboard switch is set to (0) position before connecting
the Terabee device to a PC using the USB interface. Connecting the Terabee
device with a USB interface while the device is activated will have no effect.
When switching to setup mode - after the device has been operated whilst
being powered by the battery - please wait 5-10 seconds before physically
connecting the USB 2.0 micro-B connector. Faster connection may result in
failure to enter the Setup mode.
Autotest mode (2)
Autotest mode provides users with short bursts of data via LoRaWAN - to help verify
successful network connection and data transmission.
The mode is automatically entered after turning the onboard activation switch ON, (I)
position. An alternative way to start the auto test mode is to unplug the micro-USB cable
from the device, while the activation Switch is ON.
Right after activation, device will do the following:
1. Attempt to join the LoRa network (OTAA mode) - this process can take up to 90
seconds. This step is skipped if ABP is selected as an activation method.
2. Send 15 uplink transmissions to the LoRa network server, with 2-3 minute intervals
between each transmission. Total auto test time may take between 30-40 minutes.
Please note that the first measurement in auto test mode may take up to 6-7
minutes. Further transmission intervals are set between 2-3 minutes, however this
may increase in cases when larger distances are measured.
Throughout the autotest mode, the Terabee device will cycle through active and sleep
states. The following table describes operations for each state.
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
11/36

State
Operation
LED
LED meaning
Active
1. system charging for operations
2. perform distance measurement
3 uplink payload transmission (Rx1)
4. downlink payload receival slot (Rx2)
GREEN (3 blinks)
BLUE (3 blinks)
Currently in active state
Uplink transmission
Sleep
Device is in battery-saving mode for 2min
(equivalent to being turned OFF)
Not available
After 15 uplink transmissions, the device will automatically enter sleep mode (exiting the
autotest mode). When in autotest mode, the power is supplied by the onboard battery.
Sleep mode (3), Active mode (4)
Sleep mode is the battery saving mode, allowing the device to achieve years of autonomy.
The Terabee device will be in sleep mode for most of its time while deployed on the field.
Based on pre-configured parameters, the Terabee device will wake up (exit) from the sleep
mode and enter the active mode for a short period of time. During active mode, the
Terabee device will:
1. Perform system charging for operations
2. Perform a distance measurement
3. Execute an uplink message transmission via LoRa to the configured network (Rx1)
4. Open slot for downlink messages (Rx2).
After the sequence is completed, the device will go back to sleep mode, until the next
wake-up is scheduled. The LED indication is not used during sleep nor active mode, in
order to preserve battery lifetime.
Please note that during active mode, distance measurements and data
transmission always happen in the same “wake up window”.
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
12/36

LED notifications
LED Pattern
Reason / Cause
Meaning
GREEN x continuous blinking
(0.5 sec intervals)
Device is connected to the PC
via micro-USB interface
Device is in SETUP MODE. Power is
provided via micro-USB connection
(PC)
RED x 1 blink
1. Activation switch is turned
ON ( I position )
2. Device has been connected
to PC via USB interface
Device boot up. After the red LED
switches off, the device is
successfully initiated
BLUE x continuous blinking
(0.25 sec intervals)
Automatic initiation after
device boot up is completed
Device enters AUTO TEST mode,
and is attempting to join LoRa
network (OTAA configuration)
BLUE x 3 blinks
(0.5 sec interval)
Available only AUTO TEST
mode
Uplink message sent from device to
the network server
GREEN x 3 blinks
(10 sec intervals)
Available only in AUTO TEST
mode
Regular blinking (every 10 sec)
indicates that the device is
operating in AUTO TEST mode.
WHITE LED activated
for 1 sec
(before system reset start)
In the Terabee Configuration
GUI the FACTORY RESET is
selected.
Reset factory operation selected
and to be be started immediately
ERROR NOTIFICATIONS
RED x constantly ON
Activation switch is turned
ON (I position)
Error during device boot up.
RED x 1 blink
(5 sec intervals)
After activation switch is
turned ON (I position)
Device configuration error.
One or more of the network and/or
application parameters are not
configured or configured incorrectly
RED x 2 blinks
(5 sec intervals)
After failed connection to
network
Device failed to connect to the
network
RED x continuous blinking
(0.1 sec intervals)
Internal system error
detected
Device firmware has experienced a
crash
Please see Appendix for recommended recovery steps on LED error notifications.
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
13/36

Setup and device initiation
1. Connect antenna
Join the provided LoRa antenna with the Terabee device. To do this, locate the RP-SMA
connector on the device external part, and gently screw in the antenna clockwise until it is
locked.
Please use the cap to screw the antenna to the device. Once the antenna is locked, hold
the cap fixed (use one hand) and rotate the main antenna body to adjust for a preferred
antenna position (other hand).
Use the 3-point hinge system to manipulate the antenna in the preferred position.
2. Register device with a network server
Before operation, the user must register the Terabee device with a selected LoRa network
server provider. This step includes assigning several unique identifiers between the
Terabee device and the network server, which enables device recognition on the network
and secures further data exchange.
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
14/36

An integration example with The Things Network (TTN) server is provided in a separate
document (Official product webpage →Downloads section →Documentation →LoRa
Level Monitoring XL integration with The Things Network).
Please note that without registering the Terabee device with a LoRa network, it is
not possible to transmit data via LoRa protocol!
3. Activate device
Next, unscrew the TOP lid of the device (clockwise), and power it by turning the onboard
switch to (I) position. Power will be immediately supplied to the device by the battery. The
onboard LED will indicate successful bootup accordingly
4. Connect to network
After initiation, the device will enter AUTO TEST MODE, during which it will :
1 - attempt to join (request) the LoRa network. This step can take up to 90 sec, and is only
present in the OTAA activation method. Onboard LED will constantly blink BLUE to indicate
network connection, and
2 - transmit 15 uplink messages to the LoRa network server of users’ choice, with 2-3
minutes intervals. The onboard LED will blink BLUE (3 times) - to indicate each uplink
payload transmission. Total time for auto test mode may vary between 30-40 minutes.
If the device is set to operate in the ABP activation method, it will skip the network
join part (step 1) and directly start transmission of 15 uplink messages (step 2).
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
15/36

5. Ready for operations
Once the autotest mode has ended, the device will enter the battery saving mode (SLEEP
MODE), until it will be automatically powered again for measurements and LoRa data
transmissions based on pre-configured intervals.
Before further device installation, please screw back & lock the upper device lid to ensure
IP65 protection to inner electronic components. Make sure that the antenna connection is
tight (no free movements).
Default device parameters
Terabee device comes pre-configured with default network and applications parameters.
The following list provides an overview of these parameters, configured during the
production process.
Activation method : OTAA
Device EUI :provided, unique to each device
Application EUI : -
Application Key :provided, random to each device
Radio Frequency (LoRa) : EU868 MHz; US915 MHz
Adaptive Data Rate (ADR) : Enabled
Spreading Factor : -
Uplink Confirmation : Disabled
Measurement and Transmission Interval : 1 reading / 1 hour
Level Estimation : Disabled
When using the Terabee Configuration GUI with the Terabee device, the software auto-fills
the codes in the DevEUI and AppKey parameter fields.
Device EUI (DevEUI) and Application Key (AppKey) codes for each device can be also found
embedded in a QR code that is printed on a label - located on the inner side of the TOP lid.
Example is presented below.
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
16/36

Using Terabee Configuration GUI
Terabee LoRa Level Monitoring XL comes with a Configuration GUI (Graphical User
Interface) to provide users with an easy way to perform distance measurement tests, and
configure device parameters. Terabee software supports operation on Windows, Linux and
Mac operating systems.
Connection
Connect the Terabee device to a PC using micro-USB cable (included in the package). The
USB 2.0, Micro-B connector is located under the TOP device lid. Upon successful physical
connection, the LED will constantly blink GREEN, and it will continue to do so - as long as
the Terabee device is linked to the PC. Power supply to the device is now provided via USB
interface (battery is not affected).
Download and install the Terabee Configuration GUI, located under the Downloads section
of the official product page. Open the Terabee Configuration GUI application.
The top navigation bar allows the user to easily navigate and switch between different
sections of the software (HOME, NETWORK, APPLICATION, ABOUT), at any time.
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
17/36

Home tab
Under the Control Panel, click on CONNECT DEVICE. The software will automatically
recognize & display the USB port to which the Terabee device has been joined, and connect
to the GUI.
After successful connection - a dialog window will appear, showing currently configured
device parameters. Click on CLOSE to continue.
Under the Control Panel, the Device Status field will now change to CONNECTED. Device
status can also be found in the footer (bottom left), at any time while using the software.
Current software version can also be found in the footer (bottom right).
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
18/36

Immediately after connecting, a distance data stream will be available on the left side of
the Home tab, showing real-time measurements from sensor to target (in millimeters).
Please note that fast streaming of distance data from the device is only possible
via the USB interface, and not available for communication via LoRa protocol.
Users can extract measured distance data in a txt file format, by clicking on START
RECORDING. Select a preferred location for the file and click SAVE. When enough data is
gathered, click on STOP RECORDING. Below is an example of distance measurements
extracted on a Txt file from the Terabee Configuration GUI.
At any point, the user can disconnect the device by clicking DISCONNECT DEVICE.
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
19/36

Network tab
This tab features parameters related to the LoRa network, determining how the device
operates with the selected network. The following section describes each of the parameter
fields and available selection options.
Activation method and unique keys
Activation method
Input parameter
Definition
OTAA
(Over the air
activation)
Device EUI (DevEUI)
unique 64 bit end-device identifier in the
network.
DevEUI parameter field is automatically
pre-filled with device specific code
(provided by Terabee device)
Application EUI
(App EUI)
unique 64 bit code, enabling an extra
identification layer. If an application EUI
code is provided by the selected network
server provider please input this.
Application Key
(AppKey)
128 bit application encryption key to secure
communication between device and
network.
AppKey parameter field is automatically
pre-filled with device specific code
(provided by Terabee device)
ABP
(Activation by
Personalization)
Device Address
(DevAddr)
32 bit code, identifies the end device within
the network
Network Session Key
(NwkSKey)
shared between the LoRa network and
end-device, Unique per network
Application Session
Key (AppSKey)
shared between the application and
end-device, used for message payload
encryption, unique per application
Below is an example of fully configured unique device keys, using the OTAA activation
method. The Terabee GUI allows automatic revert back to device default Device EUI, at any
point - this can be done by clicking the circular arrow inside the Device EUI field.
Copyright © Terabee 2021
Terabee, 90 Rue Henri Fabre
01630, St Genis-Pouilly, France (next to CERN)
20/36