Understanding the MyGeotab binary data types

The information in this article is useful to developers and integrators using the Geotab SDK (Software Development Kit).

In terms of engine data in MyGeotab, you have likely heard of status data and fault data. Status data (designated by type StatusData) indicates the state of a vehicle measured at a given time. For example, ignition state (on/off), engine speed, engine oil temperature and odometer readings are all types of status data.

On the other hand, fault data of type FaultData indicates irregular behaviour and potential failure of a vehicle system; engine oil temperature sensor high is an example of fault data. To identify the particulars of both of these types of data, they contain other information either defined in MyGeotab or through standards. Some examples of extra data included with fault data are Diagnostic, FailureMode and Controller fields.

There is another type of engine data, called BinaryData. The controller indicates the source of the data, if available (the protocol used is J1939 for those interested).

Five Types of Binary Data in MyGeotab

See below the five types of binary data with a description and their MyGeotab alias.

1. Engine Serial Number (EngineSerialNumber) — An identification number unique to each part (the transmission, brakes, etc. can also have values associated with this field).
2. Calibration Id (CalibrationId) — Uniquely identifies the software on the control module.
3. Software Version (SoftwareVersion) — Software version of the electronic module.
4. ECU Make (EcuMake) — A code related to the manufacturer of the Engine Control Unit (ECU)
5. ECU Model (EcuModel) — A code related to the product controlled by a particular ECU.

The data field holds an array of bytes. Although the number of bytes in this field could be very long, at the time of this writing, data retrieved from MyGeotab will not exceed 14 bytes in size and is often around 8 bytes.

You can access BinaryData through the SDK. A previous blog post shows how you can use MyGeotab bindings or wrappers to make use of the SDK. The retrieving of the data in this example will be in Python. Please note, if you copy and paste the code, certain characters like single and double quotation marks might need to be converted to the correct character.

# import modules

pip install -U mygeotab

import mygeotab as mg

import getpass

import base64

# authenticate against a database

database = input("Database: ")

username = input("Username: ")

password = getpass.getpass("Password: ")

api = mg.API(database=database, username = username, password = password)

api.authenticate()

password = None

# get all devices from data base and their corresponding vins

# combine this data with ‘DecodeVins’ functionality to get Vehicle information

# ‘DecodeVins’ takes in an array of multiple VINS, so it can be efficient

devices = api.call('Get', typeName = 'Device')

vins = dict(zip((d['id'] for d in devices),

api.call('DecodeVins', vins = [d['vehicleIdentificationNumber']

if 'vehicleIdentificationNumber' in d

else '?' for d in devices ])))

# get the ECU make for all devices

# NOTE: ONLY do this if your database has few devices, otherwise use consider using

# multicalls https://geotab.github.io/sdk/software/guides/concepts/ or the feed

ecuMake = dict(zip ((d['id'] for d in devices),

(api.call('Get',typeName='BinaryData',resultsLimit=10,search={

'deviceSearch': {'id': d['id']}, 'binaryDataType' : 'EcuMake'}

) for d in devices)))

# get vehicles whose data is to be checked

vehicle1 = getpass.getpass("Get device 1: ")

vehicle2 = getpass.getpass("Get device 2: ")

# Output data

# vehicle 1

print("Vehicle ", vins[vehicle1]['make'], vins[vehicle1]['model'])

print("Example 1:", ecuMake[vehicle1][1]['controller']['id'], ecuMake[vehicle1][1]['data'], base64.b64decode(ecuMake[vehicle1][1]['data']))

print("Example 2:", ecuMake[vehicle1][0]['controller']['id'], ecuMake[vehicle1][0]['data'], base64.b64decode(ecuMake[vehicle1][0]['data']))

print("Example 3:", ecuMake[vehicle1][2]['controller']['id'], ecuMake[vehicle1][2]['data'], base64.b64decode(ecuMake[vehicle1][2]['data']))

Vehicle  Freightliner M2 106 Medium DutyExample 1: ControllerJ1939EngineNo1Id Q01NTlM= b'CMMNS'Example 2: ControllerBrakesSystemControllerId TUVSV0I= b'MERWB'Example 3: ControllerTransmissionNo1Id QUxMU04= b'ALLSN'

# vehicle 2

print("Example 4:", ecuMake[vehicle2][1]['controller']['id'], ecuMake[vehicle2][1]['data'], base64.b64decode(ecuMake[vehicle2][1]['data']))

Example 4: ControllerJ1939EngineNo1Id aypyWCBoSXg6Cg== b'k*rX hIx:\n'

Looking at the output, we see that vehicle1 is a truck and its make is “Freightliner” and its model is “M2 106 Medium Duty.” There are three components that the GoDevice picks up:

• The engine, which uses the J1939 protocol, has a make code ‘CMMNS’
• The Brakes System, which also has a decodable name, ‘MERWB’
• The Transmission is made by ‘ALLSN’

A second device was chosen to demonstrate that not all data stored is easily readable.

Note that unlike in Python and Javascript, the data is stored as an array of bytes in C#, so appropriate conversion methods need to be used. Also note that you can get binary data through the datafeed.

If you have more questions and feel like experimenting with this, check out some of our other blog posts on using the MyGeotab API, head to the SDK page to try out the API runner, or head to the SDK forums.

Read more from this author:

5 Tips on Building Fleet Management Solutions

Get Started With the MyGeotab API Wrapper