This topic describes the Bluetooth Mesh extension message definitions for smart home devices. These definitions allow more smart home devices to connect to the IoT Platform using Bluetooth Mesh technology. Both proprietary brand projects and Tmall Genie ecosystem projects follow this protocol.
Background information
The SIG Mesh models defined by the Bluetooth Special Interest Group (Bluetooth SIG) do not cover all smart home devices. This protocol uses a vendor-defined model (Vendor Model) to control smart home devices and report their status. In Tmall Genie ecosystem projects, the Mesh gateway includes Tmall Genie speakers and the Tmall Genie app. In proprietary brand projects, the Mesh gateway includes proprietary brand gateway products and the Cloud Intelligence app. Note that some of the following messages are supported only in Tmall Genie ecosystem projects.
Vendor Model
The Bluetooth SIG defines the Vendor Model format as 4 bytes. This includes a 2-byte Company ID and a 2-byte vendor-assigned Model ID. Alibaba's Company ID is 0x01A8, as shown in the following table.
| Field | Bytes | Description |
| 16-bit Company Identifier | 2 | 0x01A8 |
| 16-bit vendor-assigned model Identifier | 2 | - |
The following table lists two Vendor Model IDs used for message extension.
| Model Name | SIG Model ID |
| Vendor Model Server | 0x01A80000 |
| Vendor Model Client | 0x01A80001 |
Extension message opcodes
- The most significant bit of a 1-byte opcode is 0. This results in a value range from 0x00 to 0x7E. The value 0x7F is reserved for future extensions.
- For a 2-byte opcode, the most significant bit of the first byte is 1, and the second bit is 0. This results in a value range from 0x8000 to 0xBFFF. These opcodes are assigned by the Bluetooth SIG.
- For a 3-byte opcode, the two most significant bits of the first byte are 1. The next two bytes, z, represent the Company ID assigned by the Bluetooth SIG. The Company ID is transmitted in little-endian format. Alibaba's Company ID is 0x01A8. The 6-bit x allows a vendor to define 64 opcodes.
| Opcode Format | Description |
| 0b0xxxxxxx (excludes 0b01111111) | 1-byte opcode. |
| 0b01111111 | Reserved for future extensions. |
| 0b10xxxxxx xxxxxxxx | 2-byte opcode. |
| 0b11xxxxxx zzzzzzzz zzzzzzzz | 3-byte opcode. |
Opcode definitions
The opcodes for IoT Platform Bluetooth Mesh extension messages are defined in the following table.
| Vendor Message Name | Opcode |
| Vendor Message Attribute Get | 0xD001A8 |
| Vendor Message Attribute Set | 0xD101A8 |
| Vendor Message Attribute Set Unacknowledged | 0xD201A8 |
| Vendor Message Attribute Status | 0xD301A8 |
| Vendor Message Attribute Indication | 0xD401A8 |
| Vendor Message Attribute Confirmation | 0xD501A8 |
| Vendor Message Attribute Indication To Tmall Genie | 0xDE01A8 |
| Vendor Message Attribute Confirmation From Tmall Genie | 0xDF01A8 |
| Vendor Message Transparent msg | 0xCF01A8 |
| Vendor Message Transparent Indication | 0xCE01A8 |
| Vendor Message Transparent ACK | 0xCD01A8 |
Vendor Model property message structure
- Vendor Message Attribute Get This message is used by a Vendor Model Client to retrieve the values of one or more properties from a Vendor Model Server. The message format is as follows.
Field Bytes Description Opcode 3 0xD001A8 TID 1 Transaction Identifier. Incremented for each new message. Attribute Type 2 The type of attribute to read. There can be up to 15 Attribute Types. When a Vendor Model Server receives an Attribute Get message, it must reply to the Vendor Model Client with an Attribute Status message. If the Vendor Model Client does not receive the Attribute Status message from the Vendor Model Server after sending this command, it can resend the command.
- Vendor Message Attribute Set This message is used by a Vendor Model Client to set the values of one or more properties on a Vendor Model Server. The message format is as follows.
Field Bytes Description Opcode 3 0xD101A8 TID 1 Transaction Identifier. Incremented for each new message. Attribute Type 2 The type of attribute to set. Attribute Parameter N The parameter of the attribute to set. There can be up to 15 pairs of Attribute Type and Attribute Parameter. When a Vendor Model Server receives an Attribute Set message, it must reply to the Vendor Model Client with an Attribute Status message. If the Vendor Model Client does not receive the Attribute Status message from the Vendor Model Server after sending this command, it can resend the command.
- Vendor Message Attribute Set Unacknowledged This message is used by a Vendor Model Client to set the values of one or more properties on a Vendor Model Server. The message format is as follows.
Field Bytes Description Opcode 3 0xD201A8 TID 1 Transaction Identifier. Incremented for each new message. Attribute Type 2 The type of attribute to set. Attribute Parameter N The parameter of the attribute to set. There can be up to 15 pairs of Attribute Type and Attribute Parameter. When a Vendor Model Server receives an Attribute Set Unacknowledged message, it does not need to send an Attribute Status message to the Vendor Model Client.
- Vendor Message Attribute Status This message is used by a Vendor Model Server to reply to Attribute Get and Attribute Set commands, or to report device status information to a Vendor Model Client. The message format is as follows.
Field Bytes Description Opcode 3 0xD301A8 TID 1 Transaction Identifier. Incremented for each new message. Attribute Type 2 The type of attribute to report. Attribute Parameter N The parameter of the attribute to report. When a Vendor Model Client receives an Attribute Status message, it does not need to reply to the Vendor Model Server.
- Vendor Message Attribute Indication This message is used by a Vendor Model Server to send properties to a Vendor Model Client. The message format is as follows.
Field Bytes Description Opcode 3 0xD401A8 TID 1 Transaction Identifier. Incremented for each new message. When replying to a control command, the TID is the same as the TID of the received message. When actively reporting a device status change, the TID loops from 128 to 191. Attribute Type 2 The type of attribute to report. Attribute Parameter N The parameter of the attribute to report. There can be up to 15 pairs of Attribute Type and Attribute Parameter. When a Vendor Model Client receives an Attribute Indication message, it must reply to the Vendor Model Server with an Attribute Confirmation message. If the Vendor Model Server does not receive the confirmation from the Vendor Model Client after sending this command, it can resend the command.
- Vendor Message Attribute Confirmation This message is used by a Vendor Model Client to reply to a Vendor Model Server. It indicates that the Indication message from the Vendor Model Server has been received. The message format is as follows.
Field Bytes Description Opcode 3 0xD501A8 TID 1 Transaction Identifier. The TID of the received Indication message. When a Vendor Model Server receives an Attribute Confirmation message, it does not need to reply to the Vendor Model Client.
- Vendor Message Attribute Indication To TmallGenie This message is used in Tmall Genie ecosystem projects for a Vendor Model Server to send properties to a Vendor Model Client. The message is processed directly by the Tmall Genie speaker. The message format is as follows.
Field Bytes Description Opcode 3 0xDE01A8 TID 1 Transaction Identifier. Incremented for each new message. Attribute Type 2 The type of attribute to report. Attribute Parameter N The parameter of the attribute to report. There can be up to 15 pairs of Attribute Type and Attribute Parameter. When a Vendor Model Client receives an Attribute Indication message, it must reply to the Vendor Model Server with an Attribute Confirmation message. If the Vendor Model Server does not receive the Confirmation from the Vendor Model Client after sending this command, it can resend the command.
- Vendor Message Attribute Confirmation From TmallGenie This message is used in Tmall Genie ecosystem projects for a Vendor Model Client to reply to a Vendor Model Server. It indicates that the Tmall Genie speaker has received the Indication message from the Vendor Model Server. The message format is as follows.
Field Bytes Description Opcode 3 0xDF01A8 TID 1 Transaction Identifier. Incremented for each new message. Attribute Type 2 The type of attribute to set. Attribute Parameter N The parameter of the attribute to set. The number of Attribute Type and Attribute Parameter pairs can range from 0 to 15. When a Vendor Model Server receives an Attribute Confirmation message, it does not need to reply to the Vendor Model Client.
Vendor Model pass-through message structure
- Vendor Message Transparent Message This message is used for pass-through data transmission between Mesh devices, Tmall Genie speakers, and the Tmall Genie app. The payload data format is defined by each vendor.
Field Bytes Description Opcode 3 0xCF01A8 TID 1 Transaction Identifier. Incremented for each new message. When replying to a control command, the TID is the same as the TID of the received message. When actively reporting a device status change, the TID loops from 0 to 255. Payload N Defined by the vendor. - Vendor Message Transparent Indication This message is used in Tmall Genie ecosystem projects for a Vendor Model Server to send pass-through data to a Vendor Model Client. The message format is as follows.
Field Bytes Description Opcode 3 0xCE01A8 TID 1 Transaction Identifier. Incremented for each new message. When replying to a control command, the TID is the same as the TID of the received message. When actively reporting a device status change, the TID loops from 128 to 191. Payload N Defined by the vendor. - Vendor Message Transparent ACK This message is used in Tmall Genie ecosystem projects for a Vendor Model Client to reply to a Vendor Model Server. It indicates that the Transparent Indication from the Vendor Model Server has been received. The message format is as follows.
Field Bytes Description Opcode 3 0xCD01A8 TID 1 Transaction Identifier. The TID of the received Indication message.
Vendor Message example data
- Vendor Model Client sets the target temperature
This example shows a Vendor Model Client setting the target temperature to 22 degrees Celsius.
- The Vendor Model Client sends an Attribute Set command to set the target temperature.
0xD1 0xA8 0x01 0x01 0x0C 0x01 0x4B 0x73 Opcode TID Attribute Type Attribute Value 0xD101A8 01 Target temperature (0x010C) Target temperature value: 22 degrees Celsius (0x734B = 295.15 K) - If the Vendor Model Server successfully sets the target temperature, it returns the following Attribute Status.
0xD3 0xA8 0x01 0x01 0x0C 0x01 0x4B 0x73 Opcode TID Attribute Type Attribute Value 0xD301A8 01 Target temperature (0x010C) Target temperature value: 22 degrees Celsius (0x734B = 295.15 K) - If the Vendor Model Server fails to set the target temperature, it returns the following Attribute Status.
0xD3 0xA8 0x01 0x01 0x00 0x00 0x0C 0x01 0x80 Opcode TID Error Code Type Attribute Type Error Code 0xD301A8 01 0x0000 Target temperature (0x010C) Status code: Device not ready (0x80)
- The Vendor Model Client sends an Attribute Set command to set the target temperature.
- Vendor Model Client reads data
This example shows a Vendor Model Client reading the front-back position, current temperature, and current humidity.
- The Vendor Model Client sends an Attribute Get message to read the front-back position, current temperature, and current humidity properties.
0xD0 0xA8 0x01 0x01 0x10 0x01 0x0D 0x01 0x0F 0x01 Opcode TID Attribute Type Attribute Type Attribute Type 0xD001A8 01 Front-back position (0x0110) Current temperature (0x010D) Current humidity (0x010F) - If the Vendor Model Server successfully reads the three properties, it returns the following Attribute Status.
D3 A8 01 01 10 01 32 0D 01 4B 73 0F 01 2D 00 Opcode TID Attribute Type Attribute Value Attribute Type Attribute Value Attribute Type Attribute Value 0xD301A8 01 Front-back position (0x0110) Front-back position: 50 (0x32) Current temperature (0x010D) Current temperature: 22 degrees Celsius (0x734B=295.15 K) Current humidity (0x010F) Current humidity: 45% (0x002D) - If the Vendor Model Server fails to read the temperature, it returns the following Attribute Status.
D3 A8 01 01 10 01 32 00 00 0D 01 81 0F 01 2D 00 Opcode TID Attribute Type Attr. Value Error Code Type Attribute Type Error Code Attribute Type Attribute Value 0xD301A8 01 Front-back position Front-back position: 50 (0x32) 0x0000 Current temperature (0x010D) Error code: Unsupported property (0x81) Current humidity Current humidity value: 45% (0x002D)
- The Vendor Model Client sends an Attribute Get message to read the front-back position, current temperature, and current humidity properties.
- Vendor Model Server reports temperature
This example shows a Vendor Model Server reporting the temperature to a Vendor Model Client.
- The Vendor Model Server sends an Attribute Indication message to report the temperature.
0xD4 0xA8 0x01 0x80 0x0D 0x01 0x4B 0x73 Opcode TID Attribute Type Attribute Value 0xD401A8 80 Current temperature (0x010D) Current temperature value: 22 degrees Celsius (0x734B = 295.15 K) - After the Vendor Model Client receives the Attribute Indication, it sends the following Confirmation.
0xD5 0xA8 0x01 0x80 Opcode TID 0xD501A8 80
- The Vendor Model Server sends an Attribute Indication message to report the temperature.
- Vendor Model Server reports a water leak fault
This example shows a Vendor Model Server reporting a water leak fault to a Vendor Model Client.
- The Vendor Model Server sends an Attribute Indication message to report the water leak fault.
0xD4 0xA8 0x01 0x80 0x09 0xF0 0x00 0x00 0x00 0xAA Opcode TID Attribute Type Attribute Value Error Code Type Error Code Value 0xD401A8 80 Event (0xF009) Fault event (0x00) Error code property (0x0000) Error code: Water leak fault (0xAA) - After the Vendor Model Client receives the Attribute Indication, it sends the following Confirmation.
0xD5 0xA8 0x01 0x80 Opcode TID 0xD501A8 80
- The Vendor Model Server sends an Attribute Indication message to report the water leak fault.