Application Integration and configuration

SoftBank specifies that your certified product must be able to update its modem firmware, regardless of the tasks run by your application.

Overview

The SoftBank FOTA library is an independent library that is intended to run together with your application when included in your project. See the following image:

Interaction between the SoftBank FOTA library and the user application

Interaction between the SoftBank FOTA library and the user application

OS layer

The SoftBank FOTA library has an OS abstraction layer. This abstraction layer makes the SoftBank FOTA library independent of some nRF Connect SDK modules and the underlying implementation of primitives such as timers, non-volatile storage, and heap allocation. For more information, see the sb_fota_os.h file or the SoftBank FOTA OS layer section for available APIs. It provides an abstraction of the following modules:

The following modules are used directly by the library:

When the SoftBank FOTA library is enabled in your application, it includes the file sdk-softbank-fota/lib/bin/sb_fota/os/sb_fota.c. This automatically runs the library’s main function (sb_fota_main()).

Configuration

Enable the library in your application by setting the CONFIG_SB_FOTA Kconfig option to y.

The SoftBank FOTA sample project configuration (sdk-softbank-fota/sample/prj.conf) contains all the configurations that are needed by the SoftBank FOTA library.

By default, sec_tag 50 is used for JWT signing and TLS. You can change the value using the CONFIG_SB_FOTA_JWT_SECURITY_TAG and CONFIG_SB_FOTA_TLS_SECURITY_TAG Kconfig options.

Configuration options

  • CONFIG_SB_FOTA - Enables the SoftBank FOTA library.

  • CONFIG_SB_FOTA_AUTOINIT - Initializes the library automatically.

  • CONFIG_SB_FOTA_TLS_SECURITY_TAG - Security tag (sec_tag) for nRF Cloud TLS connection.

  • CONFIG_SB_FOTA_JWT_SECURITY_TAG - sec_tag for authentication with the cloud.

  • CONFIG_SB_FOTA_CLIENT_ID - Determines which client ID (UUID or IMEI) will be used for nRF Cloud.

  • CONFIG_SB_FOTA_ID_PREFIX - Prefix for the client ID.

Usage

To use this library, the application must set the Kconfig option CONFIG_SB_FOTA to y and then register a callback for the library using the sb_fota_init() function. This is demonstrated in the following example, and it is based on the assumption that the Modem library is initialized and LTE connection is established when the device boots:

static void softbank_fota_callback(enum sb_fota_event e)
{
   switch(e) {
   case SB_FOTA_EVENT_DOWNLOADING:
      printk("SB_FOTA_EVENT_DOWNLOADING\n");
      break;
   case SB_FOTA_EVENT_IDLE:
      printk("SB_FOTA_EVENT_IDLE\n");
      break;
   case SB_FOTA_EVENT_MODEM_SHUTDOWN:
      printk("SB_FOTA_EVENT_MODEM_SHUTDOWN\n");
      break;
   }
}

int main(void)
{
   if (sb_fota_init(&softbank_fota_callback) != 0) {
      printk("Failed to initialize the SoftBank FOTA library\n");
      return 1;
   }
   ...
}

Limitations

The application can control the modem usage normally, like any application based on the nRF Connect SDK, but with the following limitations:

  • Occasionally, the library might need to connect to nRF Cloud to check and possibly download a new modem firmware image. It issues the SB_FOTA_EVENT_DOWNLOADING event when it starts the download. At that time, the application must not use any TLS sockets that are using the offloaded TLS stack from the modem. Also, it is recommended to stop all network operations until the SB_FOTA_EVENT_IDLE event is received, as there might be mandatory operation mode switches between NB-IoT and LTE-M networks.

  • When the modem is updated with a new firmware, it gets disconnected from the network and shuts down. This is indicated by the SB_FOTA_EVENT_MODEM_SHUTDOWN event. The modem update can take a few minutes.

It is recommended to register an event handler using the sb_fota_init() API.