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

Typedefs

typedef void (*sb_fota_callback_t)(enum sb_fota_event event)

SoftBank FOTA application callback function.

See also 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_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_OS_SEMAPHORE_COUNT

SB_FOTA_OS_WORK_COUNT

SB_FOTA_OS_DELAYED_WORK_COUNT

SB_FOTA_OS_TIMERS

SB_FOTA_SETTINGS_PREFIX

Typedefs

typedef void (*sb_fota_os_work_cb)(void*)

Generic work callback type

Enums

enum sb_fota_os_log_level

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.

void *sb_fota_os_calloc(size_t nmemb, size_t size)

Allocate memory and zero it.

void sb_fota_os_free(void *ptr)

Free memory.

int64_t sb_fota_os_uptime_get(void)

Get uptime, in milliseconds.

uint32_t sb_fota_os_uptime_get_32(void)

Get uptime, in milliseconds.

int sb_fota_os_sleep(int ms)

Put a thread to a sleep.

uint32_t sb_fota_os_rand_get(void)

Get a random value.

struct sb_fota_os_sem *sb_fota_os_sem_alloc(void)

Allocate a semaphore from OS.

Returns:

pointer to allocated semaphore or NULL on failure.

void sb_fota_os_sem_give(struct sb_fota_os_sem *sem)

Give a semaphore.

Parameters:

sem – pointer to a taken semaphore.

int sb_fota_os_sem_take(struct sb_fota_os_sem *sem, int timeout_ms)

Take a semaphore.

Parameters:

• sem – pointer to semaphore

• timeout_ms – timeout in milliseconds, or negative if call can block forever.

Returns:

zero on success or negative error code on failure.

void sb_fota_os_sem_reset(struct sb_fota_os_sem *sem)

Reset semaphore count to zero.

Parameters:

sem – pointer to a semaphore.

struct sb_fota_os_work *sb_fota_os_work_init(sb_fota_os_work_cb cb)

void sb_fota_os_work_schedule(struct sb_fota_os_work *work)

struct sb_fota_os_delayed_work *sb_fota_os_delayed_work_init(sb_fota_os_work_cb cb)

void sb_fota_os_delayed_work_schedule(struct sb_fota_os_delayed_work *work, int delay_ms)

struct sb_fota_os_timer *sb_fota_os_timer_init(sb_fota_os_work_cb cb)

void sb_fota_os_timer_start(struct sb_fota_os_timer *timer, uint64_t delay_ms)

void sb_fota_os_timer_stop(struct sb_fota_os_timer *timer)

bool sb_fota_os_timer_is_running(struct sb_fota_os_timer *timer)

int64_t sb_fota_os_timegm64(const struct tm *time)

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

void sb_fota_os_load_settings(const struct sb_fota_settings *settings)

Load array of settings from persistent storage. Settings should be given as an array that ends with element where name is NULL.

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

Store one settings value. SB_FOTA_SETTINGS_PREFIX is automatically added to the name.

void sb_fota_os_update_apply(void)

Apply modem FW update

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 lenght data like strings