Edit on GitHub

Add-On Protocol - BLE

Advertising Packet

OffsetValueDescription
10x02AD length
20x01Flags
30x06-LE General Discoverable Mode-BR/EDR Not Supported
40x06 +Optional LengthAD length
50xFFManufacturer Specific Data
60x0275Geotab’s Company ID
80x00Advertising packet version number
90xXXTx Power Level
100xXXBattery Level
Optional Length(11 to 31)0xXXOptional Information identifier
3 bytesOptional Information data
0xXXOptional Information identifier
X bytesOptional Information data

Required Data Types

DescriptionUnit typeRange
Tx Power LevelSint 8Resolution: 1 dBmMin: −100 dBmMax: 20 dBm
Battery LevelUint 8Resolution: 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 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.

Information identifierDescriptionUnit typeLength (bytes)Units
0 to 4Reserved
5Firmware VersionFP243None
6Accelerometer Event CounterFP243None
7TemperatureFP243Degrees Celsius (°C)
8IlluminanceFP243Lux (lx)
9Relative HumidityFP243Percent (%)
10Barometric PressureFP243Pascals (Pa)
11AltitudeFP243Meters (m)
12 to 199Reserved(for future data types)FP243
200 to 229Reserved
230 to 239Generic Byte (1 to 10)UINT81None
240 to 249Generic Timer (1 to 10)UINT8UINT1612Event CounterUnits Of Time
250 to 253Reserved
254Wakeup EventUINT81None
255Custom DataUINT8XNone

FP24 (Floating Point 24 bit)

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

SEEEEEEEEFFFFFFFFFFFFFFF
23222120191817161514131211109876543210

[ -216, 216 ] can be exactly represented

[ -217, -216 -1 ] or [ 216 +1, 217 ] rounded to a multiple of 2

[ -218, -217 -1 ] or [ 217 +1 218 ] rounded to a multiple of 4

Infinity at: 2128

FP24 Conversions:

Action
StoreConvert to FP32FP24 = FP32 >> 8
ReadFP32 = 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 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.

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.

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:

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.

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.

OffsetDescription
1Length
2 to LengthCustom Data

Example:

TypeLengthData
25581

Message Interleaving

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

Example Packets

Reporting temperature

OffsetValueDescription
10x02AD length
20x01Flags
30x06-LE General Discoverable Mode-BR/EDR Not Supported
40x0AAD length
50xFFManufacturer Specific Data
60x0275Geotab’s Company ID
80x00Advertising packet version number
90xC6Tx Power Level (-58dBm)
100x64Battery Level (100%)
110x07Temperature
120x000x412000 FP24 = 10°C
130x20
140x41

Reporting a timer

OffsetValueDescription
10x02AD length
20x01Flags
30x06-LE General Discoverable Mode-BR/EDR Not Supported
40x0AAD length
50xFFManufacturer Specific Data
60x0275Geotab’s Company ID
80x00Advertising packet version number
90xC6Tx Power Level (-58dBm)
100x64Battery Level (100%)
110xF1Generic Timer 2
120x03Event
130xF40x01F4 = 500 minutes
140x01

Reporting temperature and a timer

OffsetValueDescription
10x02AD length
20x01Flags
30x06-LE General Discoverable Mode-BR/EDR Not Supported
40x0EAD length
50xFFManufacturer Specific Data
60x0275Geotab’s Company ID
80x00Advertising packet version number
90xC6Tx Power Level (-58dBm)
100x64Battery Level (100%)
110x07Temperature
120x000x412000 FP24 = 10°C
130x20
140x41
150xF1Generic Timer 2
160x03Event
170xF40x01F4 = 500 minutes
180x01

Reporting custom data

OffsetValueDescription
10x02AD length
20x01Flags
30x06-LE General Discoverable Mode-BR/EDR Not Supported
40x0FAD length
50xFFManufacturer Specific Data
60x0275Geotab’s Company ID
80x00Advertising packet version number
90xC6Tx Power Level (-58dBm)
100x64Battery Level (100%)
110xFFCustom Data
120x07Length
130x42Custom data"Beacon1" in ASCII
140x65
150x61
160x63
170x6F
180x6E
190x31

Reporting temperature + counter + timer + custom data

OffsetValueDescription
10x02AD length
20x01Flags
30x06-LE General Discoverable Mode-BR/EDR Not Supported
40x19AD length
50xFFManufacturer Specific Data
60x0275Geotab’s Company ID
80x00Advertising packet version number
90xC6Tx Power Level (-58dBm)
100x64Battery Level (100%)
110x07Temperature
120x000x412000 FP24 = 10°C
130x20
140x41
150xE6Generic Counter 1
160x08Count
170xF1Generic Timer 2
180x03Event
190xF40x01F4 = 500 minutes
200x01
210xFFCustom Data
220x07Length
230x42Custom data"Beacon1" in ASCII
240x65
250x61
260x63
270x6F
280x6E
290x31