Nwave LoRaWAN Car Counter- Getting Started
- Ilnur Mukhametzyanov
- Yury Birchenko
- Nikolay Abrosimov
Table of contents
- 1 1 Principle of operation
- 2 2 First commissioning
- 3 3 LoRaWAN Interface
- 4 4 Application protocol description
- 5 5. Changelog
1 Principle of operation
The Car Counter was designed to count the number of passing cars. The maximum speed of cars for counting to be reliable is 32km/h(20mph). The maximum time a car can stay above the sensor is 2 minutes. Motorcycles are not guaranteed to be counted or not to be counted. The probability of passing a motorcycle being counted mainly depends on the relational trajectory of the motorcycle.
To maximize counting quality the minimum distance between cars should be 1 meter. This requirement should be easy to satisfy in case of safe driving as, based on the Two-second rule (https://en.wikipedia.org/wiki/Two-second_rule ), 1 meter corresponds to a speed of 0.5m/s or 1.8km/h or about 1.1mph, and in the places where the car counters are usually installed expected vehicle speed is higher and so should be the distance.
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 5 additional times (6 attempts in total). After the 6th unsuccessful attempt, the sensor will wait with exponentially increasing intervals (see chapter 3.2) and repeat the process again.
If the Join request message is not answered with a Join Accept message, the sensor retries, according to the following sequence:
Attempt | DataRate |
|---|---|
1 | Next higher datarate after Configured DR( default is DR3, as the default configured datarate is DR2) but not higher than DR4 |
2 | Next higher datarate after Configured DR( default is DR3, as the default configured datarate is DR2) but not higher than DR4 |
3 | DR3 |
4 | DR2 |
5 | DR1 |
6 | DR0 |
In case the Join accept message is received after attempts 3, 4, 5, or 6(so the first 2 attempts using configured datarate failed), and the sensor's configured datarate(DR2 by default) is higher than the next slower data rate to the datarate used in the attempt, the configured datarate will be changed to DR2, DR1, DR0, or DR0 accordingly. This behavior assumes that the configured DataRate does not allow communication with the Gateway.
A few examples:
If the configured data rate was as by default DR2, and Join will be completed in attempts 1, 2, or 3(using datarate DR3 while joining) DR2 will continue to be used as configured datarate.
If the configured data rate was as by default DR2, and Join will be completed only in attempt 5 or 6(using datarate DR1 or DR0 while joining) DR0 will be selected to be used as configured datarate.
This is done to decrease the chances of selecting datarate which does not provide good connectivity.
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).
Counter 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 counter update message transmission.
Consider a table like this.
Number of events since last counter update message transmission | Elapsed time since last counter 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 counter 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 counter update message transmission | Elapsed time since last counter 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.
There is also another factor that impacts when the counter update message is sent. Cars are counted when they leave the sensor, and even after that, there is an additional delay of 5 seconds to allow the passing car to go farther and check if there is another car following it. It allows avoiding sending messages in unstable conditions or under a car. There is a timeout of 30 seconds for this mechanism too, so if a message was ready to be sent, but conditions were not good for 30 seconds it will be sent anyway(even under a car).
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 counter 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.
You can also refer to our Java Script payload decoder shared on the Github.
Examples of decoded messages are available on the TTN device page.
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 - bits 15..8 |
1 | Counter value - bits 7..0 |
Only 16 least significant bits of the counter are sent in this message, the server must take care of possible overflows. It is also important to notice, that counter information is not stored in nonvolatile memory and so it is lost in case of reboot and the counter resets to 0. The server can correctly process reboot by processing the Startup message(if Reset cause is not equal to 0, there was reboot and the counter was reset to 0).
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 | 4..0 | Error Mask |
7..5 | Reserved | |
1 | 7..0 | Battery voltage - the last value |
2 | 7..0 | Battery voltage - the mean value(last 24 hours) |
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.
To convert transmitted values of battery voltage to mV, use the following formula:
Vbat = (2400+value*5)mV,
where value is Battery voltage value transmitted in the message.
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.
The first 2 bytes of the payload represent the debug code in Big Endian format, and the rest of the payload(if any) contains additional parameters which meaning depend on the exact debug code.
Debug code | Meaning | Additional parameters |
|---|---|---|
899 (0x383) | Invalid user request. The downlink command has not been recognised or provided configuration cannot be used. | None |
805 (0x325) | No change in configuration. Provided configuration parameters are equal to the current parameters in use | None |
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 | 2..0 | DataRate configuration | 2 (DR2) |
3 | Enable ADR(Adaptive Data Rate):
| 0 | |
6..4 | 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 | Reserved |
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(1 repetition) |
3 | Unconfirmed with 3 uplink messages(2 repetitions) |
4 | Unconfirmed with 4 uplink messages(3 repetitions) |
For example:
To change the data rate to DR0 you need to send one byte in binary representation 00010000 (0x10) to port 52. Many LNS interfaces have Base64 input and you can use an online converter from binary to Base64. 00010000 binary is “EA==” string in Base64.
To set 4 unconfirmed attempts on DR0 send “QA==” (01000000 in binary) to port 52
To change the data rate to DR3 you need to send “Ew==“ (00010011 in binary) to port 52.
To get back to default DR2 send “Eg==”(00010010 in binary) to port 52.
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 counter update threshold curve. If elapsed time of a record is equal to 0xFFF, this record is not used.
Byte | Bits | Name |
|---|---|---|
0 | 7..4 | 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 | 7..4 | 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 | 7..4 | 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 | 7..4 | 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 | 7..4 | 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 counter update message transmission | Elapsed time since last counter update message transmission, seconds |
|---|---|
0 | 3600 |
1 | 60 |
2 | 40 |
X | 0xFFF - not used |
X | 0xFFF - not used |
There is also a feature that allows you to set only used(defined) records of the policy table. So, for example, if you send just 2 bytes they will be interpreted as 1 record of the table and other records will be set as not used.
For example, for fast demonstration or debugging, you can configure a high data rate and no minimum delay between counter update messages even if there is just 1 message. To do it:
send 15 to port 52(No ADR, Data Rate DR5, unconfirmed message without repetitions)
send 10 00 to port 53( no minimum delay between counter update messages for 1 event)
Another example, if you need to perform a connectivity test, you can set Data Rate to a target value or to minimum(DR0) and set a record in the policy table with a number of events equal to 0, and elapsed time set to target transmission period, for example:
send 11 to port 52(No ADR, Data Rate DR1, unconfirmed message without repetitions)
send 00 64 to port 53( messages will be sent every 100 seconds even without any new events)
To reset the transmission policy table to default, send 0E 10 10 3C 20 28 to port 53 (3600 = 0xE10, 60 = 0x03c, 40 = 0x028).
It is important to remember, that minimum delay between LoRaWAN messages including Counter Update messages is also defined by LoRaWAN specifications(like duty cycle limitations in EU868 region) and Car Counter abides by these limitations. In the case of low data rates, delays caused by duty cycle limitations can be significant(for example, about 100 s for DR0).
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 | 3..0 | Heartbeat NACK limit | 3 |
7..4 | 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.6.7 4 January 2023
Features:
The way configured datarate is changed if attempts to join the network using this datarate fail is changed to avoid sensors being able to connect but not send messages later
Known issues and limitations:
None at the moment.
0.1.0 28 June 2021
Features:
Battery voltage added to the Heartbeat message
Known issues and limitations:
None at the moment.
0.0.7 23 June 2021
Features:
The way to configure ADR and Data Rate is changed
The way to configure counter update message transmission policy is changed
Known issues and limitations:
None at the moment.
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.