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

Mechanical Connection

Electrical connection

• UART at 2.8V

• Connector cable Pins:

  • pin 1: VCC(orange)

  • pin 2: RX(white)

  • pin 3: no use(brown)

  • pin 4: no use(green)

  • pin 5: GND(black)

  • pin 6: TX(purple)

Open

Female Connector

Open

Male Connector

• PCB-Pins(from left to right):

  • GND (black)

  • VCC(orange)

  • RX(white)

  • TX(purple)

  • GND_Battery(black)

  • V_Battery(blue)

UART Settings

• 115200 bit/s

• 8N1

• no flow control

Data Protocols

Generic AT protocol

Send a message containing arbitrary data to the cloud via the tracker:

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:

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.

Example

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 http://traccar.powunity.com in the Input tracker attribute:

PowUnity message protocol

The difference when using PowUnity’s protocol versus the generic AT Protocol, is that the various fields will get mapped to their own distinct attributes in the position object and some will get copied over to the following position objects even when there is no new data coming from the bike (think of eBike SOC e.g.)

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.

Version 1.1

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

Report battery 87% charged and assist level 3:

• PU_MSG: 1|2@87|4@3

• Resulting AT command: AT%TEST=*1234,230*(10,1|2@87|4@3)#\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