TABLE OF CONTENTS
- CSV Import via the OEM User Interface
- The OEM Web API
- List updates and checking if the list is current
Our range of hard-wired vehicle trackers can be configured and installed such that they keep an asset immobilised until a valid driver ID is presented. Once presented, the asset is able to be started. In order to achieve this, the device keeps a list of valid driver IDs in it's memory. To manage this, we need to be able to send a list of drivers down to the device. The OEM Server handles this process via it's slot mechanism. So drivers are synced via the same mechanism as system parameters and firmware.
When using Telematics Guru, the process is
- User updates the driver list in system parameters (and applies a few other settings to enable driver list management)
- Once all changes are complete, the driver list is periodically sent to OEM from TG, via an API call. There may be some delay as changes are sent in batches rather than instantaneously.
- When the device connects in to OEM server and does a slot check, the list is pushed sent to the device and stored in the device memory.
So when using a 3rd party server, we need to be able to get the driver list to OEM, and OEM Server will handle the rest. There are 2 methods.
CSV Import via the OEM User Interface
To access the import feature, your OEM user account will need the Driver Manager permission enabled. Contact DM support to have it enabled if you cannot access the Get and Set Driver options shown below.
This is the simplest and fastest method to get going. To set the driver list on a device, the process is:
- Select one or more devices for which we wish to update the list (note it will be the same list)
- Select Device Operations -> Set Drivers,
The below dialogue appears
1 = DMRFID, 2 = iButton, 7 = Wiegand.
The other missing data types 3, 4, 5 and 6 relate to discontinued pieces of hardware (keypad and console), and as such aren't used. 3 = 4DigitPin, 4 = 5DigitPin, 5 =Username, 6 = Username + Password.
The fob code, ibutton code or wiegand code etc. Care needs to be taken with Wiegand codes. Due to how the data is sent, the code marked on a card read by a Wiegand reader may not be the code that is read by the device.
The Supervisor column is unnecessary for nearly all users, it is used with a discontinued product - the Console. So this column can be left out.
Whether the user is allowed to operate the device. The default is true. So rather than use this column, we can instead only send IDs who are allowed to operate the asset, and leave out all others. However we may wish to send all drivers (and leave some disabled). This may make our CSV more human readable - or make more sense in some scenarios.
The device itself will not use the name, or send it as part of it's payload. Instead the server must compare the ID (i.e. the hex data against a list of drivers on the server to Again this field will result in a more human readable output when we retrieve the driver list from the device.
Only 2 columns are required, idtype and iddata, the rest are optional. If using only these 2 columns, we simply send ONLY the IDs (and type of these IDs) that we want to be able to start the asset. The operator column will allow us to send ALL drivers but have some enabled and some disabled. And finally the Name column will make the output more human readable.
The Format dropdown provides us with 3 options. It is best left on Auto and OEM will handle the rest and choose the smallest possible. Using the smallest possible format will allow us to store more drivers on the device. As mentioned above, the name will not be sent as part of the payload - but it can be sent to the device. However the 40 bytes means we can only fit 1/5 as many drivers if we also store the names. The 32 byte and 40 byte formats are not necessary for most applications - they are remnants of older, deprecated features - so simply leave the format set to Auto.
Once a CSV file is loaded, it is read and any errors are shown in the dialogue. We must correct any before proceeding.
Once there are no errors shown, we can click "Set Drivers" The dialogue will disappear and the import is done. Note it will not be live immediately. See List Updates and Checking if the List is current below for more details.
Get the List
To retrieve the list of drivers currently stored on OEM, simply select a single device. Then select Device Operations -> Get Drivers. A CSV will be downloaded of the driver list currently stored on the device.
The OEM Web API
The CSV import provides a convenient, user friendly method for partners to load driver lists to the device. However to be able to manage lists and add/remove drivers, we must have access to OEM server. They end user may not have this access (though it is possible to provide it, see - Can I give OEM Server access to a customer?). Additionally the CSV method will not keep up with frequent list changes and remain up to date, unless the user is regularly uploading via OEM. In this scenario list updates can be managed using the OEM Web API. Contact DM support for documentation.
List updates and checking if the list is current
In the device grid in OEM, we can check when the list was last updated on the device via the Details page. We can access this from device grid.
The version currently on the device is shown in yellow, and the list version pending on the server is shown in red. If there is no version number in brackets, then the latest version which has been seen by the server is also on the device. The Version Number is simply the time in seconds since 1/1/13 when the list was updated. See Times in the DM Protocol. So we can use this page to check if the list is up to date when testing.
The list will update with the device slots. To trigger a slot resync, we can use this button, or send the async message 0x001 as detailed in the Web API documentation. There are certain conditions in device firmware that will prevent the update happening immediately - for example if the device is in trip. But most of the time the changes should be processed within a few minutes of the device connecting in.
1. How many drivers can be stored on the list?
See here for a table showing the number of drivers which can be stored - Driver Lists