Sending Configuration Commands - Overview
The following guide demonstrates the fundamental configuration commands required to configure NCD Enterprise Low-Power Long Range Wireless Sensors. A Wireless USB Modem will be required to configure NCD wireless sensors over a wireless connection. The examples shown below assume prior knowledge of DigiMesh® API Packet Structure, including MAC addresses and checksum calculations. We STRONGLY ADVISE using NCD Alpha Station software to configure sensors; however, if integration of sensor configuration is absolutely required, the commands shown below may be used.
Please note the MAC address MUST be changed (shown in the API frames below as 00 13 A2 00 41 91 1B 83) to match the MAC address of a remote sensor. The checksum must also be re-calculated (the last byte of the API frame) to include the new MAC address. Additionally, the PAN ID must be set to 0x7BCD. This PAN ID is reserved for configuration ONLY, and may not be used for daily operation.
A working sample of configuration with source code is available by downloading Alpha Station software. Alpha Station includes an installer but also runs as editable source code under Microsoft Visual Studio Community Edition, a FREE download from Microsoft. Alpha Station handles all configuration commands automatically and is capable of configuring every device that has been discovered.
The commands shown below are explained in greater detail within product manuals, this guide is a summary overview of all configuration command samples. Also note that configuration commands cannot be sent to NCD wireless sensors while in run mode. Each sensor must be placed in configuration mode, which will drain the battery very quickly. Be SURE to execute these commands quickly and return each sensor to RUN mode to preserve battery life. Optionally, select NCD wireless sensors may be powered from a external power supply during configuration.
Enter Configuration Mode
Step 1 : Power up the sensor.
Step 2: Every sensor has 2 buttons: Reset and Configuration (RST and CFG). Enter configuration mode by holding both buttons down. Next, release the reset button. Wait 6 seconds and release the CFG button. The sensor will send a Configuration API frame, indicating configuration mode is active. The API frame will look similar to this:
7E 00 1C 90 00 13 A2 00 41 91 1B 83 FF FE C2 7A 00 00 00 23 00 00 50 47 4D 00 00 00 00 00 00 0A
Above command contains the sensor MAC address. This MAC address may be used to send future targeted commands to this particular sensor.
In the above case, the MAC address is:
00 13 A2 00 41 91 1B 83
Note: Throughout this guide we will be sending data in broadcast mode and sensors ID and node ID will be set to 0. This is done to make these commands work with all the sensors and all the nodes. These commands may be used with all the sensors without any change.
For optimal performance keep only one sensor in config mode at a time.
Reminder: During configuration mode, the sensor PAN id needs to be set as 0x7BCD. When using Alpha Station software, this operation is completed automatically during configuration.
Warning: Batteries will drain quickly in configuration mode. Be sure to exit configuration mode as soon as possible by pressing and releasing the Reset (RST) Button on the sensor once configuration changes have been completed.
Read Sleep Duration
This command may be used to read the sensor sleep duration. The sleep duration determines how frequently the sensor wakes up and send sensor data. The interval is set in seconds. Short intervals will drain the battery faster while longer intervals will provide a very long battery life.
Read Sleep Duration Command
7E 00 13 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F7 15 00 00 00 E8
In the above command the remote device address is set as broadcast. The address is:
00 00 00 00 00 00 FF FF
When sending this command to a particular sensor, replace the MAC address of the sensor. Again, the sensor MUST be in configuration mode.
The Wireless Sensor will respond with the stored delay value:
7E 00 1C 90 00 13 A2 00 41 91 1B 83 FF FE C1 7C 00 02 00 0E 00 00 00 02 58 00 00 00 00 00 00 A6
From the above command, the following data may be extracted:
A. Sensor MAC address
00 13 A2 00 41 91 1B 83
B. Sensor Over-all Payload
7C 00 02 00 0E 00 00 00 02 58 00 00 00 00 00 00
C. Delay Value
0x00 0x02 0x58 (data bytes 23, 24, and 25)
Delay in Seconds = (0x00 x 65536) + (0x02 x 256) + 0x58 = 600 Seconds = 10 Minutes
Set Sensor Node ID and Sleep Duration
This Command may be used to set the sensor node and sleep duration, note that both values are stored together using the same command. The Node ID is a user-defined value from 00 to FF that may be used to help easily identify a sensor. The Sleep Duration indicates the amount of time (in seconds) the sensor will sleep before waking up, taking a sample, sending a transmission, and going back to sleep.
Set Node ID and Sleep Duration Command Example:
7E 00 17 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F7 02 00 00 00 01 00 01 2C CD
In the above command, the remote device address is set to broadcast mode. The broadcast address is 00 00 00 00 00 00 FF FF, which will target all sensors in configuration mode. Change the broadcast address to the MAC address of a individual sensor to target a particular sensor with this command (this is usually not required). The Command Contains a Sensor payload which contains a Sensor Node ID and Delay value.
Payload
F7 02 00 00 00 01 00 01 2C
Note that F7 is the command header byte and 02 is the sub command for storing the Node ID and Sleep Duration.
A. Node ID
0x01 (Byte 23)
B. New Delay Value
00 01 2C (data bytes 24, 25, and 26)
Delay in seconds = (0x00 x 65536) + (0x01 x 256) + 0x2C = 300 Seconds = 5 Minutes
In the Above command we set the new node to 1 and sleep duration value to 300 seconds (5 Minutes).
Once the sensor receives this command, it will send a response back. This response will indicate success or failure of the command.
In his case, the response will look something like this:
7E 00 1C 90 00 13 A2 00 41 91 1B 83 FF FE C1 7C 01 05 00 0E 00 00 FF 00 00 00 00 00 00 00 00 FD
Read Sensor Network ID
The Network ID is also known as PAN ID (Personal Area Network ID). This feature may be used to build a private Wireless Sensor Network. All sensors with the same Network ID will be able to talk to modems and gateway with the same Network ID. This is useful when deploying hundreds of sensors in one area or applications which require division of sensors, modems, and gateways into different zones with independent monitoring of each zone. Each sensor, gateway, and modem in a specific zone should share identical Network IDs, allowing the separation of sensors into smaller, more manageable groups.
Large factory floors or high-rise building may consist of several groups of sensors working under different Network IDs that help characterize the different areas of the installation. Network IDs make it easy to group sensors, modems, and gateways. When broadcasting data using separate Network IDs, multiple modems and gateways may be used in each zone, allowing sensor data to be collected by several different computers or servers. This kind of redundancy is essential in large installations.
Read Sensor Network ID Command
7E 00 13 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F7 19 00 00 00 E4
Sensor will respond with the Network ID
7E 00 1C 90 00 13 A2 00 41 91 1B 83 FF FE C1 7C 00 05 00 0E 00 00 7F FF 00 00 00 00 00 00 00 7F
From the above response, following data may be extracted:
A. Sensor MAC Address
00 13 A2 00 41 91 1B 83
B. Complete Sensor Payload
7C 00 05 00 0E 00 00 7F FF 00 00 00 00 00 00 00
C. Network ID
0x07FF (data bytes 23 and 24)
Set Wireless Sensor Network ID
This command may be used to set the sensor Network ID. Please note, Network ID 0x7BCD is reserved for configuration and should NEVER be used as a network ID for general use. Please note the Modem/Gateway must also use a matching Network ID to communicate with the sensor.
Set Wireless Sensor Network ID Command:
7E 00 15 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F7 05 00 00 00 7C DE 9E
Above Command Contains the following payload:
F7 05 00 00 00 7C DE
Note that F7 is the command header byte and 05 is the sub command for setting the Sensor Network ID.
In the Above command, a new network ID of 0x7CDE is configured.
Once the sensor receives this command, it will send a response back. This response will contain information regarding command success or failure.
In his case the response was successful, responding with the following frame:
7E 00 1C 90 00 13 A2 00 41 91 1B 83 FF FE C1 7C 00 09 00 0E 00 00 FF 00 00 00 00 00 00 00 00 FA
Read Sensor Destination Address
This Command may be used to read the sensor destination address. When the Sensor is in broadcast mode, the destination address will show up as:
0x0000FFFF
This Command may be used to read the sensor destination address.
Read Sensor destination address Command:
7E 00 13 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F7 18 00 00 00 E5
Sensor will respond with the Stored destination address:
7E 00 1C 90 00 13 A2 00 41 91 1B 83 FF FE C1 7C 00 13 00 0E 00 00 00 00 FF FF 00 00 00 00 00 F1
From the above command, the following data may be extracted:
A. Complete Sensor Payload
7C 00 13 00 0E 00 00 00 00 FF FF 00 00 00 00 00
B. Sensor MAC address
00 13 A2 00 41 91 1B 83
C. Destination Address
0000FFFF (data bytes 23, 24, 25, and 26)
The sensor response 0000FFFF indicates that the sensor is in broadcast mode. Any other value will indicate the sensor is directing its data to a specific address (a specific modem or gateway). We DO NOT ADVISE sending sensor data to a specific address, we advise broadcasting data using different Network IDs (PAN IDs) to put data into clustered zones. Should a specific gateway or modem fail while in service, it will be much easier to deploy a new gateway or setup redundant gateways and modems. Otherwise, reconfiguration of each sensor for a new gateway or modem will be required.
Set Sensor Destination Address
Every sensor is designed to send sensor data either in broadcast mode or to a particular destination address (modem or gateway). By default, NCD sensors broadcast data to all available modems and gateways. Data may be restricted to a single destination address (modem or gateway), though this configuration does not provide any form of redundancy in the event of a Modem or Gateway outage. For this reason, we strongly advise against using this command. Please consider setting the Network ID (PAN ID) to Setup Zones which will allow for redundancy in the event of a service outage. The following command is provided for reference ONLY and should be used with caution as a modem or gateway failure will necessitate reconfiguration of each sensor (which would not be required if the Pan ID/Network ID were used).
What is a Destination Address? Every sensor, gateway, and modem have a unique MAC address which cannot be changed. This MAC address is also known as the destination address (printed on the side of the enclosure). By default, all sensors send data in broadcast mode. This allows all the gateways and modems in the area to receive sensors data provided they are all on the same PAN ID (Network ID) and use the same encryption key.
When a specific destination address is stored in the sensor, the sensor will send data to that specific destination address only. The sensor CANNOT communicate with any other modem or gateway in the area. The following command may be used to specify a specific destination address (modem or gateway) for all sensor data:
Set Destination address Command
This command we will send only the lower 4 bytes of the destination address (the upper 4 bytes do not change).
7E 00 17 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F7 03 00 00 00 12 34 56 78 E6
The above Command Contains the payload, including a New Sensor destination address:
Complete Payload
F7 03 00 00 00 12 34 56 78
F7 is the command header byte and 03 is the sub command for setting a specific destination address. In this example, the new Destination Address is 12345678.
Once sensor receives this command it will send a response back. This response will indicate the command success or failure.
In his example, the response will look something like this (if successful):
7E 00 1C 90 00 13 A2 00 41 91 1B 83 FF FE C1 7C 00 0E 00 0E 00 00 FF 00 00 00 00 00 00 00 00 F5
Set Sensor Destination to Broadcast
This Command may be used to set the sensor destination address to broadcast mode, which is the default operation of NCD long range wireless sensors. After setting to broadcast mode, all modems and gateways with the same PAN ID and Encryption key will receive the same sensor data. This is the preferred configuration for all NCD sensors. Segmenting sensors into groups requires a unique PAN ID (also known as Network ID) for each group. All sensors, modems, and gateways must share the same PAN ID for each group.
Set Sensor Destination address to broadcast:
7E 00 13 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F7 01 00 00 00 FC
Complete Payload
F7 01 00 00 00
F7 is the command header byte and 01 is the sub-command for setting the Destination Address to Broadcast Mode.
Read Wireless Sensor Transmission Power Level
This Command may be used to read the wireless radio transmission power. This value will indicate how much RF power the radio is emitting. The higher the value, the higher the radiated wireless power, resulting in a longer range and decreased battery life (please note that all battery ratings are shown at maximum wireless transmission power). Lower values are desirable in application that may benefit from greatly improve battery life, especially when high power data transmissions are not required.
Read Sensor Power Command:
7E 00 13 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F7 16 00 00 00 E7
Sensor will respond with the Power Level value:
7E 00 1C 90 00 13 A2 00 41 91 1B 83 FF FE C1 7C 00 09 00 0E 00 00 04 00 00 00 00 00 00 00 00 F5
From the above command, the following data may be extracted:
A. Sensor MAC Address
00 13 A2 00 41 91 1B 83
B. Sensor Payload
7C 00 09 00 0E 00 00 04 00 00 00 00 00 00 00 00
C. Power Level
0x04 (data byte 23)
The sensor will respond with a value from 0x00 to 0x04. The default value is 0x04, allowing for the greatest possible transmission range and the shortest battery life.
Set Wireless Sensor Transmission Power Level
This command may be used to change the sensor transmission power. The default value is 0x04, which indicates the highest transmission power and shortest battery life. Setting this value lower will reduce the wireless range and improve battery life.
If long range is not required, setting this value lower in all sensors with close proximity will greatly improve battery life.
The following Command may be used to change the wireless module power level:
7E 00 14 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F7 04 00 00 00 03 F6
Above Command Contains Sensor payload which contains new power level value.
Complete Payload
F7 04 00 00 00 03
F7 is the command header byte and 04 is the sub command for setting the Sensor Transmit Power Level.
In the Above command, we set the new power level to 3 (byte 23).
Once the sensor receives this command, it will send a response back. This response will contain the info regarding command success or failure.
In his case the response was successful:
7E 00 1C 90 00 13 A2 00 41 91 1B 83 FF FE C1 7C 00 19 00 0E 00 00 FF 00 00 00 00 00 00 00 00 EA
Read Wireless Sensor Retries
The following command may be used to read the number of retires. The number of retries is one of the most useful settings for NCD wireless sensors.
Lets say the number of retires is set to 5. In a normal case, the sensor will wake up, gather data, send data to the modem, and go back to sleep. But due to some environmental issues (lets say a few trucks were driving by and they came in between the sensor and the modem) the modem didn’t receive the data. In that case, the sensor will try 4 more times to send the data. If the modem still doesn’t get the data after all 5 tries, the sensor will quite trying and will go back to sleep. The sensor will wake up after the predefined sleep time and will try again.
The highest number of retries allowed is 10.
Read The number of Sensor Retries:
7E 00 13 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F7 17 00 00 00 E6
Sensor will respond with the Retries value:
7E 00 1C 90 00 13 A2 00 41 91 1B 83 FF FE C1 7C 00 1B 00 0E 00 00 0A 00 00 00 00 00 00 00 00 DD
From the above command, the following data may be extracted:
A. Sensor MAC Address
00 13 A2 00 41 91 1B 83
B. Complete Sensor Payload
7C 00 1B 00 0E 00 00 0A 00 00 00 00 00 00 00 00
C. Retries Number
0x0A (data byte 23)
Set Wireless Sensor number of Retries
This Command may be used to change the number of retries. The highest number of retries allowed is 10:
7E 00 14 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F7 06 00 00 00 05 F2
The above Command Contains a Sensor payload which contains a new number of retries value:
Complete Payload
F7 06 00 00 00 05
F7 is the command header byte and 06 is the sub command for setting the Retries value.
In the Above command we set the retries value to 5 (byte 23).
Once the sensor receives this command, it will send a response back. This response will contain the info regarding command success or failure.
In his case the response was successful:
7E 00 1C 90 00 13 A2 00 41 91 1B 83 FF FE C1 7C 00 1D 00 0E 00 00 FF 00 00 00 00 00 00 00 00 E6
Set Wireless Sensor Encryption Key
This Command may be used to set the encryption key.
All ncd.io wireless sensors comes with 128bit AES encryption. The default encryption key secures a wireless sensor network of sensors, modems, and gateways. Users have the option to change the default encryption key. Please note this is a Write ONLY operation, it is not possible to read the encryption key from Sensors, Modems, or Gateways. Be Sure to keep records accordingly.
Once the sensor encryption key is set in the sensor, be sure to set the same key in all modems and gateways. If the modem or gateway doesn’t have the same key and PAN id as the sensor, there will be no way for sensors to communicate with modems or gateways. In this event, only a factory reset may be used to recover communications.
The following Command may be used to change the encryption key:
7E 00 24 10 00 00 00 00 00 00 00 FF FF FF FE 00 00 F2 03 00 00 00 00 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA 07
Complete Payload
F2 03 00 00 00 00 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA
F2 is the command header byte and 03 is the sub command for setting the ENY Key value.
Note — There is an Extra 0x00 Right before the ENY key value. Its a reserve byte and it should be there all the time.
In the Above command, the default ENY Key value is programmed into the NCD sensor.
55 AA 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA
Once the sensor receives this command, it will change the Key immediately.
In the event a key value is lost, factory reset the device. The default key value will always be used after factory reset:
55 AA 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA
Configuration Commands Table
| No. | Command | Header | Sub Command | Parameter Field | Default Value | Description |
|---|---|---|---|---|---|---|
| 1 | Set Broadcast Transmission | 0XF7 | 0x01 | – | 0000FFFF | This will set the address to Broadcast mode. All the receiver with same ENY key and PAN ID will get the data packets |
| 2 | Set ID and Sleep Interval | 0XF7 | 0x02 | NODE ID, D0 MSB,D1, D2 LSB | 0x00,0x00,0x02,0x58 | Sets the Device node ID and Data Transmission Interval. The node id value can go from 0-255 and The Data transmission value can go from 3-0xFFFFFF Seconds |
| 3 | Set Destination Address | 0XF7 | 0x03 | A0 MSB, A1, A2, A3 | 00,00,FF,FF | Sets the Destination Address of the sensor. The sensor will send Run mode Data packets to this Address |
| 4 | Set Power | 0XF7 | 0x04 | Power ( range 1-4) | 0x04 | Sets the RF power of the Sensor Radio |
| 5 | Set PAN ID aka Network ID | 0XF7 | 0x05 | ID0 MSB, ID1 LSB | 0x7FFF | Sets the PAN ID aka Network ID in the sensor. Only sensors, Gateway, and Modes with Same ID can communicate with each other |
| 6 | Set Retries | 0XF7 | 0x06 | Retries | 0x0A | Sets the number of Retries after unsuccessful transmission for the Sensor Radio |
| 7 | Read Sleep Interval | 0XF7 | 0x15 | – | 0x00,0x02,0x58 | Reads the stored Sleep Interval value from the sensor |
| 8 | Read Power | 0XF7 | 0x16 | – | 0x04 | Reads the stored RF Power value from the sensor |
| 9 | Read Retries | 0XF7 | 0x17 | – | 0x0A | Reads the stored Retries value from the sensor |
| 10 | Read Destination Address | 0XF7 | 0x18 | – | 00,00,FF,FF | Reads the stored Destination value from the sensor |
| 11 | Read PAN ID aka Network ID | 0XF7 | 0x19 | – | 0x7FFF | Reads the PAN ID aka Network ID |
| 12 | Enable Encryption | 0XF2 | 0x01 | – | 0x01 | Enables the Encryption of the Frame Transmitted from the Sensor |
| 13 | Disable Encryption | 0XF2 | 0x02 | – | – | Disables the Encryption of the Frame Transmitted from the Sensor |
| 14 | Set Encryption Key | 0XF2 | 0x03 | 00,K0 MSB, K1,K2,K3,K4,K5,K6,K7,K8,K9,K10,K11,K12,K13,K14,K15 | 55AA55AA55AA55AA55AA55AA55AA55AA | Sets the 128 bit AES Encryption Key |