Edit on GitHub Ask developers in the Community

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:

Bits28 to 2221 to 1615 to 0
ContentsReserved: 0Message: 0–63All IOXs: 0
Individual IOX Address ID: 1–65535

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

Byte #Byte Description
0 - Bit 00 = Have been polled before.
1 = First poll after power up.
0 - Bit 10 = Not Going to Sleep.
1 = Going to Sleep.
0 - Bit 20 = Normal reply.
1 = First poll response after wake up.
0 - Bit 3-7Reserved
 The following Bytes are sent only on first poll-response
1Firmware Version Major
2Firmware Version Minor
3-42 Most significant bytes of Serial Number
5Reset Reason
0 = Power On Reset
1 = Reset Command
2 = New Firmware
All others reserved.
6Reserved
7150 to 199
IOX ID. Please contact Geotab to get one assigned.

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

Byte #Byte Description
0-3Software Version Control Number(Ex: SVN Version, Git SHA)
4Product Version
5Reserved
6Error Condition
0 = No error
1 = Memory allocation error
7Hardware Version

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

Byte #Byte Description
0-7Data to transmit

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

Byte #Byte Description
0-7Received 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

Byte #Byte Description
0 - Bit 00 = Clear to send more Rx Data.
1 = Stop sending UART Data. Buffer 80% full, withhold next frame 50 ms.
1 - Bit 1-7Reserved

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

Byte #Byte Description
0Log Type
10 = Rejected.
1 = Accepted.

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

Byte #Byte Description
0Log Type
1-7Data

Log Type: 0 (GenericDataRecord)

Log Type: 3 (PriorityDataRecord)

DataDescription
1-2Data ID
3Length
4-7Data

Log Type: 1 (externalDeviceConnectionStatus)

DataDescription
1Connected = 1, Disconnected = 0
2-3Data ID
4-5Connection flags

Log Type: 2 (GenericFaultRecord)

DataDescription
1-2Fault code
3Active / Inactive
4Log Once Per Trip / Log Every Fault

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

Byte #Byte Description
0Frame Counter (0x00)
1Log Type
2-3Length
4-7Data

Payload Subsequent Frames

Byte #Byte Description
0Frame Counter
1-7Data

Log Types

Parameter TypeDescription
0Third Party Free Format 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
1Reserved
2Bluetooth Record. Rate limit is 1200 logs per 10 minutes. If you exceed the rate limit, the GO device will stop taking data from the IOX

IOX Request/Status (0x25)

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

Payload

Byte #Byte Description
0-1Information Type
2-7Optional bytes that depend on the type

Information Type 0 — Busy

Parameter TypeDescription
0-10x0000
20 = Not busy
1 = 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.

Parameter TypeDescription
0-10x0001
20 = Beginning of data packet
1 = End of data packet

Information Type 2 - Request GO Device Data Message

Parameter TypeDescription
0-10x0002
2Message Version (1 or 2)

Information Type 3 - Connect and Send Records

Parameter TypeDescription
0-10x0003
2Unused

Information Type 4 - Request VIN Message

Parameter TypeDescription
0-10x0004
2Unused

Information Type 12 - Request Identificaiton of Go device, versions

Supported from protocol version 1.1.

Parameter TypeDescription
0-10x000C
2Request info:
0 = GO serial number
1 = GO firmware version
2 = IOX protocol version

GO Status Information (0x26)

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

Payload

Byte #Byte Description
0-1Information Type
2-7Optional bytes that depend on the type

Information Type 0 - Ignition

Parameter TypeDescription
0-10x0000
20 = Ignition Off
1 = Ignition On

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

Byte #Byte Description
0Frame Counter (0x00)
1Log Type
2-3Length
4-7Data

Payload Subsequent Frames

Byte #Byte Description
0Frame Counter
1-7Data

Log Types

Parameter TypeDescription
0Reserved
1Reserved
2GO device status packet
3VIN
12GO info

Type 12 Go info

Supported from protocol version 1.1.

payload id = 0
ByteByte Description
0=0 for payload is GO serial number.
1-12GO serial number
130
payload id = 1
ByteByte Description
0=1 for payload is GO firmware version number.
1-2GO firmware version: Product
3-4GO firmware version: Major
5-6GO firmware version: Minor
payload id = 2
ByteByte Description
0=2 for payload is IOX protocol version number.
1-2GO firmware version: Major
3-4GO firmware version: Minor