Table of Content
Overview
Preparing Firmware Image
Create Private and Public Keys
Add Related Source Files
Modify Source Codes
Build Application
SIGN SOTAFU Image
Section Layout Configuration
Section Change after Flash Download
Section Change after OTA Firmware Upgrade
OTA Upgrade Procedure
Upgrade Procedure
Control Point Command Format
Status Codes
Sample Codes in Central Side
Simple Introduction of Android Sample Codes
OTA Upgrade Procedure
This section describes the OTA upgrade procedure or protocol between central and peripheral.
Upgrade Procedure
In central’s view, the success procedure is as below:
1. Connects to peripheral.
2. Enable Handle Value Notification and Indication. (Figure 17.1)
- According to Bluetooth Specification (Core_V4.1, Volume 3, Part G, Clause 3.3.3.3), we need write value 0x0003 to descriptor UUID_DESCRIPTOR_CLIENT_CHARACTERISTIC_CONFIGURATION.
- Thus, in peripheral side, it can send the characteristic UUID_WS_SECURE_UPGRADE_CHARACTERISTIC_CONTROL_POINT’s Handle Value Notification and Indication to central to inform each command’s result.
3. Send [Prepare Download] command to peripheral, to inform it to do download preparation. (Figure 17.2)
- Write value [Prepare Download] to characteristic UUID_WS_SECURE_UPGRADE_CHARACTERISTIC_CONTROL_POINT. The format of command value, please refer to section Control Point Command Format.
- In peripheral, when received the command, it will enter “Ready For Download” state.
Note: According to the current reference application’s source codes in WICED Smart SDK, only when central receives both positive UUID_WS_SECURE_UPGRADE_CHARACTERISTIC_CONTROL_POINT’s Handle Value Notification and respond, we consider the operation as success
4. Get SOTAFU Image’s size, and Send [Download] command to peripheral with this size. (Figure 17.3)
- Write value [Download Command][Image Size] to characteristic UUID_WS_SECURE_UPGRADE_CHARACTERISTIC_CONTROL_POINT.
- In peripheral, when received the command, it will initialize the NVRAM location, calculate the patch size.
5. Read the first 4 bytes (version information) of SOTAFU Image, and send them to peripheral. (Figure 17.4)
- Write 4 bytes version information to characteristic UUID_WS_SECURE_UPGRADE_CHARACTERISTIC_DATA.
- In peripheral, after receive the version information of the OTA Image, it will check the version information as the rule mentioned before.
6. Continue to read N bytes Firmware Image Data from SOTAFU image, and send them to peripheral, until all of the Firmware Image Data are sent. (Figure 17.5)
- Write N bytes Firmware Image Data to characteristic UUID_WS_SECURE_UPGRADE_CHARACTERISTIC_DATA.
- In peripheral, it will write the received image data into NVRAM.
Note: In the reference application’s source codes, the maximum value of N is 20. According Bluetooth specification, the ATT protocol’s default ATT_MTU is 23 Bytes (Bluetooth Core Specification V4.1, Volume 3, Part G, Clause 5.2.1), and the Attribute Write Request PDU Header is 3 Bytes (Bluetooth Core Specification V4.1, Volume 3, Part F, Clause 3.4.5), so one LL (Link Layer) PDU’s maximum payload of Attribute Value is 20 Bytes.
7. Continue to read N bytes Signature Data from SOTAFU image, and send them to peripheral, until 128 Bytes Signature Data are sent. (Figure 17.6)
- Write N bytes Signature Data to characteristic UUID_WS_SECURE_UPGRADE_CHARACTERISTIC_DATA.
- In peripheral, it will save the signature data in RAM.
8. Send [Verify] command to peripheral, to inform it to do Signature Verification. (Figure 17.7)
- Write value [Verify Command] to characteristic UUID_WS_SECURE_UPGRADE_CHARACTERISTIC_CONTROL_POINT.
- In peripheral, it will verify the signature, and send the Handle Value Indication of Control Point to central. And after received the confirmation from central, it will set upgrade the firmware to a new one, then reset the device (Figure 17.8).
More detail procedure in peripheral, please refer the following function in “ws_sec_upgrade_ota.c (WICED-Smart-SDK\apps\ota_secure_firmware_upgrade)”:
- § int ws_upgrade_ota_handle_command(UINT8 *data, int len)
- § int ws_upgrade_ota_handle_data (UINT8 *data, int len)
Control Point Command Format
As mentioned above, central sends control command to peripheral by written characteristic UUID_WS_SECURE_UPGRADE_CHARACTERISTIC_CONTROL_POINT.
The value format is as below:
[Command Code (1 Byte)] [Parameter (0 – n bytes)]
The Command Code is defined in file “ws_sec_upgrade_ota.h” as shown in Figure 18.
File: ws_sec_upgrade_ota.h (WICED-Smart-SDK\Apps\ota_secure_firmware_upgrade) |
… #define WS_UPGRADE_COMMAND_PREPARE_DOWNLOAD 1 #define WS_UPGRADE_COMMAND_DOWNLOAD 2 #define WS_UPGRADE_COMMAND_VERIFY 3 #define WS_UPGRADE_COMMAND_FINISH 4 // not currently used #define WS_UPGRADE_COMMAND_GET_STATUS 5 // not currently used #define WS_UPGRADE_COMMAND_CLEAR_STATUS 6 // not currently used #define WS_UPGRADE_COMMAND_ABORT 7 … |
Figure 18: Command Codes of Control Point
Note: The parameter of command may be different between SOTAFU and OTAFU. And in different version WICED Smart SDK, it also may be different.
For SOTAFU, the main commands’ function and parameter is as follow:
- Prepare Download Command
- Inform peripheral to do prepare download, like initialize the state machine.
- No parameter.
- Download Command
- Inform peripheral the SOTAFU Image’s size.
- Parameter is SOTAFU’s total size (Include the version information and signature data), 2 Bytes.
- Verify Command
- After all SOTAFU Image is downloaded, inform peripheral to do verification.
- No parameter.
Status Codes
Status Code is the result of the command or writing data operation, returned from peripheral to central.
The status codes can be returned in the two cases as below:
- The respond of Write Characteristic (ex. Control Point, Data, etc.) Request.
- Handle Value Notification/Indication.
- Only for Control Point characteristic.
The Status Code is defined in file “ws_sec_upgrade_ota.h” as shown in Figure 19.
File: ws_sec_upgrade_ota.h (WICED-Smart-SDK\Apps\ota_secure_firmware_upgrade) |
… #define WS_UPGRADE_STATUS_OK 0 #define WS_UPGRADE_STATUS_UNSUPPORTED_COMMAND 1 #define WS_UPGRADE_STATUS_ILLEGAL_STATE 2 #define WS_UPGRADE_STATUS_VERIFICATION_FAILED 3 #define WS_UPGRADE_STATUS_INVALID_IMAGE 4 #define WS_UPGRADE_STATUS_INVALID_IMAGE_SIZE 5 #define WS_UPGRADE_STATUS_MORE_DATA 6 #define WS_UPGRADE_STATUS_INVALID_APPID 7 #define WS_UPGRADE_STATUS_INVALID_VERSION 8 #define WS_UPGRADE_WRITE_STATUS_SUCCESS 0x00 #define WS_UPGRADE_WRITE_STATUS_BAD_ID 0x81 #define WS_UPGRADE_WRITE_STATUS_BAD_MAJOR 0x82 #define WS_UPGRADE_WRITE_STATUS_TOO_MUCH_DATA 0x83 #define WS_UPGRADE_WRITE_STATUS_TOO_SHORT 0x84 #define WS_UPGRADE_WRITE_STATUS_ABORTED 0x85 … |
Figure 19: Status Codes
Sample Codes in Central Side
In WICES Smart SDK, it only provides a Windows sample codes in the central side under:
- WICED-Smart-SDK\Apps\ota_firmware_upgrade\peerapps\Windows\WsOtaUpgrade
- WICED-Smart-SDK\Apps\ota_secure_firmware_upgrade\peerapps\Windows\WsSecOtaUpgrade
Simple Introduction of Android Sample Codes
In Android, we also provide some sample codes, but in current, you need to commit a request in ours support website (support.broadcom.com) to get them.
There are two JAVA class:
- OtaUpgrader
- Abstract supper class.
- Define command data member and method.
- OtaSecureUpgrader
- OtaUpgrader’s sub-class.
- Implement all function of Secure OTA Firmware Upgrade.
The common methods are as shown in Figure 20:
- public OtaUpgrader(Context context);
- public OtaUpgrader(Context context, String deviceAddress, String patchFilePath, Callback callback);
- Constructor.
- We can specify the parameter in constructor or each separate method as below.
- public void setDeviceAddress(String deviceAddress);
- Set the Bluetooth address of the BLE device which wanted to do OTA Firmware Upgrade.
- In current design, it will connect to remote BLE device when do upgrading automatically, so it needs the device address.
- public void setPatchFilePath(String patchFilePath);
- Set the File path of patch (OTA Image).
- public void setCallback(Callback callback);
- Set the callback if we want to know the upgrading progress and result.
- Callback Interface is as below:
- public void onProgress(int realSize, int precent);
- Callback when each time when downloaded some data into remote device.
- public void onFinish(int status);
- Callback when the upgrading success or failed.
- public void onProgress(int realSize, int precent);
- public abstract void start();
- Start the OTA Firmware Upgrade.
- public abstract void stop ();
- Cancel the upgrading.
- public abstract int getPatchSize();
- Get the OTA Image size.
File: OtaUpgrader.java |
public abstract class OtaUpgrader { ... public static final int STATUS_OK = 0; ... public static final int COMMAND_PREPARE_DOWNLOAD = 1; ... public interface Callback { public void onProgress(int realSize, int precent); public void onFinish(int status); } … public OtaUpgrader(Context context) { … } public OtaUpgrader(Context context, String deviceAddress, String patchFilePath, Callback callback) { … } public void setDeviceAddress(String deviceAddress) { … } public void setPatchFilePath(String patchFilePath) { … } public void setCallback(Callback callback) { … } public abstract void start(); public abstract void stop(); public abstract int getPatchSize(); ... } |
Figure 20: OtaUpgrader Class
Like the source codes in peripheral, in class OtaSecureUpgrader, we also implement a state machine which can be easy to handle any cases.
A State class has common methods as shown in Figure 21:
- enter()
- When enter the state, this method will be called.
- exit()
- When exit the state, this method will be called.
- handleEvent() / processEvent()
- After entered the state, it will call handleEvent() to handle each received event first. The method handleEvent() handles some common events, and calls processEvent() to handle others. If a state only cares some events, it can handle these event in processEvent().
File: OtaSecureUpgrader.java |
public class OtaSecureUpgrader extends OtaUpgrader { ... private final class StateMachine extends Handler { ... private class State { … public void enter() { … } public void exit() { … } public boolean processEvent(int event, int status) { … } public void handleEvent(State destState, int event, int status) { … } } … } } |
Figure 21: Method of State Class
The methods of StateMachine class are as shown in Figure 22:
- start()
- Start the state machine
- stop()
- Abort the current state, force it transfer to finish state.
- transitionTo()
- Transition to another State.
- postEvent()
- Post the received events to current State to handle it.
- quit()
- Quit the state machine, the state machine will be died.
File: OtaSecureUpgrader.java |
public class OtaSecureUpgrader extends OtaUpgrader { ... private final class StateMachine extends Handler { … public void start() { … } public void stop() { … } public void quit() { … }
public void postEvent(int event, int status) { … } … private void transitionTo(State destState, int status) { … } … } } |
Figure 22: Method of StateMachine Class
All of states and transition between states of OtaSecureUpgrader are as shown in Figure 23.
Notice:
1. Sample code OTA_Android_Sample_NoSecure.zip is only tested in WICED Smart SDK 1.1.0.
2. Sample code AndroidOtaSampleCodes_V1.0.zip is tested in WICED Smart SDK 1.1.0 and 2.1.0.
3.Sample code AndroidOtaSampleCodes_V1.1.zip is tested in WICED Smart SDK 1.1.0 and 2.1.0.