IO Expander Protocol

General Description

The GO device and the Input-Output Expander (IOX) are connected in a dedicated CAN network. All communication is between the GO device and the IOX. IOXs do not talk to each other. Communications can be of the form: GO device to all IOXs, GO device to individual IOX, or individual IOX to GO device. Readers are recommended to find examples from CAN IOX Sample Communication Session as they read through the rest of this page.

Identification

This document describes the IOX Expander Protocol version 1.1.

All messages are supported since IOX Expander Protocol version 1.0 unless stated otherwise.

Interoperability

Third party IOX Add-ons rely on the messages and protocol defined in this document in order to properly communicate with Geotab firmware. Geotab will endeavor to maintain support for the currently-documented messages and protocol. However, from time to time Geotab may make changes to such messages and protocol which could potentially impact third party IOX Add-on implementations. If Geotab makes any such changes, Geotab will use commercially reasonable efforts to provide partners with as much notice of the impending firmware changes as is practicable in the circumstances. Geotab accepts no responsibility or liability for third party IOX Add-ons which fail to function properly, or at all, and any and all damages which arise, directly or indirectly, from such failures.

Geotab recommends that all partners who develop their own IOX Add-ons ensure they have the ability to remotely update their firmware. This can be accomplished by sending an update to the IOX Add-on using the MIME passthrough messages.

Serial Number

Each custom IOX is assigned a 4 byte Serial Number by the integrators, similar to each car having its own VIN. The 2 Most Significant Bytes of the Serial Number shall also be reported in bytes 3 and 4 of the Poll Response (0x02). The 2 Least Significant Bytes are used for differentiating each IOX which exists on the same CAN bus (attached to the same GO device) when the GO device is sending messages targeted for a specific IOX. In other words, the 2 LSB serve as the Address ID, and is included in bits 15 - 0 of the Arbitration ID.

Integrators are free to leverage any mechanism for the Serial Number assignment to each individual IOX, but Geotab recommends following the process outlined below:

1. Generate a random 4 byte value.
2. Make sure that the 2 LSBs are not equal to ‘0000’.
3. Make sure that you do not already have this value stored in your database of existing serial numbers.

Message Structure

Message identification is done with an arbitration ID.

The Arbitration ID Field for IOX Messages:

0x1F800000 IO_EXPANDER_RESERVED_MASK

0x007F0000 IO_EXPANDER_COMMAND_MASK

0x0000FFFF IO_EXPANDER_ID_MASK

Address ID

The last 2 bytes of the IOX Serial Number (MSB first) are used as the Address ID. This allows the GO device to identify the source of a message or, when the message is sent from the GO device, to identify the destination IOX.

The GO device sends messages with ID 0x0000 meant for all IOXs, or with an ID between 0x0001 and 0xFFFF when it is targeted at a specific IOX.

IOXs always use their own ID when sending messages. They never send 0x0000. For this reason, IOXs are not produced with Serial Numbers ending in 0x0000.

IOX ID

Each model of IOX is assigned an IOX ID by Geotab, similar to each model of car having a model name. Integrators shall contact Geotab to get an IOX ID assigned. The IOX ID does not need to be included in the IOX Serial Number. Integrator shall report the IOX ID in byte 7 of the Poll Response (0x02).

Acknowledge Process

1. Each IOX should receive an ACK from the GO device for every message sent. If an ACK is not received within 100 ms, the IOX should repeat the message before sending anything else.
2. The first poll after reset allows up to 1 second for the acknowledge to come in before repeating.
3. When a global message (addressed to 0x0000) requiring a response is received by an IOX, the IOX should respond with a delay of up to 70 ms in order to prevent all IOXs from trying to respond at the same time. This delay should be random and the seed for the randomizer must be based on the IOX's Serial Number.

Polling

After powering up, the GO device will poll all IOXs every 7 seconds. Each IOX must respond to this poll by obeying the ACK rules.

Device Removed

If the GO device fails to see an IOX that used to be connected (i.e. the IOX was disconnected), the GO device will remove the IOX from its internal database after 5 attempts (35 seconds) and will make the slot available for a new IOX that can be connected at any time.

New Device

Any IOX that is connected to the GO device must respond to the poll request. The GO device will notice the new IOXs and add them to its internal database.

Undocumented messages

An IOX could receive messages from the GO device that are not documented here. The IOX must be capable of handling this situation by ignoring/discarding the unknown messages.

Waking up the GO Device

Every 1 second, the GO wakes up for 2ms to look for CAN activity on the IOX bus. The IOX can wake up the GO by sending an RX Data (0x0C) message every 1ms until the GO notices the activity and sends the Wakeup (0x04) message to the IOX.

Commands

Reset (0x00)

Directed to all devices. Instructs all devices to reset and behave as if they have just powered up. IOXs should throw out any setup information they might have received, de-assert hardware control lines, and open their relays.

Poll (0x01)

Sent by the GO device in a broadcast fashion to all units to check if they are there.

Poll Response (0x02)

Sent by an IOX when a poll is received. The ACK procedure must be obeyed. The first poll-response after power up (when Byte 0 Bit 0 is 1) contains all 8 bytes. All subsequent poll-responses (when Byte 0 Bit 0 is 0) only contain the first byte.

Payload — Poll Response

When the "Go to Sleep" command is received, and before actually going to sleep, the devices will indicate they are going to sleep through the indicated bit. This bit is cleared on wakeup.

Additional Info (0x03)

Sent by the IOX after an ACK for the first poll is received. This message is not strictly required for operation. However, sending of this message is required if any version information is to be reported, including: Product, Hardware, Firmware Major, Firmware Minor, or Version Control.

Payload — Additional Info

Wakeup (0x04)

Wakes up all the IOXs from Sleep Mode. Will be sent by the GO at least twice within a space of 10 ms.

Sleep (0x05)

Causes all IOXs to go into Sleep Mode. Devices will enter Sleep Mode no sooner than 2 seconds, and not more than 20 seconds, after receiving this command. In the meantime, they will report through the poll response that they are going to sleep.

TX Data (0x0B)

Data sent from the GO device to the addressed IOX.

Payload — TX Data

RX Data (0x0C)

Data sent from an IOX to the GO device. The GO will reply with an ACK. The 0x0C message series start with a Information Type 1 - Packet Wrapper 0x25 message, and also ends with one.

Payload — RX Data

Acknowledge (0x14)

Sent by the GO to indicate that a message is being acknowledged. The ACK to an Rx Data message (0x0C) could include 1 byte of data. This data is used for streaming flow control. When the 80% watermark of the receive buffer has been reached, the flow control bit will tell the IOX to hold off sending for 50ms. The IOX will send the next frame at the end of this period and depending on the flow control bit of the ACK, it will either keep on sending or delay another 50ms, thus repeating the process. The GO device will clear the flow control bit whenever the buffer is below the 20% watermark. If transferring data as part of a wrapped packet exchange the streaming watermark can be ignored. The buffers will not overflow so long as the length limit and the modem result are honored. This byte is only sent when needed.

Payload

Application Specific Data (0x1C)

Sent by the GO device after a packet wrapped passthrough message attempt to the server. A ‘rejected’ response from the modem typically means it is not connected. If the message is ‘accepted’ this means it was added to the modem’s TCP socket buffer. It is not a confirmation the message was successfully sent.

Type 0: Modem Transmission Result

IOX Single Frame Log Data (0x1D)

Sent from the IOX to the GO device when the IOX wants to create a log that can fit into a single CAN frame.

Payload

Log Type: 0 (GenericDataRecord)

Log Type: 3 (PriorityDataRecord)

Log Type: 1 (externalDeviceConnectionStatus)

Log Type: 2 (GenericFaultRecord)

IOX Multi-Frame Log Data (0x1E)

Sent from the IOX to the GO device when the IOX wants create a log that cannot fit into a single CAN frame. The first frame contains the Type and Length. All frames start with a Frame Counter that is an incrementing sequence number. The first frame always starts with 0x00.

Payload First Frame

Payload Subsequent Frames

Log Types

IOX Request/Status (0x25)

Sent from the IOX to the GO device to inform the GO device of events or status changes.

Payload

Information Type 0 — Busy

Information Type 1 - Packet Wrapper

Note: A message of this type is to be added before the start of a 0x0C message series, and also after the end of it.

Information Type 2 - Request GO Device Data Message

Information Type 3 - Connect and Send Records

Information Type 4 - Request VIN Message

Information Type 12 - Request Identificaiton of Go device, versions

Supported from protocol version 1.1.

GO Status Information (0x26)

Sent from the GO to the IOX to pass information the IOX may need.

Payload

Information Type 0 - Ignition

GO Multi-Frame Data (0x27)

Sent from the GO to the IOX when the GO wants to transfer data that can not fit into a single CAN frame. The first frame contains the Type and Length. All frames start with a Frame Counter that is an incrementing sequence number. The first frame always starts with 0x00.

Payload First Frame

Payload Subsequent Frames

Log Types

Type 12 Go info

Supported from protocol version 1.1.

payload id = 0

payload id = 1

payload id = 2