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 (OTAA)

By default, the SensorData connects to a local LoRaWAN network using Over The Air Activation. Each SensorData is provisioned with:

• A read-only DevEUI - a 16 digit code uniquely identifying the SensorData (printed on the label)
• A configurable JoinEUI / AppEUI - a 16 digit code identifying the server the device is registered with
• A configurable NwkKey (1.1) / AppKey (1.0) - a 32 digit code that authenticates the SensorData to the network server
• A configurable AppKey (1.1) - a 32 digit code that authenticates the SensorData to the application server
  • The default JoinEUI is 70-B3-D5-70-50-00-00-02
  • Each SensorData is provisioned with a random default NwkKey and AppKey (1.1)
• A configurable Region and optional Channel Mask
  • The channel mask is used in the US915 and AU915 regions, to set the network frequencies
  • 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, JoinEUI and keys, will allow the SensorData to join the network and transmit data.

The SensorData rejoins the network once every two weeks 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 Connects (ABP)

The SensorData can also be configured to connect using Activation By Personalization. When using ABP, each SensorData must be configured with some additional numbers:

• A configurable DevAddr - an 8 digit code identifying the SensorData to the network
• 32 digit session keys FNwkSIntKey (also known as NwkSKey)and AppSKey,on LoRaWAN 1.0
• 32 digit session keys FNwkSIntKey, SNwkSIntKey, NwkSEncKey, and AppSKey, on LoRaWAN 1.1

ABP allows a LoRaWAN device to connect without exchanging the usual join request and join response, which can save on downlink bandwidth, and allow the device to work when downlink reception is difficult. However, in LoRaWAN 1.0, the ABP mechanism is somewhat problematic. It either suffers from a lack of security (if you configure your device to reset it's uplink frame counts when it resets), or difficulty with configuration (if you don't reset the frame counts, and are in a region requiring dynamic channel configuration). These issues are fixed in the LoRaWAN 1.1 specification, but since the fix negates the chief advantage of ABP by requiring some downlink traffic, we recommend OTAA.

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 SensorData:

• 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 initial configuration are performed with a plug-in USB adapter, and a Windows configuration app. Once deployed, the SensorData can be reconfigured over-the-air using downlinks (details here).

An adapter can be obtained from your SensorData distributor. 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 and firmware, enter the desired parameters in the right hand column, and check the Program Parameters button. To update the firmwares only, check the Program Firmware checkbox, and leave the Program Parameters checkbox clear.

If you click the DevEUI List button, a list of DevEUIs and cryptographic keys will pop up. You can hot-plug the adapter (and hold the push button) into many SensorDatas in sequence to populate the list. Each time a SensorData is programmed the parameter list will flash, the DevEUI list will update, and a chime will sound. The list is in CSV format, so it can be imported into a spreadsheet easily. It's worthwhile copying and pasting from this list when setting up devices on your LoRaWAN network, to avoid the chance of typos. 

The top line in the display shows the DevEUI and version string. In the screenshot above, the DevEUI is 70B3D57050003ED1, and the firmware version is 63.1.2.0 (product, hardware revision, major, minor). Hovering the cursor over a line reveals an action menu ('...') and a help pop-up ('?'), from which you can copy, reset, and inspect parameters and sections. Save and load functions are available in both the File menu and the All Parameters action menu.

Configuration Options

Basic 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. SensorData devices leaving the factory are currently pre-configured for either the European 868 MHz band, US915 or AS923 1.0.3, 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 SensorData will not transmit until configured. Otherwise, to prevent the SensorData from transmitting before configuration, click the Start button on the tool, and plug the cable into the SensorData, before inserting the batteries. The region cannot be reconfigured over the air.
Next to the region you will see the associated LoRaWAN Regional Parameters revision. Currently only AS923 and AU915 have multiple revisions to choose from:

•  In AS923, the 1.0.3 version uses both SF10 and SF9 for join requests, rather than just SF10 in the 1.0.2 version
•  In AU915, the 1.0.3 version supports the new 'uplink dwell time' restriction, so it joins at SF10 instead of SF12

Sub-Band / Channel Mask:

In fixed channel regions (US915 and AU915) you can select a sub-band or channel mask, instead of using all 72 channels at startup. Strict compliance with the LoRaWAN standard requires enabling all channels, but if you are confident that your network will not change its operating frequencies, choosing a sub-band speeds up the join process. If you choose a custom channel mask, the hex string you must provide has the lower numbered channels on the right hand side. For instance, 010F in hex is 100001111 in binary, and selects channels 0-3 and 8. On some older network servers, choosing a sub-band might be mandatory to avoid packet loss. The default is 'All'.

Activation:

This chooses between the default (and recommended) Over The Air Activation, and Activation By Personalization. In OTAA, the SensorData and the network server generate the session encryption keys and device address during a join request / join response exchange. In ABP, you have to generate the encryption keys and device address beforehand, and configure them. When choosing ABP, you also have to choose your LoRaWAN version.

Reset FCnts:

This option is available in ABP 1.0 only, and resets the uplink and downlink frame counts whenever the device is reset. This defeats the encryption entirely, but is required by many networks in LoRaWAN 1.0, so that the network server can detect the device reset and reconfigure the device's channels. It is vital that you pick the setting appropriate to your network, or your device may stop connecting after a reset. If you're not sure, you should probably choose 'Yes'. The default however is 'No', for strict compliance and security.

JoinEUI / AppEUI:

In OTAA, this identifies the server your device is registered with. If you don't set a custom JoinEUI, the default for the SensorData LoRaWAN (70-B3-D5-70-50-00-00-02) will be used. In LoRaWAN 1.1, changing the JoinEUI resets the cryptographic counters used by the join server (RJCnt1, DevNonce and JoinNonce). So if you reset the counters on your join server without changing the JoinEUI there, you can reset them on the device by choosing a temporary JoinEUI, writing it to the device, and then configuring it back again.

NwkKey (1.1) / AppKey (1.0):

In OTAA, this 32 character key authenticates the SensorData with the network server. If you don't set a custom key, 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. This key cannot be reconfigured over the air. Please note that this key was renamed by the LoRaWAN standard in the 1.0 to 1.1 upgrade, in the most confusing way possible. So the label on your SensorData will either read AppKey (with no version number), or NwkKey.

AppKey (1.1):

In OTAA, this 32 character key authenticates the SensorData with the LoRaWAN 1.1 application server. This key isn't needed in LoRaWAN 1.0. If you don't set a custom key, 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. If your SensorData is new enough, it will be written on the label on the box. On older devices, only the AppKey (1.0) is on the label.

Device Address:

This 8 character number identifies the SensorData with the network server. It is only applicable to ABP activation.

FNwkSIntKey / SNwkSIntKey / NwkSEncKey / AppSKey:

These are the 32 character ABP session keys. Only the first and last are required in LoRaWAN 1.0. They may be referred to as the Network Session Key (NwkSKey) and Application Session Key (AppSKey) on your network server.

Advanced LoRaWAN

Adaptive Data Rate:

ADR is a server side mechanism for controlling the data rate, to optimize network capacity and battery life. By default, the SensorData doesn't use ADR.

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.

Roaming Rejoin Uplink Period / Time Period:

This sets the initial maximum number of uplinks / minutes between Rejoin0 Requests in LoRaWAN 1.1. These requests facilitate roaming, and can be reconfigured by the network server at runtime. The default values are the maximums, effectively disabling these requests until the server asks for them.

Rejoin / Reset Time Period:

By default, the SensorData rejoins the network once every two weeks, 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. The exact rejoin behavior depends on the Activation and LoRaWAN version:

• In ABP, the rejoin is equivalent to removing and reinserting the batteries. All protocol state is reset, with the exception of the uplink and downlink counters (unless you have chosen to reset them as well, in LoRaWAN 1.0)
• In OTAA 1.0, the rejoin is also equivalent to removing and reinserting the batteries. A regular Join Request will be sent.
• In OTAA 1.1, a Rejoin1 Request is used to rejoin without resetting any protocol state. Please note that older network servers might not support this mechanism.

ADR Ack Limit / Delay:

This parameter control the number of uplinks between checks that the server can still hear the device when ADR is active. The device starts asking for a response once the Limit is reached, and if no response if heard after Delay attempts, the device switches to a lower data rate. The default values (64 and 32) are very slow. Please consult your network support before choosing more aggressive settings, as they may have policies forbidding lower values. In LoRaWAN 1.1, these values can also be set dynamically by the network server.

Receive / Join Delay:

These setting control the timing between a request and a response on the network. You shouldn't change them from the defaults unless instructed to by your network. The defaults are 1 and 5 seconds respectively.

Repetitions:

This sets the default number of frame repetitions (called NbTrans in the standard). Usually this value is one, until the server requests a higher number. You shouldn't change this value unless you have special requirements (for instance, a transmit-only ABP configuration).

Tx EIRP Limit:

This setting restricts the transmit power to the given value, in dBm EIRP. This allows you to save a small amount of battery on the transmission, and limit the peak current draw from the batteries. Limiting the current may be useful in cold weather (less than 0°), where batteries begin to struggle. A setting of 11 dBm drops the peak current from 127 mA down to 34 mA, which is roughly the same as the GPS module current. Lower values are not recommended. Your network server may require knowledge of the maximum power to correctly operate its ADR algorithm. In this case, be sure to configure the device accordingly on the server. The default is maximum power.

Random Tx Delay:

This parameter allows you to insert a random delay before transmission. This may be useful in applications involving a large number of SensorDatas with linked digital input alarms. The random delay spreads the transmissions out, so they don’t interfere with each other.

• The amount of delay required depends on the data rates in use. For a single spreading factor, you need approximately (Number of units) / 1500 * 1.9^SF). For instance, for 100 units at SF10, you'd need 100 / 1500 * 1.9^10) = 613 / 15 = 41 seconds.
• For multiple spreading factors, the formula is (1/DelayA + 1/DelayB + 1/DelayC + ...)^-1, where DelayX is the delay required for one of the spreading factors. So for 100 units at both SF10 (41 seconds) and SF9 (22 seconds), you'd need (1/41 + 1/22)^-1 = 14 seconds.

The default is 0 seconds.

Schedule 1 / 2

Out of the box, the SensorData is not configured to take any readings, and must first be 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 other (without grouping data into transmissions). 

Schedule Period: 

This is how often the schedule is run. When choosing this value, care must be taken not to exceed any uplink budget imposed by your LoRaWAN region or network.

Schedule Expiry:

This sets the maximum delay between a measurement being taken, and the start of its transmission. Since measurements are not sent with a timestamp (to help fit them into the tiny LoRaWAN packets), any delay between taking a measurement and sending it (due to duty cycle constraints for instance) cannot be detected on the server. Note that additional sources of latency NOT affected by this expiry are any random backoff configured, and latency induced by frame repetitions. The SensorData attempts to reduce latency to a minimum by waiting backoffs before taking measurements wherever possible, and by sending any required repetitions at the maximum speed allowed by the radio regulations. The default value is zero (no limit).

Items 1-4:

This selects which measurements will be sent every time the schedule is run. Options are:

• Version (the firmware version)
• GPS Position 
• Battery Voltage
• Analog Input
• Digital Inputs (current state of all digital inputs)
• Digital Input 1 / 2 Count (pulse count for selected input)
• Internal Temperature (measured by PCB temp sensor)
• DM Temperature Probe 1 / 2 (from external probes at I2C address 0 and 1)
• DM Ambient Sensor (from external temperature and humidity probe)
• SDI-12 Measurement 1-5 (from the corresponding SDI-12 measurement setup)

Enable 3.3V / Vout:

Enables the 3.3V or Vout output to power sensors when running the schedule. This is enabled at the schedule level: it is enabled for Power On Delay seconds at the start of the schedule, then kept active for each item in the schedule, and switched off after sampling is complete.

Power On Delay:

How many seconds to wait before running the schedule, after enabling outputs. Can be used to give external sensors enough time to power on fully. This delay is ignored if no outputs are enabled. Default is 0 seconds. This setting is provided in addition to the setting under the "analogue input 1/2" section to allow the power outputs to be use in a more flexible way (eg. power an on/off sensor before digital inputs are sampled).

Digital Input General

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'. An alarm message can be sent when an input changes to a certain value. Some further information is available in this article.

• On the first PCB revision, only input 1 can be used as a pulse counter or alarm source. From revision 2 onwards, both inputs can be used.
• When configuring alarms, care must be taken not to exceed any uplink budget imposed by your LoRaWAN region or network.

Alarm Rate Limit:

Digital Input 1 / 2

Pull Direction:

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

Alarm on High / Low:

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

Alarm Schedule:

If set, this chooses a schedule to run whenever the alarm condition is met. Default is None.

Count Edge:

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

Debounce Time:

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

Queue Alarms:

Queues alarms that would otherwise be dropped due to rate limiting. When rate limiting is enabled, each alarm event is followed by a hold-off period. By default, any events occurring within the hold-off period are dropped. When this parameter is enabled:

• Events occurring within the hold-off period will be deferred until the end of the period
• If multiple events occur for a particular input, only one event will be sent at the end of the period, for that input
• If events occur for more than one input, one event will be queued for each input. Lower numbered inputs will send their queued events first, followed by another hold-off period, and then higher numbered inputs.

Default is No.

Analog Input

The SensorData LoRaWAN has 1 analog input which can be used to measure voltages up to 30 V. Outputs on the device can be enabled just before sampling, to power external sensors. Sampling occurs over roughly 100 ms, during which multiple readings are averaged.

Enable 3.3V Out:

Enables the 3.3V output to power sensors when sampling.

Enable Vout:

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

Power On Delay:

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

SDI-12 General

Power On Delay:

This chooses the time delay between enabling power to the SDI-12 sensor, and taking the measurement.

SDI-12 Measurement 1-5

Address (0-9):

SDI-12 address of the sensor. 0 is usual if using only 1 sensor. Default is None (disabled).

Measurement Type (0-9):

This is the SDI-12 measurement number, which chooses between the different quantities a sensor can measure, such as soil moisture, temperature, and salinity. The meaning of the type number varies between different sensor models.

Measurement Count (0-20):

This is the number of data points to measure (ie. the number of zones on the sensor).

Data Type (0-9):

This sets the format that the measured values are transmitted in. Options are:

• Soil Moisture (8 bit format covering -5 to 122.5, with 0.5 precision)
• Soil Temperature (8 bit format covering -40 to 87.5, with 0.5 precision)
• INT12 (12 bit format covering -50 to 154.7, with 0.05 precision)
• INT16 (16 bit format covering -327.68 to 32767, with 0.01 precision)
• INT32 (32 bit format covering -2147483.648 to 2147483.647 with 0.001 precision)

GPS

Devices are shipped with relatively loose requirements for a fix. This generally speeds up fixes and allows fixes in adverse conditions. However, because the time spent with the GPS on is minimized, a poor fix may be accepted even in good signal conditions.

Coarse Accuracy Mask (5-100 m):

This is the required position accuracy for a position fix to be considered valid. It provides a lower bound on accuracy. Please note that it works on the estimated accuracy, and it is not uncommon for position fix errors to occasionally be two or three times larger than the mask. Also note that values lower than 20 will be difficult to achieve in practice. The default is 75 meters.

Fix Timeout (20-65535 s): 

The maximum time to spend waiting for the GPS to get a coarse position fix, per attempt. This limits the battery drain if there is no GPS signal. Values lower than 60 are likely to be problematic in practice, with 35 being an absolute minimum in very good signal. The default is 90 seconds.

Require 3D Fix:

This requires that a position fix use 4 satellites, and calculate a height as well as latitude and longitude, before being considered valid. It is recommended, as using only 3 satellites gives less redundancy in the rare event of a satellite failure, increasing the risk of a position fix giving an erroneous result. However, disabling this option can allow fixes to proceed faster, and in adverse conditions such as urban canyons. The default is false.

Discard First Fixes (0-255):

This option discards the first few valid position fixes from the GPS module. This gives the module some time to refine and cross-check its estimate, reducing the risk of an erroneous fix in the rare event of a satellite failure. We recommend the default value of 3.

Speed Accuracy Mask (3-20 km/h):

This is the required accuracy of the speed component of a fix, before the fix is considered valid. The default is 9.7 km/h.

PDOP Mask (2.5-10):

The PDOP is a measure of how imprecise a GPS fix is, due to the satellites used being too close together to triangulate effectively. This parameter sets an upper bound on the imprecision, for a fix to be considered valid. You can safely use the default value, and specify the Coarse Accuracy Mask instead. The default is 10.

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.

Sensors

MLX90614 Sample Period (0-255 mins):

Independent sampling period for the MLX90614 infrared thermometer . When non-zero, the temperature samples will be taken at regular intervals, and the latest sample will be reported when the schedule runs. This produces approximately evenly spaced samples, independent of network conditions. When set to 0, the samples are taken when the schedule runs, so they are as fresh as possible, but might not be evenly spaced. The default is 0.

MLX90614 Power On Delay (0-15 s):

The delay between turning on the MLX90614 infrared thermometer, and taking a reading. The default is 1 s.

MLX90614 Number of Samples (1-255):

The number of samples to average from the MLX90614 infrared thermometer. The default is 1.

Custom Channels 1-8

Channel Number:

In variable channel regions (everything except AU915 and US915), it is possible to pre-configure some of the channels. Usually, the device joins on one of the two or three fixed join channels specified by the LoRaWAN Regional Parameters. Thereafter, the server configures the additional channels in the join response (with the 'CFList'), or using individual NewChannelReq messages. However, you may wish to pre-configure the additional channels manually, so that the server doesn't have to. In this case the additional channels are filled in this section, with channel numbers that follow on after the default join channels. For instance, if your region specifies two default join channels (channel 0 and channel 1), you will number your first custom channel '2'. The default value is zero, which disables the channel until the server configures it.

Min / Max Data Rate:

These set the range of data rates supported by the channel. Usually the minimum is zero, and the maximum is between 4 and 7.

Tx / Rx Frequency:

These set the channel center frequencies for uplinks and downlinks respectively. Some networks use two separate frequencies, but most will use the same frequency for both.