LoRaWAN Temperature Humidity Sensor Manual

freezer monitoring system
  • Industrial Grade LPWAN IoT Sensor
  • Resolution of 0.01°C / 0.01%RH
  • Accuracy of ±0.1°C / ±1.0%RH
  • Sensor Probe Operating Temperature Range: -40 to +125ºC / -40°F to 185°F
  • Sensor Probe Operating Humidity Rating up to 0 – 100%RH
  • Wall-Mounted or Magnet Mounted IP65 Rated Enclosure
  • Up to 2 Miles of range in Urban environment and 10+ Miles of range in an open environment (Line of Sight – LoS)
  • Platform agnostic – Microsoft® Azure®, Losant, Loriot, AWS IoT Core, Helium, TTI/TTN
  • Compliant with LoRaWAN® 1.0.4
  • Power-Efficient Sleep Mode, Up to 10 Years Battery Life
  • User Configurable Sleep duration

Overview

Introducing NCD’s first LPWAN node. This device features LoRaWAN 1.0.4 compatibility providing up to 2 miles range in dense urban environment and 10+ miles range in an open environment. 

This sensor incorporates a precision Sensirion SHT45 Temperature and Humidity Sensor and a transceiver that sends data at user-defined intervals. This IoT Temperature Humidity Sensor goes into deep-sleep mode between transmissions to minimize power consumption and prolong battery life.

Incorporating a highly accurate (±0.1°C ±1.0%RH) temperature humidity sensor, the node send keep-alive packets of temperature and humidity data at user-defined intervals.  The on-board IoT Temperature Humidity Sensor is rated for -40°C to 125°C or -40°F to 185°F.

The device is powered by just 4 AA batteries (included), you can expect to achieve up to 10 years of battery life depending on environmental conditions and the transmission interval you choose.

The NCD LoRaWAN Temperature and Humidity Sensor has one of the longest ranges, highest accuracies, longest battery lives, and best build quality on the market today and it comes at a very competitive price.

Main Features/Functionalities

0.01°C / 0.01%RH Resolution:

Resolution is a metric that describes how small of a change of the measured metric it can distinguish. This directly translate to how fine the granularity of the measurements it, in other words how sensitive the device is to changes in the environment (in this case changes in temperature and relative humidity). Industrial applications tend to be more demanding when it comes to resolution, compared to general ones. As a rule of thumb temperature resolution below 0.1°C and relative humidity of below 0.1%RH is considered a measure of a good sensor. With its 0.01°C / 0.01%RH resolution the NCD sensor satisfies even the most stringent requirements (Critical and specialty applications), going beyond what the general industrial application requires.

±0.1°C ±1.0%RH Accuracy

This is a measure of how close the provided measurement data is to the actual value of the temperature / humidity. A low accuracy means introducing a relative large measurement error, which might provide data that is not correct leading to wrong decisions, or critical failure. Industrial applications require temperature accuracy beyond ±2°C and humidity accuracy of at least 5%RH. The NCD sensor is capable of a lot more, making it suitable not only for general industrial applications, but also precision level scenarios.

-40 to 125ºC Temperature and  up to 100% Humidity Operating range:

The wide range of operating temperature and the high upper limit for humidity make the sensor suitable to operate in diverse environments. Industrial settings tend to have operating conditions that are a lot more extreme than residential ones, thus a higher decree of reliability is required at a higher level of performance. This makes the device more practical as it can be utilized in opposing environments, for example the same sensor would work equally as good in a freezer or in an engine (excessive head from motor) or a  or boiler room. This simplifies network deployments as you only need one device, which makes it quicker to deploy and easier to manage.

Low Power Wide Area Network support (LPWAN) utilizing LoRaWAN®:

When it comes to wireless sensors, the range is an essential parameter (together with battery life and accuracy/resolution). If you want to upgrade a facility with wireless environmental monitors, you job will be a lot easier if you choose a technology that can provide you with a stable, interference-resistant link over as large a distance as possible (this ensures you have sufficient link budget margin in case of heavy attenuation as in dense walls and metal structures). LoRaWAN® is one of the best out there in this regard. The default Frequency plan is FSB6. 

Configuration mode:

Over-the-air (OTA) configuration via downlink messaging. You can configure all parameters relevant to the devices operation via a set of commands that are sent in real time. You can change network related settings such as Transmission interval, Node ID, Data Rate, Frequency band etc. This gives you full control over the sensor and eliminates the need of on-site configuration in order to save up time. A complete set of APIs is provided as reference to command structure (see Appendix A).

Platform agnostics, you own your data:

This sensor does not require the utilization of a specific platform. It utilizes an open communication protocol and can be used with any platform / vendor, provided one adheres to the LoRaWAN protocol data structure. You can interface it with a number of LoRaWAN Network Servers (LNS), like Microsoft® Azure®, Losant, Loriot, AWS IoT Core, Helium, TTI/TTN. As NCD provides a complete set of APIs that you can use for configuration and data parsing you can integrate your LNS with any post-processing platform. For example you can utilize it together with a generic MQTT broker to push the data to your server, send it to an HTTP endpoint, utilize open tools like Node-RED, Grafana, etc. for data post processing.

Confirmed / Unconfirmed mode.

This LoRaWAN device can send both unconfirmed and confirmed messages. Using confirmed mode you can increase reliability and make sure data integrity is preserved in case of applications where date delivery is critical. In case you want to optimize network capacity and emphasize on limiting network congestion you can use unconfirmed packets (suitable for applications that transmit often and packet loss is permissible).

Industrial quality enclosure (IP65 rated):

Suitable for harsh environments, where ingress protection is required. Most industrial applications which this sensor has been designed for work in harsh conditions, outdoors perhaps. The presence of dusty, rain, oil, etc. is command and the casing of the device needs to seal tight in order to no allow any damage/reduced functionality to befall the sensor due to these harsh operation environments. This makes the sensor suitable for use cases such as oil rigs, dig sites, factories, HVAC towers on top of high buildings, etc.

Power-efficient Built-in Deep-sleep mode:

This is essential for any good wireless, battery-powered IoT sensor. As the device performs readings over a regular time interval there is a significant time period where it is neither measuring, nor transmitting data. In most cases the bulk of the operational time of the device it is essential for it to consume as little power as possible. An efficient sleep mode guarantees that the sensor squeezes the best battery life possible, as it turns down the current consumption by switching off all of the clocks and sensors in order to preserve power, unless an interrupt is received. This is part of the firmware and one only need set the wake-up interval, the device takes care of the rest.

As a result the user can best balance between device battery longevity and the granularity of the sensor measurements that best suits their use case. A battery life of up to 10 years is possible with 4xAA batteries (see battery life reference table for details).

Applications

High-resolution Temperature and Humidity sensors are designed to provide accurate measurements of environmental data in real time for the purpose of optimizing operational conditions in various spaces (or outdoors). These devicdes are essential for stable, long term operation of factories, storage units, offices, greenhouses, etc. Gathering data from Temperature and Humidity is one of the most fundamental and cost and time-efficient methods to improve the sustainability of an environment. Here are some common use cases where this type of sensors find purpose:
 
In-House Temperature Humidity monitoring:
A very prominent use case that is seeing more and more adoption is monitoring of environmental conditions in buildings. This is applicable to both residential and commercials spaces. Keep track of the environment in an office to make sure workers are comfortable, monitor a freezer in a kitchen or a groceries store to prevent food spoilage or just keep an eye on your balcony to make sure you plants are taken care of.
 
Factory Floor Temperature Monitoring:
A typical factory is an environment with very diverse environmental conditions requirements. Temperature and humidity could vary greatly depending on the zone and type of machinery that operate there. Furthermore there are strict regulations on conditions and HVAC operation in such spaces. Thus, it is essential to keep track in real time of how the environment changes, not only for the sake of comfort the works, but also as a measure of potential machine failure. By integrating Temperature and Humidity sensors throughout the factory floor one could easily monitor the environment and integrate any measurement data with the HVAC system to better make adjustments (automation).
 

Storage Unit Environmental Monitoring System:
Battery powered sensor devices as the NCD LoRaWAN Temperature and Humidity Sensor are perfect for integrating into small storage units. For example one could monitor the environment into a medical supply cabinet to make sure medicine is stored at the appropriate condition in order to void them expiring ahead of time. By constantly monitoring Temperature and Humidity and setting up alarms you can make sure you are notified immediately if there is a critical need of adjusting the environmental conditions. As the device is small and there is no need for mains power, it is easy to integrate in small spaces and it requires no remodeling of the cabinet or storage unit to integrate it.

Warehouse Temperature Humidity Monitoring System:
This type of long range, low power device is very suitable for monitoring large storage spaces, like a warehouse or a large container/s. The long range coupled with the good wall penetration make it suitable for areas with dense structure walls. Additionally, as the nodes are cost efficient and a lot of network coverage can be provided with just 1 or 2 gateways you can deploy a dense net of sensors over a large area and make sure you perform per zone environmental monitoring, in case different goods required different storage conditions.

Agricultural Temperature and Humidity Monitoring:
There are many agricultural use cases these sensors can fit in. Their robust design and weather-proofing make them suitable for deployments in both open and closed environments. Monitoring Temperature and Humidity throughout the growth cycle of plats is essential for keeping track of their health. This data can be used to evaluate whether conditions are optimal for growth, preventing potential produce loss. For example you could use the NCD Temperature and Humidity LoRaWAN Sensor to control the environment in a greenhouse where you perform measurement over regular time intervals and feed the data in your irrigation and heating system, keeping environmental conditions at their optimal level.

Detailed Specifications

Device Overview

Printed Circuit Board Specifications

ParameterMinimumNominalMaximumNotes
Trace Width0.007 inch0.012 inch0.25 inchTrace Width depends on the Trace Type
Layer Count2L - RigidTop and Bottom Layer
Material TypeFR-4 TG170FR-4 TG170FR-4 TG180
Surface FinishENIG 2u"
IPC StandardIPC CLASS 2
Finished Copper Foil1.0/1.0 OZ
Finished Thickness0.062 inc
Fine line <4.0/4.0milNo
Blind & Burried ViasNo
Non-Conductive ResinNo
Conductive ResinNo

Sensor Specifications

ParameterTemperatureHumidity
Resolution0.01°C0.01%RH
Accuracy±0.1°C±1.0%RH
Operation Range-40 to +125ºC0 to 100%RH
Storage Range-40 to +150ºC-

Mechanical Drawing

Power Requirements and Expected Battery Life

Power Requirements

This Industrial IoT Wireless Transmitter uses four AA batteries, two are on the main circuit board and the other two are installed on the back of the top lid.

Please note, the L91 batteries are non-rechargeable Li-Ion batteries. During the battery replacement process, adhere to thefollowing guidelines:

1. Switch off the sensor before initiating the battery change.

2. Always use NEW Energizer L91 Lithium batteries.

3. Observe the polarity markings on both the battery holder and batteries to ensure correct installation (refer to the image below).

4. Replace all four batteries simultaneously; mixing old and new batteries is not recommended. To reduce the risk of explosion do not mix old and new batteries or batteries from different manufacturers.

5. Avoid changing batteries in areas where there’s a risk of fire.

6. Rechargeable batteries are not suitable for this device.

7. Batteries are installed in 2S2P Configuration.

Power Ratings:

Maximum power usage during data transmission is 300mW.

Power consumption during sleep or idle operation is minimal, at 0.165mW.

Note: If Batteries are installed backwards, batteries will discharge safely through built-in fuses and the user will experience a very short battery life. Care should be taken to install batteries correctly for maximum battery life.

Expected Battery Life

Most NCD IoT Sensors are rated for 300,000 to 500,000 transmissions until the batteries become so weak they are unreliable.  You could spread these transmissions out over a 10 year period and send 50,000 transmissions per year.  This would allow up to 136 transmissions per day, or about 5 transmissions per hour (for a 500K sensor, or 3 per hour for 300K sensor).  If you only need the batteries to last 3 years, you could send 166,666 transmissions per year, or about 456 transmissions per day (about 19 transmissions per hour for a 500K sensor).  As you can see, battery life is really up to you.  By altering advanced settings in the NCD IoT sensor, you have control over longevity.  Please note the 500,000 transmission rating is for premium alkaline batteries.  NCD ships all sensors with premium Lithium batteries, which include a ultra-wide temperature range that typically lasts in excess of 600,000 transmissions for some sensor types.  These batteries weigh less than half of alkalines, and they work in the freezer!  A word of caution though, putting a sensor in configuration mode will drain the batteries very quickly.  It’s important to configure your sensors and exit configuration mode as soon as possible or use a external power supply during configuration (if supported by the sensor).  The table below indicates how many Transmissions Per Hour (TPH) your can expect from different sensors over a lifespan of up to 10 years.

Battery Life3 Months6 Months1 Year2 Year3 Year5 Year10 Year
300K Sensors136 TPH68 TPH34 TPH17 TPH11 TPH6 TPH3 TPH
400K Sensors180 TPH90 TPH45 TPH22 TPH15 TPH9 TPH4 TPH
500K Sensors228 TPH114 TPH57 TPH28 TPH19 TPH11 TPH5 TPH
600K Sensors272 TPH136 TPH68 TPH34 TPH22 TPH13 TPH6 TPH

The Truth About Battery Life

Under the best of circumstances, the best non-rechargeable batteries commonly available today are limited to a 10 year non-working shelf life in a room temperature environment. Factors such as actual usage, temperature, and humidity will impact the working life. Be wary of any battery claims in excess of 10 years, as this would only apply to the most exotic and expensive batteries that are not commonly available. Also note that most battery chemistries are not rated for use in extreme temperatures. NCD only uses the best Non-Rechargeable Lithium batteries available today, which are also rated for use in extreme temperatures and have been tested by our customers in light radioactive environments. Lithium batteries offer a 10 year maximum expected shelf life due to limitations of battery technology. NCD will never rate sensor life beyond the rated shelf life of the best batteries available today, which is currently 10 years.

Getting Started

Pre-requisites

This is a LoRaWAN® compatible device, thus it requires a LoRaWAN® gateway within range to receive and forward packets to the LoRaWAN Network Server (LNS). Furthermore, in order for the packets to be received and successfully decrypted it needs to be registered with the aforementioned LNS.

The example in this document utilizes The Things Industries (TTI) stack. You can alternatively use its public version The Things Network (TTN), the differences in the registration procedure are negligible. The document assumes you have created an account already.

You can find more about TTI/TTN and how to register here:

https://www.thethingsindustries.com/

https://www.thethingsnetwork.org/

Default Configuration

The node comes pre-configured with a set of LoRaWAN® keys which you can use to onboard it via your preferred choice of LNS. This document will use TTI/TTN as example.

As an alternative you can obtain the pre-coded key by connecting via a Serial to USB converter to the port shown in the image below. Once connected press on the “Reset” button for the device to reboot and it will report its configuration settings and set of LoRaWAN keys.

Note: Powering the device before registering it with an LNS is not recommended as it will repeatedly try to join, to no avail (this drains battery, fast). Do this only after you have it registered (following section) or in case you need to obtain the keys via the Serial.

Below is an example Serial report for your reference (your keys will be different and the firmware version might defer depending on time of when you read this article):

The factory default settings are as follows:

Frequency region:

US915, where FSB6 is utilized for the sub band.

Join mode:

The device works in OTAA mode by default (if you require ABP functionality contact the NCD team)

ADR mode:

ADR is turned on by default, if your LNS supports it we recommend you use it with this feature, unless the node is mobile (should not be the case for this type of node in general).

Confirmed / Unconfirmed mode:

By default, it is sending confirmed uplinks. Depending on your requirements for data integrity and the transmission interval you might want to adjust this. As a general recommendation we advise to use unconfirmed mode in order to reduce dwell time, battery consumption and limit network congestion.

Note: You can reset the node to its default settings with the 0x50 command via a downlink or physically. After a reset or bootup there is a 3 seconds window where you can press the CFG key inside the device and hold it for 10 seconds to reset to the factory default settings.

Registration with the LNS

Assuming you have been provisioned with the keys separately (via a CSV file from NCD) and you need not connect to the Serial port to obtain them you can follow the steeps below in order to register your device. The method where you obtain or change the keys is going to be discussed in a separate document.

Go to your TTI/TTN account and create an application, pick a suitable name and proceed. You will see the following page where you need to press on the blue “Register end device button”.

				
					BOARD INIT OK
Release: Sep 12 2023
FW ver: 0x5
APP KEY
 0x2B 0x7E 0x15 0x16 0x28 0xAE 0xD2 0xA6 0xAB 0xF7 0x15 0x88 0x11 0x22 0x33 0x44
NWK S KEY
 0x2B 0x7E 0x15 0x16 0x28 0xAE 0xD2 0xA6 0xAB 0xF7 0x15 0x88 0x11 0x22 0x33 0x44
APP Session KEY
 0x2B 0x7E 0x15 0x16 0x28 0xAE 0xD2 0xA6 0xAB 0xF7 0x15 0x88 0x11 0x22 0x33 0x44
Dev Eui
 0x38 0x00 0x12 0x00 0x01 0x02 0x03 0x04
APP Initialized 
SHT45 Temperature = 24.786
SHT45 Humidity = 38.478
Dev not joined
Requesting to join
Dev Joined Successfully
				
			

In order to properly onboard the device you have to set up the correct parameters and keys. Select the “Enter end device specifics manually” option via the Radio button. This will open up a set of drop-down menus. As you start up setting parameters more fields will open up. Eventually you should end up with a window similar to the one shown in the image below. The parameters are as follows:

Frequency Plan

United States 902-928 MHz, FSB6

LoRaWAN version

LoRaWAN Specification 1.0.4

Regional Parameters version

RPO002 Regional Parameters 1.0.3

JoinEUI

Once these are selected you will be presented with a text field to fill in the JoinEUI. Fill it out with 0s, this can be used as default for NCD test nodes. Note this parameter is not reported via the Serial as it applies to all NCD nodes at the time of writing of this document.

00 00 00 00 00 00 00 00

DevEUI

For the DevEUI enter the one provisioned by NCD (or Serial), in our example it would be:

38 00 12 00 01 02 03 04

AppKey

For the AppKey enter the one provisioned by NCD (or Serial), in our example it would be:

2B 7E 15 16 28 AE D2 A6 AB F7 15 88 11 22 33 44

 

Leave the reset as is and finalize the procedure by pressing the blue “Register end device” button.

At his point your device is registered with the TTI/TTN LNS and is awaiting activation (initiation of the join procedure).

Joining on Boot

The device initiates the sensors and immediately initiates the OTAA join procedure, sending a join request to the LNS (Join Server). This happens when it is powered on.

If you have the device properly registered with your LNS of choice (check the previous section). It should take less than 10 seconds for it to join.

Note: The join time of around 10 seconds applies for default FSB6 (you would also need a gateway in range that supports the sub band). If the device is working in Hybrid mode and goes over all 8 FSBs it could take significantly longer (on the order of several minutes up to an hour).

The join request packet is repeatedly sent on the uplink (with an interval of 50 seconds) until a join accept downlink is received by the device and the session is negotiated with the LNS (the keys are exchanged). It the device does not receive a valid join accept message for 10 consecutive join requests it doubles its transmission interval (100 seconds in this case). This process repeats over and over until the device joins.

If you are connected via Serial, you should see the following upon a successful power up and joining of the network.

				
					BOARD INIT OK
Release: Sep 12 2023
FW ver: 0x5
APP KEY
 0x2B 0x7E 0x15 0x16 0x28 0xAE 0xD2 0xA6 0xAB 0xF7 0x15 0x88 0x11 0x22 0x33 0x44
NWK S KEY
 0x2B 0x7E 0x15 0x16 0x28 0xAE 0xD2 0xA6 0xAB 0xF7 0x15 0x88 0x11 0x22 0x33 0x44
APP Session KEY
 0x2B 0x7E 0x15 0x16 0x28 0xAE 0xD2 0xA6 0xAB 0xF7 0x15 0x88 0x11 0x22 0x33 0x44
Dev Eui
 0x38 0x0 0x12 0x0 0x1 0x2 0x3 0x4
APP Initialized 
SHT45 Temperature = 24.786
SHT45 Humidity = 38.478
Dev not joined
Requesting to join
Dev Joined Successfully
				
			

If the Device EUI and Keys in the node and LNS match upon receiving the join request the LNS will respond with a join accept. Once the node receives and processes it will establish a connection and start sending regular uplink frames over a certain pre-defined interval. At this point you should start seeing the uplinks in your LNS of choice. For the example we are using this is represented in the image below:

Advanced Configuration

Once the node has been powered on it initiates the Join Procedure. Depending on whether it is successful or not it will either back off and increase the Join Request interval, or go into Link Evaluation mode. Once the link quality has been deemed sufficient it will move to Normal Operation mode. The Link Evaluation mode is a perfect time to send downlink commands to adjust parameters before the node has started sending measurement data.

Link Evaluation Mode

This is a temporary mode and the device enters it after rejoining a network/LNS. It evaluates the wireless link based on the measured RSSI and SNR in order to ascertain that the connection is stable. Furthermore, it gives you time to send downlink commands to configure the node before it starts normal operation. The devices exits this mode once the link has been deemed stable (2 consecutive good uplink messages).

Normal Operation Mode

This is the default mode of operation. The device enters this mode after it successfully exits the Link Evaluation Mode. In this mode the device cycles between two states: Deep sleep and Active transmission.

Link Status Evaluation

After successfully joining, PRE Msg packets will be sent to the server to evaluate the network stability (RSSI and SNR). This will also give the LNS time to push any configuration downlinks before the sensor starts reporting measurement data. Upon receiving 2 successful acknowledgements for the Pre Msg packets the device will switch to normal operational mode.

There are the following cases to consider that are outside of normal operation:

  1. The node stays in this mode till 2 consecutive uplinks are acknowledge and the link quality is deemed sufficient. Until the aforementioned requirements are satisfied the node will keep sending PRE MSg pacts.
  2. If at any time device resets (due to button power loss for example), it’ll resume from where it stopped before resetting, configuration parameters are retained.
  3. As this device works in Class A by default, the server can send configuration downlinks after every uplink (this applies to any packet, whether a normal mode keep alive packet, or a Pre Msg packet, etc.).
If you check it in the TTI/TTN console at this point you should see regular uplinks coming in, with the PRE MSG header (7A). Check the following image for reference.

Normal Operation Mode

In this mode the device sends a regular keep alive uplink containing the measured parameter data. By default, this interval is 60 seconds and can be adjusted within the limitation of the LoRaWAN Duty cycle.

This is the most power efficient mode as the device goes into deep sleep when it is not sending/receiving (every 60 seconds by default). Thus, you want to stay in this mode as much as possible. The device wakes up in regular intervals, the sensors obtain measurement data, an Uplink LoRa Frame is constructed and is send via the LoRa Radio. Upon sending the packet the node awaits for a Downlink message from the LNS (if any it processes it and adjusts it parameters) and goes into deep sleep after (waking up at the next time slot).

Note: The very first packet sent in this mode, the one after switching from Link Eval mode has a specific structure that is different than regular Normal Operation mode packets. It is static in the sense that it always has the same header and payload and it carries no temperature and humidity data. The purpose of this packet is to let the application know that it has switched to Normal operation mode.

7A 01 52554E

7A – Link Eval header

01 – Device type

52554E – Normal Operation Mode payload

Automatic reboot/rejoin

Depending on how the node is configured it has a build in mechanic to rejoin the network in case connection is unstable. If the node works in confirmed mode (check Appendix B ->command 0x07) where it waits for an ACK after each uplink you can set it up to reboot and rejoin the network after a certain number of missed ACKs are registered (check Appendix B -> command 0x0D).

For example if we set the Maximum Tx Fail count to 3 via the following downlink frame F7 FFFF 01 0D 01 03, the node will send regular uplinks and if at some point for 3 consecutive uplinks the node does not receive the ACK downlink packets it will reboot and try to rejoin. It is advisable to not use too low a value for this parameter to avoid frequent rebooting.

Note! 

  • After passing maximum allowed failures, Node will reset and start new join session
  • If node failed to transmit for more than 8 times, it’ll switch to hybrid mode “Hoping in all available channels” (Applies for US915 band only)

Large packets

It is possible in certain cases that a packet is scheduled to be sent via an uplink, however it has too large a payload to fit in a single LoRa Frame, because the Data Rate is not high enough (in case the node is using a higher SF as it is having range issues). An example would be a response to a very large set of downlink commands being queued from the server.

This event generates a special packet that replaces the normal application payload that contain in its payload the minimum Data Rate (DR) to be used in order to send the packet, for example:

7E 414C45 01

7E – Alert Packet header

414C45 – Alert payload

01 – Min data rate to be used to send requested payload

Normal Operation Mode packet structure

Once the device is in Normal Operation mode, it starts sending regular Uplink packets with measurement data in the payload. It has the following structure:

Byte indexBit indexMeaning
1FW Version
27Reserved
0:6Battery Voltage
3Reserved for Message Status
4Variable length

Lets look at an example:

00 63 FF 7F 484559

00 – FW version 0

63 – Voltage

FF – Device type

7F – Reserved

484559 – Payload

Downlink command configuration

Once the node goes into Normal Operation mode, the connection is stable and it is regularly sending keep-alive packets. You can change any of the configuration settings that you want. The device is a Class A node, thus is only accepts Downlink configuration frames in a short time window after each Uplink (in this case the keep-alive), so keep this in mind, the change won’t be immediate.

You can schedule a Downlink with the appropriate payload (depending on the command you want to issue), it will be queued by the LNS and will be sent after the next Uplink frame received by the LNS.

Once the node receives the Downlink it evaluates the payload and if it corresponds to a command (if it is correct) it executes the command. This is immediately followed by an Special uplink corresponding to the exact command. The payload and header (7C) are specific and tell us whether the command was successfully implemented.

Example Downlink configuration

Let’s look at an example command (diagram below) in order to better understand how the configuration procedure works (for a full set of commands and the corresponding responses check Appendix A):

The procedure can be loosely define in 2 parts – LNS portion and Node portion.

Things start on the LNS side, where a command is queued to be sent as a Downlink packet. The server than awaits an Uplink message from the node in order to send the Downlink (as it is a class A device this is the only time it would receive it).
Once an uplink is received (any uplink would do), the server sends the downlink with the command payload (proper header, etc.) to the LoRaWAN gateway that forwards it to the node.

Assuming the node receives the packet (issues with range, power, interference could prevent it) it processes it and examines the packet payload. First it looks at the command header and determines if it is a valid one. If it is not it ignores the command, if it is it pulls the parameter value to be changed. There are two cases here.

1. The value for the parameter to be changes is outside of the allowed range for this particular parameter. In this case the node does not adjust its configuration, but sends a response to the LNS (via the gateway) with an uplink packet with an Invalid Command Payload (see Appendix A for structure). This lets you know that the command did not go through due to an error in the requested parameter change and the node did not change its configuration parameters.

2. The value for the parameter to be changes is within the allowed range for this particular parameter. In this case the node adjusts its configuration and sends a response to the LNS (via the gateway) with an uplink packet with a Valid Command Payload (see Appendix A for structure). This way the you are notified that the command has been received and the changes you requested too effect.

Command Grouping

We can group commands together and send them in one go and receive response in one go too BUT THEY MUST BE ALL OF SAME TYPE “SYSTEM COMMANDS OR APPLICATION COMMANDS” MIXING SYSTEM COMMANDS WITH APPLICATION COMMANDS ISN’T ALLOWED.

For example if we want to SET the report rate to 60s and GET the maximum allowed tx failures at the same time.

F7 02 02 04 0000003C 2C 00

F7 – System command header

02 – Number of commands

02 – SET report rate ID

04 – Parameter length

0000003C – Parameter Value (3C[HEX] = 60[DEC])

2C – GET maximum allowed tx failures ID

00 – Parameter length

Response: “If response on getter only allowed”

7C F7 2C 7F 01 10

7C – Command response header

F7 – System command header

2C – Maximum Tx fail ID

7F – Response status success

01 – Parameter length

10 – Tx Failure count

Response “ If response on all enabled”

7C F7 02 FF 00 2C 7F 01 10

7C – Command response header

F7 – System command header

02 – Set report rate ID

FF – Response status success

2C – Maximum Tx fail id

7F – Response status success

01 – Parameter length

10 – Tx Failure count

Troubleshooting

Here are some common issue one might encounter when first setting up the sensor or later on when advance configuration is performed:

1. No or low range/coverage. Data is not received by the Gateway. Make sure you have properly installed the antenna and have as little obstructions/metal surrounding the sensor. Check your LNS/Node ADR settings, if you are using a Low SF (SF7), you might want to change it to a higher one (this improves range). SF7 to SF9 are recommended in general, you can go up to SF12, but this will decrease network capacity.

2. Measurement data missing or values are inconsistent. This might be due to not installing/tightening the probe correctly. Make sure you screw it in all the way and that you position it appropriately where you want to perform the measurements,

3. In case data is not being received (was previously received) there might be a power issue. Check the batteries and or the status of the internal LEDs.

4. If there are connectivity issue where data is being received intermittently or packets are being lost, make sure that you are not in a RF heavy noise environment and/or the sensor is not positioned too far away from the nearest Gateway. You might need to install additional Gateway/s. Check if the Gateway is powered properly and operational and its antenna has been installed properly. Check whether the Gateway is properly connected to the LNS.

5. In case you still can’t solve your issue head to our Community forum to get real time help from the NCD community of experts: https://community.ncd.io/

Appendix A - Command Structure and Cheat Sheets

Depending on what mode the node is operating and what is the type of the command, there are several different payload headers. Each header has a size of 1 byte, you can find the HEX representation of each possible case below:

7A à Mode Msg Header

F7 à System Command Header

F4 à Special Command Header

7C à Command Response header (after a successful downlink has been received by the node)

7E à Alert Packet Header

Note: Some commands take effect immediately, others after you reset the node. The commands that take effect immediately are:

  1. Report rate setter
  2. Join rate setter
  3. Data rate setter
  4. Tx power setter
 

Below you can find cheat sheets for all commands to use as a quick reference for their command codes.

You can send a single command or 2 or more queued one after the other. You need to follow the structure for each command and also set the 

Command Code -> 1byte

Parameter Length for Command 1 -> 1byte

Parameter Array for Command 1 -> variable

Command Code 2 -> 1byte

Parameter Length for Command 2 -> 1byte

Parameter Array for Command 2 -> variable

…………………………………………………………

Let’s look at an example command where we Set the Report Rate and Get the Tx Power in order to understand the Command structure.

F7 FFFF 02 02 04 0000000A 28 00

F7 – System Command Header

FFFF – Device type

02 – Command count in this packet

02 – Command Code 1 for the First Command (in this case Set Report Rate)

04 – Command 1 Parameter Length (in this case the Set Report Rate command has a 4 byte length

0000000A – Command 1 Parameter Value (in this case 0x0A[HEX]=10[DEC] -> report every 10 seconds)

28 – Command Code 2 for the Second Command (in this case Get TX Power)

00 – Command 2 Parameter Length (in this case it is 0 as this is a Get Command and they have no parameters to set, thus no Parameter Value follows either).

SET Command Cheat Sheet

Command Code [HEX]Payload Length [Bytes]Description
0x024Set Report Rate (the time between 2 consecutive keep alive packets)
0x031Set Frequency Group (Select the LoRaWAN FSB)
0x041Set App Port (set the Fport for the uplink packets)
0x051Set Cfg Port (set the Fport for the downlink packets)
0x061Set Adaptive Data Rate mode (0 – off, 1 – on)
0x071Set Confirmed Mode (0 – off, 1 – on)
0x081Set Uplink Data Rate (DR) (available DR0 – DR4)
0x091Set Tx power (20dBm max)
0x0A4Set Join Retry rate (in seconds)
0x0B1Set Stable connection maximum fail count (default is 2)
0x0C4Set Stable connection msg rate (in seconds)
0x0D1Set maximum Tx Fail count. Tx Fail count = 8(const) + 16(default) = 24.
The user can only change the second value, with a minimum of 16, thus the lowest possible value is 24. If the user wants to have a count of 30 they need to set the parameter to 22.
0x0E1Set maximum Join Fail count
0x0F1Allow Setter response

GET Command Cheat Sheet

Command Code [HEX]Payload Length [Bytes]Description
0x214Get Report Rate
0x221Get Frequency group
0x231Get App port
0x241Get Cfg Port
0x251Get ADR mode status
0x261Get Confirmed mode status
0x271Get Data rate (DR)
0x281Get Tx power
0x294Get Join Retry rate
0x2A1Get Stable connection maximum fail count
0x2B4Get Stable connection msg rate
0x2C1Get maximum Tx Fail count
0x2D1Get maximum Join Fail count
0x2E1Get Setter response status

System Command Cheat Sheet

Command Code [HEX]Payload Length [Bytes]Description
0x50-Reboot node

Appendix B - Example SET commands

02 - Set Report Rate command
F7 01 02 04 00000028Example command
0xF7Packet header for System command message
0x01Command count 1
0x02Command code for Set Report Rate
0x04Command parameter length is 4 bytes
0x00000028Set Report Rate to 0x28[HEX] = 40[DEC] seconds
7C F7 02 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x02Command code for Set Report Rate
0x7FCommand status success
0x00Response parameter length is 1 byte
03 - Set Frequency Group command
F7 01 03 01 06Example command
0xF7Packet header for System command message
0x01Command count 1
0x03Command code for Set Frequency Group
0x01Command parameter length is 1 byte
0x06Set Frequency Group to FSB6
F7 01 03 01 09Opens all 64 Channels
7C F7 03 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x03Command code for Set Frequency Group
0x7FCommand status success
0x00Response parameter length
04 - App Port command
F7 01 04 01 02Example command
0xF7Packet header for System command message
0x01Command count 1
0x04Command code for Set App Port
0x01Command parameter length is 1 byte
0x02Set App Port to 2
7C F7 04 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x04Command code for Set App Port
0x7FCommand status success
0x00Response param length
05 - Set Cfg Port command
F7 01 05 01 01Example command
0xF7Packet header for System command message
0x01Command count 1
0x05Command code for Set Cfg Port
0x01Command parameter length is 1 byte
0x01Set Cfg Port to 1
7C F7 05 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x05Command code for Set Cfg Port
0x7FCommand status success
0x00Response param length
06 - Set Adaptive Data Rate mode command
F7 01 06 01 01Example command
0xF7Packet header for System command message
0x01Command count 1
0x06Command code for Set Adaptive Data Rate mode
0x01Command parameter length is 1 byte
0x01Enable Adaptive Data Rate mode
7C F7 06 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x06Command code for Set Adaptive Data Rate mode
0x7FCommand status success
0x00Response param length
07 - Set Confirmed mode command
F7 01 07 01 01Example command
0xF7Packet header for System command message
0x01Command count 1
0x07Command code for Set Confirmed mode
0x01Command parameter length is 1 byte
0x01Enable Confirmed mode
7C F7 07 FF 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x07Command code for Set Confirmed mode
0x7FCommand status success
0x00Response param length
08 - Set Uplink Data Rate command
F7 01 08 01 04Example command
0xF7Packet header for System command message
0x01Command count 1
0x08Command code for Set Uplink Data Rate
0x01Command parameter length is 1 byte
0x04Set the Data Rate to DR4
7C F7 08 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x08Command code for Set Uplink Data Rate
0xFFCommand status success
0x00Response param length
09 - Set Tx Power command
F7 01 09 01 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x09Command code for Set Tx Power
0x01Command parameter length is 1 byte
0x00Set the Tx Power to 0dBm
7C F7 09 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x09Command code for Set Tx Power
0xFFCommand status success
0x00Response param length
0A - Set Join Retry Rate command
F7 01 0A 04 0000003CExample command
0xF7Packet header for System command message
0x01Command count 1
0x0ACommand code for Set Join Retry Rate
0x04Command parameter length is 4 bytes
0x0000003CSet Join Retry Rate to 0x3C[HEX] = 60[DEC] seconds
7C F7 0A 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x0ACommand code for Set Join Retry Rate
0x7FCommand status success
0x00Response param length
0B - Set Stable connection maximum count command
F7 01 0B 01 03Example command
0xF7Packet header for System command message
0x01Command count 1
0x0BCommand code for Set Stable connection maximum count
0x01Command parameter length is 4 bytes
0x03Set Stable connection maximum count to 3
7C F7 0B 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x0BCommand code for Set Stable connection maximum count
0x7FCommand status success
0x00Response param length
0C - Set Stable connection msg rate command
F7 01 0C 04 0000003C Example command
0xF7Packet header for System command message
0x01Command count 1
0x0CCommand code for Set Stable connection msg rate
0x04Command parameter length is 4 bytes
0x0000003C Set Stable connection msg rate to 0x3C[HEX] = 60[DEC] seconds
7C F7 0C 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x0CCommand code for Set Stable connection msg rate
0x7FCommand status success
0x00Response param length
0D - Set maximum Tx Fail count command
F7 01 0D 01 03Example command
0xF7Packet header for System command message
0x01Command count 1
0x0DCommand code for Set maximum Tx Fail count
0x01Command parameter length is 1 byte
0x03Set maximum Tx Fail count to 3
7C F7 0D 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x0DCommand code for Set maximum Tx Fail count
0x7FCommand status success
0x00Response param length
0E - Set maximum Join Fail count command
F7 01 0E 01 03Example command
0xF7Packet header for System command message
0x01Command count 1
0x0ECommand code for Set maximum Join Fail count
0x01Command parameter length is 1 byte
0x03Set maximum Join Fail count to 3
7C F7 0E 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x0ECommand code for Set maximum Join Fail count
0x7FCommand status success
0x00Response param length
0F - Enable Response on all commands
F7 01 0F 01 01Example command
0xF7Packet header for System command message
0x01Command count 1
0x0FCommand code for Set Setter response status command
0x01Command parameter length is 1 byte
0x010x01 - allow response for on all commands (0x00 - allow response only on valid get commands)
7C F7 0F 7F 00Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x0FCommand code for Set Setter response status command
0x7FCommand status success
0x00Response param length

Appendix C - Example GET commands

21 - Get Report Rate command
F7 01 21 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x21Command code for Get Report Rate
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 21 7F 04 0000000AExample response
0xFCPacket header for System response
0xF7Packet header for System command message
0x21Command code for Get Report Rate
0xFFCommand status success
0x04Response param length
0x0000000AResponse value 0x0A[HEX] = 10[DEC] seconds
22 - Get Frequency Group command
F7 01 22 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x22Command code for Get Frequency Group
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 22 7F 01 02Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x22Command code for Get Frequency Group
0x7FCommand status success
0x01Response parameter length is 1 byte
0x02Response value is 02[HEX] = 02[DEC] -> FSB3
23 - Get App Port command
F7 F7 01 23 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x03Command code for Get App Port
0x01Command parameter length is 0 bytes (no parameters reported)
7C F7 23 7F 01 01Example response
0xFCPacket header for System response
0xF7Packet header for System command message
0x23Command code for Get App Port
0x7FCommand status success
0x01Response parameter length is 1 byte
0x01App Port is 1
24 - Get Cfg Port command
F7 01 24 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x24Command code for Get Cfg Port
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 24 7F 01 01Example response
0x7CPacket header for System response
0xF7Packet header for System command message
0x24Command code for Get Cfg Port
0x7FCommand status success
0x01Response param length
0x01Response value is 01[HEX] = 01[DEC] -> Cfg Port is 1
25 - Get ADR mode status command
F7 01 25 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x25Command code for Get ADR mode status
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 25 FF 01 01Example response
0x7CPacket header for System response
0xF7Packet header for System command message
0x25Command code for Get ADR mode status
0x7FCommand status success
0x01Response param length
0x01Response value is 01[HEX] = 01[DEC] -> ADR is enabled
26 - Get Confirmed mode status command
F7 01 26 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x26Command code for Get Confirmed mode status
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 26 7F 01 01Example response
0x7CPacket header for System response
0xF7Packet header for System command message
0x26Command code for Get Confirmed mode status
0x7FCommand status success
0x01Response param length
0x01Response value is 01[HEX] = 01[DEC] -> Confirmed mode is enabled
27 - Get Data rate command
F7 01 27 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x27Command code for Get Data rate
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 27 7F 01 04Example response
0x7CPacket header for System response
0xF7Packet header for System command message
0x27Command code for Get Data rate
0x7FCommand status success
0x01Response param length
0x04Response value is 04[HEX] = 04[DEC] -> Data rate is DR4
28 - Get Tx power command
F7 01 28 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x28Command code for Get Tx power
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 28 7F 01 00Example response
0x7CPacket header for System response
0xF7Packet header for System command message
0x28Command code for Get Tx power
0x7FCommand status success
0x01Response param length
0x00Response value is 00[HEX] = 00[DEC] -> Tx power is 0dBm
29 - Get Join Retry rate command
F7 01 29 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x29Command code for Get Join Retry rate
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 29 7F 04 0000000AExample response
0x7CPacket header for System response
0xF7Packet header for System command message
0x29Command code for Get Join Retry rate
0x7FCommand status success
0x04Response param length
0x0000000AResponse value is 0A[HEX] = 10[DEC] -> Join Retry rate is 10 seconds
2A - Get Stable connection maximum fail count command
F7 01 2A 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x2ACommand code for Get Stable connection maximum fail count
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 2A 7F 01 05Example response
0x7CPacket header for System response
0xF7Packet header for System command message
0x2ACommand code for Get Stable connection maximum fail count
0x7FCommand status success
0x01Response param length
0x05Response value is 05[HEX] = 05[DEC] ->Stable connection maximum fail count is 5
2B - Get Stable connection msg rate command
F7 01 2B 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x2BCommand code for Get Stable connection msg rate
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 2B 7F 04 05Example response
0x7CPacket header for System response
0xF7Packet header for System command message
0x2BCommand code for Get Stable connection msg rate
0x7FCommand status success
0x04Response param length
0x0000000AResponse value is 0A[HEX] = 10[DEC] -> Stable connection msg rate is 10
2C - Get maximum Tx Fail count command
F7 01 2C 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x2CCommand code for Get maximum Tx Fail count
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 2C 7F 01 0AExample response
0x7CPacket header for System response
0xF7Packet header for System command message
0x2CCommand code for Get maximum Tx Fail count
0x7FCommand status success
0x01Response param length
0x0AResponse value is 0A[HEX] = 10[DEC] -> maximum Tx Fail count is 10
2D - Get maximum Join Fail count command
F7 01 2D 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x2DCommand code for Get maximum Join Fail count
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 2D 7F 01 0AExample response
0x7CPacket header for System response
0xF7Packet header for System command message
0x2DCommand code for Get maximum Join Fail count
0x7FCommand status success
0x01Response param length
0x0AResponse value is 0A[HEX] = 10[DEC] -> maximum Join Fail count is 10
2E - Get Response on All commands status
F7 01 2E 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x2ECommand code for Get Setter Response status command
0x00Command parameter length is 0 bytes (no parameters reported)
7C F7 2E 7F 01 01Example response
0x7CPacket header for System response
0xF7Packet header for System command message
0x2ECommand code for Get Setter Response status command
0x7FCommand status success
0x01Response param length
0x010x01 Response on all commands (0x00 response only on valid Get commands)

Appendix D - Example System commands

51 - Reboot node command
F7 01 51 00Example command
0xF7Packet header for System command message
0x01Command count 1
0x51Command code for Reboot
0x00Command parameter length is 0 bytes (no command parameter)
-Command has no response