TOIP Pty TBSL1 User manual

User Manual
TBSL1 and Console
Copyright TOIP Pty Ltd
Version 04.00.01.30
January 2021
1

Table of Contents
1. Introduction....................................................................................................4
1.1. Hard are setup......................................................................................5
1.2. TBSL1 Data Path....................................................................................8
2. Soft are Installation....................................................................................10
2.1. Ne Installation....................................................................................10
2.2. Upgrading from Earlier Version.............................................................11
3. Using the TBSL1 GUI..................................................................................12
3.1. Connecting to the TBSL1......................................................................12
3.2. Create and Save a Configuration File for the Device...........................14
3.3. Changing the Configuration Defaults...................................................14
3.4. Changing Operating Mode...................................................................15
3.5. Configuring the TBSL1.........................................................................17
3.5.1. LoRaWAN Settings.......................................................................17
3.5.2. Packet Ackno ledgement Settings..............................................18
3.5.3. LoRa Frequency Settings.............................................................19
3.6. Time Settings........................................................................................21
3.7. Schedule Settings.................................................................................22
3.8. SDI -12 Sensor Settings:......................................................................24
3.9. Adding Pulse Sensors..........................................................................26
3.10. Adding Analogue Sensors..................................................................27
3.11. Setting up Alarms................................................................................31
3.11.1. Setting the Board ID...................................................................33
3.12. Writing a Configuration to the TBSL1.................................................33
3.13. 4G RTU Configuration – Cellular Settings..........................................35
3.13.1. Checking the MQTT Java Midlet................................................36
3.13.2. MQTT Configuration...................................................................37
3.13.3. Testing 4G Connectivity..............................................................40
3.13.4. Monitoring MQTT Server Traffic.................................................42
4. Sensor and LoRaWAN Testing....................................................................44
4.1. SDI-12 Sensor Testing..........................................................................44
4.2. LoRaWAN Testing.................................................................................45
4.2.1. LoRa WAN Testing Via Console...................................................45
4.2.2. LoRa WAN Testing from Console Menu.......................................48
4.2.2.1 Check RSSI...........................................................................48
4.2.2.2 Check Transmission..............................................................48
4.3. Starting the TBSL1 Logging.................................................................49
4.3.1. Starting the TBSL1 immediately...................................................49
2

4.3.2. Using the Hibernate Function.......................................................49
5. TBSL1 Packet Format..................................................................................50
5.1. Common Data Messages.....................................................................50
5.2. Data or Parameter Messages...............................................................52
5.2.1. Pulse Data Messages...................................................................52
5.2.2. Analogue Sensor Messages.........................................................54
5.2.3. SDI-12 Sensor Messages............................................................55
6. Firm are and Console Update....................................................................58
6.1. To Check the Current Version...............................................................58
6.1.1. Obtaining the Console GUI Version.............................................58
6.1.2. Obtaining RTU Firm are Version.................................................58
6.2. Upgrading the Console GUI.................................................................58
6.3. Upgrading the TBSL1 Firm are...........................................................58
6.3.1. Upgrading Via Console GUI.........................................................59
6.3.2. Upgrading Via ST-Link..................................................................62
6.4. Using the Debug Firm are...................................................................62
6.5. 4G Modem Firm are Upgrade.............................................................63
7. Diagnostics and Troubleshooting................................................................67
7.1. TBSL1 GUI Log Files............................................................................67
7.2. Diagnostic Mode – Error Log................................................................67
7.3. Clearing the RTU Memory....................................................................68
7.4. Do nloading Readings from Memory..................................................68
7.5. 4G Modem Testing................................................................................69
7.5.1. Testing from Monitoring Menu......................................................69
7.5.2. Testing from the Command Line..................................................70
7.5.2.1 Signal Strength Testing.........................................................70
7.5.2.2 APN Connection Testing........................................................71
7.5.2.3 Other Modem Commands.....................................................74
8. Backend Setup.............................................................................................75
8.1. Configuration Requirements.................................................................76
8.2. Passing Data to the Tekbox LoRa WAN Broker...................................79
8.3. Accessing the Broker............................................................................79
3

1. Introduction
The TBSL1 from Tekbox is a high capacity data logger ith integrated
telemetry. It is fitted ith an SDI-12 input channel as ell as an analogue and
pulse input. The TBSL1 may be fitted ith a communications board for either
LoRa WAN (TBSL1-LO) or mobile phone (cellular) communications (TBSL1-
4G).
The TBSL1 GUI is used to program the TBSL1 via a serial connection. It can
be used to set all the board’s operational parameters (time settings, SDI-12
commands, LoRaWan settings) and send commands to SDI-12 sensors or the
LoRaWAN module on the board and to display the received responses.
4

1.1. Hardware setup
The picture belo sho s the designations of the various connectors on the
TBSL1.
The TBSL1 connects to a PC using a Type B USB connection. In addition to
the connector on the case, there is a second connector on the PCB.
Using a Number 1 Philips Scre driver, undo the 4 scre s holding the cover to
the TBSL1 case and remove the cover.
Before fitting the battery, make sure that the antenna is scre ed on to the TNC
connector on top of the case and that the UFL cable from the antenna is fitted
to the upper most socket on the LoRaWAN PCB.
For the standard TBSL1 the battery is a 3.6V Lithium-Ion cell ith internal
thermistor and 3 pin JST connector. The battery is secured to a plastic holder
hich sits on 4 standoffs installed on top of the PCB. Connect the battery lead
to the matching socket on the upper left of the TBSL1 PCB.
5

If your TBSL1 is going to be po ered via a solar cell, ire the solar panel up
according to the diagram belo (Port 3). If the solar panel has been supplied
ith your unit it ill be pre- ired ith the required connector. In most
applications a 6V 2W solar panel ill operate the TBSL1 although a 5W unit
can be used if you have concerns about the po er budget or have sensors
hich dra high current or if you are using the cellular version ith 15 minute
logging/transfer.
CAUTION: Do not use the TBSL1 ith 12V solar panels. The maximum
permissible open circuit panel voltage is 7.2V. Using a panel ith a higher
voltage rating ill damage the TBSL1.
The image belo sho s the input connectors hen vie ed from the bottom or
the TBSL1. The orientation is the same as this picture hen looking do n on
the Plugs i.e. if you put the 7 pin plug in to the connector, do up the lock nut
and then remove the back-shell from the connector, hen you look do n on
the solder buckets they ill be in the same order.
6

The t o input connectors are ired in parallel. This allo s you to easily
connect t o sensors. Should you need to connect more than t o cables, you
can add a TBS04 Junction Box.
The back of the TBSL1 case is fitted ith a mounting bracket. This can be
used to secure the unit to a 40 to 50mm post using a stainless steel hose
clamp.
The colour code for the cables supplied ith the TBSL1 is as follo s:
Pin Solar
(5 pin)
Sensor
(7 pin)
1 Blue – SP + Analogue 1
2 Bro n – SP - Bro n - GND
3 Link to Pin 4 Analogue 2
4 Link to Pin 3 Pulse
5 - Green/Yello - SDI-12
6 - Blue - PWR
7 -
If you are using either of both of the Analogue inputs or the Pulse Input, you
may need to use a 6 or 7 core cable. Or you can re- ire one socket to carry
the analogue/pulse inputs and the other the SDI-12.
When using the TBSL1 ith a solar panel, mount the solar panel facing North
(south in the Northern Hemisphere) and the fit TBSL1 on the opposite side of
the pole, facing south. This ay the solar panel helps shade the TBSL1 from
the sun. If you are fitting the TBSL1 ith an external antenna, you can mount
the antenna as high as possible on the post and the TBSL1 unit directly belo
the solar panel.
7

Radio range is governed by a number of factors including terrain. Radio range
can be maximised by:
raising the height of the Gate ay antenna
raising the height of the TBSL1 antenna.
Often a compromise must be sought bet een raising the antenna height for
best coverage versus keeping it lo to allo machinery to pass over the site. If
regular machinery movement is an issue, consider using a tilt do n base pole.
The follo ing factors ill cause a decrease in range:
hills bet een the TBSL1 and the Gate ay
tree canopy bet een the TBSL1 and the Gate ay, particularly trees
ith fine needle leaves hich act can absorb signal hen they are et
metal objects placed close to the TBSL1 antenna.
1.2. TBSL1 Data Path
The path of data from a LoRa WAN Node to the Presentation soft are (the
default is to use Sensori) is sho n in the image belo .
The readings from the sensors connected to the TBSL1 are saved in the unit’s
memory. At the programmed Send Interval (e.g. 15 min) the readings are
8

transmitted via LoRa WAN to a radio base station – hich in a LoRa WAN
environment is called a Gate ay.
The Gate ay sends all the received messages (or packets) to a LoRa WAN
Server.
A LoRa WAN Server ill contain one or more “Applications” hich belong to
different users. Each Application ill in turn contain a number of “Devices”
(telemetry units or RTUs). Each Device is has a unique identifier.
When devices are created on the LoRa WAN Server, they are allocated a set
of encryption keys: one is used to signal that a device has a legitimate right to
use the net ork, the other is used to encrypt the data.
When the LoRa WAN Server receives a message, it checks to see if it
recognises the Devices unique identifier (its EUI). If not, it rejects the
message. If it does, it unencrypts the message and saves the contents in its
database.
Over time the LoRa WAN Server ill accumulate sets of readings for each
Device. These can then be collected by the programmes used to display and
interpret the readings
•the servers typically offer t o or more ays to access this data
•the first is using a proprietary URL based XML format
•the second is by using an open protocol called MQTT.
One of the complications of LoRa WAN is that the LoRa WAN Server does not
kno anything about the sending device and hence hat type of sensors(s)
are connected. So if you are orking ith devices hose configuration can
vary, you must manually unpick the contents of each data packet based on
information about the values it contains.
This can get very complex if large numbers of devices are in use or if the
configuration changes.
To deal ith this complexity, Tekbox offers an IoT Broker hich does this ork
for you.
The Broker is configured ith the details of each device including the LoRa
WAN server to hich the device belongs and the sensors attached to it. When
9

packets are received, the Broker then unpicks them (parses the packets). The
readings are then saved along ith any there relevant information, such as the
units, the type of sensor etc.
The biggest benefit of this approach is that it scales easily to hundreds or
thousands of devices. It also means that the presentation soft are can be
given other relevant information about each device: such as its type, its GPS
coordinates etc. Similarly it gets the “meta-data” for each sensor.
In the Cellular units, the data is sent to the Tekbox IoT Broker hich in turn
passes it to Sensori
2. So tware Installation
2.1. New Installation
The TBSL1 Console Installer ill install the program in the directory:
C:\Program Files (x86)\TekBox Digital Solutions Viet Nam\
TBSLnConfiguration
When prompted, select "Install for all users".
You can change the installation directory another location during the
installation. The installer ill create a Start Menu entry for the program.
If you have installed for all users, the configuration files ill be saved in the
directory:
C:/Users/Public/Public Documents/TBSL1 Configuration Tool/Json
The installer ill create a shortcut on the Desktop. To ensure that you can
create and edit configuration files, edit the Shortcut and set the properties to
“Run as administrator”.
The TBSL1 GUI program and TBSL1 Firm are must be maintained at the
same version
the GUI soft are checks the TBSL1 firm are version henever it
connects
if the versions do not match, an error ill display on the screen
10

the error message ill clear once the t o are brought to the same
versions.you can check the TBSL1 firm are version in the Info tab of
the TBSL1 configuration screen
If you received an update to the TBSL1 firm are, al ays ensure you
update the GUI at the same time. This ill ensure that configuration
incompatibilities do not create errors
from time to time version changes may also modify the format of the
information used in the program’s configuration files. You should thus
create ne configuration files hen you update the program.
2.2. Upgrading from arlier Version
If you are upgrading from a previous version you must first uninstall it
•locate the Configuration files for the previous version and copy them to
a safe location. They ill typically be installed in the directory:
C:\users\Public\Public Doucments\TBSL1 Configuration Tool\
JsonFile
•the installer ill not over rite the default config files so you must
delete them - other ise the program may exhibity unpredictable
behaviour
◦ locate and delete the t o default configuration files Settings.json
and defaultsettings.json (alternatively rename them if you ant to
retain them)
•open Control Panel and select Programs and Features
•locate the TBSL1 Console program entry and select Uninstall
◦the uninstaller ill remove the EXE file but ill leave your
configuration and log files intact
•no run the installer as sho n above
•if your old version maintained the configuration files in a different
location, copy the files to the directory used by the ne version.
11

3. Using the TBSL1 GUI
To open the GUI application, run the program from the start menu or by
clicking on the file TBSLnConfigurationTool.exe from the directory
here the application files are located, or by clicking on the desktop shortcut
you created during installation.
3.1.
Connecting to the TBSL1
In order to configure the TBSL1, the unit must have the Solar Panel
connected. This is because the start link (bet een Pins 3 & 4) on the socket is
used to activate the unit. If you are regularly setting up TBSL1 units you can
use a spare 5 pin plug to make up a dummy plug: simply solder a link bet een
pins 3 and 4 on the back of the plug. Note that you can also solder ires to
pins 1 (+) and 2 (-) to allo you to charge the battery from a 6V plugpack or
bench po er supply.
To ork ith the TBSL1, you must connect to the unit using the COM port
allocated to the device by your PC hen the unit is plugged in. Use the
Windo s Device Manager to identify the port.
To select the Port:
From the menu select Settings / Com Port Configuration
When the communications dialogue box opens, click on COM Port
and select the port allocated to the device form the drop do n list box
12

If the port has not displayed, click on REFRESH COMMS to have the
program re-scan for the available ports
Leave all the other settings on the default values
Once you have selected the port, the GUI ill attempt to communicate ith the
TBSL1. The result of the communications bet een the GUI and the device are
sho n in the Data Log section of the screen
Transmitted commands display in red >>
Responses from the TBSL1 are sho n in blue <<
If you ant to see more detailed information about the log information,
open the log file from the folder :
C:\Users\<User name>\AppData\Local\TBSL1\Logs
Warning:
I you hear the USB port on your PC continually being detected
and lost, it is likely to be because you do not have a Power Plug
in place. The link between Pins 3 and 4 on the Plug signals the
RTU to stay awake. I you connect a USB cable without this
plug/link present the PC will repeatedly detect and lose the USB
port.
13

3.2. Create and Save a Configuration File for the
Device
The TBSL1 GUI ill open ith a default configuration, hich is read from the
file:
C:\Users\Public\Public Documents\TBSL1 Configuration Tool\JsonFile\
defaultsettings.json.
To enable you to easily recall and modify configurations for specific TBSL1
units, you should save a configuration file for each device you install:
To create a ne Configuration file select File / Save As and then give
the file a suitable name e.g. TBSL1_SN_13423 or
TBSL1_Jones_Block_34
You may like to include the Serial number in the name. To identify the
Serial Number of the TBSL1, from the menu select Settings / TBSL1
Configuration and then click on the INFO tab
◦the serial number is sho n in the Board ID field.
Once you have saved configurations, you can re-load them at any time. In this
fashion you can create one device configuration file and then use it as a
template for future devices. You can also save a file for each of the standard
configurations you use (for instance your standard soil moisture probe site or
standard eather station).
3.3. Changing the Configuration Defaults
The default configuration file has settings compatible ith those used in Asia.
To save you from having to change all the settings each time you start a fresh
RTU, you can change the default settings to suit your preferences. From time
to time Tekbox may add parameters to the configuration file or change the ay
parameters are stored. This may cause the GUI to raise an error hen it is
saving a configuration file. When such changes are made Tekbox ill update
the default Configuration file. You ill then need to update the default file
again:
from the menu select File / Load Default Settings
14

once the ne configuration file opens, you should change the key
settings to suit the Channel plan you use
◦ADR Off
◦Freq Scheme AU915
◦SET CH: select and set the frequencies for AU 915 Sub Band 1
i.e. 916.8, 917.0… 918.2 (steps of 0.2)
◦Wait for ACK ON
◦Retry times 3
◦RXWIN 2 Freq DR 8
◦Tx Po er 14 Port 8
◦you can also update the Interval and SDI-12 settings
no use File / Save As and over rite the file “DefaultSettings.json”
then repeat, this time over riting "Settings.json"
the next time you need a ne configuration file it ill already have the
key values pre-set.
You should then re-create the configuration files for your devices using the
“DefaultSettings.json” as the template.
3.4. Changing Operating Mode
The TBSL1 can at any time be in one of t o modes: Console and Logging:
Console Mode: this mode is the default and is used to configure and
test the TBSL1
◦In console mode, the board doesn’t perform any
measurement/transmission operations. It only receives the
commands from the application, executes the commands on
sensor/LoRa module and send responses to the application.
Logging Mode: units must be set back to this mode to enable logging
◦This is the normal mode of operation for devices in the field
15

◦While in logging mode the GUI displays the results of commands
as they are executed on the TBSL1.
When po ered-up, the board ill send a “PING” command to the PC and ait
for a response from the application. If the application has started and the COM
port is open, it should ans er ith an “OK” response, after hich the date and
time are automatically programmed into the unit and the board ill s itch to
“Console” mode. When the TBSL1 first starts, it ill stay in “Console” mode.
In this mode, the board ill ait for commands to be sent – it ill not read the
sensors or transmit the readings. Any settings sent from the application at this
time ill only be saved in the board memory:they ill not be activated.
When you click on “Logging mode” button, the application ill send a
command to the board, telling it to s itch to “Logging” mode. Once in
“Logging” mode, the board ill activate the ne settings. After that, the board
ill go to sleep – and ill ake up according to its logging and transmission
settings.
From here you have t o options:
S itch to “Console” mode by clicking on the “Console mode”
button, hich ill send a command to the board. When the board next
akes up, it ill receive that command and s itch to “Console”
mode.
Stay in “Logging” mode. In this state, the board ill stay in its normal
logging mode of measure data -> go to sleep -> wake up -> measure
again and/or transmit data -> go to sleep again and go on. The time
bet een each sleep and ake up depends on the Interval settings in
the application.
NOTE : to save po er, the TBSL1 shuts do n the USB port if it has not been
used for a fe minutes. If you cannot get a response on the USB port, press
16

the Reset button, hich is located on the top of the PCB, belo the modem.
Alternatively, hold a magnet next to the top right corner of the case – this ill
trigger the Reset reed s itch.
3.5. Configuring the
TBSL1
Configuration can be broken do n into a number of functional areas:
Modem (Cellular or LoRaWAN) settings
◦for Cellular (4G and Cat M1) configuration, refer to section Error:
Reference source not found.
Measurement/Logging settings
Sensor Settings
3.5.1. LoRaWAN Settings
Before setting up the TBSL1 you must obtain all the relevant information on
the net ork to hich it is being connected and the Join type to be used
If you are using Over the Air Activation (OTAA) you ill need:
◦Device EUI
◦APP EUI
◦APP Key
If you are using Activation by Personalisation (ABP) you ill need
◦Device Address
◦Device EUI
◦Net ork Security Key
◦Application Security Key
17

To configure the LoRaWAN parameters:
From the menu select Settings / TBSL1 Configuration
When the Board Configuration menu, click on the LoRaWAN tab
In the LoRaWAN Settings section:
◦Select the activation type – ABP or OTAA
◦The fields required for each activation type ill be editable and
those not needed ill be greyed out
◦Fill in the required information ith the values given to you by your
LoRaWAN provider
◦Note that all fields are in “Big Endian” format i.e. ith high order
bytes first
3.5.2. Packet Acknowledgement Settings
LoRaWAN offers t o methods to reduce the risk of losing packets of data ( for
instance if t o or more devices transmitting at the same time)
No Ack rom Server : This is the simplest method : each packet is
simply transmitted multiple times in the hope that one gets through.
The LoRa Server then deletes any duplicated messages
◦The Repeat Times setting controls ho many times each
message ill be sent: initially try a value of 2, but if signal strength
is very good use 1
Wait Ack rom server : The recommended approach is to have each
Packet ackno ledged by the LoRaWAN Server. If this option is
selected, the device ill continue trying to send a packet until it
receives an Ackno ledgement. This is done by maintaining a Frame
Counter hich is incremented each time a ne packet is sent
◦the Retry Times setting controls ho many times to try repeating
the message before going on to the next packet
◦after successful transmission of a subsequent packet, the unit ill
come back and retry the missed packet(s)
18

◦set the Retry Times to a value of 3
For simple devices such as ater meters, you can use No Ack and 3
retries
For any application hich requires a contiguous data set, such as Soil
moisture and eather monitoring, you should use the Ackno ledged
packets option.
3.5.3. LoRa Frequency Settings
The LoRaWAN protocol defines a number of different channel plans based on
the region in hich the devices ill be operated. The standard channel plan for
Australia is AU915. This channel plan supports 64 channels broken up in to 8
sub bands, each ith 8 channels. This limitation is imposed because the
standard Gate ay chip set only supports 8 channels. While some early
net orks used sub band 0, most no use sub band 1 (Ch 8 to 15).
Note also some operators in Australia and Ne Zealand have also elected to
use the Asian region channel plan (AS923). This channel plan is supported by
the TBSL1 and can be selected from the TBSL1 GUI.
The RF parameters are set in the LoRa RF section of the screen
Adaptive Data Rate (ADR) set this to OFF
◦ADR helps maximise the capacity of large net orks by allo ing
devices close to the Gate ay to transmit at a high rate and those
further a ay to use a lo er data rate. But the lo data rates do
not support long packets so can not be used ith multi-parameter
sensors
Freq Scheme: this is here you choose the channel plan hich is
being used by the Gate ay
◦if you are setting up an on farm net ork, use AU915. But if you are
joining an existing net ork you must first find out hether it is
using AU915 or AS923 and then select the channel plan
accordingly. The Things Net ork uses AI915 CH 8-15
19

◦click on the SET CH button to bring up a list of the available
channels and their operating frequencies
◦The image belo sho s the settings for AU915 sub band 1. If
using Sub band 0, set the first channel to 915.2 ith each
subsequent channel 0.2 MHz higher. Clicking on Default Setting
ill reload the Sub band 0 settings (CH 0-7)
◦if you ant to avoid all other traffic, you could also use one of the
higher sub-bands
▪each sub-band just occupies the next 8 channels, ith the
frequency increasing by 0.2 MHz from one channel to the next
▪make sure that you choose the corresponding sub-band hen
setting up the Gate ay
20