API documentation

Following are the API elements used by the SoftBank FOTA library:

Header files: lib/bin/sb_fota/include

Source files: lib/bin/sb_fota

SoftBank FOTA library API 

group SoftBank FOTA client

Unnamed Group

SB_FOTA_MODEM_MODE_POWER_OFF

SoftBank FOTA modem functional modes.

Used to pass on the modem functional mode in sb_fota_on_modem_cfun(). Minimum functionality mode.

SB_FOTA_MODEM_MODE_POWER_ON: Any valid functionality mode other than SB_FOTA_MODEM_MODE_POWER_OFF.

Typedefs

typedef void (*sb_fota_callback_t)(enum sb_fota_event event)

SoftBank FOTA application callback function.

Also see sb_fota_event.

Param event:: Event ID.

Enums

enum sb_fota_event

SoftBank FOTA application events.

Values:

enumerator SB_FOTA_EVENT_DOWNLOADING: FOTA client starts networking. Application should close all TLS sockets. Modem may change the operation mode from NB-IOT to LTE-M, so any network activity is recommended to be paused.

enumerator SB_FOTA_EVENT_IDLE: FOTA client is now on idle. Application may resume normal network operations.

enumerator SB_FOTA_EVENT_MODEM_SHUTDOWN: Modem FW is going to be updated, so it is shut down. Application cannot use the network anymore until firmware is updated and device is booted.

Functions

int sb_fota_init(sb_fota_callback_t callback)

Initializes the SoftBank FOTA client.

Initializes the library and registers a callback for FOTA process. Subsequent calls may be used to change the callback function.

If Kconfig value CONFIG_SB_FOTA_AUTOINIT is set, then application is not required to call this function, but might still want to use it for registering the callback.

Parameters:: callback – Callback for the application events or NULL for no callback.
Return values:: 0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int sb_fota_on_modem_cfun(int mode)

SoftBank FOTA library modem functional mode handler.

This function must be called whenever modem functional mode is changed.

Note

This is already implemented in sb_fota_os.c.

Parameters:: mode – [in] Modem functional mode.
Return values:: 0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int sb_fota_clock_set(const char *time_str)

Sets current time for the SoftBank FOTA client and modem clock.

Sets the current time used by the SoftBank FOTA client. The given time is also set to the modem. If LTE network time is not available, current time has to be provided to the SoftBank FOTA client using this function.

LTE network time overrides the time set using this function. If time is available from the LTE network, time doesn’t have to be set using this function.

Parameters:: time_str – Time as a null terminated string in format “yy/MM/dd,hh:mm:ss±zz”, where the characters, from left to right, indicate year, month, day, hour, minutes, seconds and time zone. Time zone indicates the difference, expressed in quarters of an hour, between the local time and GMT (value range -48…+48). For example “20/10/15,09:12:47+12”.
Return values:: 0 – If the operation was successful. Otherwise, a (negative) error code is returned.

SoftBank FOTA OS layer 

group SoftBank FOTA OS layer

Defines

SB_FOTA_SETTINGS_PREFIX

Typedefs

typedef int sb_fota_os_sem_t: Generic type for OS semaphore.

typedef void (*sb_fota_os_work_cb)(void*): Generic work callback type.

typedef int sb_fota_os_work_t: Generic work type.

typedef int sb_fota_os_delayed_work_t: Generic delayed work type.

typedef int sb_fota_os_timer_t: Generic timer type.

Enums

enum sb_fota_os_log_level

Generic logging levels.

Values:

enumerator SB_FOTA_OS_LOG_LEVEL_NONE

enumerator SB_FOTA_OS_LOG_LEVEL_ERR

enumerator SB_FOTA_OS_LOG_LEVEL_WRN

enumerator SB_FOTA_OS_LOG_LEVEL_INF

enumerator SB_FOTA_OS_LOG_LEVEL_DBG

Functions

void *sb_fota_os_malloc(size_t size)

Allocate memory on the heap.

Parameters:: size – [in] Size of the memory to be allocated.
Returns:: A pointer to the allocated memory buffer or NULL if allocation failed.

void *sb_fota_os_calloc(size_t nmemb, size_t size)

Allocate memory on the heap and zero it.

Parameters:

nmemb – [in] Number of elements in the requested array
size – [in] Size of each array element.

Returns:

A pointer to the allocated memory buffer or NULL if allocation failed.

void sb_fota_os_free(void *ptr)

Free memory allocated on the heap.

Parameters:: ptr – [in] Pointer to the memory to be freed.

int64_t sb_fota_os_uptime_get(void)

Get system uptime, in milliseconds.

Returns:: Uptime in milliseconds.

uint32_t sb_fota_os_uptime_get_32(void)

Get system uptime (32-bit version), in milliseconds.

Returns:: Uptime in milliseconds.

int64_t sb_fota_os_timegm64(const struct tm *time)

Convert broken-down time to a POSIX epoch offset in seconds.

Parameters:: time – [in] Pointer to broken down time.
Returns:: Time converted to the POSIX epoch time scale.

int sb_fota_os_sleep(int ms)

Put a thread to sleep for a specific amount of time.

Parameters:: ms – [in] Timeout in milliseconds.
Return values:: zero – on success or negative error code on failure.

uint32_t sb_fota_os_rand_get(void)

Get a random value.

Returns:: 32-bit random value.

sb_fota_os_sem_t *sb_fota_os_sem_alloc(void)

Allocate a semaphore from OS.

Returns:: pointer to the allocated semaphore or NULL on failure.

void sb_fota_os_sem_give(sb_fota_os_sem_t *sem)

Give a semaphore.

Parameters:: sem – [in] Pointer to the taken semaphore.

int sb_fota_os_sem_take(sb_fota_os_sem_t *sem, int timeout_ms)

Take a semaphore.

Parameters:

sem – [in] Pointer to the semaphore
timeout_ms – [in] Timeout in milliseconds, or negative on infinite timeout.

Return values:

zero – on success or negative error code on failure.

void sb_fota_os_sem_reset(sb_fota_os_sem_t *sem)

Reset semaphore count to zero.

Parameters:: sem – [in] Pointer to the semaphore.

sb_fota_os_work_t *sb_fota_os_work_init(sb_fota_os_work_cb cb)

Initialize the next available work structure.

Parameters:: cb – [in] The handler to be invoked by the work item.
Returns:: pointer to the initialized work structure or NULL if no work items available.

void sb_fota_os_work_schedule(sb_fota_os_work_t *work)

Submit a work item on the library’s work queue.

Parameters:: work – [in] Work item to be submitted.

sb_fota_os_delayed_work_t *sb_fota_os_delayed_work_init(sb_fota_os_work_cb cb)

Initialize the next available delayed work structure.

Parameters:: cb – [in] The handler to be invoked by the delayed work item.
Returns:: pointer to the initialized delayed work structure or NULL if no work items available.

void sb_fota_os_delayed_work_schedule(sb_fota_os_delayed_work_t *work, int delay_ms)

Schedule a work item on the library’s work queue.

Parameters:

work – [in] Work item to be scheduled.
delay_ms – [in] Delay before submitting the task in milliseconds.

sb_fota_os_timer_t *sb_fota_os_timer_init(sb_fota_os_work_cb cb)

Initialize a timer.

Parameters:: cb – [in] Callback to be invoked each time the timer expires.
Returns:: Pointer to the initialized timer.

void sb_fota_os_timer_start(sb_fota_os_timer_t *timer, uint64_t delay_ms)

Start a timer.

Parameters:

timer – [in] Pointer to the timer to be started.
delay_ms – [in] Timer duration in milliseconds.

void sb_fota_os_timer_stop(sb_fota_os_timer_t *timer)

Stop a timer.

Parameters:: timer – [in] Pointer to the timer to be stopped.

bool sb_fota_os_timer_is_running(sb_fota_os_timer_t *timer)

Check if a timer is running.

Parameters:: timer – [in] Pointer to the timer.
Return values:: true – if the timer is running, false otherwise.

void sb_fota_os_log(int level, const char *fmt, ...)

Generic logging procedure.

Parameters:

level – Log level.
fmt – Format string.
... – Varargs.

void sb_fota_os_load_settings(const struct sb_fota_settings *settings)

Load the array of settings from persistent storage.

Settings must be given as an array that ends with an element whose name is NULL.

Parameters:: settings – [in] Array to load stored settings into.

void sb_fota_os_store_setting(const char *name, size_t len, const void *ptr)

Store a setting value in persistent storage.

SB_FOTA_SETTINGS_PREFIX is automatically added to the name.

Parameters:

name – [in] Null-terminated name of the setting to be stored.
len – [in] Length of the setting value to be stored.
ptr – [in] Value of the setting to be stored.

void sb_fota_os_update_apply(void): Apply the modem firmware update and restore the LTE connection.

int sb_fota_os_lte_online(void)

Activate the LTE service in the modem.

Return values:: zero – on success or negative error code on failure.

int sb_fota_os_lte_offline(void)

Deactivate the LTE service in the modem.

Return values:: zero – on success or negative error code on failure.

int sb_fota_os_lte_mode_request_ltem(void)

Request to set LTE-M (Cat-M1) as the preferred bearer in the modem.

Return values:: zero – on success or negative error code on failure.

int sb_fota_os_lte_mode_restore(void)

Request to restore the application-preferred bearer in the modem.

Return values:: zero – on success or negative error code on failure.

struct sb_fota_settings

#include <sb_fota_os.h>

Structure used to load settings from persistent storage.

Public Members

size_t len: Name of the setting

void *ptr: Size of data, or zero for variable length data like strings

SoftBank FOTA build-time settings 

group SoftBank FOTA build time settings

Defines

SB_FOTA_CLIENT_ID_LEN

Functions

int sb_fota_settings_cloud_sec_tag_get(void)

Get sec_tag for cloud TLS communication.

Returns:: sec_tag

int sb_fota_settings_jwt_sec_tag_get(void)

Get sec_tag for generating JWT tokens.

Returns:: sec_tag

const char *sb_fota_settings_client_id_get(void)

Get client identifier.

Returns:: client identifier string

void sb_fota_settings_client_id_set(const char *id)

Set client identifier for FOTA library.

If not set, default IMEI or UUID is used depending on the Kconfig option.

Parameters:: id – Client identifier string, maximum NRF_DEVICE_UUID_STR_LEN characters.

API documentation

SoftBank FOTA library API

SoftBank FOTA OS layer

SoftBank FOTA build-time settings

SoftBank FOTA library API 

SoftBank FOTA OS layer 

SoftBank FOTA build-time settings 