From 1e46b6574e2fcb73c27873d5158f390c2f51aee8 Mon Sep 17 00:00:00 2001 From: fmgeotab Date: Wed, 1 Nov 2023 13:14:33 -0700 Subject: [PATCH 1/2] Update protocol.md Technical writing review of content --- src/hardware/developing-an-iox/protocol.md | 70 +++++++++++----------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/src/hardware/developing-an-iox/protocol.md b/src/hardware/developing-an-iox/protocol.md index 9841a2b9d..e370f85c9 100644 --- a/src/hardware/developing-an-iox/protocol.md +++ b/src/hardware/developing-an-iox/protocol.md @@ -6,22 +6,22 @@ title: 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](https://docs.google.com/document/d/1BExcPst5bNzv-IZGX6ZbPeHK5MO1s2AI0rqzEhHbNZ4/edit?usp=sharing) as they read through the rest of this page. +The GO device and Input-Output Expanders (IOX) are connected in a dedicated CAN network. All communication is between the GO device and any connected IOXs - in particular, IOXs do not communicate with other IOXs. The following communication scenarios exist: GO device to all connected IOXs; GO device to an individual IOX; and an individual IOX to GO device. Readers are encouraged to look at examples from [CAN IOX Sample Communication Session](https://docs.google.com/document/d/1BExcPst5bNzv-IZGX6ZbPeHK5MO1s2AI0rqzEhHbNZ4/edit?usp=sharing) as they read through the rest of this page. ### Identification This document describes the IOX Expander Protocol version 1.2. -All messages are supported since IOX Expander Protocol version 1.0 unless stated otherwise. +All messages since IOX Expander Protocol version 1.0 are supported, 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. +Third-party IOX Add-ons rely on the messages and protocols defined in this document 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 protocols which can 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 practical given 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]({{site.baseurl}}/hardware/developing-an-iox/mime-protocol/). ### 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. +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 are reported in bytes 3 and 4 of the Poll Response (0x02). The 2 Least Significant Bytes are used to differentiate each IOX connected to 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 are 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. @@ -53,20 +53,20 @@ The GO device sends messages with ID 0x0000 meant for all IOXs, or with an ID be 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). +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. Integrators 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 150 ms, the IOX should repeat the message before sending anything else. -2. The IOX must respond to the poll request within 500ms. +2. The IOX must respond to the poll request within 500 ms. ## 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. Unless otherwise described, most commands can only be sent after the first poll (handshake) is completed with the GO. +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. Unless otherwise described, most commands can only be sent after the first poll (handshake) is completed with the GO device. ### 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. +If the GO device fails to detect an IOX that used to be connected (that is, 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 @@ -77,14 +77,14 @@ Any IOX that is connected to the GO device must respond to the poll request. The 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)](#rx-data-0x0c) message every 1ms until the GO notices the activity and sends the [Wakeup (0x04)](#wakeup-0x04) message to the IOX. +Every 1 second, the GO wakes up for 2 ms to look for CAN activity on the IOX bus. The IOX can wake up the GO by sending an [RX Data (0x0C)](#rx-data-0x0c) message every 1 ms until the GO device notices the activity and sends the [Wakeup (0x04)](#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. +Directed to all devices. Instructs all devices to reset and behave as if they have just powered up. IOXs should discard any setup information they might have received, de-assert hardware control lines, and open their relays. ### Poll (0x01) @@ -92,7 +92,7 @@ Sent by the GO device in a broadcast fashion to all units to check if they are t ### 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. +Sent by an IOX when a poll is received. The ACK procedure must be obeyed. The first poll response after powerup (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 @@ -110,7 +110,7 @@ Sent by an IOX when a poll is received. The ACK procedure must be obeyed. The fi | 6 | Reserved | | 7 | 150 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. +When the "Go to Sleep" command is received, but 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) @@ -128,7 +128,7 @@ Sent by the IOX after an ACK for the first poll is received. This message is not ### Wakeup (0x04) -Wakes up all the IOXs from Sleep Mode. Will be sent by the GO at least twice within a space of 50 ms. Currently the GO device sends this message 5 times with 10ms between. +Wakes up all the IOXs from Sleep Mode. Is sent by the GO at least twice within a space of 50 ms. Currently the GO device sends this message 5 times with 10 ms intervals. ### Sleep (0x05) @@ -147,7 +147,7 @@ Data sent from the GO device to the addressed IOX. The contents of this payload ### RX Data (0x0C) Data sent from an IOX to the GO device. The GO will reply with an ACK. The contents of this payload may follow a higher level protocol structure such as [MIME]({{site.baseurl}}/hardware/developing-an-iox/mime-protocol/). -The 0x0C message series start with a Information Type 1 - Packet Wrapper [0x25 message](#iox-requeststatus-0x25), and also ends with one. +The 0x0C message series start and end with a Information Type 1 - Packet Wrapper [0x25 message](#iox-requeststatus-0x25). #### Payload — RX Data @@ -157,18 +157,18 @@ The 0x0C message series start with a Information Type 1 - Packet Wrapper [0x25 m ### 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. +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 50 ms. 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 continue sending or delay another 50 ms, 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 0 | 0 = Clear to send more Rx Data.
1 = Stop sending UART Data. Buffer 80% full, withhold next frame 50 ms. | +| 0 - Bit 0 | 0 = Clear to send more RX Data.
1 = Stop sending UART Data. Buffer 80% full, withhold next frame 50 ms. | | 1 - Bit 1-7 | Reserved | ### 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 that the message was successfully sent. +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 that the message was successfully sent. #### Type 0: Modem Transmission Result @@ -201,7 +201,7 @@ Used to request the GO log normal status data. #### Log Type: 3 (PriorityDataRecord) -Used to request the GO log status data and additionally send via Iridium if available. +Used to request the GO log status data and also send via Iridium, if available. | Data | Description | | --- | --- | @@ -318,7 +318,7 @@ Further details can be found here: [Add-On Protocol - BLE]({{site.baseurl}}/hard #### Type 11 Curve Logging -This message can be used to send the 4byte (int32_t) data that is curve logged by the GO. Additional information about curve logging can be found here: [Curve Logging](https://github.com/Geotab/curve) +This message can be used to send the 4-byte (int32_t) data that is curve logged by the GO. Additional information about curve logging can be found here: [Curve Logging](https://github.com/Geotab/curve) | Byte # | Curve Logging | | --- | --- | @@ -340,7 +340,7 @@ This message can be used to send the 4byte (int32_t) data that is curve logged b #### Type 12 Logging With Timestamp -This message can be used to send status data along with a provided timestamp. +This message can be used to send status data with a timestamp. Possible use cases: 1. Store data in the IOX while the GO device is asleep and send all data after waking up 2. Run the curve logging algorithm in the IOX and send those points to be transmitted to MyGeotab. @@ -358,7 +358,7 @@ Additional information about curve logging can be found here: [Curve Logging](ht Supported from Add-On protocol version 1.2. -This message allows an IOX to send a protobuf encoded payload to the GO. It supports a publish/subscribe model of vehicle status information. The GO responds with GO Multi-Frame Data (0x27) - Type 13. +This message allows an IOX to send a protobuf-encoded payload to the GO device. It supports a publish/subscribe model of vehicle status information. The GO device responds with GO Multi-Frame Data (0x27) - Type 13. [Protobuf Schema](https://github.com/Geotab/android-external-device-example/blob/master/app/src/main/proto/iox_messaging.proto). The currently supported topics are: | Topic | @@ -388,7 +388,7 @@ This message allows an IOX to send a protobuf encoded payload to the GO. It supp ### Buzzer Beep (0x24) -Sent from an IOX to the GO to request the buzzer beep with the given parameters. +Sent from an IOX to the GO device to request the buzzer beep with the given parameters. #### Payload @@ -412,7 +412,7 @@ Sent from the IOX to the GO device to inform the GO device of events or status c #### Information Type 0 — Busy -This message is used to inform the GO device that the issuing IOX is busy with some critical tasks and the GO should not enter the sleep state. The IOX should send this message again to release the GO when it has completed its critical tasks. +This message indicates to the GO device that the issuing IOX is busy with a critical task and that the GO should not enter the sleep state. The IOX should send this message again to release the GO device once it has completed its critical tasks. | Parameter Type | Description | | --- | --- | @@ -421,11 +421,11 @@ This message is used to inform the GO device that the issuing IOX is busy with s #### Information Type 1 - Packet Wrapper -This is used to send a packet of up to 1023 bytes of binary data through the GO to MyGeotab. +This is used to send a packet of up to 1023 bytes of binary data through the GO device to MyGeotab. -Usage: +Use cases: 1. Send Packet Wrapper - Beginning of data packet (0). -2. Multiple Rx Data (0x0C) messages until the entire bypass binary data is sent. Pay attention to the Acknowledge (0x14) message responded from GO if the GO Receive-Buffer is ready to accept the next Rx Data (0x0C) message. The streaming flow control bit in the ACK is not relevant for this type of exchange and can be ignored. +2. Multiple RX Data (0x0C) messages until the entire bypass binary data is sent. Pay attention to the Acknowledge (0x14) message responded from GO if the GO Receive-Buffer is ready to accept the next RX Data (0x0C) message. The streaming flow control bit in the ACK is not relevant for this type of exchange and can be ignored. 3. Send Packet Wrapper - End of data packet (1). 4. At the end, GO sends confirmation with a Application Specific Data (0x1C) Type 0 (Modem transmission result) message to indicate if the packet has been accepted within 6 seconds. @@ -436,7 +436,7 @@ Usage: #### Information Type 2 - Request GO Device Data Message -This message is used by an IOX which requires vehicle information from the GO device. This will cause GO to respond with GO Multi-Frame Data (0x27) - Type 2 message. +This message is used by an IOX which requires vehicle information from the GO device. The GO device responds with a GO Multi-Frame Data (0x27) - Type 2 message. | Parameter Type | Description | | --- | --- | @@ -445,7 +445,7 @@ This message is used by an IOX which requires vehicle information from the GO de #### Information Type 3 - Connect and Send Records -This message requests the GO modem initiate a connection to the server. +This message requests the GO modem initiate a connection to the server. | Parameter Type | Description | | --- | --- | @@ -454,7 +454,7 @@ This message requests the GO modem initiate a connection to the server. #### Information Type 4 - Request VIN Message -An IOX uses this message to request the vehicle VIN number from GO. The GO will respond with GO Multi-frame Data (0x27) - Type 3 message. +An IOX uses this message to request the vehicle's VIN from the GO device. The GO device responds with a GO Multi-frame Data (0x27) - Type 3 message. | Parameter Type | Description | | --- | --- | @@ -465,7 +465,7 @@ An IOX uses this message to request the vehicle VIN number from GO. The GO will Supported from protocol version 1.1. -Sent from the IOX to the GO requesting the identification information. The will respond with a GO Multi-Frame Data (0x27) - Type 12 message. +Sent from the IOX to the GO device requesting the identification information. The GO device responds with a GO Multi-Frame Data (0x27) - Type 12 message. | Parameter Type | Description | | --- | --- | @@ -475,7 +475,7 @@ Sent from the IOX to the GO requesting the identification information. The will ### GO Status Information (0x26) -Sent from the GO to the IOX to pass information the IOX may need. This is a broadcast message. It is sent once any corresponding information type changes. +Sent from the GO device to the IOX to pass information the IOX may need. This is a broadcast message. It is sent once any corresponding information type changes. #### Payload @@ -501,7 +501,7 @@ Sent from the GO to the IOX to pass information the IOX may need. This is a broa ### 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. +Sent from the GO device to the IOX when the GO device wants to transfer data that does 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 @@ -533,7 +533,7 @@ Sent from the GO to the IOX when the GO wants to transfer data that can not fit #### Type 2 GO Device Data -Sent in response to IOX Request(0x25) message with Type Request GO Device Data Message (0x02). +Sent in response to an IOX Request(0x25) message with a Type Request GO Device Data Message (0x02). | Bytes | GO Device Data | | --- | --- | @@ -553,7 +553,7 @@ Sent in response to IOX Request(0x25) message with Type Request GO Device Data M #### Type 3 VIN -Sent in response to IOX Request(0x25) message with Type Request VIN (0x04). +Sent in response to an IOX Request(0x25) message with Type Request VIN (0x04). | Bytes | GO Device Data | | --- | --- | @@ -593,7 +593,7 @@ Sent in response to IOX Request/Status (0x25) - Type 12. Supported from protocol version 1.2. -This message allows an GO to send a protobuf encoded payload to the IOX. It supports a publish/subscribe model of vehicle status information. It is a response to GO Multi-Frame Data (0x1E) - Type 13. +This message allows a GO device to send a protobuf-encoded payload to the IOX. It supports a publish/subscribe model of vehicle status information. It is a response to GO Multi-Frame Data (0x1E) - Type 13. [Protobuf Schema](https://github.com/Geotab/android-external-device-example/blob/master/app/src/main/proto/iox_messaging.proto). From 47790c06560a1811b5b26b89d6258f1cdf4ae8bf Mon Sep 17 00:00:00 2001 From: fmgeotab Date: Wed, 1 Nov 2023 14:03:30 -0700 Subject: [PATCH 2/2] Technical writing review General grammar/wording review of the public pages listed in TECHWRSD-882 --- src/hardware/addon-protocols/ble.md | 18 ++--- src/hardware/addon-protocols/can.md | 22 +++---- src/hardware/addon-protocols/rs232-usb.md | 80 +++++++++++------------ 3 files changed, 60 insertions(+), 60 deletions(-) diff --git a/src/hardware/addon-protocols/ble.md b/src/hardware/addon-protocols/ble.md index 01f2b57a3..07c85136f 100644 --- a/src/hardware/addon-protocols/ble.md +++ b/src/hardware/addon-protocols/ble.md @@ -4,11 +4,11 @@ permalink: /hardware/addon-protocols/ble/ title: Add-On Protocol - BLE --- -External devices can communicate with the Geotab GO device through the Third-Party Bluetooth Low Energy (BLE) protocol below. The hardware interface will be the [IOX-BT](https://support.geotab.com/ioxs/installation/doc/iox-bt). +External devices can communicate with the Geotab GO device through the Third-Party Bluetooth Low Energy (BLE) protocol described on this page. The hardware interface is the [IOX-BT](https://support.geotab.com/ioxs/installation/doc/iox-bt). -The IOX-BT is a read-only BLE sensor hub that supports up to 200 in-range beacons and will detect in/out of range for any Bluetooth beacon with a public MAC Address. However, sending any other data points requires the beacon to conform to the below specified Geotab BLE protocol. Rate limit is 1200 logs per 10 minutes. If you exceed the rate limit, the GO device will stop taking data from the IOX. +The IOX-BT is a read-only BLE sensor hub that supports up to 200 in-range beacons and will detect in/out of range for any Bluetooth beacon with a public MAC Address. However, sending any other data points requires the beacon to conform to the specified Geotab BLE protocol. Rate limit is 1200 logs per 10 minutes. If you exceed the rate limit, the GO device will stop taking data from the IOX. -Because it can only read packets, no handshake is required. Two way communication and device pairing are not possible. +Because it can only read packets, no handshake is required. Two-way communication and device pairings are not possible. ## Advertising Packet @@ -38,7 +38,7 @@ Because it can only read packets, no handshake is required. Two way communicatio ### Optional Information Types -These information types are optional and are not part of the required packet structure. Each entry must be preceded by the corresponding information identifier byte. If multiple information entries are used in the same advertisement packet, they should be arranged in an incrementing order based on their information identifier. The identifiers in the table below are those that are currently defined. Geotab will define new identifiers for any new sensors as required. You must use the IDs as defined by Geotab. If there is undefined data, contact us via the Help Desk and we will define the data and send you the required ID. +These information types are optional and are not part of the required packet structure. Each entry must be preceded by the corresponding information identifier byte. If multiple information entries are used in the same advertisement packet, they should be arranged in an incrementing order based on their information identifier. The currently defined identifiers are listed in the table below. Geotab will define new identifiers for any new sensors, as required. You must use the IDs as defined by Geotab. If there is undefined data, contact us via the Help Desk and we will define the data and send you the required ID. | Information identifier | Description | Unit type | Length (bytes) | Units | | --- | --- | --- | --- | --- | @@ -101,25 +101,25 @@ For all information types that use the FP24 format, a new log will be generated ### Generic Byte -The Generic Byte type can store one byte of data (0 to 255). It could be used to count the number of times a button is pressed. Or simply store the state of a toggle (0 or 1) switch. A new log will be generated on any change of data. +The Generic Byte type can store one byte of data (0 to 255). It can be used to count the number of times a button is pressed, or simply store the state of a toggle switch (0 or 1). Any data changes will generate a new log. ### Generic Timer -The Generic Timer allows keeping track of an elapsed time. The Units Of Time are not specifically defined and can be chosen by the implementor. If may make sense to measure some durations in hours, while others may warrant seconds. The Units Of Time may continuously increment. A new log will not be saved until a new event counter value is reported. The Generic Timer can be associated with other data types. For example, you could associate Generic Timer 1 with temperature to indicating the time when a chosen temperature threshold was exceeded. +The Generic Timer allows keeping track of an elapsed time. The Units Of Time are not specifically defined and can be chosen by the implementor. It may make sense to measure some durations in hours, while others may warrant seconds. The Units Of Time may continuously increment. A new log will not be saved until a new event counter value is reported. The Generic Timer can be associated with other data types. For example, you can associate Generic Timer 1 with temperature to indicate the time when a chosen temperature threshold was exceeded. ### Wakeup Event -A custom parameter is used to configure the IOX-BT to wakeup periodically to check for any wakeup events from beacons within range. The wakeup duration is 1s every 30s while sleeping. This periodic wakeup can be enabled using the following custom parameter: +A custom parameter is used to configure the IOX-BT to wake up periodically to check for any wakeup events from beacons within range. The wakeup duration is 1s every 30s while sleeping. This periodic wakeup can be enabled using the following custom parameter: ``` ``` The implementor of this protocol should increase the frequency of advertisements sent during an attempted wakeup event. A 100ms advertisement interval that persists for a minimum of 1 minute is recommended. -When sending the wakeup event as part of the advertisement data a value of 0x00 means "no event". Anything greater than 0 that has not already been reported on will cause the GO to wakeup and report on the beacon advertisements. The event is only used as an indication for reporting the changes in the rest of the advertisement data. The actual contents of the alert event byte will not be sent/reported. +When sending the wakeup event as part of the advertisement data, a value of 0x00 means "no event". Anything greater than 0 that has not already been reported will cause the GO device to wake up and report on the beacon advertisements. The event is only used as an indication for reporting any changes in the rest of the advertisement data. The actual contents of the alert event byte will not be sent/reported. ### Custom Data -Arbitrary data can be placed in the custom data segment. The data will not be interpreted by MyGeotab, but will be accessible through the API. The onus is on the implementor to extract and interpret the data. The data must be preceded by the length. The length is limited by the amount of data that can fit in the optional information section. The maximum custom data length is 18 bytes. A new log will be generated on any change in the data. +Arbitrary data can be placed in the custom data segment. The data will not be interpreted by MyGeotab, but will be accessible through the API. The onus is on the implementor to extract and interpret the data. The data must be preceded by the length. The length is limited by the amount of data that can fit in the optional information section. The maximum custom data length is 18 bytes. Any data changes will generate a new log. | Offset | Description | | --- | --- | diff --git a/src/hardware/addon-protocols/can.md b/src/hardware/addon-protocols/can.md index 11a77d7fe..a8b617037 100644 --- a/src/hardware/addon-protocols/can.md +++ b/src/hardware/addon-protocols/can.md @@ -6,11 +6,11 @@ title: 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](https://www.geotab.com/documentation/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 in the correct format. Once processed, the third-party data will be saved and sent to MyGeotab as Status Data. +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 attempting to integrate a third-party device with the GO device using our Third-Party Data CAN Protocol: +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 @@ -22,11 +22,11 @@ There is an extensively defined Status Data ID list which can be found at [MyGeo ### 3 - Implement the Third-Party CAN Protocol -Implement the Third-Party CAN Protocol in the external device as detailed 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. +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 will be an extended frame message (29-bit) and will be 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: +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: | Byte | Description | Value | | --- | --- | --- | @@ -47,18 +47,18 @@ Each piece of information related to the third-party device must be sent individ Note: See [Appendix A](#appendix-a-raw-message-data-example-for-iox-can) 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. Ignition must be on for the handshake process. +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](#msg-type-0x81-third-party-device-id) 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](#msg-type-0x02-third-party-data-acknowledge) 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 detailed in [Messages from MyGeotab](#messages-from-mygeotab) +3. The MyAdmin API can now be used to produce CAN messages from the IOX-CAN as described in [Messages from MyGeotab](#messages-from-mygeotab) ## Messages from GO device ### Msg Type 0x02: Third-Party Data Acknowledge -Issued by the GO device on receipt of Third-Party Data from the External Device. +Issued by the GO device upon receipt of Third-Party Data from the external device. | CAN ID Breakdown | Value | | --- | --- | @@ -75,7 +75,7 @@ Issued by the GO device on receipt of Third-Party Data from the External Device. ### Msg Type 0x81: Third-Party Device ID -Issued by the external device on power-up every second until the Acknowledge message (Msg Type 0x02) is received. +Issued by the external device upon power-up, once every second until an Acknowledge message (Msg Type 0x02) is received. | CAN ID Breakdown | Value | | --- | --- | @@ -112,7 +112,7 @@ Currently not implemented. ### 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. +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. | CAN ID Breakdown | Value | | --- | --- | @@ -129,7 +129,7 @@ Priority Status Data will follow an expedited processing workflow on the GoDevic ## Messages from MyGeotab -A [handshake](#handshake) must be completed before this functionality will work. To send messages from MyGeotab to the external device, please download the source code of the [Starter Kit](https://geotab.github.io/sdk/software/js-samples/#starter-kit) sample, and replace the [Sample API](https://github.com/Geotab/sdk/blob/master/src/software/js-samples/starterKit.html#L76) with the following script. The alternative is paste the script in the [Runner](https://geotab.github.io/sdk/software/api/runner.html). +A [handshake](#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](https://geotab.github.io/sdk/software/js-samples/#starter-kit) sample, and replace the [Sample API](https://github.com/Geotab/sdk/blob/master/src/software/js-samples/starterKit.html#L76) with the following script. The alternative is to paste the script in the [Runner](https://geotab.github.io/sdk/software/api/runner.html). ```javascript api.call("Add", { "typeName": "TextMessage", @@ -160,7 +160,7 @@ A [handshake](#handshake) must be completed before this functionality will work. ### Appendix A: Raw Message Data Example for IOX-CAN -Third-Party Device ID from External Device (4208 is a test Device ID). +Third-Party Device ID from external device (4208 is a test Device ID). (Device ID: 4208 = 0x1070) diff --git a/src/hardware/addon-protocols/rs232-usb.md b/src/hardware/addon-protocols/rs232-usb.md index 149ac8e01..5a733d0c4 100644 --- a/src/hardware/addon-protocols/rs232-usb.md +++ b/src/hardware/addon-protocols/rs232-usb.md @@ -4,7 +4,7 @@ permalink: /hardware/addon-protocols/rs232-usb/ title: 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: +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](https://www.geotab.com/documentation/iox-rs232/ "IOX-RS232 Support Documentation") - [IOX-USB](https://www.geotab.com/documentation/iox-usb/ "IOX-USB Support Documentation") @@ -12,7 +12,7 @@ External devices can communicate with the Geotab GO device through the Third-Par ## 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. +To enable third-party data communication on the IOX-USB, apply the following custom parameter to the GO device through MyGeotab: ```xml @@ -31,27 +31,27 @@ The IOX-USB operates as a USB 2.0 full-speed host. The maximum data transfer rat 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. +- 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. +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 +- 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. +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](mailto:soleng@geotab.com) with a detailed integration proposal, this should include: +Contact the [Geotab Solutions Engineering team](mailto:soleng@geotab.com) with a detailed integration proposal, which should include: - A name for the integration - The interfacing hardware @@ -60,7 +60,7 @@ Contact the [Geotab Solutions Engineering team](mailto:soleng@geotab.com) with a - 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. +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](https://docs.google.com/presentation/d/1nkmDYw2tscZxKaezFm5sR3jLItI3IRJTS6JIhgg0rFU/edit#slide=id.g625282e7fc_0_0) with integration walkthrough. @@ -70,7 +70,7 @@ There is an extensively defined Status Data ID list which can be found at [MyGeo ### 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. +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](#handshake-sync-auto-baud-detect-for-rs232) 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. @@ -83,9 +83,9 @@ An initial Handshake **is required** in order for the GO device to accept third- ### 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. +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 pseudo code: +Checksum calculation pseudocode: ```js byte ChkA = 0; @@ -102,12 +102,12 @@ ChkB = ChkB + ChkA; ### Data Endianness -All values must be sent using Little Endian Byte Order, meaning the least significant byte first. +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 GO device on receipt of the Handshake Sync and periodically re-sent to confirm that the external device is still attached. +Issued by the GO device upon receipt of the Handshake Sync, and periodically re-sent to confirm that the external device is still connected. | | Bytes | Position | | --- | --- | --- | @@ -120,7 +120,7 @@ Issued by GO device on receipt of the Handshake Sync and periodically re-sent to ### Msg Type 0x02: Third-Party Data Acknowledge -Issued by GO device on receipt of Third-Party Data from the External Device. +Issued by the GO device upon receipt of Third-Party Data from the External Device. | | Bytes | Position | | --- | --- | --- | @@ -132,7 +132,7 @@ Issued by GO device on receipt of Third-Party Data from the External Device. ### Msg Type 0x21: GO Device Data -Issued by GO device every 2 seconds to a connected Enhanced Hours Of Service Device (ID: 4141) or periodically when a 0x85 request message is received. +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. @@ -179,7 +179,7 @@ Issued by GO device every 2 seconds to a connected Enhanced Hours Of Service Dev ### Msg Type 0x22: Binary Data Response -Issued by the GO device on 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. +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. | | Bytes | Position | | --- | --- | --- | @@ -193,7 +193,7 @@ Issued by the GO device on acceptance or rejection of either a Binary Data (0x86 ### Msg Type 0x23: Binary Data Packet -Issued by the GO device on receipt of a Binary Data packet of 255 bytes or less 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. +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. | | Bytes | Position | | --- | --- | --- | @@ -220,7 +220,7 @@ Sent by the GO device to the external device. Can be in response to a 0x88 messa ### Msg Type 0x25: Extended binary data packet -Issued by the GO device on 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. +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. | | Bytes | Position | | --- | --- | --- | @@ -233,8 +233,8 @@ Issued by the GO device on receipt of a Binary Data packet of 256 bytes or more ### Msg Type 0x26: Protobuf data packet -Available with add-on protocol version >= 1.2. -Issued by the GO device in response to 0x8C. Also issued by the GO device to publish information for the topics subscribed by the AddOn device. +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. | | Bytes | Position | | --- | --- | --- | @@ -245,11 +245,11 @@ Issued by the GO device in response to 0x8C. Also issued by the GO device to pub | Checksum | 2 | 3+x | | ETX (0x03) | 1 | 5+x | -The payload is protobuf encoded. Please see [Protobuf Schema](https://github.com/Geotab/android-external-device-example/blob/master/app/src/main/proto/iox_messaging.proto) for details. +The payload is protobuf-encoded. Please see [Protobuf Schema](https://github.com/Geotab/android-external-device-example/blob/master/app/src/main/proto/iox_messaging.proto) for details. ### Msg Type 0x27: Add-On protocol version to external device -Sent by the GO to an external device as a reply to the Add-On protocol version request (0x8B). +Sent by the GO device to an external device as a reply to the Add-On protocol version request (0x8B). | | Bytes | Position | | --- | --- | --- | @@ -265,7 +265,7 @@ Sent by the GO to an external device as a reply to the Add-On protocol version r ### Handshake Sync (Auto-BAUD detect for RS232) -Issued by External Device every second until the Handshake Request is received. +Issued by an external device every second until the Handshake Request is received. | | Bytes | Position | | --- | --- | --- | @@ -274,7 +274,7 @@ Issued by 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. +Issued by the external device when it receives the Handshake Request. | | Bytes | Position | | --- | --- | --- | @@ -289,16 +289,16 @@ 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 ACKed with a Third Party Data Acknowledge message. +- 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: +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 handhsake to complete. +- 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 @@ -318,7 +318,7 @@ Issued by the external device whenever it requires Third-Party Data to be saved ### 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. +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. | | Bytes | Position | | --- | --- | --- | @@ -344,9 +344,9 @@ 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 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. +- 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 @@ -363,7 +363,7 @@ This is a request-response message. It can be issued by the External Device when ### Msg Type 0x86: Binary Data Packet -Sent by the external device when sending messages with <= 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. +Sent by the external device when sending messages with less than 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. | | Bytes | Position | | --- | --- | --- | @@ -375,11 +375,11 @@ Sent by the external device when sending messages with <= 255 bytes of data cont | ETX (0x03) | 1 | 5+x | | Reply: Binary Data Response ([Msg Type 0x22](#msg-type-0x22-binary-data-response)) | | | -The payload of the binary data needs to adhere to protocols understood by MyGeotab. MIME protocol is one these protocols. Please see [Appendix C](#appendix-c-using-binary-data-messages-to-transfer-mime-data) for implementation details. +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](#appendix-c-using-binary-data-messages-to-transfer-mime-data) for implementation details. ### Msg Type 0x87: Third-Party Data as Priority Status Data -Priority Status Data will follow an expedited processing workflow on the GO 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. +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. | | Bytes | Position | | --- | --- | --- | @@ -394,7 +394,7 @@ Priority Status Data will follow an expedited processing workflow on the GO but ### 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 Keyless. +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. | | Bytes | Position | | --- | --- | --- | @@ -408,7 +408,7 @@ Extended application specific data from external device is sent by the external ### 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). +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). | | Bytes | Position | | --- | --- | --- | @@ -433,11 +433,11 @@ Sent by the external device when sending messages with <= 1000 bytes of data con | ETX (0x03) | 1 | 6+x | | Reply: Binary Data Response ([Msg Type 0x22](#msg-type-0x22-binary-data-response)) | | | -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](#appendix-c-using-binary-data-messages-to-transfer-mime-data) for implementation details. +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](#appendix-c-using-binary-data-messages-to-transfer-mime-data) 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 receives this request it will reply with 0x27. +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. | | Bytes | Position | | --- | --- | --- | @@ -450,7 +450,7 @@ Sent by the external device when requesting the add on protocol version number. ### Msg Type 0x8C: Protobuf data packet -Available with add-on protocol version >= 1.2. +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. | | Bytes | Position | @@ -463,7 +463,7 @@ Sent by the external device to subscribe to various topics/information. The GO d | ETX (0x03) | 1 | 5 + x | | Reply: Protobuf data packet ([Msg Type 0x26](#msg-type-0x26-Protobuf-data-packet)) | -The payload is protobuf encoded. Please see [Protobuf Schema](https://github.com/Geotab/android-external-device-example/blob/master/app/src/main/proto/iox_messaging.proto) for details. The currently supported topics are: +The payload is protobuf-encoded. Please see [Protobuf Schema](https://github.com/Geotab/android-external-device-example/blob/master/app/src/main/proto/iox_messaging.proto) for details. The currently supported topics are: | Topic | | --- |