Add-On Protocol - RS232 & USB

External devices can communicate with a Geotab GO device through the Third-Party RS232 and USB protocols linked below. Two-way communication is supported, allowing a MyGeotab API call to produce messages from the IOX device to reach the external device. The hardware interface is one of the following:

• IOX-RS232 F/M
• IOX-USB

Special Requirements

Enabling IOX-USB Data Transfer

To enable third-party data communication on the IOX-USB, apply the following custom parameter to the GO device through MyGeotab:

<GoParameters><Parameter Description="Enable USB Data" Offset="164" Bytes="02"/></GoParameters>

* Note - The GO device will automatically upgrade to the ProPlus rate plan once third-party data transfer begins.

IOX-USB Communication Consideration

The IOX-USB operates as a USB 2.0 full-speed host. The maximum data transfer rate is 12 Mbit/s. The IOX-USB can use two methods to enumerate a USB device:

1. The Android Open Accessory protocol (AOA). This sample project can be used as a framework.
2. USB-CDC (Communications Device Class)

Powering a device using the IOX-RS232 and IOX-USB

Both the IOX-USB and the IOX-RS232 can provide power to an Add-On Device.

• The IOX-USB can provide 1.5A at 5V as a power output.
• The IOX-RS232 supports 900mA at 12/24V to the external red (power) and black (ground) wires. However, it is not required to power the Add-On device using the IOX-RS232.

Grounding a device

Even if the Hardware Add-On has a separate connection to vehicle power and ground, it is still recommended to connect the Add-On ground to the ground wire of the IOX-RS232, as this improves signal integrity.

Serial Port Settings For Add-Ons

Geotab recommends that RS232/USB serial ports are programmed in accordance with the following specifications:

• Baud Rate: 9600 or 115200. Note: the device is equipped with autobaud detection, so other standard rates are acceptable.
• Parity: None
• Stop Bits: 1
• Flow Control: None

Integration Process

The following process should be followed when integrating a third-party device with the GO device using our Third-Party Data Protocol:

Contact Solutions Engineering

Contact the Geotab Solutions Engineering team with a detailed integration proposal, which should include:

• A name for the integration
• The interfacing hardware
• Data types that will be sent to MyGeotab
• The required Status Data
• Direction of data transfer
• Expected timelines for integrating

The Solutions Engineering team will respond with followup questions to define the integration, and assign an External device ID and any Status Data IDs that would be required.

An additional resource is the Hardware Integration Toolkit with integration walkthrough.

Using Status Data IDs

There is an extensively defined Status Data ID list which can be found at MyGeotab Diagnostics. Specifics regarding Status Data ID implementations can be found on the README sheet.

Handshake

An initial Handshake is required in order for the GO device to accept third-party data. Vehicle ignition must be on during the handshake process.

1. After powering up, the GO device will enter an external device detection cycle. The external device will be powered for 72 seconds. In this interval, the GO device will listen for a Handshake Sync from the external device. The Handshake Sync is used to indicate that an external device is present. For implementations using the IOX-RS232, the Handshake Sync is also used to detect baud rate.
   • The external device must send the Handshake Sync message once per second.
   • If a Handshake Sync message is not detected from the external device after 72 seconds, the external device is powered down for 5 seconds, then powered up again to restart the detection cycle.
2. The GO device will reply to a Handshake Sync with a Handshake Request.
3. The external device must reply with a Handshake Confirmation message within 2 seconds. If the external device would like an acknowledgment from the GO device that it received the Handshake Confirmation message, the corresponding flag in the Handshake Confirmation message may be set.
4. After sending the Handshake Confirmation message, the external device can begin to send third-party data as required. For every Third-Party Data Message sent, the GO device will reply with a Data Acknowledge message.
   • If the external device receives no response to a Third-Party Data message, it must restart the handshake process — returning to step 1 above.
5. The GO device may send a Handshake Request message at any time after the initial handshake. The external device must respond with a Handshake Confirmation message. If the external device does not respond, it must restart the handshake process — returning to step 1 above.

Checksum

Each message contains a 2-byte Fletcher’s Checksum calculated across all the bytes of the message except the checksum itself. The checksum values are bytes, and as such overflow from 255 (0xFF) to 0 (0x00). The bytes used for the checksum calculation are all the bytes up to the checksum byte, including STX, LEN, TYPE, but not including ETX.

Checksum calculation pseudocode:

byte ChkA = 0;
byte ChkB = 0;
// n is the number of bytes in the message
// up to, but not including, the checksum
for (i = 0; i < n; i++)
{
ChkA = ChkA + MsgBuffer[i];
ChkB = ChkB + ChkA;
}
// ChkA precedes ChkB in the message

Data Endianness

All values must be sent using Little-Endian Byte Order, meaning the least significant byte is first.

Messages from the GO device

Msg Type 0x01: Handshake Request

Issued by the GO device upon receipt of the Handshake Sync, and periodically re-sent to confirm that the external device is still connected.

Msg Type 0x02: Third-Party Data Acknowledge

Issued by the GO device upon receipt of Third-Party Data from the External Device.

Msg Type 0x21: GO Device Data

Issued by the GO device every 2 seconds to a connected Enhanced Hours Of Service Device (ID: 4141), or periodically when a 0x85 request message is received.

• An Enhanced Hours Of Service Device must ACK this message with a 0x84 message.
• If the data is requested periodically using the 0x85 message, the ACK is optional.

1. All implementations of this message must cater for the message length increasing in the future.
2. “Date/Time” is a ‘seconds’ counter starting from 1st of January 2002.
3. If Road Speed from the engine is not available, GPS speed is used.
4. Increase of odometer since the most recent ignition on. If Odometer is not available, GPS device distance is used.
5. Time passed since the most recent ignition on.
6. Driver ID is only available when using the IOX-NFC.

Conversions

Msg Type 0x22: Binary Data Response

Issued by the GO device upon acceptance or rejection of either a Binary Data (0x86), an Extended Application Specific Data (0x88), or an Extended Binary Data (0x8A) message from the external device.

Msg Type 0x23: Binary Data Packet

Issued by the GO device upon receipt of a Binary Data packet of 255 bytes or less from MyGeotab destined for the external device. This message format is only used if the corresponding “Binary Data Packet Wrapping” flag has been set by the external device during the Handshake Confirmation. The payload of the binary data packet message will be the raw bytes sent from MyGeotab.

Msg Type 0x24: Extended application specific data to external device

Sent by the GO device to the external device. Can be in response to a 0x88 message and used for payloads larger than 1 byte. Currently only used for Keyless.

Msg Type 0x25: Extended binary data packet

Issued by the GO device upon receipt of a Binary Data packet of 256 bytes or more from MyGeotab destined for the external device This message format will only be used if the corresponding “Binary Data Packet Wrapping” flag has been set by the external device during the Handshake Confirmation. The payload of the binary data packet message will be the raw bytes as sent from MyGeotab. The maximum length currently supported by the GO is 1000 bytes.

Msg Type 0x26: Protobuf data packet

Available with add-on protocol versions 1.2 and later. Issued by the GO device in response to 0x8C. Also issued by the GO device to publish information for the topics subscribed by the Add-On device.

The payload is protobuf-encoded. Please see Protobuf Schema for details.

Msg Type 0x27: Add-On protocol version to external device

Sent by the GO device to an external device as a reply to the Add-On protocol version request (0x8B).

Messages from External Device

Handshake Sync (Auto-BAUD detect for RS232)

Issued by an external device every second until the Handshake Request is received.

Msg Type 0x81: Handshake Confirmation

Issued by the external device when it receives the Handshake Request.

Handshake Confirmation ACK:

• 0: No Ack to Handshake Confirmation message will be sent by the GO device.
• 1: The Handshake Confirmation is to be acknowledged with a Third-Party Data Acknowledge message.

Binary Data Packet Wrapping:

• 0: The passthrough data from the server will be passed to the external device without modification.
• 1: The passthrough data from the server will be wrapped in a Binary Data Packet message before being sent to the external device.

Self-Powered External Device:

• 0: The External Device receives power from the IOX. After waking up, the IOX will restore power to the External Device and wait for the handshake to complete.
• 1: The External Device has its own power source. The IOX will not wait for the handshake and will assume it can initiate communication with the External Device immediately after waking up.

Msg Type 0x80: Third-Party Data as Status Data

Issued by the external device whenever it requires Third-Party Data to be saved on the GO device as Status Data. Rate limit is 100 logs per 10 minutes, for each distinct data ID. If you exceed the rate limit, the GO device will stop taking data from the IOX.

Msg Type 0x82: Free Format Third-Party Data

Issued by the external device whenever it wants Third-Party Data to be saved on the GO device in a free format (1 to 27 bytes) that will be saved in MyGeotab as Custom Data. Rate limit is 500 logs per 10 minutes. If you exceed the rate limit, the GO device will stop taking data from the IOX.

Msg Type 0x84: Device Data ACK

Issued by the External Device on receipt of the GO Device Data message.

For the purpose of acknowledging the GO Device Data message when connected as an Enhanced Hours Of Service Device:

• The GO device will keep streaming the GO Device Data messages for up to 30 seconds, even if no ACK is received.
• If no ACK is received in that time frame, the GO Device will send an External Device Disconnected record to the server and will wait for a new Handshake Sync request from the External Device.
• If the ACK message is received within the 30 seconds, the counter is re-initialized.

Msg Type 0x85: Request Device Data Message

This is a request-response message. It can be issued by the External Device whenever it wishes to receive the Device Data Info Message (0x21).

Msg Type 0x86: Binary Data Packet

Sent by the external device when sending messages with less than or equal to 255 bytes of data content to MyGeotab. The GO device will respond with the Binary Data Response message indicating whether the data was accepted into the modem’s socket buffer.

The payload of the binary data needs to adhere to protocols understood by MyGeotab. MIME protocol is one of these protocols. Please see Appendix C for implementation details.

Msg Type 0x87: Third-Party Data as Priority Status Data

Priority Status Data follows an expedited processing workflow on the GO device, but will otherwise be treated the same as an 0x80 Status Data message. It will also be logged using an Iridium modem connection, if available.

Msg Type 0x88: Extended application specific data from external device

Extended application-specific data from external device is sent by the external device to the GO device. Can be used for payloads larger than 1 byte. There must be an associated service running on the GO device that is looking for these messages. Currently only used for Keyless.

Msg Type 0x89: Ping

After handshaking, this message can be issued periodically by the external device to check that the GO device is active and ready. The GO device will normally reply with the Third-Party Data Ack (Msg Type 0x02). If this reply is not received, the external device should reset and begin sending the Handshake Sync (0x55).

Msg Type 0x8A: Extended binary data packet

Sent by the external device when sending messages with <= 1000 bytes of data content to MyGeotab. The GO device will respond with the Binary Data Response message indicating whether the data was accepted into the modem’s socket buffer.

The payload of the binary data needs to adhere to protocols understood by the Geotab servers. MIME protocol is one of these protocols. Please see Appendix C for implementation details.

Msg Type 0x8B: Add-On protocol version request

Sent by the external device when requesting the Add-On protocol version number. Once the GO device receives this request, it will reply with 0x27.

Msg Type 0x8C: Protobuf data packet

Available with Add-On protocol versions 1.2 and later. Sent by the external device to subscribe to various topics/information. The GO device will respond with 0x26 ACK.

The payload is protobuf-encoded. Please see Protobuf Schema for details. The currently supported topics are:

Appendices

Appendix A: Raw Message Data Example for IOX-USB & IOX-RS232

Handshake Sync from External Device
0x55... 0x55... 0x55

Handshake Request from GO device
0x02, 0x01, 0x00, 0x03, 0x08, 0x03

Handshake Confirmation from External Device (4208 is a test Device ID)
(Device ID: 4208 = 0x00001070)
0x02, 0x81, 0x04, 0x70, 0x10, 0x00, 0x00, 0x07, 0x18, 0x03

Third-Party Data from External Device
(Status Data ID: 35349 = 0x8A15, Data Value: 200 = 0x000000C8)
0x02, 0x80, 0x06, 0x15, 0x8A, 0xC8, 0x00, 0x00, 0x00, 0xEF, 0x8C, 0x03

Third-Party Data Acknowledge from GO device
0x02, 0x02, 0x00, 0x04, 0x0A, 0x03

Appendix B: Sample Message Flow for IOX-USB & IOX-RS232

Appendix C: Using Binary Data Messages to Transfer MIME Data

MIME-type data can be transferred from an external device to the server via the GO device. The protocol is described in MIME passthrough messages.

The Message Flow is similar to that outlined in Appendix B, with the following variations:

1. Third-Party Data Message is instantiated as Binary Data Packet Containing MIME Type Data, whose format is such
2. Data Acknowledge Message is instantiated as Binary Data Response (0x22)
3. After the last Binary Data Response, add a Binary Data Packet Containing MIME Type Acknowledge, whose format is such. Once the complete payload of the MIME message is successfully received by MyGeotab, a MIME ACK will be sent back from MyGeotab.

Readers are encouraged to also read the Geotab MIME Data Exchange Example IOX-RS232 to better understand of the protocol.

Binary Data Packets Containing MIME Type Data

This is an example of binary data packets for image data transferred using the MIME type “image/jpeg”. The image size is 83000 bytes. The packet size is 250.

First packet:

Second packet:

Binary Data Packet Containing MIME Type Acknowledge