VTAP BLE GATT custom service

The VTAP BLE GATT service has a 16-bit service UUID of 0xD0F0. The client app can scan for BLE devices that advertise this service and potentially offer the user a list of devices which they can connect to.

The service provides 3 characteristics each with 16-bit UUIDs as follows:

0xD0F1 - Used to send data to the VTAP reader
0xD0F2 - Used to receive data from the VTAP reader
0xD0F3 - Status information

The data transferred on all three characteristics takes the form of a JSON string, which does not need to be zero terminated.

The data received (0xD0F2) and status (0xD0F3) characteristics will notify when they change. So when a tap is sent, the 0xD0F2 characteristic will be updated with the new tap data and the application will receive a notification of the change. It can read the tap data from the characteristic. The tap data will remain available until the connection is closed or a new tap is received.

The application can send a JSON string to the VTAP at any time by writing it to the 0xD0F1 characteristic. Normally this would be in response to a tap, to send a JSON string containing actions to perform, but this is not enforced. In the future, it may be used to support other commands or functions.

The 0xD0F3 characteristic can be read at any time, to query status information. The client app can also receive notifications when this value changes. The client application should use the notifications, after doing an initial read, rather than polling for status.

The tap data received (stored in the 0xD0F2 characteristic) takes this format:

Example: Tap data received in JSON (stored in the 0xD0F2 characteristic)

Copy

{
    "serialno":"CC123456",
    "payload": "3|DA2VbMkO_n-x61wN|32128290592065|Valued",
    "passtype":"G16",
    "passuid": "08E9460F"
}

This list of JSON attributes may be expanded in the future.

The client can send an action JSON message to provide user feedback, triggering LEDs and/or buzzer on the VTAP reader, by writing to the 0xD0F1 characteristic. This is in the same form as a response in the VTAP Cloud application:

Example: Action JSON message (written to the 0xD0F1 characteristic)

Copy

{
    "action": {
        "led": "?led ff0000,3000",
        "beep":"?beep 100,100,2"
    }
}

The "controls" and "outputs" arrays in a standard VTAP action JSON response (see below) are also supported within the action JSON, as well as the single "control" and "output" attributes defined in a VTAP Cloud application response. These attributes allow relays connected to VTAP PRO reader to be operated and allow messages to be sent to other VTAP PRO interfaces.

Standard VTAP action JSON response:

Copy

{ 
    "action": { 
        "beep": "100,50,2",
        "led": "00FF00,100,50,2",
        "message": "User Authorised",
        "controls": [
            {
                "control": "?relay 0 on delay=100 off" 
            }, 
            { 
                "control": "?relay 1,timed,6000" 
            }
        ],
        "outputs": [
            { 
                "output": ">k:A:POS barcode output via USB keyboard" 
            },
            { 
                "output": ">c:A:Output to USB COM port" 
            }
        ]
    }
}

Standard VTAP action JSON response schema
Item	Definition
beep	Can be used to send simple buzzer tones or complex sequences / play tunes. For more refer to the `?beepr` command and the buzzer control section in VTAP Commands Reference Guide. The example `"beep": "100,50,2"` sets two 100ms beeps, spaced by 50ms, at default frequency.
led	Can be used to send simple RGB colours or complex serial LED sequences. For more refer to the `?ledr` command and LED control section in VTAP Commands Reference Guide. The example `"led": "00FF00,100,50,2"` sets two 100ms green LED flashes, spaced by 50ms.
message	For readers connected to VTAP Cloud only: This message will appear in the 'Last tap response' field on the Readers page in VTAP Cloud UI. Select the blue button next to a reader to view reader activity - Last tap response.
controls	An array of one or more control commands, allows independent timed switching of relays. For more refer to the `?relay` command in VTAP Commands Reference Guide.
outputs	An array of one or more output commands, allows messages or payloads to be sent to any of the VTAP reader interfaces. For more refer to the `>` command in VTAP Commands Reference Guide.

The status on the 0xD0F3 characteristic is another JSON string:

Example: Status JSON string (written to the 0xD0F3 characteristic)

Copy

{
    "SerialNumber": "CC123456",
    "MaxData": 514,
    "AuthRequired": false
}

The “SerialNumber” attribute provides the assigned serial number of the VTAP reader.
The “MaxData” attribute lets the client know how much data can be sent in one go on the 0xD0F1 characteristic. Most BT stacks will negotiate this on connection, up to the maximum of 514 characters, but this can be restricted on some systems. If a blob of JSON longer than MaxData needs to be sent, the client can write the first part of the JSON blob up to MaxData characters, wait for a response acknowledgement and then write the next part(s) in the same manner, until all the data is sent. A VTAP PRO reader will combine successive writes until it has a valid JSON string.
The “AuthRequired” attribute is currently always false - this is intended for future use, when more advanced authentication schemes may be added.