Revision History

The Geotab Keyless System allows for the simultaneous storage of up to four distinct stored Virtual Keys (reservations) locally on the GO device that can be accessed via Geotab Keyless NFC tags (tapCards). Each Stored Virtual Key has distinct permissions, privileges, NFC tapCard allow lists, start, and end times. This can be used to facilitate various vehicle access levels as shown below.

Figure 5: Reservation storage overview

Figure 6: Sample use case

Hardware Requirements:

1. Geotab GO device firmware version: 33.37 or above
2. MyGeotab Build Version: 2101.1487 or above
3. 1. Build version can be found by navigating to Administration > About

NFC tags typically operate at relatively low input powers/low voltage and this NFC product is not designed to be able to operate when exposed to a wireless charging electromagnetic field. Affix the NFC Tag/Sticker on a wallet or employee identification card, or other ID you have with your person.

WARNING! Do NOT place the NFC sticker/tag near wireless charging (e.g., the back of a cell phone) to prevent thermal damage or serious injury.

Keyless Service

The Keyless Service serves as the keyless controller in the Geotab software ecosystem. It has three responsibilities with regards to the Keyless NFC vehicle access feature:

1. Provide an API for integrators to be notified of taps against their vehicles
2. Create, manage, and synchronize stored virtual keys (up to 4) with GO devices OTA
3. Send commands associated with a virtual key to Go devices, such as check-in, check-out, etc.

The Keyless Service version 1.1 API (required for NFC functionality) can be found here.

Synchronizing Virtual Keys On GO Devices

The Keyless service will be responsible for keeping stored virtual keys in sync by running a virtual key synchronization workflow periodically. The GO device will report Status Data diagnostics 3407 - Reservation Sync ID and 3408 - Allow-list Sync ID. Payload data for 3407 and 3408 should always match for a given virtual key synchronization event

Send Commands With Virtual Key Context

Optional virtualKeyId or virtualKeyRequest properties may be included in the body of a device commands request. Requests to the commands API endpoint containing a valid virtualKeyRequest body, will create a virtual key in addition to scheduling the relevant command to be sent down to the GO device with the created virtual key.

Any command sent to the commands API endpoint, without a reservation context (virtualKeyId or valid virtualKeyRequest body), with the exception of CHECKIN or CHECKOUT will be executed unconditionally.

Upon reception, the GO device will treat the received command as if it arrived over bluetooth:

1. If the virtualKeyId is the same as the one currently checked in, execute commands
2. If the virtualKeyId is not the same as the one currently checked in, only allow LOCATE
3. If there is no active reservation (no virtual key checked in), the message contains a CHECKIN operation and a valid virutalKeyRequest, the GO device will execute the CHECKIN if the reservation/virtual key is valid (time/serial number).

Stored Virtual Keys (Offline Access)

Geotab Keyless integrators have the ability to create Stored Virtual Keys using the Geotab Keyless Service API. Stored Virtual Keys will be downloaded onto the GO telematics device for subsequent offline vehicle access after the virtual key and associated authorized user list are successfully saved to the GO device. Distinct user NFC Tag(s) may be assigned to individual Stored Virtual Keys.

Creating Stored Virtual Keys

When a request is received to create a stored virtual key, the request undergoes validation to see if the structure is valid; if yes, the creation of the virtual key is allowed to proceed.

Before the virtual key is sent to the GO device, a new virtual key synchronization resource with a hash will be generated to represent the set of active stored virtual keys for the given GO device. Each virtual key has an endingTimestamp property which is equivalent to an expiry timestamp. The Geotab Keyless Service uses this expiry timestamp to keep track of the currently active virtual keys.

The GO device will periodically report a StatusData diagnostic which will contain the latest hash on the device. The Keyless Service will compare the latest hash in the virtual key synchronization resource against the existing hash stored on the device received from the StatusData diagnostic. If there’s a mismatch, a synchronization message will be sent to the device.

Example: We have four existing virtual keys and we are trying to create a new virtual key vk_5 at say current_timestamp: t1+2500.

Then, from the above set of virtual keys, vk_2 has expired as is evident from the ending_timestamp of t1+500. Therefore, we currently have 3 active virtual keys and we will allow the creation of vk_5 to proceed. If none of the existing 4 virtual keys (vk_1, vk_2, vk_3, vk_4) had expired then the creation of the 5th Virtual Key would be rejected according to the validation rule that the maximum number of stored virtual keys on a GO device can be 4.

The GO device will store a set of up to 4 virtual keys in flash memory. These keys will remain on the device until the Keyless service sends a synchronization message containing a new set of virtual keys. There are no limits on the number of tapCardSerialNumbers that can be associated with each stored virtual key, however there is a cumulative maximum of 2024 tapCardSerialNumbers per device.

Deleting Stored Virtual Keys

Two new API endpoints have been introduced to allow for the deletion of stored virtual keys on the GO device in the Geotab Keyless Service. The first allows for the deletion of distinct virtual keys by specifying the virtualKeyId that should be targeted for deletion.

Integrators may also choose to delete all stored virtual keys from device memory with the following request. Upon successfully scheduling the deletion of a virtual key, a virtual key synchronization message will be sent to the GO device.

Tap & Go (Online Access)

In this scenario, Tap & Go, a user may use a Geotab Keyless NFC tag to access a vehicle without a valid virtualKey containing their NFC tag serial number stored locally on the GO device. Upon performing a long hold action, the GO device will check if the tapped NFC tag is contained within a valid stored virtualKey. If the Serial Number is not found, and the GO device has network connection, a CheckIn Request process is initiated.

A webhook subscription will be used to notify Geotab Keyless Integrators of pending CheckIn Requests. Once received, Integrators may then accept the CheckIn Request by generating an OTA CheckIn command.

! IMPORTANT: Online Access requires network connectivity, and therefore should only be deployed in strong network reception environments.

Notification Subscription

Notification subscriptions can be created, retrieved, and modified using the appropriate subscription endpoints.

Creating or modifying a notification subscription will send a notification to the provided webhook url with the following JSON content structure.

CheckIn Requests

The GO device will generate a CheckIn request in a scenario where the vehicle is in an unbooked state, the end user has initiated a long tap, and the tapped NFC card serial number is not found within the stored Virtual Keys in local memory. Upon generating a CheckIn Request, the IOX-NFCREADER will display an Orange-Green alternating LED sequence indicating that an action is in progress.

✱ NOTE: The GO device will disallow all card taps while a NFC command execution is in progress. This includes taps from the card that scheduled the NFC command in execution.

CheckIn Response

Integrators will use the commands endpoint to acknowledge and accept a pending CheckIn Request. CheckIn approvals consist of an OTA CheckIn command and virtualKeyRequest.The recommended CheckIn response is provided below.

✱ NOTE: CheckIn requests will initiate a 1 minute CheckIn response timer. The CheckIn attempt will automatically be rejected by the GO device if no integrator response is received before the expiration of the CheckIn response timer

Disable Online CheckIn

The following custom device parameter can be utilized to disable online CheckIn functionality. With the “Disable Online CheckIn” parameter enabled, the GO device will automatically reject any taps attempted by a NFC tag serial number that is not stored locally on the device. The GO device will not generate CheckIn requests.

Custom Parameter: Disable Online CheckIn

Tap Event Notifications

The Geotab Keyless API will provide various tap event notifications via webhook notifications to inform the integrator of vehicle access activity.

Pending CheckIn Requests will have the following JSON content structure. A type of “CheckIn” indicates that the Geotab Keyless Service API is awaiting a response from the integrator to approve the CheckIn request.

Notifications of type “TapCheckInComplete” indicate that a user has used an approved Geotab Keyless NFC tag to access the vehicle via a stored virtual key (Offline Access).

✱ NOTE: : TapCheckInComplete notifications will be delivered once the vehicle establishes a network connection. In the event that a user accesses a vehicle while out of network connection, the Keyless Integrator will receive the TapCheckInComplete notification once the device regains network connectivity. Offline vehicle access notifications will be delivered for tap events occurring within a 24hr period prior to the device establishing network connection.

CheckOut Notifications

Upon completion of a CheckOut event, the Geotab Keyless Service will send a notification of type “CheckOutComplete”.

✱ NOTE: CheckOutComplete notifications will be delivered once the vehicle establishes a network connection. In the event that a user completes a CheckOut operation while out of network connection, the Keyless Integrator will receive the CheckOutComplete notification once the device regains network connectivity. Offline vehicle access notifications will be delivered for tap events occurring within a 24hr period prior to the device establishing network connection.

NFC Reader User Feedback

For simple references to provide your NFC users:

1. Using Keyless without a pre-reservation (“tap-n-go”):
2. Using Keyless with a pre-reservation:

The IOX-NFCREADERA will illuminate two LEDs (Green and Orange) in a particular order to provide visual feedback to the user during NFC interactions. Figure 7 details the LED sequence pattern for various NFC actions.

Figure 7: NFC LED Feedback

1. NFC tapCard detect: Green LED - On (125ms) , Off (125ms)
2. Vehicle Booking Active: Orange LED - On (25ms) , Off (1000ms). Only while ignition is OFF
3. Lock/Unlock completed: Green LED - On (3000ms)
4. CheckIn/CheckOut completed: [Green LED - On (500ms) , Off (500ms) ] x 3
5. Action in progress: Green LED On (125ms) , Orange LED On (125ms)
6. Access denied: Orange LED - On (1500ms)

✱ NOTE: LED sequence timing is approximate

NFC long hold

Depending on the state of the vehicle, an NFC long hold will either start or end reservation if the tapCardSerialNumber of the presented NFC tag is found in the allow list of a stored virtual key.

To perform a NFC long hold:

1. Place the Geotab Keyless NFC tag in close proximity to the IOX-NFCREADERA
2. Hold the NFC tag in place until the “Action in progress” LED sequence starts on the IOX-NFCREADERA (approximately 7 seconds).

A successful long hold action will result in the “CheckIn/ CheckOut completed” LED sequence.

NFC short tap

Depending on the state of the vehicle, a NFC short tap will either start a reservation, unlock and enable vehicle start, or lock and inhibit vehicle start.

To perform a NFC short tap:

1. Place the Geotab Keyless NFC tag in close proximity to the IOX-NFCREADERA
2. Hold the NFC tag in place until the “NFC Tag Detected” LED sequence starts on the IOX-NFCREADERA
3. Remove the NFC tag

✱ NOTE: A short tap CheckIn will only be performed in scenarios where the tapCardSerialNumber is stored in local memory and the vehicle is not currency in a booked state

NFC Serial Number Validation

Geotab encourages integrators to perform rudimentary checks to ensure an end-user has entered a valid NFC tag(s) serial number(s) prior to creating a stored Virtual Key Request. A Valid NFC tag serial number will abide by the following rules:

1. Serial Number should be ten characters long;
2. The first eight characters should be one of the following characters: 23456789ABCDEFGHJKLMNPQRSTUVWXYZ