GATT command service

Description

The GATT command service facilitates command transmission to the device via a Bluetooth connection, superseding the traditional MQTT method. This service operates without the necessity for a script and employs a variant of the BCE IOTM protocol. The Command service UUID is 00000100-0000-1000-8000-00805f9b34fb, and it encompasses two characteristics:

1. Command TX characteristic. UUID: 00000101-0000-1000-8000-00805f9b34fb.

   1. This characteristic is utilized for sending commands to the device.

   2. It is write-only.

2. Command RX characteristic. UUID: 00000102-0000-1000-8000-00805f9b34fb

   1. This characteristic serves as a command response after transmitting a command to the device, confirming whether it has been executed successfully.

   2. It can be either read or subscribed to.

Prerequisites:

• GATT-compatible device firmware. This functionality is enabled from the 01_132 main firmware version and 2.1.8 Bluetooth firmware version.

• A compatible settings template with Bluetooth/GATT server properties must be utilized. The minimum required version is V8.

Quick start guide

Command service security:

• A HMACSHA256 access token is appended in front of the payload. It consists of the IMEI, message expiry time, and key that are hashed using the HMACSHA256 algorithm. The access token also serves as a device identifier as it encompasses the device IMEI.

• A six-digit passkey is recommended. This enables Bluetooth communication to be encrypted and is essential for protection against MITM attacks.

GATT output control sequence

Open

Command TX characteristic (00000101-0000-1000-8000-00805f9b34fb)

Command message structure

Open

The command message consists of two fields:

1. HMACSHA256 - access token generated using:

   1. IMEI - IMEI of the device receiving the command.

   2. EXPIRY TIME - expiry time of the message - identical to that used in command message data (XG IOTM protocol).

   3. KEY - Up to 32-character key string. It must be configured in device settings.

2. COMMAND MESSAGE DATA - The actual command message in XG IOTM protocol format. Refer to the BT IOTM output command generation section.

• Example:

Open

Command RX characteristic (00000102-0000-1000-8000-00805f9b34fb)

This characteristic is employed to receive the command response from the device. It features a straightforward protocol structure that includes output ID to identify which output command was requested, a unique ID to differentiate between commands with the same output ID, and the result.

Command response structure

Open

1. Record type - Output command return record type (It will always be 04h).

2. Record length - The remaining length of the record.

3. System time - Time when the response was generated.

4. Output ID - Output command ID from the last received command message. It will be 0 if the message format is incorrect. Refer to the response code field for the exact reason.

5. Unique ID - Unique command ID from the last received command message. It will be 0 if the message format is incorrect. Refer to the response code field for the exact reason.

6. Response length - Length of the response code data. (It will always be 1).

7. Response code - Result of the last GATT command. Zero indicates success. For other return codes, refer to the table below:

• Successful command response example in little-endian hexadecimal format:

Open