Third-party Bluetooth Device Integration

1. Introduction

With the mass shipment of locks using the TTLock solution, more and more third-party devices need to control our locks. If the third-party device has an Android or Apple system, it can be supported by our provided SDK. However, many devices do not have an operating system and require us to open some protocols for control. This solution is designed to meet this usage scenario, allowing the door lock to be controlled by a Bluetooth module (without an operating system) to unlock or lock and query the lock status.

1.1 Supported chip models for third-party devices

The following chip models support adding and adjusting Bluetooth broadcast times for third-party devices. Please contact your lock manufacturer/vendor to purchase a lock with the corresponding chip model or request a firmware version upgrade:

SN534-15-1, SN534-16-1, SN503-18-1, SN8534-3-1, SN8534-1-1, SN8503-2-1

2.Operation Procedures

When adding a device, communication is required between the app, the lock, and the third-party Bluetooth device. The third-party Bluetooth device must also support receiving Bluetooth broadcast data. The specific process is as follows:

2.1. Unlocking with third-party devices

2.2. Lockout with third-party devices

2.3. Query lock status

The lock status can be obtained directly from the lock's normal broadcast data. Below is an example of broadcast data:

The manufacturer-defined data of type 0xFF contains door lock status information, with the following specific format:

Please Note: The lock status can also be queried using the following command.

3. Communication Protocol

3.1. Communication format

Synchronization Header: 2 bytes, fixed at 0x7F 0x5A

Fixed Data 1: 7 bytes, fixed at 0x05 0x03 0x00 0x00 0x01 0x00 0x01

Command Code: 1 byte, see commands below for details

Fixed Data 2: 1 byte, fixed at 0xB0

Data Length: 1 byte, the number of bytes in the following data field

Data: n bytes, the specific number of bytes is indicated by the value of the data length field. The content of the data field needs to be encrypted and decrypted using the AES algorithm, see the appendix for the algorithm.

CRC Checksum: 1 byte, the CRC checksum value of all data from the synchronization header (0x7F 0x5A) to this field, see the appendix for the algorithm.

Example Data Packet: 7F5A0503000001000188B010C18C99218D9912CB9D36CE659678D95CDC0D0A0A

3.2. Communication key between third-party devices and the lock

Fixed AES key:

0x87,0x12,0x35,0xAE,0x45,0x23,0xC9,0xE3,0x3F,0x67,0x34,0x32,0xBD,0xF9,0xA2,0xC9 The device addition process uses the above fixed AES key; other processes use the key generated during the addition process.

3.3. Broadcast data

After receiving the command from the App to allow the addition of a device, the lock will broadcast via Bluetooth. The broadcast UUID is 0x1911, and the broadcast manufacturer-defined data is as follows (where the status field is 0x01).：

After adding a third-party device, the broadcast status field changes to 0x02.

Please Note: Third-party Bluetooth devices can search for Bluetooth devices with UUID 0x1911 and manufacturer-defined data starting with 0x06, 0x01, or 0x01 to add the device.

3.4. Communication Commands

3.4.1. Communication commands between third-party Bluetooth devices and door locks

Command code: 0x88

Subcommand code：

3.4.1.1. Add Devices

A. Request parameters

B. Response parameters

3.4.1.2. Get Temporary Token

A. Request parameters

B. Response parameters

3.4.1.3. Unlock

A. Request parameters

B. Response parameters

3.4.1.4. Lock

A. Request parameters

B. Response parameters

3.4.1.5. Query lock status

A. Request parameters

B. Response parameters

Note: The lock status can also be obtained through the lock's broadcast data.

3.5. Error code table

3.6. Appendix

3.6.1. CRC value calculation method

//================

//8-bit CRC Cheat Sheet

//================

xxxxxxxxxx
34
1
unsigned char const CRC_TABLE[256] =
2
{
3
 0x00,0x5E,0xBC,0xE2,0x61,0x3F,0xDD,0x83,0xC2,0x9C,0x7E,0x20,0xA3,0xFD,0x1F,0x41,
4

5
 0x9D,0xC3,0x21,0x7F,0xFC,0xA2,0x40,0x1E,0x5F,0x01,0xE3,0xBD,0x3E,0x60,0x82,0xDC,
6

7
 0x23,0x07,0x9F,0xC1,0x42,0x1C,0xFE,0xA0,0xE1,0xBF,0x5D,0x03,0x80,0xDE,0x3C,0x62,
8

9
 0xBE,0xE0,0x02,0x5C,0xDF,0x81,0x63,0x3D,0x7C,0x22,0xC0,0x9E,0x1D,0x43,0xA1,0xFF,
10

11
 0x46,0x18,0xFA,0xA4,0x27,0x79,0x9B,0xC5,0x84,0xDA,0x38,0x66,0xE5,0xBB,0x59,0x07,
12

13
 0xDB,0x85,0x67,0x39,0xBA,0xE4,0x06,0x58,0x19,0x47,0xA5,0xFB,0x78,0x26,0xC4,0x9A,
14

15
 0x65,0x3B,0xD9,0x87,0x04,0x5A,0xB8,0xE6,0xA7,0xF9,0x1B,0x45,0xC6,0x98,0x7A,0x24,
16

17
 0xF8,0xA6,0x44,0x1A,0x99,0xC7,0x25,0x7B,0x3A,0x64,0x86,0xD8,0x5B,0x05,0xE7,0xB9,
18

19
 0x8C,0xD2,0x30,0x6E,0xED,0xB3,0x51,0x0F,0x4E,0x10,0xF2,0xAC,0x2F,0x71,0x93,0xCD,
20

21
 0x11,0x4F,0xAD,0xF3,0x70,0x2E,0xCC,0x92,0xD3,0x8D,0x6F,0x31,0xB2,0xEC,0x0E,0x50,
22

23
 0xAF,0xF1,0x13,0x4D,0xCE,0x90,0x72,0x2C,0x6D,0x33,0xD1,0x8F,0x0C,0x52,0xB0,0xEE,
24

25
 0x32,0x6C,0x8E,0xD0,0x53,0x0D,0xEF,0xB1,0xF0,0xAE,0x4C,0x12,0x91,0xCF,0x2D,0x73,
26

27
 0xCA,0x94,0x76,0x28,0xAB,0xF5,0x17,0x49,0x08,0x56,0xB4,0xEA,0x69,0x37,0xD5,0x8B,
28

29
 0x57,0x09,0xEB,0xB5,0x36,0x68,0x8A,0xD4,0x95,0xCB,0x29,0x77,0xF4,0xAA,0x48,0x16,
30

31
 0xE9,0xB7,0x55,0x0B,0x88,0xD6,0x34,0x6A,0x2B,0x75,0x97,0xC9,0x4A,0x14,0xF6,0xA8,
32

33
 0x74,0x2A,0xC8,0x96,0x15,0x4B,0xA9,0xF7,0xB6,0xE8,0x0A,0x54,0xD7,0x89,0x6B,0x35
34
};

/*

* Description:

* Calculates the CRC result using a fast lookup table method.

* Parameters:

* pData: The array to be calculated for CRC.

* nDataCount: The number of bytes in the array to be calculated for CRC.

* Return Value:

* CRC value.

*/

xxxxxxxxxx
11
1
int CalcCRC(LPBYTE pData, int nDataCount)
2
{
3
 unsigned char CRC_result = 0;  
4
 
5
 while(nDataCount--)
6
 {
7
  CRC_result ^= *pData++;
8
  CRC_result = CRC_TABLE[CRC_result];  
9
 }
10
 return CRC_result;
11
}

3.6.2 Example of adding a third-party device

Third-party device data：

MAC address of third-party device: 00-a1-26-66-bf-01

Fixed AES key：0x87,0x12,0x35,0xAE,0x45,0x23,0xC9,0xE3,0x3F,0x67,0x34,0x32,0xBD,0xF9,0xA2,0xC9

Parameters before encryption：0x01,0x00,0xA1,0x26,0x66,0xBF,0x01

Encrypted parameters：0xC1 0x8C 0x99 0x21 0x8D 0x99 0x12 0xCB 0x9D 0x36 0xCE 0x65 0x96 0x78 0xD9 0x5C

CRC checksum：0xDC

Complete data packet：7F5A0503000001000188B010C18C99218D9912CB9D36CE659678D95CDC0D0A

Lock reply data：

-7f-5a-05-03-00-00-01-00-01-54-b0-20-4a-6c-86-90-bd-43-29-c8-e1-8c-75-95-2c-4b-34-10-e8-ec-b9-81-8c-cc-f8-ad-4e-e1-e9-77-8b-89-af-45-f0-0d-0a-

Decrypted parameters:

-88-01-3d-00-1c-de-1a-d0-cb-c2-25-4f-29-6e-a8-ab-71-5f-7a-a9-a5-3f-93-f6-

4.Demo

Third party Bluetooth device integration code：demo