Bluetooth Mesh module software specifications

Glossary

Basic requirements

• Bluetooth Mesh devices must support PB-ADV and PB-GATT.

• Bluetooth Mesh devices must support the Proxy feature defined in the Mesh protocol.

• Non-low-power Bluetooth Mesh devices must support the Relay feature defined in the Mesh protocol. This feature must be configurable to be enabled or disabled.

• The LPN and Friend features are optional.

• Low-power control devices, such as those supporting switch properties and downstream control, must use the Genie Low Power (GLP) solution.

• Bluetooth Mesh devices must support at least one NetKey and two AppKeys.

• If a product requires only a subset of features, the required features will be specified in the product specifications.

UUID format

The Universally Unique Identifier (UUID) is used in Unprovisioned Device Beacon and PB-GATT broadcasts. The Device UUID in the advertising packet is the key information for identifying a device. The fields in the UUID are stored in little-endian format. The Device UUID is defined as follows.

Bluetooth Mesh advertising packet format

• Unprovisioned Device Beacon

  After a Bluetooth Mesh device powers on in an unprovisioned state, it must broadcast an Unprovisioned Device Beacon. Each broadcast must last for at least 120 ms, with an interval of 500 ms. The broadcast duration is typically 10 minutes. The specific broadcast start method and duration depend on the product requirements. If the device is not provisioned before the timeout, it stops the PB-ADV broadcast.

  The following is an example of unprovisioned broadcast data:

  0x14	0x2B	0x00	A8 01 71 81 02 00 00 55 43 CB 07 DA 78 02 00 00	0x00	0x00
  	Mesh Beacon	Unprovisioned Device beacon	Device UUID	OOB Information
  Length	Type	Beacon Type	Beacon Data
  Advertising data header		Advertising data payload

• PB-GATT broadcast

  Devices that do not support PB-ADV, such as mobile phones, must first establish a GATT connection with a node and communicate through the Mesh Provisioning Service. Therefore, before establishing a GATT connection, the device must broadcast a PB-GATT advertising packet. The UUID in the GATT advertising packet must also follow the UUID format. For more information about the PB-GATT broadcast data format, see the Mesh Profile Specification.

  PB-GATT broadcast sending rules follow the BLE broadcast sending rules. The recommended interval for each broadcast is 100 ms to 160 ms.

• AIS broadcast

  For more information about AIS broadcasts, see Bluetooth BLE basic specifications.

  AIS broadcast sending rules follow the BLE broadcast sending rules. The recommended interval for each broadcast is 100 ms to 160 ms.

• Proxy broadcast

  For more information about the Proxy broadcast data format, see the Mesh Profile Specification.

  Proxy broadcast sending rules follow the BLE broadcast sending rules. The recommended interval for each broadcast is 100 ms to 160 ms.

Advertising packet sending rules

• Device state and switching rules

  Device states include unprovisioned broadcast state, provisioning state, and provisioned state.

  • When an unprovisioned device powers on, it must enter the unprovisioned broadcast state. The default broadcast duration is 10 minutes. The specific broadcast start method and duration depend on the product requirements.

  • If a device is unprovisioned through an app, or if its provisioning information (including Mesh network information, heartbeat configuration, and multicast configuration) is cleared by a hardware reset, the device must re-enter the unprovisioned broadcast state.

  • When the device responds to a connection establishment request (by replying with a link ACK or establishing a connection through PB-GATT), it enters the provisioning state.

  • When the device completes the provisioning process (marked by the Provisioning Complete event), it enters the provisioned state. Otherwise, it returns to the unprovisioned broadcast state.

• Unprovisioned broadcast state

  When a device is in the unprovisioned broadcast state, it must simultaneously broadcast the Unprovisioned Device Beacon, PB-GATT broadcast, and AIS broadcast.

• Network Provisioning Status

  A device can establish only one provisioning connection (Mesh or GATT) at a time. During provisioning, the device stops broadcasting the Unprovisioned Device Beacon and other GATT advertising packets.

• Provisioned state

  When a device is in the provisioned state, it must no longer respond to provisioning connection establishment requests. It must also send proxy broadcasts and AIS broadcasts simultaneously.

Provisioning flow

The provisioning flow for Bluetooth Mesh devices follows the standard Bluetooth Mesh provisioning flow. The steps that use custom data are described as follows.

• Provisioning Capabilities stage

  In the Provisioning Capabilities stage, Bluetooth Mesh devices provide an Out-of-Band (OOB) method. Only the Static OOB method is supported. The AuthValue is calculated as follows:

  Extended AuthValue flag value	AuthValue calculation method
  0	The first 16 bytes of AuthValue = SHA256(ProductID,MAC,Secret)
  1	The first 16 bytes of AuthValueProvisioner = SHA256(ProductID,MAC,Secret,RandomProvisioner), and the first 16 bytes of AuthValueDevice = SHA256(ProductID,MAC,Secret,RandomDevice)

  Concatenate the device certificate's ProductID, MAC address, Secret, and the random number from the provisioning process into a comma-separated string. Then, calculate the SHA256 hash and use the first 16 bytes. Note that all English letters used for the SHA256 calculation must be lowercase. For private brand projects, the extended AuthValue flag must be 1.

  The following is an example of SHA256 calculation when the extended AuthValue flag is 0:

  Data field	Data format and example	Input string for calculation
  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"
  Device Secret	"53daed805bc534a4a93c825ed20a7063"	"53daed805bc534a4a93c825ed20a7063"
  Concatenated string for Device	"000293e2,abcdf0f1f2f3,53daed805bc534a4a93c825ed20a7063"
  SHA256 result output (HEX)	c1c76741553236fb7da0a586e62298c231dac2885e735feba6b8b4417c 7d9e72
  AuthValue (HEX)	c1c76741553236fb7da0a586e62298c2

  The following is an example of SHA256 calculation when the extended AuthValue flag is 1:

  Data field	Data format and example	Input string for calculation
  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	"53daed805bc534a4a93c825ed20a7063"	"53daed805bc534a4a93c825ed20a7063"
  RandomDevice	"7889b0af417b967bdcd7b814d2bbffaf"	"7889b0af417b967bdcd7b814d2bbffaf"
  RandomProvisioner	"aa484b099ae4c7762fcb1b71968ba7df"	"aa484b099ae4c7762fcb1b71968ba7df"
  Concatenated string for Device	"000293e2,abcdf0f1f2f3,53daed805bc534a4a93c825ed20a7063,7889b0af417b967bdcd7b814d2bbffaf"
  SHA256 result output for Device (HEX)	0f66e504a5d3609c06db70162345a0375d9b9d71d4cbe346a1c55d5c25738329
  AuthValueDevice (HEX)	0f66e504a5d3609c06db70162345a037
  Concatenated string for Provisioner	"000293e2,abcdf0f1f2f3,53daed805bc534a4a93c825ed20a7063,aa484b099ae4c7762fcb1b71968ba7df"
  SHA256 Result: Device (HEX)	f45f15d1e38339b79fda5b63c3970ff01ba40285fe20b303ff332f54f8de729c
  Device Authentication Value (HEX)	f45f15d1e38339b79fda5b63c3970ff0

• Provisioning Confirmation stage

  In this stage, the IoT Platform and the Mesh device perform authentication using the Static OOB method. If the Confirmation values calculated by the IoT Platform and the Mesh device do not match, authentication fails and the process ends. In this stage of the Mesh protocol, the device generates a random number and sends it to the Mesh gateway. The Mesh gateway then sends this random number to the cloud for authentication. The IoT Platform saves the random number sent by the device. If the device sends a random number that has been used before, the platform rejects the device's provisioning request. Therefore, you must ensure that the random number generated each time is unique.

• Provisioning Data stage

  For multi-element devices, the IoT Platform only sends the Unicast Address of the Primary Element in this stage. The Unicast Addresses of the other elements are incremented by 1 from the address of the previous element.

• Provisioning Complete configuration stage

  After Provisioning Complete, the IoT Platform sends the AppKey. Other configurations vary depending on the UUID version.

  UUID version	Configuration method
  0	The IoT Platform sends a Config_Model_App_bind for the primary element. The device must return a success status, or provisioning will fail. The remaining models must bind the AppKey themselves. The IoT Platform sends a Config_Model_Subscription_Add for the primary element. The device must return a success status, or provisioning will fail. The remaining models must bind the Subscription Address themselves.
  1, 2	The IoT Platform does not send Config_model_app_bind and Config_Model_Subscrption_Add messages. The IoT device must bind the sent AppKey to all models of all elements itself. It must also subscribe each model to the corresponding multicast address based on the product type. For specific product category multicast addresses, see the software specifications for each product. After a Bluetooth Mesh device completes provisioning, it must report a message. The reported message includes all supported reportable properties of the device.

  Note

  Currently, third-party access mainly uses UUID version 1. Version 0 is no longer recommended. Version 2 is for Genie Mesh SDK use only.

Mesh data sending and receiving

• Data receiving

  Typically, we recommend setting the device's scan window, interval, and period to 10 ms, 10 ms, and 100 ms, respectively.

• Data sending

  Each Mesh data packet transmission lasts for approximately 200 ms, with a 20 ms interval between packets. Data is sent simultaneously on the three advertising channels: 37, 38, and 39. When sending a long packet, after each segmented packet is sent according to the preceding timing, the next segmented packet is sent immediately.

  When sending a long packet, each segmented packet is sent for 200 ms according to the preceding timing. After the first segmented packet is sent, the second segmented packet is sent immediately. After sending the segmented packets in order, you can wait for a few milliseconds before retransmitting if needed. The retransmission interval must not be less than 400 ms. We recommend that you calculate it as follows: Retransmission interval = (200 ms + 100 ms × TTL + 200 ms × Number of segments). The recommended Time to Live (TTL) for sending data is 5 or less.

Device status reporting

• When a device's property changes, it must send a Vendor Message Attribute Indication or Vendor Message Attribute Status message containing the updated property value to the Mesh gateway's subscription address (0xF000).

  • If the property value to be reported is important and requires a reply from the Mesh gateway before transmission stops, such as a security alarm message, send a Vendor Message Attribute Indication message.

  • When a device needs to report property values periodically, it must send a Vendor Message Attribute Status message, not a Vendor Message Attribute Indication message.

  • For reported messages that have little impact on business logic, such as the device firmware version number, we recommend that you send a Vendor Message Attribute Status message.

• Vendor Message Attribute Indication message sending rule

  After sending an Indication message, enable scanning. If a Vendor Message Attribute Confirmation message from the Mesh gateway is received within the retransmission interval, stop sending. Otherwise, retransmit the message several times until a Confirmation message is received. For more information about the retransmission interval, see Mesh data sending and receiving.

• Vendor Message Attribute Status message sending rule

  • To reduce unnecessary message sending, limit the number of retransmissions for messages that have little impact on business logic.

  • If a device needs to report property values periodically, the period must be at least tens of seconds. The sending period should ideally be dynamically adjustable.

• Property synchronization for devices without periodic property reporting

  When a device receives a downstream control instruction, it first replies with the corresponding status message as required by the protocol. If the device's status changes, it reports the new device status using an Indication message. The interaction flow is shown in the following figure.

  

• Property synchronization for devices with periodic property reporting

  When a device receives a downstream control instruction, it first replies with the corresponding status message as required by the protocol. If the device's status changes, it waits for the next reporting period to report the new device status. The interaction flow is shown in the following figure.

  

• Proactive device reporting scenario

  If the device status changes for other reasons, such as a direct user operation on the device or the device meeting certain conditions, the device must proactively report its current status by sending a Vendor Message Attribute Indication or Vendor Message Attribute Status message. You only need to report the specific changed status, not all device properties. If a device needs to report its status periodically and continuously, such as a temperature and humidity sensor, water shortage report, or material shortage report, the reporting period for such messages must be greater than 30 seconds. The content of the report is determined by each device based on the business scenario. In principle, less data is better. If the reporting frequency is too high, the product's upstream link may be restricted.

  

Device seq rules

• Bluetooth Mesh devices must differentiate the sequence number (seq) for different unicast addresses. We recommend that you support seq storage for at least 10 unicast addresses. The seq for each address must be continuously updated while the device is powered on.

• When a multi-element device is re-provisioned, we recommend that you save the seq of each address before provisioning and restore it after re-provisioning.

TID specification

If a Mesh message contains a Transaction Identifier (TID) field, such as a Generic OnOff Set instruction or a Vendor Message Attr Set instruction, the following rules must be followed.

• All related services must use the same TID. For example, if a device receives a set or query instruction, the TID in the status message replied by the device, if any, must be the same as the TID in the downstream set or query instruction.

• The TID range for proactive upstream messages from the device is 128 to 191 (0x80 to 0xBF).

• When a Mesh device receives a message sent to it or a group it belongs to, it records the TID. If the device receives another message with the same TID within 6 seconds, it ignores the later message. The device must reply with the corresponding status message, but the service layer does not process the message. The recorded TID is discarded after 6 seconds.

• If the destination of a message is not the device or a group the device belongs to, the device ignores the message and does not record the TID.

Multicast addresses

• Each element of a Bluetooth Mesh device must support at least 8 multicast addresses. If a Bluetooth Mesh device receives a Config Model Subscription Add Message and finds that the multicast addresses stored for that element are full, it must discard the new multicast address as specified in the Mesh Profile Specification. It must also return the error code 0x05 (Insufficient Resources) in the Status Code field of the Config Model Subscription Status Message.

• For more information about the default product category multicast addresses, see the definitions in Device multicast addresses. During the Provisioning Complete configuration stage, the device must bind all models of all its elements to the corresponding multicast addresses.

• When a user configures the device's location or alias, the IoT Platform modifies the device's multicast address subscription. During this process, the IoT Platform adds or deletes a multicast address subscription (Config Model Subscription Add or Config Model Subscription Delete) for one model of an element on the device. The device must synchronize the received multicast address configuration (add or delete) to all models on that element.

Heartbeat feature

• Bluetooth Mesh devices must support the heartbeat feature. For more information about specific configuration messages, see the Mesh Profile Specification.

• For devices that support the heartbeat feature, heartbeat settings are configured by setting parameters for the device's primary element. The device must send corresponding heartbeat packets strictly according to the configured parameters. For more information about sending rules, see Mesh data sending and receiving.

• If the number of heartbeat packet transmissions in the heartbeat parameters is set to infinite, the device must save the heartbeat parameters. After the device is powered off or restarted, it must reload these parameters.

Generic OnOff Server Model

IV Index Update

Device power-on and restart specifications

• After a Bluetooth Mesh device powers on, it must delay for a random period of 0 to 10 seconds before it sends a Vendor Message Attribute Indication or Vendor Message Attribute Status message. The reported message must include all supported reportable properties of the device (required) and the power-on event (optional). Note that the device properties and the power-on event must be reported separately. You must report the device properties first, and then the power-on event. The following is an example of a device power-on event.

  0xD4	0xA8	0x01	0x80	0x09	0xF0	0x03
  Opcode			TID	Attr Name		Event
  0xD401A8			0x80	Event report		Device power-on

• The Bluetooth Mesh device restart specification follows the device power-on specification. A device restart is treated as a device power-on.

Device reset specifications

After a device is reset and then provisioned again, it must reconfigure the multicast according to the default configuration defined in the product's specification during the Provisioning Complete configuration stage. When a device is reset, it decides whether to delete the device application configuration information, such as the fan's switch state or the temperature settings for different zones of a refrigerator, based on the product's specification. If a GATT connection exists when a device is reset, all GATT connections must be disconnected.

• Software reset (unprovisioning)

  Bluetooth Mesh devices must support node removal using a soft reset with Config Node Reset. When a device performs a software reset, it removes the saved provisioning information and enters the unprovisioned broadcast state. It also decides whether to delete the device configuration information based on the product's features. If the device needs to be restarted during the software reset process, the restart must have minimal impact on the device's normal operation.

• Hardware reset (factory reset)

  When a Bluetooth Mesh device is reset to its factory settings using a hardware reset, it must remove the saved provisioning information and enter the unprovisioned broadcast state. When you perform a hardware reset, the device must first report a hardware reset event using a Vendor Message Attribute Indication message. After the report is complete, the hardware reset action is performed. The hardware reset action includes deleting provisioning information and entering the unprovisioned broadcast state. If no corresponding reply is received for the report message, the reporting must last for at least 3 seconds.

  0xD4	0xA8	0x01	0x80	0x09	0xF0	0x23
  Opcode			TID	Attr Name		Event
  0xD401A8			0x80	Event report		Hardware reset

OTA update

Modules must support BLE OTA updates based on their product form. For more information, see Bluetooth BLE OTA specifications.

Genie Low Power (GLP)

If a module is used in a low-latency, low-power device that receives downstream data, such as a single-live-wire switch or a battery-powered curtain motor, you can use the Genie Low Power (GLP) solution. When you create a product on the IoT Platform, select Genie Low Power in the properties. This way, when Tmall Genie sends data to this device, it continuously sends data for 1.2 seconds. Therefore, the device only needs to wake up for 60 ms every 1.2 seconds to receive data from Tmall Genie in a timely manner while in a low-power state.

Compared with the LPN solution that requires a connection between the LPN and the Friend node, the GLP solution does not require a connection. The sleep and active duty cycle is fixed, which allows for precise calculation of the device's standby power consumption.

Custom low power

If a module is used in a low-power device that uploads upstream data, such as a battery-powered door sensor or infrared sensor, you can use the custom low-power solution. When you create a product on the IoT Platform, select custom low power in the properties. You can customize the data reporting solution based on device requirements, such as trigger-based reporting or custom timed reporting. Users can modify the reporting solution based on standard protocols. Note that if you use the custom low-power solution, the device cannot maintain a real-time connection with Tmall Genie, and information sent by Tmall Genie cannot reach the device. However, information reported by the device can reach Tmall Genie. This is an important difference from the GLP solution.