Table of contents
1 Principle of operation
Data from the device’s sensors are processed by the device's embedded algorithm. The algorithm output is the number of passing cars. Device configuration defines when the updated number of passing cars will be transmitted to the network.
2 First commissioning
Default sensor firmware was designed to minimize power consumption and radio spectrum usage until the sensor will be installed. When a sensor is installed it is necessary to calibrate it using Nwave Device Management App. Only when the sensor is calibrated it will start a vehicle detection algorithm and LoRaWAN network join procedure.
3 LoRaWAN Interface
A car counter device is equipped with a LoRa radio operated in Class A. The implemented functionality complies with the LoRaWAN Specification 1.0.3.
The frequencies supported and receive window parameters follow the LoRaWAN v1.0.3 EU868 Regional Parameters rev. a.
3.1 Join Procedure
The first calibration initiates the join process. The Join procedure follows the Over-the-Air Activation (OTAA) described in the LoRaWAN Specification 1.0.2. Activation By Personalization (ABP) is not supported.
After powering up the car counter device, it will try to join a LoRaWAN Network by sending the join request message. In case the join request is not answered, the sensor will retry as soon as possible, according to transmission time limitations, up to 4 additional times (5 attempts in total). After the 5th unsuccessful attempt, the sensor will wait with exponentially increasing intervals (see chapter 3.2) and repeat the process 5 more times.
If the Join request message is not answered with a Join Accept message, the sensor retries, according to the following sequence:
In case the Join accept message is received after attempts 3, 4, or 5, the sensor restores the configured DataRate to the default value (DR2). This behavior assumes that the configured DataRate does not allow communication with the Gateway.
3.2 Exponentially increasing intervals
If the join sequence will not successful the sensor retries again with exponentially increasing intervals. The intervals are: 1, 2, 4, 8, 16, 32, 64, 128 minutes. Once reached 128 minutes, the wait time is always 128 minutes. There is also an additional random delay from 0 to 32 seconds added every time to the selected interval.
3.3 Device EUI
The device EUI of the sensor is pre-provisioned during production and may be derived from the serial number printed on the sensor casing. The device EUI may be derived from the serial number as in this example:
If the serial number will be 123456, the device EUI is 00 E8 BF 3B 00 12 34 56.
Exchanging the DevEUI of the sensor is not possible.
3.4 Application EUI
The AppEUI is pre-provisioned during production and will be delivered with the sensor zone. Exchanging the AppEUI of the sensor is currently impossible.
3.5 Application Key
The AppKey is pre-provisioned during production and will be delivered with the sensor zone. Exchanging the AppKey of the sensor is impossible.
4 Application protocol description
After a successful join (join accepted message is received) the sensor will send a startup message, then starts with the normal operation and sends counter update when necessary. Some application messages (startup message, heartbeat message) are always sent as confirmed. The counter update message is not confirmed by default but can be configured as confirmed. In case of the confirmation is not received, the sensor will retry 7 more times, adapting the DataRate as recommended in the LoRaWAN v1.0.2 spec(look at 18.4 Data-Rate Adaptation during Message Retransmissions and 18.1 Uplink Timing Diagram for Confirmed Data Messages).
Count update message transmission policy is configured via a table that describes the threshold for joint value of elapsed time and number of events since the last count update message transmission.
Consider a table like this.
Number of events since last count update message transmission | Elapsed time since last count update message transmission |
---|---|
0 | 1200 |
1 | 300 |
2 | 200 |
5 | 100 |
10 | 60 |
The table describes a threshold in 2D space that defines if a count update message must be sent. If a point lies left from the curve the message must be sent.
So this configuration allows to set:
the minimum period between messages. In this case, it is 60 seconds and no matter how many cars passed after the last message a new message will be sent not earlier than 60 seconds after the last message.
the minimum number of events necessary to send the next message. In this case, it is 0, and even if there were no new passing cars after the last message the new one will be sent in 1200 seconds after the last message.
Another example.
Number of events since last count update message transmission | Elapsed time since last count update message transmission |
---|---|
2 | 200 |
5 | 100 |
10 | 60 |
Here the minimum number of new events is 2, so if after the last message there were none or only 1 event there will be no new counter update message ever.
The counter update message can be configured as not confirmed with or without repetitions. It reduces the usage of the duty cycle to acknowledge all messages, but may also reduce the percentage of successfully received messages by the Gateway.
The DataRate is used in the uplink messages by the sensor is DR2 by default but may be configured from DR0 to DR5, ADR(Adaptive Data Rate also can be enabled).
The application protocol may be subject to change. The functionality may be extended in the next versions.
4.1 Expected lifespan of the car counter vs number of LoRaWAN messages per day and configured Data Rate
By configuring count update message transmission policy we can indirectly affect how many messages the device will send per day, and by configuring the data rate we define how much energy uses each message.
Here is a table showing the expected lifespan in years of the device vs the number of messages per day and configured data rate(or actual data rate in case of ADR enabled).
Data rate\Number of messages per day | 10 | 20 | 50 | 100 | 200 | 500 |
DR0(SF12) | 7.4 | 7.2 | 6.6 | 5.9 | 4.8 | 3.1 |
DR1(SF11) | 7.5 | 7.4 | 7.0 | 6.5 | 5.7 | 4.2 |
DR2(SF10) | 7.5 | 7.5 | 7.3 | 7.0 | 6.5 | 5.4 |
DR3(SF9) | 7.6 | 7.5 | 7.5 | 7.3 | 7.0 | 6.3 |
DR4(SF8) | 7.6 | 7.6 | 7.5 | 7.4 | 7.3 | 6.8 |
DR5(SF7) | 7.6 | 7.6 | 7.6 | 7.5 | 7.4 | 7.2 |
4.2 Uplink messages
Uplink messages are those sent from the sensor to the network.
4.2.1 Counter update
Counter update message uses port 1 and is not confirmed with 0 repetitions by default. It may be configured as confirmed or unconfirmed with repetitions (see downlink messages).
Byte | Name |
---|---|
0 | Counter value - Low Byte |
1 | Counter value - High Byte |
Only 16 least significant bits of the counter are sent in this message, the server must take care of possible overflows.
4.2.2 Heartbeat
The heartbeat message uses port 2 and it is always confirmed. The heartbeat message is sent every 24 hours (by default).
Byte | Bits | Name |
---|---|---|
0 | 0..4 | Error Mask |
5..7 | Reserved |
Heartbeat messages allow the device’s health monitoring using Error Mask, where all zeros values which are not hardware issues were detected.
Heartbeat messages are also used to initiate the re-join procedure (which is similar to the join procedure). If a count of sequential heartbeat messages without acknowledgment is bigger than the Heartbeat NACK limit (described in 4.2.5) re-join procedure will be initiated. This behavior assumes that the connection with the network has been lost. This is generally a good indicator that the Gateways are not able to maintain stable communication with the sensor.
4.2.3 Startup
The startup message uses port 3 and it is always confirmed. It will be sent after every startup/reboot / (re-) join event:
Byte | Name |
---|---|
0 | Major part of version number |
1 | Minor part of version number |
2 | Micro part of version number |
3 | Reset cause 0x00 No reset ( Startup message after re-joining LoRaWAN network) 0x01: Watchdog reset 0x02: Power On Reset 0x03: User Request Reset 0x06 - Brownout Reset 0x07 - Others |
4.2.4 Debug messages
The Debug messages use port 6 and they are always unconfirmed. By default, these messages are enabled and have no repetitions, but they may be disabled or increased by the number of repetitions used (see downlink messages). These messages do not have a fixed length as their payload depends on the type of debug message.
4.3 Downlink messages
Downlink messages are those sent from the Network to the Sensor. The sensor supports confirmed and unconfirmed downlink messages.
4.3.1 DataRate and counter update confirmation configuration
DataRate configuration uses port 52. The default value is DR2 (0x02) The selected configuration is persistent unless overwritten in the join procedure. Higher DataRates increases the battery lifetime of the sensor but may reduce the reliability of the reception of messages by the Gateway. This is especially the case for unconfirmed messages.
Byte | Bits | Name | Default value |
---|---|---|---|
0 | 0..2 | DataRate configuration | 2 (DR2) |
3 | Reserved | 0 | |
4..6 | Counter update confirmation configuration | 1(Unconfirmed with 1 uplink message(0 repetitions)) | |
7 | Reserved | 0 |
DataRate configuration value | DataRate(Spreading Factor) |
---|---|
0 | DR0 (SF12) |
1 | DR1 (SF11) |
2 | DR2 (SF10) |
3 | DR3 (SF9) |
4 | DR4 (SF8) |
5 | DR5 (SF7) |
6 | Reserved |
7 | Enable ADR(Adaptive Data Rate) |
Counter update confirmation configuration | Description |
---|---|
0 | Confirmed(up to 8 repetitions) |
1 | Unconfirmed with 1 uplink message(0 repetitions) |
2 | Unconfirmed with 2 uplink messages(up to 1 repetition) |
3 | Unconfirmed with 3 uplink messages(up to 2 repetitions) |
4 | Unconfirmed with 4 uplink messages(up to 3 repetitions) |
4.3.2 Update transmission threshold configuration
Update transmission threshold configuration uses port 53. The configuration selected is persistent. The configuration is a table where every record represents a point of the count update threshold curve. If elapsed time of a record is equal to 0xFFF, this record is not used.
Byte | Bits | Name |
---|---|---|
0 | 4..7 | Record 1 - Number of events |
3..0 | Record 1 - Elapsed time, seconds(bits 11..8) | |
1 | 7..0 | Record 1 - Elapsed time, seconds(bits 7..0) |
2 | 4..7 | Record 2 - Number of events |
3..0 | Record 2 - Elapsed time, seconds(bits 11..8) | |
3 | 7..0 | Record 2 - Elapsed time, seconds(bits 7..0) |
4 | 4..7 | Record 3 - Number of events |
3..0 | Record 3 - Elapsed time, seconds(bits 11..8) | |
5 | 7..0 | Record 3 - Elapsed time, seconds(bits 7..0) |
6 | 4..7 | Record 4 - Number of events |
3..0 | Record 4 - Elapsed time, seconds(bits 11..8) | |
7 | 7..0 | Record 4 - Elapsed time, seconds(bits 7..0) |
8 | 4..7 | Record 5 - Number of events |
3..0 | Record 5 - Elapsed time, seconds(bits 11..8) | |
9 | 7..0 | Record 5 - Elapsed time, seconds(bits 7..0) |
The default counter update message transmission policy table described below.
Number of events since last count update message transmission | Elapsed time since last count update message transmission, seconds |
---|---|
0 | 3600 |
1 | 60 |
2 | 40 |
X | 0xFFF - not used |
X | 0xFFF - not used |
4.3.3 Heartbeat frequency
Heartbeat frequency uses port 55. The default value is 23 what is equal to 24 hours. The configuration selected is persistent.
Byte | Name |
---|---|
0 | Heartbeat interval configuration Interval = (value+1)hours |
4.3.4 Debug configuration
Debug configuration uses port 56 and is used to enable or disable the Debug messages (see uplink messages) and select the number of repetitions. By default, the Debug messages are enabled with 0 repetitions. The configuration selected is persistent.
4.3.5 Heartbeat NACK limit
Heartbeat NACK limit configuration uses port 72 and is used to specify how many heartbeat messages may be unacknowledged without initiating re-join procedure. The selected configuration is persistent. Default value is 3. 15 (0xF) and it is a special value that disables re-join functionality completely
Byte | Bits | Name | Default value |
---|---|---|---|
0 | 0..3 | Heartbeat NACK limit | 3 |
4..7 | Reserved | 0 |
4.3.6 Command
Command uses port 71 and it is used to initiate different commands mainly for debugging.
Write:
1 (1 byte) to calibrate the device,
2 (1 byte) to reboot the device,
3 (1 byte) to put the device into the initial energy-saving mode (the device sleeps until the next calibration with no detection and no LoRaWAN messages).
5. Changelog
0.0.0 21 June 2021
Features:
Configurable counter update transmission policy
Configurable Data Rate or ADR
Known issues and limitations:
None at the moment.