Edit on GitHub Ask developers in the Community

Add-On Protocol - RS232 & USB

External devices can communicate with the Geotab GO device through the Third-Party RS232 and USB protocol 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 will be one of the following:

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 will improve 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, this 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 follow up 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. Ignition must be on for 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 will contain 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 pseudo code:

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 first.

Messages from the GO device

Msg Type 0x01: Handshake Request

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

 BytesPosition
STX (0x02)10
Message Type = 0x0111
Message Body Length = 012
Checksum23
ETX (0x03)15
Reply: Handshake Confirmation (Msg Type 0x81)  

Msg Type 0x02: Third-Party Data Acknowledge

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

 BytesPosition
STX (0x02)10
Message Type = 0x0211
Message Body Length = 012
Checksum23
ETX (0x03)15

Msg Type 0x21: GO Device Data

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

  • An Enhanced HOS Device must ACK this message with a 0x84 message.
  • If the data is requested periodically using the 0x85 message, the ACK is optional.
 BytesPosition
STX (0x02)10
Message Type = 0x2111
Message Body Length >= 52 [1]12
Date / Time [2]43
Latitude47
Longitude411
Road Speed [3]115
RPM216
Odometer [4]418
Status Flags (from LSB):
1st bit: 1 = GPS Valid
2nd bit: 1 = Ignition On
3rd bit: 1 = Engine Bus Activity
4th bit: 1 = Date/Time Valid
5th bit: 1 = Speed From Engine
6th bit: 1 = Odometer From Engine
122
Trip Odometer [4]423
Total Engine Hours427
Trip Duration [5]431
GO Device ID [6]435
Driver ID [7]439
GO Device Serial Number1243
Checksum2Length + 3
ETX (0x03)1Length + 5
Reply: Device Data Ack (Msg Type 0x84)  
  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. GO Device ID is a legacy field. It will contain invalid values by April 15, 2021.
  7. Driver ID only available when using the IOX-NFC.

Conversions

DataConversionUnits
Engine Road Speed1km/h
Odometer0.1km
RPM0.25RPM
Lat/Long1e-7degrees
Engine Hours0.1h
Trip Duration1s

Msg Type 0x22: Binary Data Response

Issued by the GO device on successful/unsuccessful transmission of Binary Data (via Msg Type 0x86) to the server.

 BytesPosition
STX (0x02)10
Message Type = 0x2211
Message Body Length = 412
Binary data transmission success
0 = transmission failure
1 = transmission success
13
Reserved34
Checksum27
ETX (0x03)19

Msg Type 0x23: Binary Data Packet

Issued by the GO device on receipt of Binary Data from the server 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 the server.

 BytesPosition
STX (0x02)10
Message Type = 0x2311
Message Body Length = x (0 - 249)12
Binary Datax3
Checksum23+x
ETX (0x03)15+x

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

Sent by the GO device to the external device. Send data as multi-frame data to iox. Once iox recieved the data, it will foward data to external device. Currently only used for carshare.

 BytesPosition
STX (0x02)10
Message Type = 0x2411
Message Body Length = x (0 - 119)12
Extended_binary_datax3
Checksum23+x
ETX (0x03)15+x

Msg Type 0x25: Extended binary data packet

Issued by the GO device on receipt of Binary Data of 256 bytes or more from the server 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 the server.

 BytesPosition
STX (0x02)10
Message Type = 0x2511
Message Body Length = x (256 - 1023)12
Extended_binary_datax3
Checksum23+x
ETX (0x03)15+x

Msg Type 0x26: Protobuf data packet

Available with add-on protocol version >= 1.2. Issued by the GO device in response to Msg Type 0x8C. Also issued by the GO device to publish information for the topics (defined in Appendix D) subscribed by the third party device. The information includes a payload containing data encoded in the protobuf format.

 BytesPosition
STX (0x02)10
Message Type = 0x2611
Message Body Length = x (1 - 255)12
Data Payload Protobuf (1-255)x3
Checksum23+x
ETX (0x03)15+x

The payload of the protobuf data needs to adhere to protocols understood by the Geotab servers. Please see Appendix D for the payload details.

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

Issued by the GO device on receipt of 0x8B.Should be paired with 0x8B. 0x27 is a reply to 0x8B. Sent by the GO to an external device as a reply to the Add-On protocol version request. The protocol version sent includes the Major and Minor version numbers.

 BytesPosition
STX (0x02)10
Message Type = 0x2711
Message Body Length = 412
Protocol major version23
Protocol minor version25
Checksum27
ETX (0x03)19

Messages from External Device

Handshake Sync (Auto-BAUD detect for RS232)

Issued by External Device every second until the Handshake Request is received.

 BytesPosition
Sync Char (0x55)10
Reply: Handshake Request (Msg Type 0x01)  

Msg Type 0x81: Handshake Confirmation

Issued by the External Device when it receives the Handshake Request.

 BytesPosition
STX (0x02)10
Message Type = 0x8111
Message Body Length = 412
External Device ID (assigned by Geotab)23
Flags
1st bit: Handshake Confirmation ACK
2nd bit: Binary Data Packet Wrapping
All other bits:Reserved for future implementation, must be set to 0
25
Checksum27
ETX (0x03)19

Handshake Confirmation ACK:

  • 0: No Ack to Handshake Confirmation message will be sent by the GO device.
  • 1: The Handshake Confirmation is to be ACKed 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.

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.

 BytesPosition
STX (0x02)10
Message Type = 0x8011
Message Body Length = 612
Data ID (assigned by Geotab)23
Data45
Checksum29
ETX (0x03)111
Reply: Third-Party Data Ack (Msg Type 0x02)  

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 into 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.

 BytesPosition
STX (0x02)10
Message Type = 0x8211
Message Body Length = x (1 to 27)12
Datax3
Checksum23 + x
ETX (0x03)15 + x
Reply: Third-Party Data Ack (Msg Type 0x02)  

Msg Type 0x84: Device Data ACK

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

 BytesPosition
STX (0x02)10
Message Type = 0x8411
Message Body Length = 012
Checksum23
ETX (0x03)15

For the purpose of acknowledging the GO Device Data message when connected as an Enhanced HOS Device:

  • The GO device will keep streaming the GO Device Data messages even if no ACK is received for up to 30 seconds.
  • 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 will be 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 (Msg Type 0x21).

 BytesPosition
STX (0x02)10
Message Type = 0x8511
Message Body Length = 012
Checksum23
ETX (0x03)15
Reply: GO Device Data (Msg Type 0x21)  

Msg Type 0x86: Binary Data Packet

Sent by the external device when sending binary data directly to the server. The contents of the message will be ignored by the GO device and simply sent on to the server for processing. The GO device will respond with the Binary Data Response message indicating whether the data was successfully sent via the modem.

 BytesPosition
STX (0x02)10
Message Type = 0x8611
Message Body Length = x (0 - 250)12
Binary Datax3
Checksum23+x
ETX (0x03)15+x
Reply: Binary Data Response (Msg Type 0x22)  

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

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

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

 BytesPosition
STX (0x02)10
Message Type = 0x8711
Message Body Length = 612
Data ID (assigned by Geotab)23
Data45
Checksum29
ETX (0x03)111
Reply: Third-Party Data Ack (Msg Type 0x02)  

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 that is looking for these messages. Currently only used for carshare.

 BytesPosition     
STX (0x02)10     
Message Type = 0x8811     
Message Body Length = x (1 to 1024)12     
extended_binary_data (message_body) =0123x-1(data content could be from 0 to 0xff)
Checksum23+x     
ETX (0x03)15+x     
Reply: Binary Data Response (Msg Type 0x22)       

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).

 BytesPosition
STX (0x02)10
Message Type = 0x8911
Message Body Length = 012
Checksum23
ETX (0x03)15
Reply: Third-Party Data Ack (Msg Type 0x02)  

Msg Type 0x8B: Add-On protocol version request

Sent by the external device when requesting the add on protocol version number. Once the GO receives this request it will reply with 0x27.

 BytesPosition
STX (0x02)10
Message Type = 0x8B11
Message Body Length = 012
Checksum23
ETX (0x03)15
Reply: Third-Party version Ack Reply (Msg Type 0x27)  

Msg Type 0x8C: Protobuf data packet

Available with add-on protocol version >= 1.2. Sent by the external device to subscribe to various topics/information. The GO device will respond with 0x26 ACK. The topics that the third party is interested in are requested in the form of a payload data encoded using protobuf format.

 BytesPosition
STX (0x02)10
Message Type = 0x8C11
Message Body Length = x(1-255)12
Data Payload Protobuf (message_body) = x (1 to 255)x3
Checksum23 + x
ETX (0x03)15 + x
Reply: Protobuf data packet (Msg Type 0x26)  

The payload of the protobuf data needs to adhere to protocols understood by the Geotab servers. Please see Appendix D for the payload details.

Messages from MyGeotab

To send messages from MyGeotab to the external device, please download the source code of the Starter Kit sample, and replace the Sample API with the following script. The alternative is paste the script in the Runner.

    api.call("Add", {
            "typeName": "TextMessage",
            "entity": {
              "user": {
                "id": user.id               //Replace with user id of interest
              },
              "device": {
                "id": device.id             //Replace with device id of interest
              },
              "messageContent": {
                "contentType": "SerialIox",
                "channel": 1,               //Taken from Get<IoxAddOn> call
                "data": base64_encoded_byte //Replace with your data encoded in base64
              },
              "isDirectionToVehicle": true
            }
          }, function(result) {
              console.log("Done: ", result);
          }, function(e) {
              console.error("Failed:", e);
          });)

To send MIME messages from MyGeotab to the external device, please use the following script instead:

    api.call("Add", {
    "typeName": "TextMessage",
    "entity":{
        "user":{"id":user.id},                    //Replace with user id of interest
        "device":{"id":device.id},                //Replace with device id of interest
        "messageContent":{
            "contentType":"MimeContent",
            "channelNumber":1,
            "mimeType":"text",                    //Can be changed to any free format text value
			      "binaryDataPacketDelay":"00:00:03.0000000", //applies a 
            //configurable delay of up to 5 seconds in between each sequenced message
            // of a multimessage MIME payload
            "data":base64_encoded_byte //Replace with your data encoded in base64
        },
        "isDirectionToVehicle":true},
      }, function(result) {
          console.log("Done: ", result);
      }, function(e) {
          console.error("Failed:", e);
      });

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. Readers are encouraged to read the Geotab MIME Data Exchange Example IOX-RS232 to better understand the subsequent protocol. 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 to the GO device.

MIME-type data will be saved as a MIME-type blob on the server. The blob can be accessed through the software SDK as a TextMessage. The SDK can also be used to send MIME-type data from the server to an external device connected to a GO device.

The MIME Type Protocol:

 BytesPosition
MIME type length = x10
MIME type in ASCIIx1
Payload Length = y41 + x
Binary Payloady5 + x

The MIME protocol will be an inner protocol within the binary data packet messages. The MIME data will be broken into 250 byte chunks and sent within binary data packet messages. The first byte within the message will be a sequence counter; all remaining bytes will contain the MIME data.

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.

First packet:

 BytesPosition
STX (0x02)10
Message Type = 0x8611
Message Body Length = 25012
Sequence number = 013
MIME type length = 1014
MIME type (“image/jpeg”)105
Payload Length = 83000415
Binary Payload (the first 234 bytes)23419
Checksum2253
ETX (0x03)1255

Second packet:

 BytesPosition
STX (0x02)10
Message Type = 0x8611
Message Body Length = 25012
Sequence number = 1*13
Binary Payload (the next 249 bytes)2494
Checksum2253
ETX (0x03)1255

* If the sequence number reaches 255 (0xFF) and more packets need to be sent, the sequence number must reset to a value of 1 and continue counting. A sequence number of 0 must only be used for the first packet.

Binary Data Packet Containing MIME Type Acknowledge

 BytesPosition
STX (0x02)10
Message Type = 0x2311
Message Body Length = 9+x12
Sequence Number = 013
MIME type length = 314
MIME type in ASCII = ‘ACK’35
Payload Length = x48
Total Number of Payload Bytes Receivedx12
Checksum212+x
ETX (0x03)114+x

Appendix D: Using protobuf Messages to Communicate by using 0x8C, 0x26

Top

PUB/Sub Protocol Documentation

Introduction

This Proto file defines message payloads for the Third party Message Type 0x8C (Protobuf Data Packet from IOX to GO) and Message Type 0x26 (Protobuf Data Packet from GO to IOX). The protobufs defined here follows a simple pub/sub protocol, where a third party IOX device can subscribe to one of the supported TOPICs (enum Topic) and receive the desired information from the GO. The appropriate master switch needs to be set to use the pub/sub functionality correctly.

The list of some of the (unordered) messages and their use is as mentioned below.

  1. To get a list of all the subscribable topics: The external device needs to send an IoxToGo message with the pub_sub.list_avail_topics field set. The GO device responds with an IoxFromGo message with the pub_sub.topic_info_list field.

  2. To subscribe to a topic: The external device needs to send an IoxToGo message with the pub_sub.sub field set. The Go device responds with an IoxFromGo message with the pub_sub.sub_ack.result field containing ‘SUB_ACK_RESULT_SUCCESS’.

  3. To get a list of subscribed topics: The external device needs to send a IoxToGo message with the pub_sub.msg.list_subs field set. The GO device responds with an IoxFromGo message with the pub_sub.topic_list field.

  4. How the external device gets published information for subscribed topics: When there is an update to a subscribed topic, the GO device sends the update in an IoxFromGo message with the pub_sub.pub field set.

  5. To remove a topic from the subscription: The external device needs to send a IoxToGo message with the pub_sub.msg.unsub field set. The Go device responds with an IoxFromGo message with the pub_sub.sub_ack.result field containing a ‘SUB_ACK_RESULT_SUCCESS’.

  6. To clear the entire subscription list: The external device needs to send a IoxToGo message with the pub_sub.msg.clear_subs field set. The Go device responds with an IoxFromGo message with the pub_sub.clear_subs_ack.result field containing a ‘CLEAR_SUBS_ACK_RESULT_SUCCESS’.

Note: The a ‘PubSubFromGo’ message with the ‘sub_ack’ or the ‘clear_subs_ack’ field can contain the source of error when a request cannot be performed successfully.

Note: The subscription is cleared if the GO or the IOX lost power or if the IOX is disconnected from the GO device.

Note, If the master switch is not enabled: - An IOX will not able to subscribe any topic. - The list of subscribable topics will be empty.

Example Message from IOX to GO:

  • 0x8C is a message type sent from an external device to GO, to either subscribe or to get a list of topics or to get a list of subscribed topics etc.
  • The payload of the 0x8C message is the Pub/Sub message, encoded with Protobuf using nanopb.
  • An example usage of the 0x8C message to subscribe to one of the topics like TOPIC_ACCEL is as described below.
    • 0x8C fields values:
      STX=0x02, MessageId = 0x8C, Data payload: Protobuf encoding for message IoxToGo (detailed below), ETX=0x03
      IoxToGo message = { 
          .which_msg = IoxToGo_pub_sub_tag, 
          .pub_sub = { .which_msg = PubSubToGo_sub_tag, .sub = { .topic = TOPIC_ACCEL }}
      };
      IoxToGo message = { .which_msg = 0x01, .pub_sub = { .which_msg = 0x01, .sub = { .topic = 0x01 }}};
      
    • So, IoxToGo message, i.e. Data Payload, after Protobuf encoding: {0x0A 0x04 0x0A 0x02 0x08 0x01}
    • This leads to, IoxToGo message length after Protobuf encoding to be 0x06.
    • Checksum calculation from (0x02 0x8C 0x06, 0x0A 0x04 0x0A 0x02 0x08 0x01) = (0xB7 0x28)
    • The result Data Payload = (0x06 0x0A 0x04 0x0A 0x02 0x08 0x01 0xB7 0x28)

    • The final byte stream that the external device would send to GO, in order to subscribe for the TOPIC_ACCEL should be:
      <0x02 0x8C 0x06 0x0A 0x04 0x0A 0x02 0x08 0x01 0xB7 0x28 0x03>

Example Response/Event from GO to IOX:

  • 0x26 is a message type sent from GO to an external device, to either acknowledge a subscription request or other request sent from the external device.
  • An example usage of the 0x26 message is to acknowledge a request to subscribe to a topic such as TOPIC_ACCEL, the message is described as below.
    • The external device will receive a 0x26 message from the GO device such as:
      (0x02 0x26 0x08 0x0A 0x06 0x0A 0x04 0x08 0x01 0x10 0x01 0x68 0xE8 0x03)
    • The extracted IoxFromGo message with Protobuf encoding = (0x0A 0x06 0x0A 0x04 0x08 0x01 0x10 0x01)

    • The IoxFromGo message after decoding =
      {
          .which_msg = 0x01, 
          .pub_sub = {
              .which_msg = 0x01, 
              .suback = { .result = 0x01, .topic = 0x01 }
          }
      }
      
    • The IoxFromGo message can be interpreted as
      { 
          .which_msg = IoxFromGo_pub_sub_tag, 
          .pub_sub = {
              .which_msg = PubSubFromGo_sub_ack_tag, 
              .suback = { .result = SubAck_SUB_ACK_RESULT_SUCCESS, .topic = TOPIC_ACCEL }
          }
      } 
      

Topic

The ID of all the subscribable topics. @exclude Includes status data IDs @exclude The comment is CSV format: 1st field is the type, 2nd field is the unit, 3rd field is the extra information (if any).

NameNumberDescription
TOPIC_UNSPECIFIED0Invalid topic,, (DO NOT USE)
TOPIC_ACCEL1Vec3, m/s^2, To be implemented
TOPIC_GPS2Gps, Lat/Long: degrees. speed: km/h, To be implemented
TOPIC_BATTERY_VOLTAGE3float, Volt, To be implemented
TOPIC_VIN4String, Unitless
TOPIC_GEAR532 bit signed int, Unitless, 1=Reverse. 0=Neutral. 1 to 8:Nth gear. 126=Park. 127=Drive. 129=Intermediate. 130=Unknown.
TOPIC_ENGINE_SPEED632 bit float, RPM
TOPIC_ENGINE_LOAD732 bit float, %
TOPIC_ODOMETER832 bit float, km
TOPIC_ACCEL_PEDAL_PERCENTAGE932 bit float, %
TOPIC_COOLANT_TEMP1032 bit float, degC
TOPIC_DOC_INTAKE_GAS_TEMP1132 bit float, degC
TOPIC_DOC_OUTLET_GAS_TEMP1232 bit float, degC
TOPIC_FUELTANK1_UNITS1332 bit float, Litres
TOPIC_FUELTANK2_UNITS1432 bit float, Litres
TOPIC_FUELTANK1_PERCENT1532 bit float, %
TOPIC_FUELTANK2_PERCENT1632 bit float, %
TOPIC_STATE_OF_CHARGE1732 bit float, %
TOPIC_ENGINE_ROAD_SPEED1832 bit float, km/h
TOPIC_VEHICLE_ACTIVE1932 bit signed int, Unitless, 0=Ignition Off. 1=Ignition On.
TOPIC_DRIVER_SEATBELT2032 bit signed int, Unitless, 0=Buckled. 1=Unbuckled.
TOPIC_LEFT_TURN_SIGNAL2132 bit signed int, Unitless, 0=Off. 1=On
TOPIC_RIGHT_TURN_SIGNAL2232 bit signed int, Unitless, 0=Off. 1=On
TOPIC_EV_CHARGING_STATE2332 bit signed int, Unitless, 0=Not Charging. 1=AC charging. 2=DC charging.
TOPIC_PARK_BRAKE2432 bit signed int, Unitless, 0=Off. 1=On. 2=Error.

ClearSubsAck

GO to IOX: 3rd level of an IoxFromGo message. This is a response to a Clear subscription request.

FieldTypeLabelDescription
resultClearSubsAck.Result This is the result of a Clear subscription request.

Gps

GO to IOX: This structure is used for publishing the output of the GPS.

FieldTypeLabelDescription
latitudefloat Latitude, in degrees (+ve = north, -ve = south)
longitudefloat Longitude, in degrees (+ve = east, -ve = west)
speedfloat Speed, in km/h
headingfloat Heading, in degrees
gps_timegoogle.protobuf.Timestamp Time the GPS data is sampled.

IoxFromGo

GO to IOX: Top level of a pub/sub message. An IoxFromGo message can only contain one PubSubFromGo message.

FieldTypeLabelDescription
pub_subPubSubFromGo  

IoxToGo

IOX to GO: Top level of a pub/sub message. An IoxToGo message can only contain one PubSubToGo message.

FieldTypeLabelDescription
pub_subPubSubToGo  

PubSubFromGo

GO to IOX: 2nd level of an IoxFromGo message. This level identifies the type of information/response.

FieldTypeLabelDescription
sub_ackSubAck Reply to sub and unsub, indicating success/failure
topic_listTopicList Reply to list_subs, containing all subscribed topics
topic_info_listTopicInfoList Reply to list_avail_topics, containing info on all supported topics
pubPublish Data sample published by the GO
clear_subs_ackClearSubsAck Reply to clear_subs, indicating success/failure

PubSubToGo

IOX to GO: 2nd level of an IoxToGo message. This level identifies the type of requests to the subscription.

FieldTypeLabelDescription
subSubscribe Subscribe request: Add a topic to the subscription.
unsubUnsubscribe Unsubscribe request: Remove the topic from the subscription.
list_subsgoogle.protobuf.Empty Subscribed list request: gps_time all subscribed topics.
clear_subsgoogle.protobuf.Empty Clear subscription request: Clear all the subscribed topics from the subscription.
list_avail_topicsgoogle.protobuf.Empty Subscribable list request: Get the list of all subscribable topics.

Publish

GO to IOX: 3nd level of an IoxFromGo message. The Go device sends this message for each subscribed topic when an update to the status of the topic is available.

FieldTypeLabelDescription
timegoogle.protobuf.Timestamp Time since 1970-01-01 00:00:00 UTC.
topicTopic ID of the subscribed topic this message contains.
bool_valuebool  
int_valueint32  
uint_valueuint32  
float_valuefloat  
string_valuestring Used for VIN (17 digits)
vec3_valueVec3 Used for acceleration
gps_valueGps Used for GPS output.

SubAck

GO to IOX: 3nd level of a IoxFromGo message. This structure contains a response to a Subscribe request or an Unsubscribe request.

FieldTypeLabelDescription
resultSubAck.Result The result of a subscribe request or an unsubscribe request.
topicTopic The topic specified in the request.

Subscribe

IOX to GO: 3rd level of an IoxToGo message. Subscribe request: An external device sends this message to subscribe an available topic.

FieldTypeLabelDescription
topicTopic ID of the topic the IOX wishes to subscribe.

TopicInfo

GO to IOX: This is part of the response to the Subscribable list request message. This structure contains the information of one subscribable topics.

FieldTypeLabelDescription
topicTopic  

TopicInfoList

GO to IOX: 3rd level of an IoxFromGo message. This is a response to the Subscribable list request message. This structure contains the information of all subscribable topics.

FieldTypeLabelDescription
topicsTopicInforepeatedarray of topic information, each from a subscribable topic.

TopicList

GO to IOX: 3rd level of an IoxFromGo message. This is a response to the Subscribed list request message. This structure provides the list of all the subscribed topics.

FieldTypeLabelDescription
topicsTopicrepeatedAn array of topics.
array of IDs, each from a subscribed topic.

Unsubscribe

IOX to GO: 3rd level of an IoxToGo message. Unsubscribe request: An external device sends this message to unsubscribe a topic.

FieldTypeLabelDescription
topicTopic ID of a subscribed topic, the IOX wishes to removed.

Vec3

GO to IOX: This structure is used for publishing the output of the accelerometer.

FieldTypeLabelDescription
xfloat Output of the X-axis.
yfloat Output of the Y-axis.
zfloat Output of the Z-axis.

ClearSubsAck.Result

Possible result of a Clear subscription request.

NameNumberDescription
CLEAR_SUBS_ACK_RESULT_UNSPECIFIED0Not used. ClearSubAck will never return a result = zero.
CLEAR_SUBS_ACK_RESULT_SUCCESS1Clear subscription succeeded
CLEAR_SUBS_ACK_RESULT_UNAVAILABLE2Clear subscription failed: The subscription is owned by another IOX.
CLEAR_SUBS_ACK_RESULT_DISABLED3Clear subscription failed: Pub/Sub is not enabled by Master Switch.

SubAck.Result

Possible result returned from a Subscribe request or an Unsubscribe request.

NameNumberDescription
SUB_ACK_RESULT_UNSPECIFIED0Not used; zero is never returned as a Result.
SUB_ACK_RESULT_SUCCESS1Subscription success
SUB_ACK_RESULT_FAILED2Generic subscription failure
SUB_ACK_RESULT_UNKNOWN_TOPIC3Subscribe fails if an unknown topic is specified
SUB_ACK_RESULT_TOPIC_ALREADY_SUBBED4Subscribe fails if the topic has already been subscribed to
SUB_ACK_RESULT_TOPIC_NOT_SUBBED5Unsubscribe fails if the topic has not been subscribed to
SUB_ACK_RESULT_UNAVAILABLE6Unsubscribe fails if the subscription belongs to another IOX.
SUB_ACK_RESULT_DISABLED7IOX Pub/Sub is not enabled by Master Switch.