ipc_softwareupdate

Software Update Service. More...

Data Structures
struct	a_ipc_dyn_array_enum_software_update_result
	Dynamic-length array of a_ipc_enum_software_update_result. More...
struct	a_ipc_dyn_array_enum_software_validation_result
	Dynamic-length array of a_ipc_enum_software_validation_result. More...
struct	a_ipc_dyn_array_enum_software_update_status
	Dynamic-length array of a_ipc_enum_software_update_status. More...
struct	a_ipc_dyn_array_enum_software_update_type
	Dynamic-length array of a_ipc_enum_software_update_type. More...
struct	a_ipc_msg_software_update_version_req
	Read versions of installed software. More...
struct	a_ipc_msg_software_update_version_rsp
	Software version response. More...
struct	a_ipc_msg_software_update_user_post_validation_req
	Verify an update. More...
struct	a_ipc_msg_software_update_user_post_validation_rsp
	Software verification response. More...
struct	a_ipc_msg_software_update_local_prepare_req_norsp
	Prepare the device for a local update. More...
struct	a_ipc_msg_software_update_start_req_norsp
	Start a pending update. More...
struct	a_ipc_msg_software_update_abort_req_norsp
	Abort a pending update. More...
struct	a_ipc_msg_software_update_status_publish_ind
	Indicates the update service state. More...
struct	a_ipc_msg_software_update_status_subscribe_req
	Subscribe to updates for software_update_status. More...
struct	a_ipc_msg_software_update_status_subscribe_rsp
	Sent in response to a_ipc_msg_software_update_status_subscribe_req. More...
struct	a_ipc_msg_software_update_status_unsubscribe_req_norsp
	Unsubscribe from updates for software_update_status. More...

Enumerations
enum	a_ipc_enum_software_update_result { A_IPC_ENUM_SOFTWARE_UPDATE_RESULT_OK , A_IPC_ENUM_SOFTWARE_UPDATE_RESULT_ERROR }
	Software update result codes used in responses. More...
enum	a_ipc_enum_software_validation_result { A_IPC_ENUM_SOFTWARE_VALIDATION_RESULT_UPDATE_OK , A_IPC_ENUM_SOFTWARE_VALIDATION_RESULT_UPDATE_NOT_OK }
	Software validation result codes. More...
enum	a_ipc_enum_software_update_status {   A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_PREPARING , A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_REJECT , A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_WAITING_FOR_FILES , A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_UPDATE_PENDING ,   A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_UPDATING , A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_ABORTED_BY_USER , A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_VALIDATION_PENDING , A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_FAIL }
	Update status. More...
enum	a_ipc_enum_software_update_type { A_IPC_ENUM_SOFTWARE_UPDATE_TYPE_NOT_APPLICABLE , A_IPC_ENUM_SOFTWARE_UPDATE_TYPE_REMOTE , A_IPC_ENUM_SOFTWARE_UPDATE_TYPE_LOCAL }
	Indicates whether an update was triggered remotely (OTA) or locally (the user application). More...

Functions
int	a_open_software_update_stream (void)
	Open a stream for sending update packages to Software Update. More...
A_IPC_RESULT	a_ipc_init_software_update_version_req (a_ipc_msg *msg)
	Initialize the message buffer to contain a_ipc_msg_software_update_version_req. More...
A_IPC_RESULT	a_ipc_init_software_update_version_rsp (a_ipc_msg *msg, uint32_t base_software_actia_part_number_maxlength, uint32_t local_config_actia_part_number_maxlength, uint32_t nad_firmware_actia_part_number_maxlength, uint32_t user_software_article_number_maxlength)
	Initialize the message buffer to contain a_ipc_msg_software_update_version_rsp. More...
A_IPC_RESULT	a_ipc_init_software_update_user_post_validation_req (a_ipc_msg *msg)
	Initialize the message buffer to contain a_ipc_msg_software_update_user_post_validation_req. More...
A_IPC_RESULT	a_ipc_init_software_update_user_post_validation_rsp (a_ipc_msg *msg)
	Initialize the message buffer to contain a_ipc_msg_software_update_user_post_validation_rsp. More...
A_IPC_RESULT	a_ipc_init_software_update_local_prepare_req_norsp (a_ipc_msg *msg)
	Initialize the message buffer to contain a_ipc_msg_software_update_local_prepare_req_norsp. More...
A_IPC_RESULT	a_ipc_init_software_update_start_req_norsp (a_ipc_msg *msg)
	Initialize the message buffer to contain a_ipc_msg_software_update_start_req_norsp. More...
A_IPC_RESULT	a_ipc_init_software_update_abort_req_norsp (a_ipc_msg *msg)
	Initialize the message buffer to contain a_ipc_msg_software_update_abort_req_norsp. More...
A_IPC_RESULT	a_ipc_init_software_update_status_publish_ind (a_ipc_msg *msg)
	Initialize the message buffer to contain a_ipc_msg_software_update_status_publish_ind. More...
A_IPC_RESULT	a_ipc_init_software_update_status_subscribe_req (a_ipc_msg *msg)
	Initialize the message buffer to contain a_ipc_msg_software_update_status_subscribe_req. More...
A_IPC_RESULT	a_ipc_init_software_update_status_subscribe_rsp (a_ipc_msg *msg)
	Initialize the message buffer to contain a_ipc_msg_software_update_status_subscribe_rsp. More...
A_IPC_RESULT	a_ipc_init_software_update_status_unsubscribe_req_norsp (a_ipc_msg *msg)
	Initialize the message buffer to contain a_ipc_msg_software_update_status_unsubscribe_req_norsp. More...

Detailed Description

Software Update Service.

This page contains documentation of the Software Update Service API.

---

Data Structure Documentation

a_ipc_dyn_array_enum_software_update_result

struct a_ipc_dyn_array_enum_software_update_result

Dynamic-length array of a_ipc_enum_software_update_result.

Data Fields
uint32_t	length	Length of the array (number of elements)
a_ipc_enum_software_update_result *	value	The contents of the array.

a_ipc_dyn_array_enum_software_validation_result

struct a_ipc_dyn_array_enum_software_validation_result

Dynamic-length array of a_ipc_enum_software_validation_result.

Data Fields
uint32_t	length	Length of the array (number of elements)
a_ipc_enum_software_validation_result *	value	The contents of the array.

a_ipc_dyn_array_enum_software_update_status

struct a_ipc_dyn_array_enum_software_update_status

Dynamic-length array of a_ipc_enum_software_update_status.

Data Fields
uint32_t	length	Length of the array (number of elements)
a_ipc_enum_software_update_status *	value	The contents of the array.

a_ipc_dyn_array_enum_software_update_type

struct a_ipc_dyn_array_enum_software_update_type

Dynamic-length array of a_ipc_enum_software_update_type.

Data Fields
uint32_t	length	Length of the array (number of elements)
a_ipc_enum_software_update_type *	value	The contents of the array.

a_ipc_msg_software_update_version_req

struct a_ipc_msg_software_update_version_req

Read versions of installed software.

If successful the request will return the versions for all software components. The NAD part number will be "N/A" if the modem hasn't been fully initialized.

Response is delivered in a_ipc_msg_software_update_version_rsp.

Create using a_ipc_init_software_update_version_req().

Message type is A_IPC_MSG_SOFTWARE_UPDATE_VERSION_REQ.

a_ipc_msg_software_update_version_rsp

struct a_ipc_msg_software_update_version_rsp

Software version response.

The part number consists of article number and SemVer 2.0 (https://semver.org/) on the form: AAAA-BBB-CC x.y.z-<metadata>, where AAAA-BBB-CC is the article number, and x.y.z is the version.

Example

The part number 1047-201-01 2.0.0-dev+gcece4c5 means that the component with article number 1047-201-01 is of version 2.0.0.

Sent in response to a_ipc_msg_software_update_version_req.

Create using a_ipc_init_software_update_version_rsp().

Message type is A_IPC_MSG_SOFTWARE_UPDATE_VERSION_RSP.

Data Fields
a_ipc_dyn_string	base_software_actia_part_number	Base software version information.
a_ipc_dyn_string	local_config_actia_part_number	Local configuration version information.
a_ipc_dyn_string	nad_firmware_actia_part_number	NAD Firmware version information.
a_ipc_enum_software_update_result	result	Result of the operation.
a_ipc_dyn_string	user_software_article_number	User software version information.

a_ipc_msg_software_update_user_post_validation_req

struct a_ipc_msg_software_update_user_post_validation_req

Verify an update.

This function is used by a user to confirm if the software update was successful or not. It is recommended to run some sort of sanity checking before calling this function because no revert of the installed software is possible after confirming an update.

Response is delivered in a_ipc_msg_software_update_user_post_validation_rsp.

Create using a_ipc_init_software_update_user_post_validation_req().

Message type is A_IPC_MSG_SOFTWARE_UPDATE_USER_POST_VALIDATION_REQ.

Data Fields
a_ipc_enum_software_validation_result	result	Result of the operation.

a_ipc_msg_software_update_user_post_validation_rsp

struct a_ipc_msg_software_update_user_post_validation_rsp

Software verification response.

Sent in response to a_ipc_msg_software_update_user_post_validation_req.

Create using a_ipc_init_software_update_user_post_validation_rsp().

Message type is A_IPC_MSG_SOFTWARE_UPDATE_USER_POST_VALIDATION_RSP.

Data Fields
a_ipc_enum_software_update_result	result	Result of the operation.

a_ipc_msg_software_update_local_prepare_req_norsp

struct a_ipc_msg_software_update_local_prepare_req_norsp

Prepare the device for a local update.

The operation may take several minutes.

software_update_status_ind indicates the status.

Create using a_ipc_init_software_update_local_prepare_req_norsp().

Message type is A_IPC_MSG_SOFTWARE_UPDATE_LOCAL_PREPARE_REQ_NORSP.

a_ipc_msg_software_update_start_req_norsp

struct a_ipc_msg_software_update_start_req_norsp

Start a pending update.

software_update_status_ind indicates when the update starts.

Create using a_ipc_init_software_update_start_req_norsp().

Message type is A_IPC_MSG_SOFTWARE_UPDATE_START_REQ_NORSP.

a_ipc_msg_software_update_abort_req_norsp

struct a_ipc_msg_software_update_abort_req_norsp

Abort a pending update.

Currently only callable in VALIDATION_PENDING state

Create using a_ipc_init_software_update_abort_req_norsp().

Message type is A_IPC_MSG_SOFTWARE_UPDATE_ABORT_REQ_NORSP.

a_ipc_msg_software_update_status_publish_ind

struct a_ipc_msg_software_update_status_publish_ind

Indicates the update service state.

Subscribe using a_ipc_msg_software_update_status_subscribe_req and unsubscribe using a_ipc_msg_software_update_status_unsubscribe_req_norsp.

Create using a_ipc_init_software_update_status_publish_ind().

Message type is A_IPC_MSG_SOFTWARE_UPDATE_STATUS_PUBLISH_IND.

Data Fields
a_ipc_enum_software_update_status	status	Current updater status.
a_ipc_enum_software_update_type	update_type	Type of update, when applicable.

a_ipc_msg_software_update_status_subscribe_req

struct a_ipc_msg_software_update_status_subscribe_req

Subscribe to updates for software_update_status.

a_ipc_msg_software_update_status_publish_ind will be received until a_ipc_msg_software_update_status_unsubscribe_req_norsp is sent.

Response is delivered in a_ipc_msg_software_update_status_subscribe_rsp.

Create using a_ipc_init_software_update_status_subscribe_req().

Message type is A_IPC_MSG_SOFTWARE_UPDATE_STATUS_SUBSCRIBE_REQ.

a_ipc_msg_software_update_status_subscribe_rsp

struct a_ipc_msg_software_update_status_subscribe_rsp

Sent in response to a_ipc_msg_software_update_status_subscribe_req.

Create using a_ipc_init_software_update_status_subscribe_rsp().

Message type is A_IPC_MSG_SOFTWARE_UPDATE_STATUS_SUBSCRIBE_RSP.

Data Fields
a_ipc_enum_ipc_subscribe_result	result	The result of the subscription request.

a_ipc_msg_software_update_status_unsubscribe_req_norsp

struct a_ipc_msg_software_update_status_unsubscribe_req_norsp

Unsubscribe from updates for software_update_status.

a_ipc_msg_software_update_status_publish_ind will no longer be received.

Create using a_ipc_init_software_update_status_unsubscribe_req_norsp().

Message type is A_IPC_MSG_SOFTWARE_UPDATE_STATUS_UNSUBSCRIBE_REQ_NORSP.

Enumeration Type Documentation

a_ipc_enum_software_update_result

enum a_ipc_enum_software_update_result

Software update result codes used in responses.

Enumerator
A_IPC_ENUM_SOFTWARE_UPDATE_RESULT_OK	OK.
A_IPC_ENUM_SOFTWARE_UPDATE_RESULT_ERROR	Error.

a_ipc_enum_software_update_status

enum a_ipc_enum_software_update_status

Update status.

Enumerator
A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_PREPARING	Base system is preparing the update.
A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_REJECT	Another update is on-going or the request was invalid.
A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_WAITING_FOR_FILES	Base system is ready to receive update files. Use a_open_software_update_stream() to send the file data.
A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_UPDATE_PENDING	Base system is ready to start the update.
A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_UPDATING	Update has started. Board will reboot and complete the update.
A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_ABORTED_BY_USER	The user application aborted the update.
A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_VALIDATION_PENDING	There is an ongoing software update and the user must confirm the software update by calling a_ipc_msg_software_update_user_post_validation_req. This status is sent periodically until post validation has been performed.
A_IPC_ENUM_SOFTWARE_UPDATE_STATUS_FAIL	Error. Refer to device logs for more information.

a_ipc_enum_software_update_type

enum a_ipc_enum_software_update_type

Indicates whether an update was triggered remotely (OTA) or locally (the user application).

Enumerator
A_IPC_ENUM_SOFTWARE_UPDATE_TYPE_NOT_APPLICABLE	Not applicable in the current state (no update on-going).
A_IPC_ENUM_SOFTWARE_UPDATE_TYPE_REMOTE	Update was triggered by the Device Manager backend.
A_IPC_ENUM_SOFTWARE_UPDATE_TYPE_LOCAL	Update was triggered by a user application.

a_ipc_enum_software_validation_result

enum a_ipc_enum_software_validation_result

Software validation result codes.

Enumerator
A_IPC_ENUM_SOFTWARE_VALIDATION_RESULT_UPDATE_OK	Update OK.
A_IPC_ENUM_SOFTWARE_VALIDATION_RESULT_UPDATE_NOT_OK	Update not OK.

Function Documentation

a_ipc_init_software_update_abort_req_norsp()

A_IPC_RESULT a_ipc_init_software_update_abort_req_norsp

(

a_ipc_msg *

msg

)

Initialize the message buffer to contain a_ipc_msg_software_update_abort_req_norsp.

msg->info.type will be A_IPC_MSG_SOFTWARE_UPDATE_ABORT_REQ_NORSP.

This function can be called on an already initialized message to change its type.

Parameters

msg	The message buffer to initialize

a_ipc_init_software_update_local_prepare_req_norsp()

A_IPC_RESULT a_ipc_init_software_update_local_prepare_req_norsp

(

a_ipc_msg *

msg

)

Initialize the message buffer to contain a_ipc_msg_software_update_local_prepare_req_norsp.

msg->info.type will be A_IPC_MSG_SOFTWARE_UPDATE_LOCAL_PREPARE_REQ_NORSP.

This function can be called on an already initialized message to change its type.

Parameters

msg	The message buffer to initialize

a_ipc_init_software_update_start_req_norsp()

A_IPC_RESULT a_ipc_init_software_update_start_req_norsp

(

a_ipc_msg *

msg

)

Initialize the message buffer to contain a_ipc_msg_software_update_start_req_norsp.

msg->info.type will be A_IPC_MSG_SOFTWARE_UPDATE_START_REQ_NORSP.

This function can be called on an already initialized message to change its type.

Parameters

msg	The message buffer to initialize

a_ipc_init_software_update_status_publish_ind()

A_IPC_RESULT a_ipc_init_software_update_status_publish_ind

(

a_ipc_msg *

msg

)

Initialize the message buffer to contain a_ipc_msg_software_update_status_publish_ind.

msg->info.type will be A_IPC_MSG_SOFTWARE_UPDATE_STATUS_PUBLISH_IND.

This function can be called on an already initialized message to change its type.

Parameters

msg	The message buffer to initialize

a_ipc_init_software_update_status_subscribe_req()

A_IPC_RESULT a_ipc_init_software_update_status_subscribe_req

(

a_ipc_msg *

msg

)

Initialize the message buffer to contain a_ipc_msg_software_update_status_subscribe_req.

msg->info.type will be A_IPC_MSG_SOFTWARE_UPDATE_STATUS_SUBSCRIBE_REQ.

This function can be called on an already initialized message to change its type.

Parameters

msg	The message buffer to initialize

a_ipc_init_software_update_status_subscribe_rsp()

A_IPC_RESULT a_ipc_init_software_update_status_subscribe_rsp

(

a_ipc_msg *

msg

)

Initialize the message buffer to contain a_ipc_msg_software_update_status_subscribe_rsp.

msg->info.type will be A_IPC_MSG_SOFTWARE_UPDATE_STATUS_SUBSCRIBE_RSP.

This function can be called on an already initialized message to change its type.

Parameters

msg	The message buffer to initialize

a_ipc_init_software_update_status_unsubscribe_req_norsp()

A_IPC_RESULT a_ipc_init_software_update_status_unsubscribe_req_norsp

(

a_ipc_msg *

msg

)

Initialize the message buffer to contain a_ipc_msg_software_update_status_unsubscribe_req_norsp.

msg->info.type will be A_IPC_MSG_SOFTWARE_UPDATE_STATUS_UNSUBSCRIBE_REQ_NORSP.

This function can be called on an already initialized message to change its type.

Parameters

msg	The message buffer to initialize

a_ipc_init_software_update_user_post_validation_req()

A_IPC_RESULT a_ipc_init_software_update_user_post_validation_req

(

a_ipc_msg *

msg

)

Initialize the message buffer to contain a_ipc_msg_software_update_user_post_validation_req.

msg->info.type will be A_IPC_MSG_SOFTWARE_UPDATE_USER_POST_VALIDATION_REQ.

This function can be called on an already initialized message to change its type.

Parameters

msg	The message buffer to initialize

a_ipc_init_software_update_user_post_validation_rsp()

A_IPC_RESULT a_ipc_init_software_update_user_post_validation_rsp

(

a_ipc_msg *

msg

)

Initialize the message buffer to contain a_ipc_msg_software_update_user_post_validation_rsp.

msg->info.type will be A_IPC_MSG_SOFTWARE_UPDATE_USER_POST_VALIDATION_RSP.

This function can be called on an already initialized message to change its type.

Parameters

msg	The message buffer to initialize

a_ipc_init_software_update_version_req()

A_IPC_RESULT a_ipc_init_software_update_version_req

(

a_ipc_msg *

msg

)

Initialize the message buffer to contain a_ipc_msg_software_update_version_req.

msg->info.type will be A_IPC_MSG_SOFTWARE_UPDATE_VERSION_REQ.

This function can be called on an already initialized message to change its type.

Parameters

msg	The message buffer to initialize

a_ipc_init_software_update_version_rsp()

A_IPC_RESULT a_ipc_init_software_update_version_rsp	(	a_ipc_msg *	msg,
		uint32_t	base_software_actia_part_number_maxlength,
		uint32_t	local_config_actia_part_number_maxlength,
		uint32_t	nad_firmware_actia_part_number_maxlength,
		uint32_t	user_software_article_number_maxlength
	)

Initialize the message buffer to contain a_ipc_msg_software_update_version_rsp.

msg->info.type will be A_IPC_MSG_SOFTWARE_UPDATE_VERSION_RSP.

This function can be called on an already initialized message to change its type.

Parameters

msg	The message buffer to initialize
base_software_actia_part_number_maxlength	The maximum string length for base_software_actia_part_number in the message.
local_config_actia_part_number_maxlength	The maximum string length for local_config_actia_part_number in the message.
nad_firmware_actia_part_number_maxlength	The maximum string length for nad_firmware_actia_part_number in the message.
user_software_article_number_maxlength	The maximum string length for user_software_article_number in the message.

a_open_software_update_stream()

int a_open_software_update_stream

(

void

)

Open a stream for sending update packages to Software Update.

Call this function when the updater is waiting for files.

If the update includes multiple files, stream them back-to-back.

The stream is non-blocking, but this open call is blocking. The stream file descriptor might be a socket, but it is NOT guaranteed to be a socket.

Note: If the stream unexpectedly closes, write() to the stream can trigger a SIGPIPE signal to the process.

Returns

The stream file descriptor, or a negative error code on error

Variable Documentation

base_software_actia_part_number

a_ipc_dyn_string a_ipc_msg_software_update_version_rsp::base_software_actia_part_number

Base software version information.

local_config_actia_part_number

a_ipc_dyn_string a_ipc_msg_software_update_version_rsp::local_config_actia_part_number

Local configuration version information.

nad_firmware_actia_part_number

a_ipc_dyn_string a_ipc_msg_software_update_version_rsp::nad_firmware_actia_part_number

NAD Firmware version information.

result [1/4]

a_ipc_enum_software_update_result a_ipc_msg_software_update_version_rsp::result

Result of the operation.

result [2/4]

a_ipc_enum_software_validation_result a_ipc_msg_software_update_user_post_validation_req::result

Result of the operation.

result [3/4]

a_ipc_enum_software_update_result a_ipc_msg_software_update_user_post_validation_rsp::result

Result of the operation.

result [4/4]

a_ipc_enum_ipc_subscribe_result a_ipc_msg_software_update_status_subscribe_rsp::result

The result of the subscription request.

status

a_ipc_enum_software_update_status a_ipc_msg_software_update_status_publish_ind::status

Current updater status.

update_type

a_ipc_enum_software_update_type a_ipc_msg_software_update_status_publish_ind::update_type

Type of update, when applicable.

user_software_article_number

a_ipc_dyn_string a_ipc_msg_software_update_version_rsp::user_software_article_number

User software version information.