TCR LoRaWAN® Payload Description

V2.2 | V2.1 | V2.0 | V1.3

This document describes LoRaWAN® Payload formats of Parametric TCR Traffic Counters used in Firmware V2.2

Changes made in this version of the document.

• New Counter Payload V2. (Changed sbx_batt to voltage to get either DC power or SBX voltage)
• Fixed downlink command c152 radar_channel

Payload Types

TCR devices send 3 different payloads types. Each payload has a unique prefix to easily separate them. In addition, different ports are used in each case.

Format	Prefix	Bytes	Port	Uplink	Downlink
DeviceID Payload V2	be02xxd2	10	190	once	n/a
Counters Payload V2	a2	10	14, 15, 16, 17	interval	on request
Config Payload V1	c1	6-7	1	on request	on request

DeviceID Payload (Port 190)

After TCR has successfully joined a LoRaWAN® network, a DeviceID payload is sent once via port 190.

The DeviceID payload contains device identification data and firmware version information. This can be useful in large installations to maintain a device inventory with information such as type and firmware version. If this is not needed, ignore this payload data.

Downlinks to port 190 will be ignored.

Payload Format

Total length: 10 bytes (20 ASCII characters)

Examples

Counter Payload (Port 14, 15, 16, 17)

Counter data is sent at regular intervals or on detection (totalizer mode).

To save airtime, the payload has been reduced to 10 bytes. This allows operation in all major LoRaWAN® regions such as EU868, AS923, AU915 and US915.

Payload Format

Byte	Property	Description	Uplink Values	Downlink Values
0	pay_type	a2 = Counter Payload V2	a2	a2
1-2	data{x}_timestamp	Timestamp of data, Hours (GMT) HHMM	0000-2359	-
3-4	l{x}_cnt	Left-to-right counter value x = 0, 1, 2, 3 (Cat. P, A, B, C)	0000-ffff	0000-ffff
5	l{x}_avg	Left-to-right average speed [km/h] x = 0, 1, 2, 3 (Cat. P, A, B, C)	0000-ffff	-
6-7	r{x}_cnt	Right-to-left counter value x = 0, 1, 2, 3 (Cat. P, A, B, C)	0000-ffff	0000-ffff
8	r{x}_avg	Right-to-left average speed [km/h] x = 0, 1, 2, 3 (Cat. P, A, B, C)	0000-ffff	-
9	voltage	Power supply voltage (dc power or solar power) Multiply with 100 to get mV dc power measurement is currently limited to 6600mV due to a hardware limitation	0000-ffff	-

{x} : 0, 1, 2, 3

Total length: 10 bytes (20 ASCII characters)

Ports used

Counter data are sent on different ports to indicate different traffic classes. As an example car category will always be sent using port 16.

Note: Not all payloads are used on all device types.

Examples

Config Downlinks (Port 1)

Config downlinks are used to change device settings remotely. A key / value pair is sent to the device for this purpose.

Config Payloads are sent and received at port 1. As soon as the device receives a downlink, the setting will be range-checked and saved to ROM. The devices applies most of the settings during operation.

Note: It is a good idea to send a c1ee when you are done to let the device restart and re-join.

Payload Format

Total length: 4 bytes (8 ASCII characters)

Application Settings

Downlinks to change application settings. Send c1ee to apply settings an restart the device.

Traffic Categories

Downlinks to configure traffic categorization. This includes object size and speed of an object. If both values are in the defined range, the object will be marked to be cat 0, 1, 2 or 3.

Following tables shows default categories enabled by device type. However it is possible to enable all categories on all types.

Cat P

Following downlinks are used to configure people detection filters. Send c1ee to apply settings an restart the device.

Cat A

Following downlinks are used to configure detection of bicycles or motorbikes. Send c1ee to apply settings an restart the device.

Cat B

Following downlinks are used to configure detection of cars. Send c1ee to apply settings an restart the device.

Cat C

Following downlinks are used to configure detection of heavy vehicles (HGV). Send c1ee to apply settings an restart the device.

Radar Settings

Downlinks to change radar settings. Send c1ee to apply settings an restart the device.

LoRaWAN® Settings

Downlinks to change some LoRaWAN® settings. Send c1ee to apply settings an restart the device.

Device Control Commands

These downlinks are used to execute commands on the device

A typical configuration sequence

Following example shows a typical sequence to change only one setting.

DL: c102000a            <- change interval to 10 min 
UL: c102000a            <- uplink showing the value has been accepted
DL: c1ee                <- send the restart command 
.
JOIN                    <- device restarts and joins
.                             
UL: be0200d012040000    <- DeviceID payload (port 190) after join accept received
.

Get one setting

To read back a single setting simply send the key without a value.

The following payload will request a uplink of the LoRaWAN® interval setting

    c102

After a while you will receive

    c102000a     // Interval = 10

Get all settings

It is possible to read back all settings at once by using the configuration uplink sequence.

To start the sequence send the configuration downlink c1cf to port 1. This will start an uplink sequence startin with setting number 00. The sequence can take up to 30 minutes. During this uplinking other data is paused. Nevertheless counting is still active and counter values will be transferred later.

Example

    c1cf

After a while you a uplink on port 1 each minute

    c101xxxx    
    c102xxxx    
    c103xxxx    
    c104xxxx    
    c105xxxx    
    ...
    ...

Best Practice

A few hints for implementing payload decoders. You can find code examples on our public repository

Implementing a decoder

In order to stay backwards compatible with future developments we highly recommend checking uplink port and payload prefix to select an encoder

var obj = {};

    if (port == 15 && bytes[0] == 0xbe && bytes[1] == 0x02 && bytes[2] == 0x01) {
        // it's an Application Payload V1
        obj = app_payload_v1_decoder(bytes, port);
    }

    if (port == 15 && bytes[0] == 0xbe && bytes[1] == 0x02 && bytes[2] == 0x02) {
        // it's an Application Payload V2
        obj = app_payload_v2_decoder(bytes, port);
    }

    if (port >= 14 && port <= 17 && bytes[0] == 0xa1) {
        // it's a Counting Payload V1 (TCR V2.0 )
        obj = counting_payload_V1_decoder(bytes, port);
    }

    if (port == 190 && bytes[0] == 0xbe && bytes[1] == 0x02 && bytes[2] == 0x01) {
        // it's a Configuration Payload V1
        obj = config_payload_v1_decoder(bytes, port);
    }

    if (port == 190 && bytes[0] == 0xbe && bytes[1] == 0x02 && bytes[2] == 0x02) {
        // it's a Configuration Payload V2
        obj = config_payload_v2_decoder(bytes, port);
    }

    if (port == 190 && bytes[0] == 0xbe && bytes[1] == 0x02 && bytes[2] == 0x03) {
        // it's a Configuration Payload V3
        obj = config_payload_v3_decoder(bytes, port);
    }

    if (port == 190 && bytes[0] == 0xbe && bytes[1] == 0x02 && bytes[2] == 0x04) {
        // it's a Configuration Payload V4
        obj = config_payload_v4_decoder(bytes, port);
    }

    if (port == 190 && bytes[0] == 0xbe && bytes[1] == 0x02 && bytes[3] == 0xd1) {
        // it's a DeviceId Payload V1
        obj = device_id_v1_decoder(bytes, port);
    }

    if (port == 190 && bytes[0] == 0xbe && bytes[1] == 0x02 && bytes[3] == 0xd2) {
        // it's a DeviceId Payload V2
        obj = device_id_v2_decoder(bytes, port);
    }

    if (port == 1 && bytes[0] == 0xc1) {
        // it's a Config Payload Response (Uplinked ACK of a Config Downlink) V1 (TCR V2.0)
        obj = config_payload_V1_decoder(bytes, port);
    }


    return obj;

Check Timestamp

A confirmed uplink message is a message where a LoRaWAN® endpoint (TCR) is requesting the LoRaWAN® network to confirm the reception of its uplink message. If it receives a message within the first or second RX window, which ‘ACK’ flag set to 1, it will consider the original uplink message delivered.

If there is no message received, it means the network has not received the uplink. In this case TCR simply sends the uplink again and again (up to 10 times or according the attempts setting before doing a rejoin). Counter values are only reset when TCR received an ACK for not loosing data.

With firmware V2.0 we added a GMT timestmp (hours and minutes) to the payload. This works like a serial number for the submitted data. Checking this value allows the application server to determine if the ACK has been received by the device or if data is missing.

Example Uplink Sequence

Following sequence of uplinks show problems with RX path of the device. Uplinks have been received by the network. But the device did not hear the ACK.

a1 0f 2d 00 01 05 00 02 06 00   <- Message has been created 15:45 GMT 
a1 0f 37 00 12 04 00 11 05 00   <- Message has been created 15:55 GMT 
a1 0f 37 00 12 04 00 11 05 00   <- Identical timestamp (Repeated message! *) 
a1 10 05 00 12 04 00 11 05 00   <- New message 

Repeated messages apear when device did not receive an ACK.

Implementation of an algorithm

• App Server should save the last timestamp received
• When a new uplink is received the decoder should check if timestamp changed. (Compare with saved value)
• If changed, save the counter values to the database. If timestamp is identical, the message is a repetition and can be ignored. Check LoRaWAN® reception path (range) in this case.

Payload Decoder Examples

Find more example code in our public repository.

Disclaimer

ALL PRODUCT, PRODUCT SPECIFICATIONS AND DATA ARE SUBJECT TO CHANGE WITHOUT NOTICE TO IMPROVE RELIABILITY, FUNCTION OR DESIGN OR OTHERWISE.

PMY Systems AG, its affiliates, agents, and employees, and all persons acting on its or their behalf (collectively, "PMX"), disclaim any and all liability for any errors, inaccuracies or incompleteness contained in any datasheet or in any other disclosure relating to any product.

PMX makes no warranty, representation or guarantee regarding the suitability of the products for any particular purpose or the continuing production of any product. To the maximum extent permitted by applicable law, PMX disclaims (i) any and all liability arising out of the application or use of any product, (ii) any and all liability, including without limitation special, consequential or incidental damages, and (iii) any and all implied warranties, including warranties of fitness for particular purpose, non-infringement and merchantability.

Statements regarding the suitability of products for certain types of applications are based on PMX's knowledge of typical requirements that are often placed on Paramtric products in generic applications. Such statements are not binding statements about the suitability of products for a particular application. It is the customer's responsibility to validate that a particular product with the properties described in the product specification is suitable for use in a particular application. Parameters provided in datasheets and / or specifications may vary in different applications and performance may vary over time. All operating parameters, including typical parameters, must be validated for each customer application by the customer's technical experts. Product specifications do not expand or otherwise modify Paramtric's terms and conditions of purchase, including but not limited to the warranty expressed therein.

Hyperlinks may direct users to third-party websites. These links are provided as a convenience and for informational purposes only. Inclusion of these hyperlinks does not constitute an endorsement or an approval by PMX of any of the products, services or opinions of the corporation, organization or individual associated with the third-party website. PMX disclaims any and all liability and bears no responsibility for the accuracy, legality or content of the third-party website or for that of subsequent links.

Except as expressly indicated in writing, PMX products are not designed for use in medical, life-saving, or life-sustaining applications or for any other application in which the failure of the PMX product could result in personal injury or death. Customers using or selling PMX products not expressly indicated for use in such applications do so at their own risk. Please contact authorized PMX personnel to obtain written terms and conditions regarding products designed for such applications.

No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted by this document or by any conduct of PMX. Product names and markings noted herein may be trademarks of their respective owners