Basic Bluetooth LE specifications

Glossary

Broadcast specification

• Bluetooth broadcast packet

  The Bluetooth broadcast packet format complies with the Bluetooth 4.0 specification. It consists of several AD Structures (see Bluetooth 4.2 Core Specification, Volume 3, Part C, Chapter 11). Each AD Structure consists of a Length, an AD Type, and AD Data, as shown in the following figure.

  
• Broadcast data packet format
  The broadcast packet of a Bluetooth device that connects to the IoT Platform must include the custom manufacturer format defined by Alibaba (Manufacturer Specific Data, AD Type: 0xFF). The Alibaba custom broadcast format consists of (6+n) bytes. Different broadcast types correspond to different values of n and Content, as shown in the following figure.

  Byte order	Name	Value	Description
  0	Length	0x0F	Manufacturer Specific Data Length. This document uses the basic type, so the value is the length of the basic type.
  1	Type	0xFF	Manufacturer Specific Data Type
  2 to 3	CID	0x01A8	Company Identifier. 0x01A8 is the company code for Alibaba.
  4	VID and Subtype	0xb5	Bits 0 to 3: Alibaba Bluetooth specification version number. The current version is 5, and the value is 0b0101. Bits 4 to 7: Subtype. 0b1000: Basic Bluetooth type. Mesh devices use this type for AIS broadcasts. 0b1001: Bluetooth Beacon type. 0b1010: Bluetooth voice type. 0b1011: Bluetooth GATT type. Connected BLE devices use this type.
  5	FMSK	0x03	Function Mask for capabilities provided by the software development kit (SDK), such as security, over-the-air (OTA) upgrades, Bluetooth version, and secure broadcast.
  6 to n	Content	xx...xx	Content data corresponding to the Subtype.

  Note The Subtype affects only the data format of bytes 6 to n in the broadcast. This document uses the Bluetooth GATT type for this description. Typically, a device class needs to implement only one broadcast type.

  FMSK indicates the capabilities of the device. The bits are defined as follows.

  Bit order	Feature description
  0 to 1	Bluetooth version. 00: BLE 4.0. 01: BLE 4.2. 10: BLE 5.0. 11: Later than BLE 5.0.
  2	0: OTA not supported. 1: OTA supported.
  3	0: No security authentication. 1: Security authentication is performed. For the detailed procedure, see the Security authentication section.
  4	0: One secret per product model. 1: One secret per device.
  5	Provisioning flag. 0: Not provisioned. 1: Provisioned.
  6 to 7	Reserved for future use. Fill with all 0s.

• GATT broadcast format
  The Subtype for a GATT broadcast is 0x0b. The data format is as follows.
  Bytes 6 to 15 are defined as follows.

  Byte order	Name	Example value	Description
  6 to 9	PID	0x00ef1000	Product ID. A 4-byte ID issued by the IoT Platform.
  10 to 15	MAC	0xb0b448d07882	The 6-byte MAC address of the Bluetooth device. This is a unique device address issued by the IoT Platform.

  Note The data in the broadcast packet must be stored in little-endian format.

AIS service specification

Bluetooth devices that connect to the IoT Platform must comply with the custom Alibaba IoT Service (AIS).

• AIS service declaration:

  The AIS service is declared as a Primary Service with the Service UUID 0xFEB3.

• AIS characteristics:

  The AIS service includes the following five characteristics.

  Characteristic name	Characteristic UUID	Required	Property	Permission
  Read Characteristics	0xFED4	Yes	Read	Read
  Write Properties	0xFED5	Yes	Read or Write	Write
  Features	0xFED6	Yes	Read or Indicate	None
  WriteWithNoRsp Property	0xFED7	Yes	Read or Write with No Response	Write
  Notification Characteristics	0xFED8	Yes	Read or Notify	None

Data transmission specification

Because Bluetooth 4.0 can send only 20 bytes of valid data at a time, a packet larger than 20 bytes cannot be sent at once. Long data packets must be split before they are sent and reassembled upon receipt.

• Maximum data length per packet

  The following table shows the application layer data length and the specification data length for different Bluetooth versions. In this topic, N represents the specification data length.

  BLE version	Application layer data length	Specification data length (N)
  BLE 4.0	20	16
  BLE 4.2	244	240
  BLE 5.0	244	240

• Data format
  • Each data packet consists of a Header and a Payload.
  • The Header is 4 bytes long and contains information such as message indicators, message length, sequence number, and the total number of split packets.
  • The Payload is 0 to N bytes long.
  • If a message is longer than N bytes, it is split into multiple frames. The frames are reassembled at the receiving end based on the information in the Header.
  • The Header is 4 bytes, and the Payload data length is 0 to N bytes. Therefore, the total packet length is between 4 and 4+N bytes.

  Header	Payload
  4 bytes	0 to N bytes

• Detailed data format definition
  • Header Byte 0: Data encryption flag, message ID indicator, and other information. The details are as follows.

    Bit order	Description	Notes
    0 to 3	Message ID (Msg ID)	The message ID increments by 1 for each message sent. If a message requires an acknowledgement, the message ID of the acknowledgement must match the message ID of the request. If the ID exceeds 15, it automatically loops back to 1.
    4	Data encryption indicator	Set to 0.
    5 to 7	Version information	Set to 0.

  • Header Byte 1: Instruction type. The following table provides examples of instruction definitions for interactions between the Bluetooth device application layer and the mobile app.

    Category	Instruction	Description
    Device-initiated report	0x01	Device status actively reported by the Bluetooth device.
    Request-Response model	0x02	A request instruction sent by the mobile app that requires a response from the device. Corresponds to 0x03.
    Request-Response model	0x03	The Bluetooth device responds to a request instruction. Corresponds to 0x02.
    Request-Response model	0x04	A request instruction sent by the Bluetooth device that requires a response from the mobile app. Corresponds to 0x05.
    Request-Response model	0x05	The mobile app responds to a request instruction. Corresponds to 0x04.
    Abnormal report	0x0F	Abnormal instruction notification. Used by the Bluetooth device to notify the mobile app that the device received an incorrect instruction or a process error occurred.
    Other instructions	-	Other instructions defined to meet business requirements. They are divided into two types: Instruction set for connection establishment. For more information, see Connection establishment instruction set Instruction set for over-the-air (OTA) upgrades. For more information, see OTA instruction set

    Note Device-initiated reports and Request-Response model instructions are general instructions. The Payload format is not restricted and can be user-defined. If a Bluetooth device receives an incorrect instruction, it must discard the instruction and notify the mobile app of the error using instruction 0x0F.
  • Header Byte 2: Message frame count and frame sequence number. The details are as follows.

    Bit order	Description	Notes
    0 to 3	Frame sequence number	The value is from 0 to 15. The frame sequence number starts from 0.
    4 to 7	Total number of split frames	The value is from 0 to 15. The actual total number of split frames is the value of Bits 4 to 7 plus 1. If the Payload is empty, Byte 2 and Byte 3 of the Header are all zeros.

  • Header Byte 3: Frame data length.

    The data length is 0 to 16 for Bluetooth 4.0, and 0 to 240 for Bluetooth 4.2 and later versions.

  • Payload: Valid data.

    The Payload is also transmitted in little-endian format.

  • Message ID (MsgID): The MsgID is used to match request instructions and response instructions between the device and the app. It is maintained internally by the SDK.

    When the device actively reports its status, the MsgID must be set to 0. When the app sends an instruction that requires a response, the device must save the MsgID and include the same MsgID in the response instruction. The value of MsgID ranges from 1 to 15. Each time the app sends an instruction that requires a device response, the MsgID increments by 1. When it reaches 15, it loops back to 1. For Over-the-Air (OTA) upgrade scenarios, the MsgID is always set to 0.

• Data length

  A split Bluetooth data packet cannot have more than 16 frames. For Bluetooth 4.0, the maximum length of each packet is 16 bytes. Therefore, the total data length cannot exceed 256 bytes. For Bluetooth 4.2 and later, the total data length cannot exceed 3840 bytes. The firmware length for an OTA upgrade is not subject to this limit.

• Data sending and receiving specification

  Data is sent and received by a Bluetooth device serially. This process is maintained by the SDK. A complete message, which may be split into multiple packets, must be fully sent before the next message can be sent or received.

Security authentication

Security authentication allows the device and the mobile phone to verify each other's identity to prevent counterfeiting. This feature is intended for devices or scenarios with high security requirements. Security authentication relies on cloud-based capabilities. For devices that use security authentication, the third bit of the FMSK field in the broadcast packet must be set to 0b1. The mobile phone performs the security authentication process each time it connects. After successful security authentication, data transmission between the mobile phone and the device is encrypted. Security authentication is optional. You can choose whether to use it based on the security requirements of the device or specific business scenarios.

Algorithm and security notes

• Product ID, MAC address, and Secret are values allocated by the cloud and are pre-flashed onto the device. To ensure security, the Secret is not transmitted over the air or passed to the mobile phone.
• Random is defined as a 16-byte random string. A new Random value must be generated for each authentication.
• Define BLE Key = SHA256(Random,PID,MAC,Secret). This means you concatenate the string values of Random, PID, MAC, and Secret, calculate the SHA256 digest, and use the first 16 bytes of the result.
• Define Cipher = AES128BLE Key(Random). To generate the Cipher, encrypt Random using the BLE Key and the AES-128 CBC algorithm, and then take the first 16 bytes of the ciphertext.
• After successful security authentication, data is transmitted as ciphertext. The data is encrypted using the AES-128 CBC algorithm with the BLE Key.
• During the authentication process, the cloud verifies that the device identity has not changed and that the device is a legitimate device belonging to a valid user.
• Each time the mobile phone connects, it requests the generation of a new BLE Key. After each disconnection, the device and the mobile phone must purge the currently used BLE Key.
• The following table provides an example of the parameters for the BLE Key calculation process:

  Data field	Data format and example	Input string for calculation
  Random	Random string: "drfiHgbsvomOieog"	"drfiHgbsvomOieog"
  Product ID	Decimal value: 168930, corresponding hexadecimal value: 0x293e2	"000293e2"
  MAC Address	"AB:CD:F0:F1:F2:F3" (MAC address of the scanned Bluetooth device)	"abcdf0f1f2f3"
  Secret	String: "atFY1tGDCxxxxx3PvBI5WXb"	"atFY1tGDCxxxxx3PvBI5WXb"
  String after concatenation with commas	"drfiHgbsvomOieog,000293e2,abcdf0f1f2f3,atFY1tGDCxxxxx3PvBI5WXb"

Connection establishment flow

Connection establishment instruction set

• CMD 0x10

  The mobile phone starts the authentication process and sends the Random value to the device.

  CmdType (1 byte)	Total Frame & Seq (1 byte)	Length (1 byte)	Payload description (1 byte)
  0x10	0x00	0x10	16-byte Random data

  Note A value of 0x00 in the Total Frame & Seq field indicates that the message consists of a single frame.
• CMD 0x11

  The device performs the authentication process, generates the Cipher ciphertext, and sends the ciphertext to the mobile phone.

  CmdType (1 byte)	Total Frame & Seq (1 byte)	Length (1 byte)	Payload description (1 byte)
  0x11	0x00	0x10	16-byte Cipher data

• CMD 0x12

  The mobile phone sends the verification result to the device.

  CmdType (1 byte)	Total Frame & Seq (1 byte)	Length (1 byte)	Payload description (1 byte)
  0x12	0x00	0x01	0x00: Success. 0x01: Failed.

• CMD 0x13

  The device returns the result of the BLE Key processing to the mobile phone.

  CmdType (1 byte)	Total Frame & Seq (1 byte)	Length (1 byte)	Payload description (1 byte)
  0x13	0x00	0x01	0x00: Success. 0x01: Failed.

  Note The MsgID of the 0x13 instruction must be the same as the MsgID in the 0x12 instruction.
• CMD 0x14

  The mobile phone notifies the device that provisioning is successful.

  CmdType (1 byte)	Total Frame & Seq (1 byte)	Length (1 byte)	Payload description (1 byte)
  0x14	0x00	0x01	Notifies the device of the provisioning/detaching result. 0x00: Detach. 0x01: Provision.

• CMD 0x15

  The device replies with a successful provisioning result.

  CmdType (1 byte)	Total Frame & Seq (1 byte)	Length (1 byte)	Payload description (1 byte)
  0x15	0x00	0x01	Provisioning/detaching success ACK 0x01

  Note The MsgID of the 0x15 instruction must be the same as the MsgID in the 0x14 instruction.

Mapping between connection establishment instructions and characteristics

References

• Bluetooth 4.2 Core Specification
• Bluetooth Core Specification Supplement v5