This topic addresses common questions and provides troubleshooting methods for Bluetooth mesh development.
Question: Tmall Genie reports that the device cannot be found
Check the following items:
Check whether the mesh device is broadcasting an Unprovisioned Device Beacon.
Check whether the UUID in the Unprovisioned Device Beacon conforms to the UUID format.
Check whether the broadcast frequency of the Unprovisioned Device Beacon complies with the specifications in Mesh data sending and receiving.
Question: Tmall Genie reports a device type that does not match the actual product
Check whether the Product ID in the UUID of the Unprovisioned Device Beacon is correct. The Product ID from the console and the downloaded Product ID are in decimal format, which you must convert to hexadecimal format for use. For more information about the format, see UUID format.
Question: Tmall Genie reports a network provisioning failure
Check the following items:
Check whether the device certificate, which includes the Product ID, MAC address (Device Name), and Device Secret, is flashed correctly.
Ensure that the Tmall Genie speaker has a stable Wi-Fi connection.
Verify that the entire process is correct. For more information, see Network provisioning flow.
Ensure that the Provisioning Capabilities calculation complies with the specifications.
Check for duplicate random numbers.
During the configuration phase after provisioning is complete, check whether the device sends a success status message back to Tmall Genie.
Check whether the device can receive broadcast messages from the Tmall Genie speaker.
Question: The Tmall Genie app cannot find the device during network provisioning
Check the following items:
Check whether the device certificate, which includes the Product ID, MAC address (Device Name), and Device Secret, is flashed correctly.
Check whether you have configured the network provisioning guide page for the product in the IoT Platform console under User Interaction.
Ensure that the features for mobile app provisioning and proxy connections are enabled in the device firmware. If you are developing based on the Tmall Genie Mesh SDK, check whether the `CONFIG_BT_MESH_PB_GATT` and `CONFIG_BT_MESH_GATT_PROXY` macros are enabled.
Question: Low success rate for network provisioning
If the network provisioning success rate is low during module or product testing, or if provisioning frequently fails on certain mobile phone models, check the following items:
Ensure that the module has undergone frequency offset calibration or that the correct frequency offset parameters are set. To verify this, you can use Ellisys software to capture over-the-air packets from the device and check the Initial Center Frequency parameter in the RF Channel information. Ensure that the actual frequency offset is within the range of -40 kHz to +40 kHz. A large frequency offset can cause a high failure rate with some mobile phone models.
If failures occur continuously, ensure that the speaker has a stable Wi-Fi connection.
When a provisioning failure occurs, check for duplicate random numbers.
Question: After a local hardware reset, the device is not reported as detached or deleted when a Tmall Genie speaker is present
If the speaker does not provide a voice prompt that the device is detached and the device is not deleted from the device list in the app after a local hardware reset, check the following items:
Check whether the hardware reset event (`hardwareReset`, `0x0023`) is defined in the product's feature definitions. If it is not, add it.
Check whether the firmware includes logic to report the hardware reset event and performs several retransmissions. For more information, see Device reset specifications.
Verify that the speaker's Wi-Fi network connection is working correctly.
Question: A local hardware reset is not reported successfully when no Tmall Genie speaker is online
When no Tmall Genie speaker is online, the Tmall Genie app forwards the device's hardware reset event to the server-side. Ensure that the device can communicate with the Tmall Genie app and that the test phone has an active internet connection. If these conditions are not met, the hardware reset event cannot be reported.
Question: After successful provisioning, voice control feedback indicates that a feature is uncontrollable or unsupported
Check the following items:
On the feature definition page for the product in the IoT Platform, check whether the correct properties have been added.
Try sending instructions using the online debugging feature on the device debugging page of the IoT Platform instead of using voice control.
Question: After successful provisioning, voice control feedback indicates success, but the device does not respond
Check the following items:
During the configuration phase after provisioning is complete, check whether the device is configured correctly based on its UUID version.
If you have access to device-side logs, check whether the network provisioning and binding were successful.
Check the distance between the device and the Tmall Genie, and remove any obstructions.
Send binary instructions using the online debugging feature on the device debugging page of the IoT Platform. Check whether the device receives the instructions.
Confirm whether multiple devices of the same type are attached to the account. Check whether the unresponsive device is configured with the correct multicast address for its category. For more information about category multicast addresses, see Device multicast addresses.
Question: The device executes a command from Tmall Genie correctly, but querying the device status from Tmall Genie results in an error
Check the following items:
Check whether the device-side has reported the correct device status to Tmall Genie.
After a status change, check whether the device-side uses a Vendor Model Indication to report the status to Tmall Genie. Also, check whether Tmall Genie sends a Confirmation message back to the device.
Question: Instructions sent from the online debugging feature on the IoT Platform device debugging page are ineffective
Check the following items:
Check whether the Tmall Genie selected for debugging is the one you are currently testing.
Check whether the device selected for debugging is the one you are currently using.
Check for format errors in the sent instructions.
Question: After successful provisioning, voice control feedback indicates the device is offline
Primarily, check whether the device complies with the Device power-on and restart specifications.
After the device powers on, check whether it reports its property values to Tmall Genie using an Indication and receives a Confirmation message.
After the device powers on, check whether it reports the power-on event to Tmall Genie using an Indication and receives a Confirmation message.
Question: When no Tmall Genie speaker is present, data sent from the device sometimes fails to reach the app
If you are developing with the TG7100B or TG_B_7101 module, upgrade the Mesh SDK to V1.2.6. For more information, see Obtain the SDK.
Question: When no Tmall Genie speaker is present, the app cannot control the device
Check the following items:
Check whether the macro that enables the Proxy feature is enabled in the device firmware. For example, the corresponding macro in the Tmall Genie Mesh SDK is `CONFIG_BT_MESH_GATT_PROXY`.
Check whether you selected the low-power option when you created the product. Low-power devices enter sleep mode, which prevents the app from controlling them.
Question: The OTA interface is stuck on "Connecting to device"
Refer to the Bluetooth BLE OTA specifications and check the following items:
Check whether the device's Bluetooth MAC address matches the Device Name in the device certificate. When you change the device certificate during development and debugging, ensure that you also change the MAC address accordingly.
Confirm whether the device is a low-power device. The device must first send broadcast packets to establish a GATT connection. If the device is in sleep mode, ensure that a wake-up mechanism exists and can correctly wake the device to send broadcast packets.
During an OTA update, the mobile app establishes a GATT connection with the device. Because devices typically allow only one GATT connection, check whether the device has an existing GATT connection that has not been disconnected.
Ensure that the module has undergone frequency offset calibration or that the correct frequency offset parameters are set. A large frequency offset can prevent some mobile phones from establishing a GATT connection.
Question: The OTA interface prompts that the device does not allow OTA updates
Refer to the Bluetooth BLE OTA specifications and check the following items:
Check whether the version number pushed from the IoT Platform is greater than the version number of the firmware that is currently flashed on the device.
Check whether the MAC address of the device that is receiving the OTA update matches the MAC address that is flashed in the device.
Ensure that the uploaded .bin file is correct. The device-side checks the file size and rejects the upgrade if the size exceeds the available flash storage for OTA.
Question: The device upgrades successfully, but the app reports a failure
Refer to the Bluetooth BLE OTA specifications and check the following items:
Ensure that the firmware version number that you entered in the console for the push matches the version number that is compiled in the firmware. Pay close attention to the version format. For more information about the version format definition, see Version format.
If the device has upgraded successfully and step 24 in the Interaction flow is complete, focus on troubleshooting steps 25 to 29.
Question: Do sensor products need to support GLP?
This depends on whether the sensor needs to support downstream setting instructions.
If the sensor only reports data and does not need to support downstream instructions, it does not need to support GLP. In this case, select "Non-low-power" instead of "Low-power" when you create the product.
If the sensor needs to support downstream setting instructions, you must evaluate whether to support GLP based on product interaction, user experience, and power consumption requirements. You can implement GLP according to the relevant specifications. If you implement GLP, select "Low-power" when you create the product. Alternatively, you can implement a manual wake-up method, such as a button press. The device remains awake for a set period, during which you can send setting instructions. The device returns to sleep mode after another button press or when a timeout occurs.