Over-The-Air Device Firmware Upgrade#

The Wi-SUN Over-The-Air Device Firmware Upgrade (OTA DFU) service is implemented to facilitate the updating of Wi-SUN device firmware. This component requires the Gecko Bootloader API to execute firmware writing, verification, and bootload operations.

To obtain a new Gecko Bootloader File (GBL) from a remote host Over-The-Air, a Trivial File Transfer Protocol (TFTP) client is employed, leveraging the Wi-SUN network. The entire firmware upgrade session is manageable over CoAP, with the service offering remote host connection settings, firmware file selection, notification, and status request capabilities. Configuration of the connection to the TFTP remote host can be accomplished within the component configuration file. To use this component, a bootloader must be flashed onto the device. The component relies on functions that reside within the bootloader. To choose the appropriate bootloader, consider factors such as flash location (internal or external) and size. To save on download time, we recommend applying compression on both the bootloader and device projects.

The following diagram shows the component architecture:

ota-dfu-componentota-dfu-component

The example below shows how OTA DFU can be performed in any project.

#include <stdio.h>
#include "cmsis_os2.h"
#include "sl_wisun_ota_dfu.h"

static void start_ota_dfu(void) {
  sl_status_t api_status = SL_STATUS_FAIL;
  uint32_t fw_update_status = 0;

  // Set remote host that stores the firmware image.
  // TFTP protocol is used to download the firmware.
  // 69 is the default TFTP Port
  api_status = sl_wisun_ota_dfu_set_host_addr("2001:db8::1", 69);
  if (api_status != SL_STATUS_OK) {
    // Error handling
    return;
  }

  // Set GBL file path
  // The path is relative to the preconfigured TFTP shared directory
  api_status = sl_wisun_ota_dfu_set_gbl_path("my_new_firmware.gbl");
  if (api_status != SL_STATUS_OK) {
    // Error handling
    return;
  }

  // Start firmware update
  api_status = sl_wisun_ota_dfu_start_fw_update();
  if (api_status != SL_STATUS_OK) {
    // Error handling
    return;
  }

  // Waiting for the firmware download to finish.
  while(1) {
    fw_update_status = sl_wisun_ota_dfu_get_fw_update_status();
    if (fw_update_status & (1 << SL_WISUN_OTA_DFU_STATUS_FW_DOWNLOADED)) {
      printf("Firmware downloaded. Preparing to bootload\n");
      break;
    } else if (fw_update_status & (1 << SL_WISUN_OTA_DFU_STATUS_FW_DOWNLOAD_ERROR)) {
      printf("Firmware download failed\n");
      break;
    }
    osDelay(1);
  }
}

The CoAP remote settings can be configured as follows:

coap-client -m get -N -B 3 -t text coap://[$WISUN_NODE_IPV6_ADDR]:5683/ota/dfu -e "help"

Commands:

[P: POST (set), G: GET (get)]
[G] help
[G] (empty payload) status
[P] start
[P] stop
[P] install
[G|P] host_address <ipv6> <port>
[G|P] gbl <path>
[G|P] uri <path>
[G|P] notify_host_address <ipv6> <port>
[G|P] notify_uri <path>
[G|P] notify_chunk_cnt <count>

Modules#

Type definitions

Configurations

Functions#

void
sl_wisun_ota_dfu_error_hnd(const sl_wisun_ota_dfu_error_code_t error_code, sl_wisun_ota_dfu_error_ctx_t *const ctx)

OTA DFU error handler (weak implementation)

void
sl_wisun_ota_dfu_free_fw_update_status_json_str(const char *str)

Free the status string buffer.

uint32_t
sl_wisun_ota_dfu_get_fw_update_status(void)

Get the status value.

bool
sl_wisun_ota_dfu_get_fw_update_status_flag(const sl_wisun_ota_dfu_status_t status_flag)

Get the status flag value.

const char *
sl_wisun_ota_dfu_get_fw_update_status_json_str(void)

Get the status string in JSON format.

sl_status_t
sl_wisun_ota_dfu_get_gbl_path(char *const dst_gbl_path, const uint16_t dst_gbl_path_size)

Get GBL file path.

sl_status_t
sl_wisun_ota_dfu_get_host_addr(char *const dst_host, const uint16_t dst_host_size, uint16_t *dst_port)

Get host addres and port.

sl_status_t
sl_wisun_ota_dfu_get_host_uri(char *const dst_uri, const uint16_t dst_uri_size)

Get host uri path.

void
sl_wisun_ota_dfu_init(void)

Initialize the device firmware upgrade service.

sl_status_t
sl_wisun_ota_dfu_reboot_and_install(void)

Reboot device.

sl_status_t
sl_wisun_ota_dfu_set_gbl_path(const char *gbl_path)

Set GBL file path.

sl_status_t
sl_wisun_ota_dfu_set_host_addr(const char *host, const uint16_t port)

Set host address and port.

sl_status_t
sl_wisun_ota_dfu_set_host_uri(const char *uri)

Set host uri path.

sl_status_t
sl_wisun_ota_dfu_start_fw_update(void)

Start firmware update.

sl_status_t
sl_wisun_ota_dfu_stop_fw_update(void)

Stop firmware update.

Macros#

#define
SL_WISUN_OTA_DFU_COAP_URI_PATH_STR_BUF_LEN 128U

OTA DFU CoAP URI Path string buffer length.

#define
SL_WISUN_OTA_DFU_GBL_PATH_STR_BUF_LEN 256U

OTA DFU GBL File name string buffer length.

#define
SL_WISUN_OTA_DFU_IPV6_STR_BUF_LEN 40U

OTA DFU IPV6 string buffer length.

#define
SL_WISUN_OTA_DFU_SERVICE_LOOP ()

OTA DFU Service loop.

Function Documentation#

sl_wisun_ota_dfu_error_hnd#

void sl_wisun_ota_dfu_error_hnd (const sl_wisun_ota_dfu_error_code_t error_code, sl_wisun_ota_dfu_error_ctx_t *const ctx)

OTA DFU error handler (weak implementation)

Parameters
[in]error_code

Error code

[in]ctx

Error context with error details

Catch error in different stages of boot load.


Definition at line 214 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_free_fw_update_status_json_str#

void sl_wisun_ota_dfu_free_fw_update_status_json_str (const char * str)

Free the status string buffer.

Parameters
[in]str

String ptr

Call CoAP free to release allocated memory


Definition at line 198 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_get_fw_update_status#

uint32_t sl_wisun_ota_dfu_get_fw_update_status (void )

Get the status value.

Parameters
N/A

Returning the value of event flags Returns

  • uint32_t Status


Definition at line 184 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_get_fw_update_status_flag#

bool sl_wisun_ota_dfu_get_fw_update_status_flag (const sl_wisun_ota_dfu_status_t status_flag)

Get the status flag value.

Parameters
[in]status_flag

Status flag enum

Bool representation of status variable bit value Returns

  • bool true if the flag is set, otherwise false


Definition at line 206 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_get_fw_update_status_json_str#

const char * sl_wisun_ota_dfu_get_fw_update_status_json_str (void )

Get the status string in JSON format.

Parameters
N/A

String buffer is allocated in heap by CoAP allocator Returns

  • const char * Allocated string pointer on success, otherwise NULL


Definition at line 191 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_get_gbl_path#

sl_status_t sl_wisun_ota_dfu_get_gbl_path (char *const dst_gbl_path, const uint16_t dst_gbl_path_size)

Get GBL file path.

Parameters
[out]dst_gbl_path

GBL file path

[in]dst_gbl_path_size

GBL path size

Get GBL file path Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


Definition at line 271 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_get_host_addr#

sl_status_t sl_wisun_ota_dfu_get_host_addr (char *const dst_host, const uint16_t dst_host_size, uint16_t * dst_port)

Get host addres and port.

Parameters
[out]dst_host

Host address

[in]dst_host_size

Host address size

[out]dst_port

Host port

Get host address and port Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


Definition at line 234 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_get_host_uri#

sl_status_t sl_wisun_ota_dfu_get_host_uri (char *const dst_uri, const uint16_t dst_uri_size)

Get host uri path.

Parameters
[out]dst_uri

Uri path

[in]dst_uri_size

Uri path size

Get host uri path Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


Definition at line 253 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_init#

void sl_wisun_ota_dfu_init (void )

Initialize the device firmware upgrade service.

Parameters
N/A

Initialize Wi-SUN OTA Device Firmware Upgrade service.


Definition at line 150 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_reboot_and_install#

sl_status_t sl_wisun_ota_dfu_reboot_and_install (void )

Reboot device.

Parameters
N/A

Reboot device with calling corresponding gecko bootloader 'bootloader_rebootAndInstall' API This functions is available if auto-reboot mode is disabled. Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


Definition at line 176 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_set_gbl_path#

sl_status_t sl_wisun_ota_dfu_set_gbl_path (const char * gbl_path)

Set GBL file path.

Parameters
[in]gbl_path

GBL file path

Set GBL file path Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


Definition at line 262 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_set_host_addr#

sl_status_t sl_wisun_ota_dfu_set_host_addr (const char * host, const uint16_t port)

Set host address and port.

Parameters
[in]host

Host address

[in]port

Host port

Set host address and port Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


Definition at line 224 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_set_host_uri#

sl_status_t sl_wisun_ota_dfu_set_host_uri (const char * uri)

Set host uri path.

Parameters
[in]uri

Uri path

Set host uri path Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


Definition at line 244 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_start_fw_update#

sl_status_t sl_wisun_ota_dfu_start_fw_update (void )

Start firmware update.

Parameters
N/A

Start firmware update by setting SL_WISUN_OTA_DFU_STATUS_FW_UPDATE_STARTED flag Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


Definition at line 158 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

sl_wisun_ota_dfu_stop_fw_update#

sl_status_t sl_wisun_ota_dfu_stop_fw_update (void )

Stop firmware update.

Parameters
N/A

Stop firmware update by setting SL_WISUN_OTA_DFU_STATUS_FW_UPDATE_STOPPED flag Returns

  • sl_status_t SL_STATUS_OK on success, otherwise SL_STATUS_FAIL


Definition at line 166 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

Macro Definition Documentation#

SL_WISUN_OTA_DFU_COAP_URI_PATH_STR_BUF_LEN#

#define SL_WISUN_OTA_DFU_COAP_URI_PATH_STR_BUF_LEN
Value:
128U

OTA DFU CoAP URI Path string buffer length.


Definition at line 61 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

SL_WISUN_OTA_DFU_GBL_PATH_STR_BUF_LEN#

#define SL_WISUN_OTA_DFU_GBL_PATH_STR_BUF_LEN
Value:
256U

OTA DFU GBL File name string buffer length.


Definition at line 64 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

SL_WISUN_OTA_DFU_IPV6_STR_BUF_LEN#

#define SL_WISUN_OTA_DFU_IPV6_STR_BUF_LEN
Value:
40U

OTA DFU IPV6 string buffer length.


Definition at line 58 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h

SL_WISUN_OTA_DFU_SERVICE_LOOP#

#define SL_WISUN_OTA_DFU_SERVICE_LOOP
Value:
()

OTA DFU Service loop.


Definition at line 68 of file /mnt/raid/workspaces/ws.obQFDUprC/overlay/gsdk/app/wisun/component/ota_dfu/sl_wisun_ota_dfu.h