Add-On Protocol - BLE Advertisement | Hardware

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.

The IOX-BT supports two modes of operation:

Connectionless data intake from advertisement packets
The IOX-BT acts as a passive BLE sensor hub, detecting presence for up to 200 Bluetooth beacons within range. While it can detect any beacon with a public MAC address, sending custom data requires the beacon to use the Geotab BLE protocol. Note that a rate limit of 1200 logs per 10 minutes applies. Exceeding this limit will halt data intake from the IOX-BT.
Two-way communication with device pairing
This mode allows for direct data exchange with the GO device, enabling requests and responses. However, saving custom data is not supported in this mode.

Connectionless Advertising

Offset	Value	Description
1	0x02	AD length
2	0x01	Flags
3	0x06	-LE General discoverable mode-BR/EDR not supported
4	0x06 + optional length	AD length
5	0xFF	Manufacturer specific data
6	0x0275	Geotab's company ID
8	0x00	Advertising packet version number
9	0xXX	Tx power level
10	0xXX	Battery level
Optional length(11 to 31)	0xXX	Optional information identifier
3 bytes	Optional information data
…	…
0xXX	Optional information identifier
X bytes	Optional information data

Required data types

Description	Unit type	Range
Tx power level	Sint 8	Resolution: 1 dBm, Min: -100 dBm, Max: 20 dBm
Battery level	Uint 8	Resolution: 1%, Min: 0%, Max: 100%

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

0 to 4

Reserved

Firmware version

FP24

None

Accelerometer event counter

FP24

None

Temperature

FP24

Degrees Celsius (°C)

Illuminance

FP24

Lux (lx)

Relative humidity

FP24

Percent (%)

Barometric pressure

FP24

Pascals (Pa)

Altitude

FP24

Meters (m)

Particulate matter (less than 1 µm)

FP24

Micrograms per cubic meter (µg/m3)

Particulate matter (less than 2.5 µm)

FP24

Micrograms per cubic meter (µg/m3)

Particulate matter (less than 10 µm)

FP24

Micrograms per cubic meter (µg/m3)

Nitric oxide

FP24

Parts per million (ppm)

Nitrogen dioxide

FP24

Parts per million (ppm)

Carbon monoxide

FP24

Parts per million (ppm)

Ammonia

FP24

Parts per million (ppm)

Methane

FP24

Parts per million (ppm)

Ethanol

FP24

Parts per million (ppm)

Hydrogen

FP24

Parts per million (ppm)

Carbon dioxide

FP24

Parts per million (ppm)

Fuel level

FP24

Percent (%)

24 to 199

Reserved(for future data types)

FP24

200 to 227

Reserved

228

Counter

UINT16

Counter for change of state events

229

State

UINT16

Current State of asset

230 to 239

Generic byte (1 to 10)

UINT8

None

240 to 249

Generic timer (1 to 10)

UINT8

UINT16

Event Counter

units of time

250 to 253

Reserved

254

Wakeup event

UINT8

None

255

Custom data

UINT8

None

FP24 (floating point 24 bit)

Same as FP32 but the 8 least-significant bits dropped.

S	E	E	E	E	E	E	E	E	F	F	F	F	F	F	F	F	F	F	F	F	F	F	F
23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0

[ -2^16, 2^16 ] can be exactly represented

[ -2^17, -2^16 -1 ] or [ 2^16 +1, 2^17 ] rounded to a multiple of 2

[ -2^18, -2^17 -1 ] or [ 2^17 +1 2^18 ] rounded to a multiple of 4

…

Infinity at: 2^128

FP24 conversions:

Action
Store	Convert to FP32FP24 = FP32 » 8
Read	FP32 = FP24 « 8Read as FP32

Note:

For all information types that use the FP24 format, a new log will be generated for any change in the data. For example, a change in temperature from 2°C to 2.000061°C would trigger a new log. Some implementations may only require a reporting resolution of 1°C. If an excessive number of logs are generated, we will disable reporting on BLE data. The onus is on the implementer to choose an appropriate reporting resolution for their data.

Generic byte

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. 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 wake up periodically to check for any wakeup events from beacons within range. The wakeup duration is 100ms every 3s 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. We recommend a 100ms advertisement interval that persists for a minimum of 1 minute.

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. Any data changes will generate a new log.

Offset	Description
1	Length
2 to length	Custom data

Example:

Type	Length	Data
255	8	1	2	3	4	5	6	7	8

Message interleaving

Message interleaving is not supported. The data types in the packet must remain consistent between advertisements.

Example packets

Reporting temperature

Offset	Value	Description
1	0x02	AD length
2	0x01	Flags
3	0x06	-LE general discoverable mode-BR/EDR not supported
4	0x0A	AD length
5	0xFF	Manufacturer specific data
6	0x0275	Geotab's company ID
8	0x00	Advertising packet version number
9	0xC6	Tx power level (-58dBm)
10	0x64	Battery level (100%)
11	0x07	Temperature
12	0x00	0x412000 FP24 = 10°C
13	0x20
14	0x41

Reporting a timer

Offset	Value	Description
1	0x02	AD length
2	0x01	Flags
3	0x06	-LE general discoverable mode-BR/EDR not supported
4	0x0A	AD length
5	0xFF	Manufacturer specific data
6	0x0275	Geotab's company ID
8	0x00	Advertising packet version number
9	0xC6	Tx Power level (-58dBm)
10	0x64	Battery level (100%)
11	0xF1	Generic timer 2
12	0x03	Event
13	0xF4	0x01F4 = 500 minutes
14	0x01

Reporting temperature and a timer

Offset	Value	Description
1	0x02	AD length
2	0x01	Flags
3	0x06	-LE general discoverable mode-BR/EDR not supported
4	0x0E	AD length
5	0xFF	Manufacturer specific data
6	0x0275	Geotab's company ID
8	0x00	Advertising packet version number
9	0xC6	Tx power level (-58dBm)
10	0x64	Battery level (100%)
11	0x07	Temperature
12	0x00	0x412000 FP24 = 10°C
13	0x20
14	0x41
15	0xF1	Generic timer 2
16	0x03	Event
17	0xF4	0x01F4 = 500 minutes
18	0x01

Reporting custom data

Offset	Value	Description
1	0x02	AD length
2	0x01	Flags
3	0x06	-LE general discoverable mode-BR/EDR not supported
4	0x0F	AD length
5	0xFF	Manufacturer specific data
6	0x0275	Geotab's company ID
8	0x00	Advertising packet version number
9	0xC6	Tx power level (-58dBm)
10	0x64	Battery level (100%)
11	0xFF	Custom data
12	0x07	Length
13	0x42	Custom data "Beacon1" in ASCII
14	0x65
15	0x61
16	0x63
17	0x6F
18	0x6E
19	0x31

Reporting temperature + counter + timer + custom data

Offset	Value	Description
1	0x02	AD length
2	0x01	Flags
3	0x06	-LE general discoverable mode-BR/EDR not supported
4	0x19	AD length
5	0xFF	Manufacturer specific data
6	0x0275	Geotab's company ID
8	0x00	Advertising packet version number
9	0xC6	Tx power level (-58dBm)
10	0x64	Battery level (100%)
11	0x07	Temperature
12	0x00	0x412000 FP24 = 10°C
13	0x20
14	0x41
15	0xE6	Generic counter 1
16	0x08	Count
17	0xF1	Generic timer 2
18	0x03	Event
19	0xF4	0x01F4 = 500 minutes
20	0x01
21	0xFF	Custom data
22	0x07	Length
23	0x42	Custom data "Beacon1" in ASCII
24	0x65
25	0x61
26	0x63
27	0x6F
28	0x6E
29	0x31

Device Pairing

Pairing Request Advertising Packet

The following table describes the format of the advertising packet used for pairing requests:

Offset	Value	Description
1	0x02	AD length (2 bytes to follow, 1 byte for AD type and 1 byte AD Flags data).
2	0x01	AD Type (0x01 = BT_DATA_FLAGS).
3	0xXX	Flags (Generally controlled by the Phone’s driver layer)
4	0x11	AD length (17 bytes to follow, 1 byte for AD type, 16-bytes/128-bit of Service UUID)
5	0x07	Complete List of 128-bit Service Class UUID
6 to 21		First 16 bytes of a SHA-256 of the GO device serial number to initiate pairing with

Example: Service UUID

The Service UUID is derived from the first 16 bytes of a SHA-256 hash of the GO device serial number.

GO device serial number	G9D620F4D6D4
SHA 256	07963db2184e93fff6145e5442ca4691dd5ce660cb5b502e74179e527340a555
Service UUID	07963db2184e93fff6145e5442ca4691

Characteristics

Characteristic	UUID	Property	Characteristic
Tx	430F2EA3-C765-4051-9134-A341254CFD00	Read, Notify, Write	Tx Enable CCCD "0x2902"
Rx	906EE7E0-D8DB-44F3-AF54-6B0DFCECDF1C	Write

Usable data transferred per data packet is 20 bytes.

Note

The GO device will write to "Tx Enable" after a connection is established.
For bonding, the BLE security is mode 1 level 2 (Just-Works).
When the vehicle ignition is OFF and there is a Bluetooth connection with no data transfer for 10 minutes, the GO will drop the connection.

External device messages protocol

Please refer to Add-On Protocol - RS232 & USB & BLE for the protocol once connected.