本节介绍固件升级HAL模块和固件升级OTA模块公开的函数。开发人员可以使用本文档中描述的OTA示例协议,并调用ota_firmware_upgrade…函数或开发完全不同的方法来交付固件镜像到嵌入式应用程序,并直接调用wiced_firmware_upgrade_…函数。
一、固件升级库初始化
该函数通常由OTA固件升级模块(参见下面第六条)或应用程序在初始化期间调用,以配置串行flash节的位置和长度。
原型:
wiced_bool_t wiced_firmware_upgrade_init(wiced_fw_upgrade_nv_loc_len_t *p_sflash_nv_loc_len, uint32_t sflash_size);
参数:
p_sflash_nv_loc_len:连续flash中不同部分的位置和长度。位置和长度应该与构建过程中在平台BTP文件中配置的值匹配。在固件升级过程中不可能更改这些值。这些值被传递到wiced_fw_upgrade_nv_loc_len_t结构中的固件升级模块,如下所示。
typedef struct
{
uint32_t ss_loc; // static section location
uint32_t ds1_loc; // ds1 location
uint32_t ds1_len; // ds1 length
uint32_t ds2_loc; // ds2 location
uint32_t ds2_len; // ds2 length
uint32_t vs1_loc; // vendor specific location 1
uint32_t vs1_len; // vendor specific location 1 length
uint32_t vs2_loc; // vendor specific location 2
uint32_t vs2_len; // vendor specific location 2 length
} wiced_fw_upgrade_nv_loc_len_t;
返回值:如果成功验证了位置和长度,则WICED_TRUE。如果初始化函数返回WICED_FALSE,以后启动另一个固件升级的尝试将失败。在这种状态下,编写新版本的唯一方法是直接或通过HCI UART编写串行flash。
二、固件升级初始化NV位置
OTA固件升级模块或应用程序应该在固件下载过程开始时调用这个函数来设置内存连接。如果下载已启动,但未成功完成,则应再次调用此函数。
原型:
wiced_bool_t wiced_firmware_upgrade_init_nv_locations(void);
返回值:成功返回WICED_TRUE,失败返回WICED_FALSE。
三、固件升级存储数据到NV
OTA固件升级模块或应用程序可以调用此函数将数据块存储到物理非易失性存储介质。不活动的分区将被写入。应用程序不需要知道所使用的内存类型或正在升级的分区。通常,OTA过程在从下载程序接收到下一个数据包时将调用此函数。
原型:
uint32_t wiced_firmware_upgrade_store_to_nv(uint32_t offset, uint8_t *data, uint32_t len);
参数:
offset:存储数据的内存偏移量。
data:指向要存储的数据块的指针。
len:要存储的内存块的大小。
返回值:如果成功,则返回存储到存储器的字节数,否则返回为0。
四、固件升级从NV获取数据
OTA固件升级模块或应用程序可以调用此函数来从物理非易失性存储介质中检索数据块。不活动的分区将被读取。应用程序不需要知道所使用的内存类型或正在升级的分区。通常,OTA过程将在验证期间调用此函数,以验证是否存储了完整且正确的镜像。
原型:
uint32_t wiced_firmware_upgrade_retrieve_from_nv(uint32_t offset, uint8_t *data, uint32_t len);
参数:
offset:将从中检索数据的内存偏移量。
data:指向库将存储检索到的数据的位置的指针。
len:要检索的内存块的大小。
返回值:如果成功,则从存储器中检索到的字节数,否则为0。
五、固件升级完成
下载完成并验证之后,可以调用此函数来切换活动分区与接收新映像的分区。此函数使先前的活动分区无效,并启动重新启动。
原型:
void wiced_firmware_upgrade_finish(void);
六、OTA固件升级初始化
想要利用OTA固件升级模块功能的应用程序在启动时应调用此功能。它可以选择注册一个回调,在升级过程结束时,芯片重新启动之前发出。要使用ECDSA固件验证方法的应用程序应该为有效的公钥传递一个指针。如果应用程序使用简单的CRC32验证,则指向公钥的点应该设置为NULL。
原型:
wiced_bool_t wiced_ota_fw_upgrade_init(void *p_public_key,wiced_firmware_upgrade_pre_reboot_callback_t* p_callback);
参数:
p_public_key:如果应用程序需要ECDSA验证,它应该将指针传递给存储在映像中的公钥。否则应用程序应该传递空指针。
p_callback:在升级过程结束时,在重新启动芯片之前发出的回调,如果在重新启动芯片之前不需要通知应用程序,则为NULL。回调被定义为:
typedef void wiced_firmware_upgrade_pre_reboot_callback_t(void);
七、OTA固件升级连接状态
使用OTA固件升级模块的应用程序在对等设备建立BLE连接或连接发生故障时调用该功能。
原型:
void wiced_ota_fw_upgrade_connection_status_event(wiced_bt_gatt_connection_status_t *p_status);
参数:
p_status:指向应用程序从堆栈接收到的已连接的BT GATT连接状态结构的指针。
八、OTA固件升级读处理程序
使用OTA固件升级模块的应用程序应该调用此函数,将GATT读请求传递给库,以获取属于OTA升级服务的属性。该函数返回应该传递回堆栈的数据和错误代码。
原型:
wiced_bt_gatt_status_t wiced_ota_fw_upgrade_read_handler(uint16_t conn_id, wiced_bt_gatt_read_t *p_read_data);
参数:
conn_id:GATT connection ID.
p_read_data :指向应用程序从堆栈接收到的GATT读结构的指针。
返回值:GATT读操作的现状
九、OTA固件升级写处理程序
使用OTA固件升级模块的应用程序应该调用此函数,将GATT针对属于OTA升级服务的属性的写请求传递给库。如果应用程序使用ECDSA验证方法,则不应调用此函数。
原型:
wiced_bt_gatt_status_t wiced_ota_fw_upgrade_write_handler(uint16_t conn_id, wiced_bt_gatt_write_t *p_write_data);
参数:
conn_id :GATT connection ID.
p_write_data:指向应用程序从堆栈接收到的GATT写结构的指针。
返回值:GATT写操作的状态。
十、OTA固件升级指示确认
使用OTA固件升级模块的应用程序应该调用此函数来传递GATT指示,以向库确认属于OTA升级服务的属性请求。
原型:
wiced_bt_gatt_status_t wiced_ota_fw_upgrade_indication_cfm_handler(uint16_t conn_id, uint16_t handle);
参数:
conn_id:GATT connection ID.
handle:表示已接收到确认消息的属性句柄。
返回值:GATT显示状态确认操作。