Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Technical writing review for TECHWRSD-882 #343

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Technical writing review for TECHWRSD-882 #343

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1e46b65
Update protocol.md
fmgeotab Nov 1, 2023
47790c0
Technical writing review
fmgeotab Nov 1, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions src/hardware/addon-protocols/ble.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 |
| --- | --- | --- | --- | --- |
Expand Down Expand Up @@ -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:
```
<Parameter Description='Enable Periodic Bluetooth Wakeup' Offset='167' Bytes='80' IsEnabled='true'/>
```
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 |
| --- | --- |
Expand Down
22 changes: 11 additions & 11 deletions src/hardware/addon-protocols/can.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 |
| --- | --- | --- |
Expand All @@ -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 |
| --- | --- |
Expand All @@ -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 |
| --- | --- |
Expand Down Expand Up @@ -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 |
| --- | --- |
Expand All @@ -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",
Expand Down Expand Up @@ -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)

Expand Down
Loading