Telemetry Data Forwarding

BikeTrax allows external telemetry devices to send telemetry data to the PowUnity GPS platform. An example of this would be to report an eBike's current battery charge level.

Overview

An external telemetry device is attached to the tracker via UART. This UART interface exposes an AT console. Telemetry values are encoded using the PU protocol, these PU messages are encapsulated in a AT command message and sent over the UART.

This results in the following encpsulation/layers:

UART -> AT -> PU -> The telemetry value

Electrical connection

• UART at 2.8V

• Pads on top side of tracker (Next to SIM holder, with pin 1 labeled 'VBAT')

  • pin 3: UART_GND - same as VIN_GND (ground for VIN which is the external power supply to the tracker)

  • pin 4: TRACKER_TX (tracker TX on this pin)

  • pin 5: TRACKER_RX (external device TX on this pin)

UART protocol

• 115200 bit/s

• 8N1

• no flow control

AT protocol

Send a message to the cloud via the tracker:

AT%TEST=*1234,230*(PU_MSG_LEN,PU_MSG)#\r\n

Where:

• \r\n are a CRLF sequence

• PU_MSG is a PU message defined below

• PU_MSG_LEN is the length (number of characters) of the PU_MSG. The numeric length is ASCII string encoded, to a length of 12 would send the two characters 12, which are the two bytes 0x3132

The tracker will immediately ACK the receipt of the command by sending the following line, OK\r\n (where \r\n are a CRLF sequence).

The tracker will then attempt to contact the cloud and upload the PU_MSG payload. If and once the upload is successful the tracker will send the following line over the AT console:

Send OK\r\n

Where PU_MSG and PU_MSG_LEN are the same as in the send AT command.

This is called the PU_ACK and is simply the acknowledgement that the PU message was sent successully.

If the PU message could not be uploaded to the cloud the Send OK\r\n is not sent. In future versions of this protocol we plan on adding a known timeout value and an error response once this timeout has occurred. For now we need to manage timeouts in the PU protocol. See below.

PU_MSG message protocol, version 1.1

The PU_MSG is an 8-bit ASCII encoded string made up of a version field and one or more data label+value pairs. The version and data pairs are delimeted by the | character. The data label and data value are delimited by the @ character.

VERSION|DATA_LABEL@DATA_VALUE or VERSION|DATA_LABEL@DATA_VALUE|DATA_LABEL@DATA_VALUE etc.

Where the VERSION field is the PU_MSG’s major version. Please always use the ASCII 1.

See the table below for possible DATA_LABEL values. The data value must be an alphanumeric ASCII string.

There can be more than one DATA_LABEL@DATA_VALUE pairs, however, the maximum PU_MSG length must not exceed 16 bytes/characters.

After the PU_MSG has been sent the telemetry device should await the PU_ACK message (see the AT protocol section above) and determine if the message should be resent after a timeout.

For sending battery telemetry (a PU_MSG containing battery information) we recommend waiting for the PU_ACK message for 1 minute and, if no PU_ACK, sending it again,until a PU_ACK is received. Once a PU_ACK has been received we recommend to wait 10 minutes before sending the next battery telemetry message.

Example 1

Report 13,8 Volt battery voltage and battery 87% charged:

• PU_MSG: 1|1@87|2@138

• Resulting AT command: AT%TEST=*1234,230*(12,1|1@87|2@138)#\r\n

• Resulting AT repsonse after tracker receipt: OK\r\n

• Resulting AT response after tracker could send to the cloud: Send OK\r\n

Example 2

Send powunity20:

• PU_MSG: powunity20

• PU_MSG_LEN: 10

• Resulting AT command: AT%TEST=*1234,230*(10,powunity20)#\r\n

• Resulting AT repsonse after tracker receipt: OK\r\n

• Resulting AT response after tracker could send to the cloud: Send OK\r\n

Sending the data via a serial terminal (left side of picture). The message can be seen on traccar.powunity.com in the Input tracker attribute: