Add-On Protocol - CAN

External devices can communicate with the Geotab GO device through the revised Third-Party Data CAN protocol. The hardware interface will be the IOX-CAN. Two-way communication is supported, allowing a MyGeotab API call to produce messages on the connected CAN network using the IOX-CAN. An initial handshake is required before messages can be produced using the IOX-CAN.

The GO device will start processing third-party data if it is properly formatted. Once processed, the third-party data will be saved and sent to MyGeotab as Status Data.

Integration Process

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

1 - Request External Device ID

Contact Geotab Solution Engineering team to obtain an External Device ID for your third-party device. This will allow us to uniquely identify your device when it connects to a GO device. Thereafter, any connection established by that type of external device will be recorded as Status Data in MyGeotab under the naming format "[External device name] device connected".

2 - Request 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.

3 - Implement the Third-Party CAN Protocol

Implement the Third-Party CAN Protocol in the external device as described below. The CAN speed to be used will be 250K or 500K, and the external device should have its CAN transceiver set to normal mode. The IOX CAN will auto-baud between 250K and 500K.

CAN ID

The CAN ID is an extended frame message (29-bit) and is broken down into 4 bytes, with the most significant byte (MSB) (byte 1) containing 5 bits to make up the 29-bit ID header. A breakdown of the CAN ID is shown below:

Data Length (DLC)

Indicates how many bytes of data are being sent (up to a maximum of 8).

Data

All values must be sent with the least significant byte first.

Each piece of information related to the third-party device must be sent individually and have its own Status Data ID as part of the message.

Note: See Appendix A for an example of raw message data.

Handshake

An initial Handshake is required in order for the GO device to accept MyGeotab API calls to produce CAN messages from the IOX-CAN. Vehicle ignition must be on during the handshake process.

1. After powering up, the GO device will enter an external device detection cycle. The GO device will listen for a Msg Type 0x81 from the external device. This message is used to indicate that an external device is present.
   • The external device must send this message once per second.
2. The GO device will reply with a Msg Type 0x02 to acknowledge it has received the external device ID. After detecting this response, the external device may stop broadcasting Msg Type 0x81.
3. The MyAdmin API can now be used to produce CAN messages from the IOX-CAN as described in Messages from MyGeotab

Messages from GO device

Msg Type 0x02: Third-Party Data Acknowledge

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

Messages from External Device

Msg Type 0x81: Third-Party Device ID

Issued by the external device upon powerup once every second until an Acknowledge message (Msg Type 0x02) is received.

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

Issued by the external device whenever it wants Third-Party Data saved on the GO device. 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

Currently not implemented.

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 the 0x80 Status Data message. It will also be logged using an Iridium modem connection, if available.

Messages from MyGeotab

A handshake must be completed before this functionality will work. To send messages from MyGeotab to the external device, download the source code of the Starter Kit sample, and replace the Sample API with the following script. The alternative is to paste the script in the Runner.

    api.call("Add", {
                "typeName": "TextMessage",
                "entity": {
                  "isDirectionToVehicle": true,
                  "activeFrom": "1986-01-01T00:00:00.000Z",
                  "activeTo": "2050-01-01T00:00:00.000Z",
                  "messageContent": {
                    "contentType": "CAN",  
                    "channel": 1,                   //Taken from Get<IoxAddOn> call
                    "arbitrationId":  217055107,    //Fixed value do not change
                    "isAcknowledgeRequired": true,
                    "extendedFrameFlag": true,
                    "data": base64_encoded_byte     //Replace with your data encoded in base64
                  },
                  "device": {
                    "id": device.id                 //Replace with device id of interest
                  }
                }
              }, function(result) {
                  console.log("Done: ", result);
              }, function(e) {
                  console.error("Failed:", e);
              });

Appendix

Appendix A: Raw Message Data Example for IOX-CAN

Third-Party Device ID from external device (4208 is a test Device ID).

(Device ID: 4208 = 0x1070)

CAN ID: 0x000FDB81

DLC: 02

Data: 0x70, 0x10

Third-Party Device ID Acknowledge from GO device

CAN ID: 0x000FDB02

DLC: 01

Data: 0x81

…

Third-Party Data from External Device

(Status Data ID: 9999 = 0x270F, Data Value: 230 = 0x000000E6)

CAN ID: 0x000FDB80

DLC: 06

Data: 0x0F, 0x27, 0xE6, 0x00, 0x00, 0x00

Third-Party Data Acknowledge from GO device

CAN ID: 0x000FDB02

DLC: 01

Data: 0x80