The SensorData provides a number of configurable parameters, to allow its behavior to be tailored to specific applications.

Factors affecting the configuration you might choose include:

  • How many messages per day your network will allow
  • How often you intend to change the batteries, and the type of batteries in use
  • How good the GPS reception is in your installation


How the SensorData Connects

The SensorData connects to a local LoRaWAN network using Over The Air Activation (OTAA). Each SensorData is provisioned with:

  • A read-only DevEUI - a 16 digit code uniquely identifying the SensorData (printed on the label)
  • A configurable AppEUI - a 16 digit code uniquely identifying the website that data will be sent to
  • A configurable AppKey - a 32 digit code that authenticates the SensorData to the website and network server
    • The default AppEUI is 70-B3-D5-70-50-00-00-02 - this can be programmed with the config app. 
    • Each SensorData is provisioned with a random default AppKey - this can be read or programmed to another value via the app
  • A configurable Region and Channel Mask
    • The channel mask is only required in the US and ANZ regions, to set the network frequencies. Using an incorrect channel mask will result in unreliable data transmission. 
    • Other regions don't need the channel mask, as all their networks use the same OTAA frequencies

Once the region has been configured, the SensorData will attempt to join local networks by transmitting join requests. Any network that hears the join requests and has knowledge of the SensorData's DevEUI, AppEUI and AppKey, will allow the SensorData to join the network and transmit data.


Once joined, SensorData repeats the OTAA process once a week by default. This renegotiates encryption keys for enhanced security, and ensures continued operation in the event of a network losing the keys (for instance, if the device is mistakenly deleted).


How The SensorData Uses LoRaWAN Airtime

LoRaWAN devices can transmit at various data rates, usually denoted DR0, DR1, DR2, and so forth. The lowest data rate (DR0) takes the longest to transmit, but has the longest range. As the data rate goes up, the range goes down a bit, and the transmission time goes down a lot. SensorDatas can be configured to use a particular data rate, or a range of data rates (ie. DR2-DR4). Lower data rates will have the longest range, but also use the most battery power and airtime. When configured to use a range of data rates, the SensorData spends an equal amount of airtime using each data rate. The SensorData also has optional Adaptive Data Rate support, which allows the network server to intelligently control the data rate.


There are several factors limiting the maximum transmission rate of an SensorDatar:

  • Radio regulations may limit the transmission time
    • In Europe the law limits you to 36 seconds of transmit time per hour on most frequencies
    • Whereas in Australia there is no legal limit
  • Networks may limit the transmission time, to prevent congestion
    • The Things Network for instance limits you to 30 seconds of transmit time per day
    • At DR0, this gives you 20 messages with 100% range
    • At DR1, this gives you 36 messages with 75% range
    • At DR2, this gives you 80 messages with 50% range
    • At DR3, this gives you 145 messages with 37% range
    • At DR4, this gives you 265 messages with 28% range
    • At DR5, this gives you 486 messages with 21% range
    • In America, data rates are all two increments higher, so DR0 corresponds to DR2 in the above list
  • Networks may limit the number of messages, for billing purposes
    • Your network might require you to pay more for higher throughput

The radio regulations are automatically enforced by inserting delays between messages where required. It is up to the user to configure their SensorData with a low enough transmission rate to meet network and battery life requirements.


How the SensorData is configured

Firmware updates (and optionally, configuration) are performed with a plug-in USB adapter, and a Windows configuration app. An adapter can be obtained from your SensorData distributor. 

Get the config tool here: https://www.oemserver.com/tools/SensorDataLoRaWAN/ConfigTool/setup.exe 


The adapter plugs into the four pin connector near the push button. If your adapter has a red wire fitted, it will supply power to the SensorData while it is plugged in. If it doesn't, you must power the SensorData with batteries during configuration. 




To read the available parameters, select your adapter from the drop-down list in the top right, and click Start. Then hold down the push button for 5 seconds, until the board LED turns on. The configuration tool will read the currently programmed parameters, and display them in the center column. To program new parameters, enter the desired parameters in the right hand column, and check the Program Parameters button. Checking the Program Firmware button will additionally update the SensorData with the bundled firmware.



If you click the DEV EUI button, a list containing the Dev EUI, Default AppKey, AppEUI and AppKey will pop up. You can hot-plug the adapter (and hold the push button) into many SensorDatas in sequence to populate the list. When no changes are made to a SensorData, the information is added in grey. When the SensorData is programmed, the keys are added in black. After programming, the SensorData will take several seconds to reboot before it will be visible in the application again. It is not necessary to wait for this to occur before moving on to programming the next unit.


It is worthwhile copying and pasting from this list when setting up devices on your LoRaWAN network, to avoid the chance of typos. 



Configuration Options

The top line in the display shows the Dev EUI, and firmware version. In the screenshot above, the Dev EUI is 467D12542B3F4596, the firmware version is 63.1.1.1 (product, hardware revision, major, minor)


The 'Reset To Default' button in the top of the right column resets the whole right column to the default settings. The settings are described below


Parameter Date:

    When the SensorData was last programmed. 


LoRaWAN 

Region:

This selects the radio frequencies to use according to your country. Please be sure to select the correct region, to maintain compliance with your country's radio regulations. SensorDatas leaving the factory are currently pre-configured for either the European 868 MHz band, or sub-band 2 of the Australian 915 MHz region, depending on their hardware type. However, this is subject to change, and in the future the region may be left unset. If the region is unset, the Oyster will not transmit until configured.

AppEUI: 

This identifies the backend website that your data should be sent to. If you leave it blank, the default for the SensorData LoRaWAN (70-B3-D5-70-50-00-00-02) will be used.

AppKey: 

This 32 character key authenticates the SensorData with the backend website and network server. If you leave it blank, the SensorData will use a unique random key, which was written to it in the factory. This default key can be read from the DevEUI list dialog, or the label on the box. It is not printed on the SensorData's label. The AppKey cannot be reconfigured over the air.

Channel Mask:

In the US and ANZ region, you must set this channel mask to select which of the 72 uplink channels your network provider uses. The parameter is one big hexadecimal number, with the lowest channels corresponding to the rightmost digits. For example:

Sub-band 1 uses channels     0-7, and channel 64, so it's mask is 0100000000000000FF

Sub-band 2 uses channels   8-15, and channel 65, so it's mask is 02000000000000FF00

Sub-band 3 uses channels 16-23, and channel 66, so it's mask is 040000000000FF0000

Sub-band 4 uses channels 24-31, and channel 67, so it's mask is 0800000000FF000000

Sub-band 5 uses channels 32-39, and channel 68, so it's mask is 10000000FF00000000

Sub-band 6 uses channels 40-47, and channel 69, so it's mask is 200000FF0000000000

Sub-band 7 uses channels 48-55, and channel 70, so it's mask is 4000FF000000000000

Sub-band 8 uses channels 56-63, and channel 71, so it's mask is 80FF00000000000000

To select all channels, you'd use FFFFFFFFFFFFFFFFFF

The configuration app default is blank, which results in the selected region's default channels being used. In both the US and ANZ region, this is the same as enabling all channels, and will lead to packet loss if your network is only using a single sub-band.

Min/Max Data Rate:

These parameters select the minimum and maximum data rates to transmit at, when ADR is not active. A '0' selects DR0, the lowest data rate with the longest range. If you set both parameters to the same value, the SensorData will always use that rate. If you choose a range, the SensorData will alternate between the allowed data rates in such a way as to spread the transmit time evenly. This means it will use the higher data rates more often. Using a range of data rates allows the network to support more devices per gateway, but reduces your guaranteed range to the range of the highest data rate. Using higher data rates may allow you to send more messages per day. Please see the section 'How The SensorData Uses LoRaWAN Airtime' above. The default is DR0-DR2.

Adaptive Data Rate:


Rejoin Period:

By default, the Oyster rejoins the network once a week, in case the network server has somehow forgotten the session keys. This period can be extended to up to 255 days, or disabled entirely (0). However, if a device is accidentally deleted on the network server, or the network server suffers a database failure and loses the session keys, the server will be unable to decrypt any device data until it has rejoined. Rejoining weekly generates several extra transmissions, but lowers the time spent out of service in the event of an accident.


Scheduler:    


Out of the box, the SensorData LoRaWAN is not configured to take any readings, and must be first configured by setting up schedules. Currently, there can be up to 5 different schedules, each with 4 items, which represent a single data source (analog input reading, GPS position, battery voltage, etc). Each schedule is completely independent, but if 2 (or more) happen to occur at the same time, they will be run one after the after (without grouping data into transmissions). 


Period: 

In minutes, this is how often the schedule gets run. Care must be taken in choosing this value, in order to not exceed your uplink budget, which is determined by your LoRaWAN network.


Item IDs: 

Options are - Version, GPS Position, Battery Voltage, Analog Input 1, Analog Input 2, Digital Inputs (returns all digital input states), Digital Input 1 Count, Digital Input 2 Count, Digital Input 3 Count, Internal Temperature (Temp as measured by PCB temp sensor), DM Temperature Probe 1 (probe at I2C address 0), DM Temperature Probe 2 (probe at I2C address 1), DM Ambient Sensor, SDI12 Measurement 1, SDI12 Measurement 2, SDI12 Measurement 3, SDI12 Measurement 4, SDI12 Measurement 5

        

SDI 12 Measurements

    Currently, 5 are available


Vout Power Up Delay: 

    How long to wait after powering up the sensor until a reading is taken

Address:

    SDI 12 address of the sensor, 0-9  - 0 is the default if using only 1 sensor

Measurement Type:

SDI 12 measurement number 0-9

Measurement Count:

    Number of data points, 1-15

Data Conversion:

Soil Moisture (UINT8):

Values are packed into UINT8 fields. SMP = (Value in field / 2) - 5. Providing a range of -5 to 122.5 with 0.5 precision

Temperature (UINT8): 

Temp = (Value in field / 2) - 40, yielding a range of -40 to 87.5 with 0.5 precision

Generic INT16 * 100

Allows a reading to be +-32767.00 with 2 decimal places

Generic INT32 * 1000 (not yet implemented) 

Allows a reading to be +- 2 147 483 with 3dp


GPS

Devices are shipped with relatively loose requirements for a fix - shown below. This generally speeds up fixes and allows fixes in adverse conditions. Simply put, the device will minimise the time spent with the GPS on. This means that even in good signal conditions, a poor fix may be accepted


Fix Timeout:

    Maximum time to spend for the GPS to get a position fix, per attempt. Default is 20s. This limits the battery drain if there is no GPS signal.

Minimum Required PDOP:

    Position Dilution of Precision (PDOP) values below this value will be accepted

Minimum Required Position Accuracy:

    Position accuracy values lower than this are accepted

Minimum Required Speed Accuracy:

    Fixes with speed accuracy values lower than this are accepted

GPS Model:

This informs the GPS module of what sort of motion to expect from the asset, allowing it to make better estimates when moving. The Automotive setting is a safe default, but the Pedestrian and Stationary settings may be useful as well. Setting the model appropriately allows the GPS to filter out noise more effectively

Require 3D Fix:

    When unchecked (False) 2D fixes are accepted. 

Discard First N Fixes:

    Discard this number of fixes once the accuracy requirements are met. 


Digital Inputs

See here for an article on Digital Inputs


There are 2 digital inputs on the SensorData LoRaWAN. These can be used to monitor the state of external devices or switches, or to count pulses - from a rain gauge for example. 

The inputs have a maximum input of 48V, and anything about 2.5V or above is considered 'on'. 

Note: On the initial PCB revision, only input 1 can be used as a pulse counter or alarm source. This will be changed in future revisions. 


An alarm message can be sent, if set up, when an input changes to a certain value. Care must be taken with the parameters to ensure that alarms aren't generated that would use up the uplink budget of the LoRaWAN plan in use. 


Maximum Alarm Rate:

The minimum time between alarm transmissions. If an alarm occurs before this time has passed (from a previous alarm), it will be ignored. Default is 600s (10 minutes). This can prevent excessive uploads if for some reason an input stays at a certain value, and helps conserve your uplink budget. 

Input Pull Direction:

    Whether the input should be set to pull up or pull down. See here for more information.

Input Alarm on High/Low:

    Enabling either of these will send an alarm message when the condition is met, i.e. Alarm on high enabled = sending message when the input turns on. Default is disabled for both.

Input Count Edge:

Sets if the input count is incremented when the input turns on, or off. Default is high (count when input turns on).

Input Debounce Period:

    The input has to change for this amount of time for the change to be detected. Default value is 1000 ms (1 second).


Analog Inputs

The SensorData LoRaWAN has 2 analog inputs which can be used to measure voltages up to 30v. Outputs on the device can be enabled just before sampling, to power external sensors. Sampling occurs over roughly 100 ms, in which multiple readings are taking, and the average is calculated to be sent over the network. The following parameters are configurable:


3.3V Out on Sample:

Enables the 3.3V output to power sensors when sampling.

Vout on Sample:

Enables Vout when taking a sample. This can be either 6 or 12v, depending on whether output boost is enabled on the circuit board (using the jumper).

Power on Delay:

 How many seconds after enabling outputs the device will wait, before taking a sample. Can be used to give external sensors enough time to power on fully. This delay is ignored if no outputs are to be enabled.