FAQ

1. Noun/Process Description

1.1 The difference between single backup OTA and dual backup OTA

Type	Single backup	Dual backup
Storage	In addition to the support space required for the project, Just add the space required by the loader	Required engineering support space * 2
Upgrade	Need to disconnect and reconnect once	No need to upgrade, no need to reconnect
Process	Download loader -> Device restart (run loader) -> Reconnect device -> Upgrading Firmware	Upgrading Firmware
Safety	There is a chance that a forced upgrade is required (Bluetooth disconnected, APP killed to terminate OTA, etc.)	No security risk
Cost	Lower	Higher

Warning

Products with dual backup mode cannot be changed to single backup OTA products through OTA for the time being.

The OTA mode can only be changed through the wire flash method.

1.2 The role of Boot Loader

The minimum system of the device, providing BLE operation and implementing OTA functions. It is used for single backup OTA upgrades. At the same time, it ensures that the device will not become a brick after an abnormality occurs in the OTA, and can be restored through upgrades.

A Dos operating system similar to Windows.

Warning

1. The boot loader needs to decide whether to go through the authentication process based on the configuration.

2. Currently the loader only supports BLE communication.

3. The loader only has the UUID service of OTA function

2. Access issues

2.1 The Bluetooth device is connected, why does calling the OTA library interface return an error, 4114(0x1012), the device is not connected

The Device not connected callback of the OTA library means that the OTA library was not initialized successfully and the device information was not obtained.

If the above situation occurs, you can follow the steps below to troubleshoot:

1. Confirm whether the device authentication status of the firmware and OTA library is consistent;

* Device authentication is only performed when the device is successfully connected and cannot be repeated.

2. Confirm whether the device connection status is correctly passed to the OTA library. Note: The connection status needs to be converted to 3.6   Status Code

* Make sure the device status you pass in is correct. Do not pass in the same device status repeatedly.

3. Confirm that the connection status of the received 3.4   Bluetooth event callback #``onConnection`` callback is StateCode#CONNECTION_OK

* Ensure that the OTA library is initially completed before performing OTA library interface operations

The OTA library will perform operations such as RCSP protocol initialization and device information synchronization when the client passes in the Device Connected state.

Warning

Device disconnection also needs to be passed to the OTA library in real time to release the resources of the related devices, otherwise it may affect the next OTA library initialization.

2.2 Error code: 12290(0x3002), Failed to send data

If the above situation occurs, you can follow the steps below to troubleshoot:

1. Please check the return result of BluetoothOTAManager#sendDataToDevice(device, data)

2.3 The data was sent successfully, but no reply data was received

Most of the command data in the OTA library is carried out in a “question-and-answer” manner.

If the above situation occurs, you can follow the steps below to troubleshoot:

1. Ensure that the communication channel is valid

* Ensure that the notification attribute of the UUID of the enabled device is

* Ensure that the device UUID for writing data is valid

2. Ensure the integrity of the sent data

* For BLE implementation, you need to use MTU packetization and queue-based data transmission. For details, refer to the SendBleDataThread in the demo.

2.4 Error code: 12295(0x3007), Timeout in sending data

Most of the command data in the OTA library is carried out in a “question-and-answer” manner.

When a command sent by the SDK does not receive a response within the specified time, the SDK will repeat it three times. If there is no response, the SDK will throw a Send command timeout error.

If the above situation occurs, you can follow the steps below to troubleshoot:

1. Ensure that the communication channel is valid

* Ensure that the notification attribute of the UUID of the enabled device is

* Ensure that the device UUID for writing data is valid

2. Ensure the integrity of the sent data

* For BLE implementation, you need to use MTU packetization and queue-based data transmission. For details, refer to the SendBleDataThread in the demo.

3. Ensure that data is correctly sent back to the OTA library

* The received data is sent back to the OTA library via 2.1.3.2   Passing received Bluetooth data

Warning

The OTA library will parse the commands belonging to the OTA process according to the data structure, and can directly pass in raw data.

2.5 Error code: 20481 (0x5001), Device authentication failed

The OTA library’s device authentication process occurs when the client passes in the Device Connected state and sets the conditions for starting device authentication.

If the above situation occurs, you can follow the steps below to troubleshoot:

1. Ensure that the device authentication status of the firmware and OTA library are consistent

* Ensure that the firmware has device authentication enabled, the OTA library also has device authentication enabled, and vice versa.

2. Ensure that the communication channel is valid

* Ensure that the notification attribute of the UUID of the enabled device is

* Ensure that the device UUID for writing data is valid

3. Make sure the incoming device status is correct

* Ensure that device status is not repeatedly transmitted

* Device authentication is only performed when the device is successfully connected and cannot be repeated. If the device has been authenticated, it will not respond to authentication data.

* Users should record the device authentication identifier to determine whether device authentication is required

2.6 Error code: 12296 (0x3008), response failed

After receiving the command, the device replies with a failed status based on its own reasons, indicating that the operation failed.

For specific reasons, please refer to 3.6.2   Reply Status

3. OTA Issues

3.1 Upgrade failed, error code: 12299(0x300B), waiting for command timeout

During the OTA process, the device continuously requests data from the SDK.

If the device does not request the next packet of data within 20 seconds before the OTA process is completed, the OTA library will report an error.

If the above situation occurs, you can follow the steps below to troubleshoot:

1. Ensure the integrity of the sent data

* For BLE implementation, you need to use MTU packetization and queue-based data transmission. For details, refer to the SendBleDataThread in the demo.

2. Ensure that the communication channel is valid

* Ensure that the notification attribute of the UUID of the enabled device is

* Ensure that the device UUID for writing data is valid

3. Check whether the device does not process the data sent by the SDK

Warning

In this case, you need to eliminate the problem on the SDK side first, and then find the problem on the device side.

3.2 Upgrade failed, error code: 16392(0x4008), Upgrade process in progress

When BluetoothOTAManager#isOTA()` == true, calling the ``startOTA API, the SDK will return an error “upgrade process in progress”.

3.3 Upgrade failed, error code: 16385(0x4001), OTA upgrade failed

During the OTA process, the device or SDK returns an OTA failure error.

Warning

1. There are many reasons for this situation, and a print log is required.

2. Output print log, reference: Debug Instructions

3.4 Upgrade failed, error code: 16386(0x4002), device low voltage

The device determines that the battery is too low and does not allow OTA upgrades. Please charge the device to a suitable level before performing OTA upgrades.

3.5 Upgrade failed, error code: 16387(0x4003), upgrade file error

During the OTA process, the device will verify the data. If the data is incomplete or the same data is sent repeatedly, the data stored in the device will be incorrect.

If the above situation occurs, you can follow the steps below to troubleshoot:

1. Ensure the integrity of the sent data

* For BLE implementation, you need to use MTU packetization and queue-based data transmission. For details, refer to the SendBleDataThread in the demo.

2. Make sure the upgrade file is the same as the firmware program

* The device upgrade will verify whether the program is the same. If the SDK upgrade files of different chip platforms cannot be upgraded to each other.

* Even if the firmware is the same, but the storage method is changed, for example: 4K alignment, 256 alignment, etc., it will not be able to be upgraded through OTA, and it needs to be flashed before OTA upgrade.

3. Make sure that one device has only one OTAManager initialized. If you initialize OTAManager repeatedly, the same device will be sent repeatedly.

Warning

1. There are many reasons for this situation. If the above steps cannot solve the problem, please contact the corresponding SDK person in charge for inquiry. The print log needs to be attached.

2. Output print log, reference: Debug Instructions

3.6 Upgrade failed, error: 16389(0x4005), data verification failed

During the OTA process, the device failed to verify the integrity of the upgrade data.

If the above situation occurs, you can follow the steps below to troubleshoot:

1. Ensure the integrity of the sent data

* For BLE implementation, you need to use MTU packetization and queue-based data transmission. For details, refer to the SendBleDataThread in the demo.

2. Make sure that one device has only one OTAManager initialized. If you initialize OTAManager repeatedly, the same device will be sent repeatedly.

3.7 Upgrade failed, error code: 16396 (0x400C), the firmware version of the upgrade file is the same

The version number of the upgrade file is consistent with the firmware version number of the current device, and the upgrade is not allowed.

3.8 Upgrade failed, error code: 16397(0x400D), TWS not connected

The TWS headset is not paired with TWS and cannot be upgraded.

3.9 Upgrade failed, error code: 16399(0x400F), same file

The upgrade file is consistent with the current device firmware content, and the upgrade is not allowed.

3.10 Upgrade failed, error code: 16401(0x4011), timeout on connecting to device

In the single backup OTA process, after downloading the Loader, the device needs to be restarted and switched to the loader system. This requires the SDK to perform the device reconnection process.

The SDK determines whether to use a custom reconnect device process based on 2.2.1   BluetoothOTAConfigure # isUseReconnect. The SDK has a built-in reconnect device process by default.

Customers can also set up a custom process for reconnecting to the device. The SDK will call back through 3.3   OTA process callback # onNeedReconnect when reconnecting to the device.

If the above situation occurs, you can follow the steps below to troubleshoot:

1. Make sure Bluetooth permission is granted

* If you are using Android 6+, you need to apply for location permission

* If it is Android 12+, you need to apply for Bluetooth scanning permission and Bluetooth connection permission

2. Ensure that the device enters the loader state normally and can search for the device’s broadcast packet

3. If the 3.3   OTA process callback # onNeedReconnect callback device uses the new reconnection method, the device will change the BLE address

* The new reconnection method is determined by changing the address based on the special broadcast packet. The following is the format of the new reconnection broadcast packet

Byte 0	Byte 1	Byte 2-3	Byte 4-8	Byte 9	Byte 10-15
Length	Type	VID	Flag	Version	Payload(Original BLE address)
0x??	0xFF	0xD605	ATOLJ	0x00	??:??:??:??:??:??

字段解析

* Length : Length of (Type + VID + Identifier + Version Number + Payload)

* Type : Fixed 0xFF, manufacturer-defined data

* VID : Chip manufacturer ID, the default is 0xD605 (little endian), which means “Jie Li Technology”

* Flag : Filter flag, “ATOLJ” (little endian), means “JLOTA”

* Version : 0x00

* Payload : Valid data, changes according to version number

* The client compares the original BLE address of the 3.3   OTA process callback # onNeedReconnect callback with the original BLE address of the advertising packet.

If they are consistent, the device in the advertising packet is the device that needs to be reconnected.

Warning

1. Broadcast packet data is stored in little-endian format. Please pay attention to the big-endian and small-endian conversion when parsing.

2. There are many reasons for this situation. If the above steps cannot solve the problem, please contact the corresponding SDK person in charge for inquiry. The print log needs to be attached.

3. Output print log, reference: Debug Instructions

3.11 Upgrade failed, error code: 16404(0x4014), the device is in dual-connection mode

The upgrade device is in Dual-connection mode, and the upgrade is not allowed.

3.12 Upgrade failed, error code: 16390(0x4006), encryption key does not match

Whether the upgrade file carries a key must be consistent with the firmware program.

The one with a key is a mass production version, and the one without a key is a test version.

The production key (Key) is a unique identifier generated by our company after the customer applies to us. It is mainly used to distinguish products.

3.13 Upgrade failed, error code: 20484(0x5004), upgrade file not found

An exception occurred during the reading of the upgrade file data

If the above situation occurs, you can follow the steps below to troubleshoot:

1. Check whether the upgrade file exists and whether the upgrade file path is correct.

2. Check whether the application has permission to read the upgrade file data

4. Other Issues

4.1 Can I enable two characteristics at the same time? Will it have any impact?

No impact.

Warning

1. When multiple Characteristic are enabled, they cannot be executed concurrently and need to be executed in a queue. Wait for a Characteristic to be enabled and then execute the next one.

2. Single backup OTA, back to the device, in the loader state, the device only has the OTA UUID service, and multiple Characteristic cannot be enabled

4.2 Why is there two progress changes from 0 to 99 during OTA upgrade?

There are two processes for single backup OTA, Download resources and Upgrade firmware.

3.3   OTA process callback # onProgress callbacks type, indicating the type of upgrade progress.

- Type == 0, Download Resources

- Type == 1, Upgrading Firmware