Table of contents

1 1 Principle of operation
2 2 Calibration and first commissioning
3 3 LoRaWAN Interface
- 3.1 3.1 Join Procedure
- 3.2 3.2 Exponentially increasing intervals
- 3.3 3.3 Device EUI
- 3.4 3.4 Application EUI
- 3.5 3.5 Application Key
4 4 Application protocol description
- 4.1 4.1 Additional features
  - 4.1.1 4.1.1 Short stay filtration
  - 4.1.2 4.1.2 Preconfigured frequency sub-bands for US915 and AU915
- 4.2 4.2 Uplink messages
  - 4.2.1 4.2.1 Parking status
  - 4.2.2 4.2.2 Heartbeat
  - 4.2.3 4.2.3 Startup
  - 4.2.4 4.2.4 SDI tag registration message
  - 4.2.5 4.2.5 Debug messages
  - 4.2.6 4.2.6 Configuration feedback message
- 4.3 4.3 Downlink messages
  - 4.3.1 4.3.1 Parking status confirmable configuration
  - 4.3.2 4.3.2 DataRate configuration
  - 4.3.3 4.3.3 Heartbeat frequency
  - 4.3.4 4.3.4 Debug configuration
  - 4.3.5 4.3.5 Heartbeat NACK limit
  - 4.3.6 4.3.6 Short stay filtration configuration
  - 4.3.7 4.3.7 Full configuration
    - 4.3.7.1 4.3.7.1 The default configuration and other configuration examples
  - 4.3.8 4.3.8 Command
5 5. Changelog
- 5.1 2.3.2 28 March 2022
- 5.2 2.3.1 14 March 2022
- 5.3 2.1.0 18 January 2022
- 5.4 1.14.1 23 September 2021
- 5.5 1.14.0 20 June 2021
- 5.6 1.13.4 8 April 2021
- 5.7 1.13.0 16 December 2020
- 5.8 1.12.0 12 December 2020
- 5.9 1.11.0 7 December 2020
- 5.10 1.10.1 1 December 2020

1 Principle of operation

Data from the device’s sensors are processed by the device's embedded algorithm. The algorithm output is the parking state “free” or “occupied”. Device checks, if the parking status has been changed since the last processing run and in case the parking state change will be communicated via the LoRa interface. This means, that the parking sensor will only report if the parking state has been changed. Generally, the parking state detection time is about 3 seconds after conditions were stabilized (a vehicle stopped above the sensor or left the parking lot completely).
Considering an additional delay caused by the LoRa transmission and possibly re-transmissions, transmission time limitation of every device, transmission from the Gateway to the LoRa network, and processing by the LoRa network, the complete delay from new parking status until the state becomes visible in the LoRa application server maybe 4 or more seconds.

2 Calibration and first commissioning

Default sensor firmware was designed to minimize power consumption and radio spectrum usage until the sensor will be installed. When a sensor has been installed it is necessary to calibrate it using Nwave Device Management App. The first calibration works as an activation procedure and only after the first calibration the sensor will start detecting vehicles and try to join a LoRaWAN network.

Calibration must be done when the sensor is vacant(no car above the sensor). If the sensor was removed and then installed again it must be calibrated again. There is a slower automatic calibration that is designed to adjust to changing environmental conditions. Even if the initial calibration has been made with a car above the sensor or the sensor was moved after the last manual calibration the automatic calibration will make the sensor work but it can require some undetermined time depending on environment.

Note for developers:

If the sensor was moved or rotated you need to calibrate it in order to make it detect vehicles correctly. You can use a phone to simulate vehicle, to do it put it on the sensor covering square in the middle. You can stick the sensor with double-sided tape to something that does not move(floor or a table) to prevent sensor from moving or rotating.

3 LoRaWAN Interface

A parking sensor 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 parking sensor 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 will not be answered with a Join Accept message, the sensor retries, according to the following sequence:

In case the Join accept message is received while attempts 3, 4, or 5, the sensor restores the configured DataRate to the default value (DR2) if the data rate used was lower than the configured data rate(4.3.2). This behavior assumes that the configured DataRate does not allow communication with the Gateway.

For regions where multiple frequency sub-bands exist(like US915) it is necessary to keep in mind that in default firmware only 1 sub-band is enabled(4.1.2).

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 send park status messages whenever a change is detected. Most part of the application messages (startup message, heartbeat message, and parking state message) are sent as confirmed by default. 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).

The parking state message can be configured as not confirmed with or without repetitions. It reduces gateway utilization 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(4.3.2) from DR0 to DR5(for EU868).

Nwave Parking Sensor does not enable Adaptive Data Rate(ADR), as RF conditions of a sensor depend significantly on whether there is a vehicle above the sensor or not. Adjacent vehicles are also able to impact the RF conditions. As in the case of ADR, it is the network server's responsibility to correctly choose data rate, and this is done with the assumption that RF conditions are stable, so this could lead to unpredictable behavior.

The application protocol may be subject to change. The functionality may be extended in the next versions.

4.1 Additional features

4.1.1 Short stay filtration

Nwave parking sensor is able to detect cars in a very short time(within 5 seconds after car stopped) but there are some cases when sending messages for each short parking session is not desirable. For example, in a situation where the gateway is far away from the sensor and you need to use low datarate(DR0, DR1) but the place is often used as a drop-off point it may be necessary to use short stay filtration to save energy and decrease airtime to enable more sensors per gateway. Or for example, if sensors are mainly used to enforce parking rules and are not used to show real-time data it can be useful to use parking status messages with confirmation and probably low data rate but to have a significant delay after occupation before parking status message is sent.

The short stay filtration implemented in Nwave parking sensor consists of 2 different mechanisms(4.3.6):

static filtration by using Minimal occupation duration. Minimal occupation duration sets the delay between occupation and parking status message transmission.
adaptive filtration by setting expected maximum of parking sessions per day. If there are more sessions than were expected the sensor will try to gradually increase the delay between occupation and parking status message transmission. The maximum delay that can be set by this mechanism is 100 seconds.

In both cases, if parking session was too short, no messages will be sent. Both filtration mechanisms can work together. In some cases delay before message transmission can be caused duty cycle restrictions rather than short stay filtration. Short stay filtration does not affect sending parking status messages when vehicle released the sensor.

4.1.2 Preconfigured frequency sub-bands for US915 and AU915

By default sensors for these regions are sent with preconfigured FSB2. If you need another sub-band or full band enabled please contact Nwave.

4.2 Uplink messages

Uplink messages are those sent from the sensor to the network. The device has four (4) types of Uplink messages:

Parking status - port 1
Heartbeat - port 2
Startup - port 3
SDI tag registration - port 10

The simplest method of getting occupancy status from 1 and 2 is shown in the following Java Script code example:

The first example is for cases when the payload type is string (Nwave HTTP Calls for example):

payload = "E91F345678"

// cut out 1st byte and convert to integer
first_byte = parseInt(payload.slice(0,2), 16)

// the sensor is occupied if 1st bit is 1
occupied = Boolean(first_byte & 0x01 === 1)

console.log("Occupied: ", occupied);

The second example is for cases when the payload type is array of integers (TTN, TTI for example):

payload = [0xE9, 0x1F, 0x34, 0x56, 0x78]

// the sensor is occupied if 1st bit of the first byte is 1
occupied = Boolean(payload[0] & 0x01 === 1)

console.log("Occupied: ", occupied);

The last example shows how to get occupancy status from base64 encoded binary message:

msg_base64 = 'AQ=='

// decode base64
msg_bytes = atob(msg_base64)

// get the first byte of decoded message
first_byte = msg_bytes[0].charCodeAt()

// the sensor is occupied if 1st bit of the first byte is 1
occupied = Boolean(first_byte & 0x01 === 1)

console.log('Occupied: ' + occupied)

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.

Please refer to the sections below for detailed information on message payload structure.

4.2.1 Parking status

The parking status message uses port 1 and is confirmed by default. It may be configured as unconfirmed with or without repetitions (see downlink messages).

Byte	Bits	Name

Byte

Bits

Name

0

Parking status

0: Free parking space

1: Occupied parking space

7..1

Compressed duration of the previous status

Compressed duration of the previous status may be used to restore (with some limitation) the time of the previous status change(the same as the time of the last Parking Status message, may differ from the time of actual parking event if the Parking Status message was delayed due to some limitations ) if the previous parking status message was lost. It makes historic data more consistent if connectivity is not 100% (for example, if parking status messages are configured as unconfirmed).

The following table demonstrates how to calculate the previous status duration using the compressed value.

Compressed duration	Calculated duration(full minutes)	Maximum compression error(minutes)**

Compressed duration	Calculated duration(full minutes)	Maximum compression error(minutes)**
compressed_duration < 90	compressed_duration	0
90 ≤ compressed_duration <120	90 + (compressed_duration - 90)*5	4
120 ≤ compressed_duration <127	240 + (compressed_duration - 120)*60	59
127	>= 660	undefined

** Total error of previous status duration consists of:

Maximum compression error;
Rounding error up to 1 minute because duration is calculated in full minutes;
Transmission delay caused by LoRaWAN in-air limitations.

This error is additive, so the actual previous status duration is in the range [Calculated duration .. Calculated duration + total error].

4.2.2 Heartbeat

The heartbeat message uses port 2 and it is always confirmed. The heartbeat message contains parking status and information necessary for sensor health monitoring and it is sent every 24 hours (by default).

Byte	Bits	Name

Byte	Bits	Name
0	0	Parking status 0: Free parking space 1: Occupied parking space
0	7..1	Error Mask
1	7..0	Battery voltage. To convert to actual voltage: Vbat = (2500 + X*4)mV, where X is the value of the byte as unsigned integer This parameter can be used as a source for Low Battery Alert: >= 3000 - normal <3000 - low <2900 - critical
2	7..0	Temperature at which battery voltage was obtained *
3	7..0	Minimum temperature during last 24 hours *
4	7..0	Maximum temperature during last 24 hours *
5	7..6	Nwave debug data. Ignore these bytes.
5	5..0	Average current consumption estimation for the last 24 hours. Only power consumption of embedded sensors is used in the estimation(LoRaWAN messages transmission/reception consumption is not used in the estimation). To convert this value (unsigned integer) to current consumption: Current consumption = (X + 10)uA. Current consumption should be less than 50uA. Please contact Nwave support if you get higher numbers (X>40).

Heartbeat messages allow the device’s health monitoring using Error Mask, where all zeros mean that no 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.

* All temperatures have good linearity but their absolute offset can be +/- 5C in the temperature range 30..80C(contact nwave if you need more accurate temperature measurements). To convert the transmitted value into temperature in Celsius:

T = (t/2 + 10), where t is the value of the transmitted byte as signed integer(two's complement).

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

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	Bit 0 - parking status 0: Free parking space 1: Occupied parking space Bits 7..1 - reserved

4.2.4 SDI tag registration message

The SDI tag registration message uses port 10 and it is always confirmed. It provides 32 bit SDI tag serial ID (Big Endian)

https://nwaveio.atlassian.net/wiki/spaces/ND/pages/1574731877

Byte	Name

Byte	Name
0	This byte value depends on when Registration message is being sent: if it is being sent after Parking Status message indicating this occupancy session was sent the value will be 0 if it is being sent before parking status change message for this Occupancy session was sent the first byte will be equal to such in Parking Status message and Parking Status change message won’t be sent(so in this case SDI tag registration message combines registration data and Parking Status message in one message to decrease delay in getting Registration message)
1	SDI tag serial address, bits 31..24
2	SDI tag serial address, bits 23..16
3	SDI tag serial address, bits 15..8
4	SDI tag serial address, bits 7..0

4.2.5 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

Debug code	Meaning	Additional parameters
404 (0x194)	Calibration has been competed. The calibration could have been an initial calibration after activation or requested by user calibration. Automatic calibration (adjustment to changing environment) does not cause this message to be sent.	1 byte
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.2.6 Configuration feedback message

Nwave parking sensor allows reading its current configuration. The request to read the configuration can be sent via Downlink messages. It can be done in two ways:

by requesting it via Command(4.3.8)
by appending the acknowledgment flag to the Full configuration downlink message(4.3.7)

The configuration feedback message uses port 7 and is always confirmed. The structure of the message is equal to Full configuration downlink message(4.3.7)

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 Parking status confirmable configuration

Parking status confirmable configuration uses port 51 and it applies only to the parking status message. The default value is Confirmed (0x00). The configuration selected is persistent.

4.3.2 DataRate configuration

DataRate configuration uses port 52. There are different configurations for data rate when the sensor assumes that it is occupied and when it assumes that it is vacant. The default value is DR2 (0x02) for the occupied state and DR3 (0x03) for the vacant state. 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. The data rate for “vacant” state must be not less than for “occupied” state.

Byte	Bits	Name	Default value

Byte	Bits	Name	Default value
0	2..0	DataRate configuration for “vacant” state	3 (DR3)
	3	Reserved
	6..4	DataRate configuration for “occupied” state. This data rate is also used during first 2 attempts in Join cycly sequence.	2 (DR2)
	7	Reserved

DataRate configuration value	DataRate(Spreading Factor) EU868

DataRate configuration value	DataRate(Spreading Factor) EU868
0	DR0 (SF12BW125)
1	DR1 (SF11BW125)
2	DR2 (SF10BW125)
3	DR3 (SF9BW125)
4	DR4 (SF8BW125)
5	DR5 (SF7BW125)

DataRate configuration value	DataRate(Spreading Factor) US915

DataRate configuration value	DataRate(Spreading Factor) US915
0	DR0 (SF10BW125)
1	DR1 (SF9BW125)
2	DR2 (SF8BW125)
3	DR3 (SF7BW125)
4	DR4 (SF8BW500)

4.3.3 Heartbeat frequency

Heartbeat frequency uses port 53. The default value is 23 what is equal to 24 hours. The configuration selected is persistent.

Byte	Name

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. The default value is 3. 15 (0xF) and it is a special value that disables re-join functionality completely.

Byte	Bits	Name	Default value

Byte	Bits	Name	Default value
0	3..0	Heartbeat NACK limit	3
0	7..4	Reserved	0

4.3.6 Short stay filtration configuration

Short stay filtration can be used to optimize battery power consumption and decrease airtime (to decrease gateway utilization and to enable more sensors to be served by each gateway). It uses port 73 and the selected configuration is persistent.

Byte	Bits	Name	Default value

Byte	Bits	Name	Default value
0	7..0	Expected maximum count of sessions per day. Value 0 is special and means that adaptive filtration is disabled.	35
1	7..0	Minimal occupation duration. The value of delay between occupation detection and Parking Status message transmission is DELAY = value * 10s. The delay before transmission can be different due to LoRaWAN duty cycle restrictions.	0

4.3.7 Full configuration

The full configuration uses port 70 and is used to configure all parameters in one message.

Byte	Bits	Name	Default value

Byte	Bits	Name	Default value
0	2..0	Parking status confirmable configuration (4.3.1 )	0
	3	Reserved	0
	6..4	Debug configuration (4.3.4)	1
	7	Reserved	0
1	2..0	DataRate configuration for “vacant” state (4.3.2)	3 (DR3)
	3	Reserved	0
	6..4	DataRate configuration for “occupied” state (4.3.2)	2 (DR2)
	7	Reserved	0
2	3..0	Heartbeat NACK limit (4.5.2)	3
2	7..4	Reserved	0
3	7..0	Heartbeat frequency (4.3.3)	23 (0x17)
4	7..0	Short stay filtration - expected maximum count of sessions per day (4.3.6)	35 (0x23)
5	7..0	Short stay filtration - minimal occupation duration(4.3.6)	0

If you append 1 more byte equal to AA to this message, you will also be sent a Configuration feedback message as a way to acknowledge if the configuration was accepted.

4.3.7.1 The default configuration and other configuration examples

The default configuration described above looks like

10 23 03 17 23 00

Here is an example of some configuration messages that can be useful:

10 02 03 17 23 00 AA - change data rate to DR0 and DR2 for Occupied/Vacant messages accordingly and send an acknowledgment. Can be used if the sensors are known to be far away from the gateways(so lower datarates are needed to decrease the reception delay of the uplink messages).

11 01 03 17 23 00 AA - change data rate to DR0 and DR1 for Occupied/Vacant messages accordingly, send Parking status messages as unconfirmed without repetitions, and send an acknowledgment. Can be used if the sensors are known to be far away from the gateways(so lower datarates are needed to decrease the reception delay of the uplink messages) and utilization of gateways does not allow to send enough confirmation messages.

10 23 03 17 00 00 AA - disable adaptive filtration and send an acknowledgment. Can be used when a lot of parking sessions are expected and need to be sent without any additional delays, for example, for developers while testing or on demonstrations.

4.3.8 Command

Command uses port 71 and it is used to initiate different commands mainly for debugging.

Write:

01 (1 byte) to calibrate the device,
02 (1 byte) to reboot the device,
03 (1 byte) to put the device into initial mode (the device sleeps until the next calibration with no detection and no LoRaWAN messages).
04(1 byte) to read current configuration(to request transmission of Configuration feedback message)

5. Changelog

2.3.2 28 March 2022

Features:

Request for reading configuration was added

Known issues and limitations:

None at the moment.

2.3.1 14 March 2022

Features:

Improved detection
Fix for occasional rare hardware errors

Known issues and limitations:

None at the moment.

2.1.0 18 January 2022

Features:

Heartbeat message is extended to provide data for sensor health monitoring

Known issues and limitations:

None at the moment.

1.14.1 23 September 2021

Features:

Increased Error Mask to improve monitoring
Health Check via BLE support added

Known issues and limitations:

None at the moment.

1.14.0 20 June 2021

Features:

Short stay filtration mechanism added.

Known issues and limitations:

None at the moment.

1.13.4 8 April 2021

Features:

Support for the version of hardware with high power radio output (for the USA market) . There are 2 different firmware images for 2 versions of the sensors.
General performance improvement

Known issues and limitations:

None at the moment.

1.13.0 16 December 2020

Features:

Compressed duration of the previous status was added to Parking Status message.

Known issues and limitations:

None at the moment.

1.12.0 12 December 2020

Features:

Fix of magnetometer initialization error.

Known issues and limitations:

None at the moment.

1.11.0 7 December 2020

This firmware contains a bug leading to decreased detection performance - updating is required.

Features:

Heartbeat NACK limit default value changed to 3;
Sleep until the next calibration command was added.

Known issues and limitations:

Magnetometer initialization bug leading to decreased detection performance.

1.10.1 1 December 2020

This firmware contains a bug leading to decreased detection performance - updating is required.

Features:

Independent data rate configuration for occupied and vacant statuses;
Minimized consumption until the first calibration;
Configurable re-join behavior.

Known issues and limitations:

Magnetometer initialization bug leading to decreased detection performance.