Support Document

0 mins to read

Revision History

Version

Date

Editor

Changes

0

December, 2022

Ben Gaffney

Version 0 Released

  1. Migrated legacy NFC access integration information from integration manual to separate document
  2. Edited/updated content

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 GO9 telematics device or newer
    2. IOX-Keyless, IOX-Keyless-NK or IOX-Keybox
    3. IOX-NFCREADERA: Refer for installation and specifications.
    4. Geotab Keyless NFC tags (GEO-KLNFCFOB)
    5. SPR-NFCBRKTV2ASY (for affixing the IOX-NFCREADERA to a windshield of a vehicle)

    Software Requirements:

    1. Geotab GO device firmware version: 33.37 or above
    2. MyGeotab Build Version: 2101.1487 or above
      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.

    Method

    Endpoint

    Request

    POST

    /api/tenants/{database}/devices/{serialNumber}/commands

    { "commands" : [ ], "virtualKeyId": "string", "virtualKeyRequest": {

    "isStoredVirtualKey": false,

    "tapCardSerialNumber": "6D4297YA",

    "userReference": "user@example.com",

    "beginningTimestamp": 1582747558000,

    "endingTimestamp": 1582833958000,

    "permissions": [

    "Lock"

    ],

    "privileges": [

    "ResetAtEndOfBooking"

    ],

    "endBookConditions": [

    "IgnitionOff"

    ]

    } }


    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 sent to the GO 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

    Method

    Endpoint

    Request

    Response

    POST

    /api/tenants/{database}/devices/{serialNumber}/virtual-keys

    { "isStoredVirtualKey": <bool>, "tapCardSerialNumbers": [ "tC_1","tC_2", ...], "userReference": "string", "beginningTimestamp": <long>, "endingTimestamp": <long>, "permissions": [ ], "privileges": [ ], "endBookConditions": [ ] }

    { "virtualKeyId": "string", "isStoredVirtualKey": true, "tapCardSerialNumbers": [ ], "userReference": "string", "serialNumber": "string", "keylessToken": "string", "rsaKeyPairId": "string", "beginningTimestamp": <long>, "endingTimestamp": <long>, "permissions": [ ], "privileges": [ ], "endBookConditions": [ ] }


    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.

    GO Device serialNumber

    virtualKeyId

    beginningTimestamp

    endingTimestamp

    device_1

    vk_5

    t1+400

    t1+4000

    device_1

    vk_4

    t1+300

    t1+3000

    device_1

    vk_3

    t1+200

    t1+2750

    device_1

    vk_2

    t1+100

    t1+500

    device_1

    vk_1

    t1

    t1+1000


    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.

    Method

    Endpoint

    Request

    Response

    DELETE

    /api/tenants/{database}/devices/{serialNumber}/virtual-keys/{virtualKeyId}

    { "isStoredVirtualKey": <bool>, "tapCardSerialNumbers": [ "tC_1","tC_2"...], "userReference": "string", "beginningTimestamp": <long>, "endingTimestamp": <long>, "permissions": [], "privileges": [], "endBookConditions": [] }

    Response Code: 202

    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.

    Method

    Endpoint

    Request

    Response

    DELETE

    /api/tenants/{database}/devices/{serialNumber}/virtual-keys

    { "isStoredVirtualKey": <bool>, "tapCardSerialNumbers": [ "tC_1","tC_2"...], "userReference": "string", "beginningTimestamp": <long>, "endingTimestamp": <long>, "permissions": [], "privileges": [], "endBookConditions": [] }

    Response Code: 202


    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.

    Method

    Endpoint

    Request

    Response

    POST, PATCH,

    GET

    /api/tenants/{database}/notification-subscriptions}

    { "webhook": "string", "securityToken": "string" }

    { "webhook": "string", "securityToken": "string" }


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

    { "timestamp": 4102448461000, "type": 2, "notificationId": "3B991FAA-4D8F-4ADF-804E-AB4A6CCDF98C" }


    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.

    Method

    Endpoint

    Request

    Response

    POST,

    /api/tenants/{database}/devices/{serialNumber}/commands

    { "commands": [ "CheckIn", "Unlock", "IgnitionEnable" ], "virtualKeyRequest": { "tapCardSerialNumber": "743227D3PR", "userReference": "user@example.com", "beginningTimestamp": 1582747558000, "endingTimestamp": 1620365451000, "endBookConditions": [ "IgnitionOff" ] } }

    { "commands": [ "CheckIn", "Unlock", "IgnitionEnable" ], "virtualKeyId": "string" }


    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

    <Parameter Description='Disable Online CheckIn' Offset='181' Bytes='80' IsEnabled='true'/>


    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.

    { "NotificationId": "858261C6-4711-48F6-8B86-9EC2C53E2D65", "Database": "databaseName", "Timestamp": 1620359058770, "Type": "CheckIn", "Data": "{\"deviceSerialNumber\":\"G9A720FBE29A\",\"tapCardSerialNumber\":\"743227D3PR\"}" }


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

    {

    "NotificationId": "2651AAF8-EECA-489C-8673-A7A96CF78AAD",

    "Database": "databaseName",

    "Timestamp": 1634325392007,

    "Type": "TapCheckInComplete",

    "Data": "{\"deviceSerialNumber\":\"G9A720FBE29A\",\"tapCardSerialNumber\":\"743227D3PR\",\"virtualKeyId\":\"ABF26238-455E-4FC1-93FC-3B05D6CF5069\"}"

    }


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

    {

    "NotificationId": "8433F143-A066-4DE8-8B92-6D8239F9E0BD",

    "Database": "keylessnfc",

    "Timestamp": 1634325446690,

    "Type": "CheckOutComplete",

    "Data": "{\"deviceSerialNumber\":\"G9A720FBE29A\",\"virtualKeyId\":\"ABF26238-455E-4FC1-93FC-3B05D6CF5069\"}"

    }


    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 Interaction

    Generated Command

    Reservation Start

    NFC long hold

    CHECKIN, IGNITIONENABLE, UNLOCK

    Reservation End

    NFC long hold

    LOCK, IGNITIONINHIBIT, CHECKOUT


    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

    NFC Interaction

    Generated Command

    Reservation Start

    NFC short tap

    CHECKIN, IGNITIONENABLE, UNLOCK

    Unlock

    NFC short tap

    UNLOCK, IGNITIONENABLE

    Lock

    NFC short tap

    LOCK, IGNITIONINHIBIT


    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


    scroll-up