fw_update.h File Reference

Default implementation of the LwM2M Firmware Update Object (/5). More...

#include <anj/init.h>
#include <stddef.h>
#include <stdint.h>
#include <anj/core.h>
#include <anj/dm/core.h>

Go to the source code of this file.

Data Structures
struct	anj_dm_fw_update_handlers_t
struct	anj_dm_fw_update_entity_ctx_t

Typedefs
typedef anj_dm_fw_update_result_t	anj_dm_fw_update_package_write_start_t(void *user_ptr)
typedef anj_dm_fw_update_result_t	anj_dm_fw_update_package_write_t(void *user_ptr, const void *data, size_t data_size)
typedef anj_dm_fw_update_result_t	anj_dm_fw_update_package_write_finish_t(void *user_ptr)
typedef anj_dm_fw_update_result_t	anj_dm_fw_update_uri_write_t(void *user_ptr, const char *uri)
typedef int	anj_dm_fw_update_update_start_t(void *user_ptr)
typedef const char *	anj_dm_fw_update_get_name_t(void *user_ptr)
typedef const char *	anj_dm_fw_update_get_version_t(void *user_ptr)
typedef void	anj_dm_fw_update_reset_t(void *user_ptr)

Enumerations
enum	anj_dm_fw_update_state_t { ANJ_DM_FW_UPDATE_STATE_IDLE = 0 , ANJ_DM_FW_UPDATE_STATE_DOWNLOADING = 1 , ANJ_DM_FW_UPDATE_STATE_DOWNLOADED = 2 , ANJ_DM_FW_UPDATE_STATE_UPDATING = 3 }
enum	anj_dm_fw_update_result_t {   ANJ_DM_FW_UPDATE_RESULT_INITIAL = 0 , ANJ_DM_FW_UPDATE_RESULT_SUCCESS = 1 , ANJ_DM_FW_UPDATE_RESULT_NOT_ENOUGH_SPACE = 2 , ANJ_DM_FW_UPDATE_RESULT_OUT_OF_MEMORY = 3 ,   ANJ_DM_FW_UPDATE_RESULT_CONNECTION_LOST = 4 , ANJ_DM_FW_UPDATE_RESULT_INTEGRITY_FAILURE = 5 , ANJ_DM_FW_UPDATE_RESULT_UNSUPPORTED_PACKAGE_TYPE = 6 , ANJ_DM_FW_UPDATE_RESULT_INVALID_URI = 7 ,   ANJ_DM_FW_UPDATE_RESULT_FAILED = 8 , ANJ_DM_FW_UPDATE_RESULT_UNSUPPORTED_PROTOCOL = 9 }

Functions
int	anj_dm_fw_update_object_install (anj_t *anj, anj_dm_fw_update_entity_ctx_t *entity_ctx, anj_dm_fw_update_handlers_t *handlers, void *user_ptr)
void	anj_dm_fw_update_object_set_update_result (anj_t *anj, anj_dm_fw_update_entity_ctx_t *entity_ctx, anj_dm_fw_update_result_t result)
int	anj_dm_fw_update_object_set_download_result (anj_t *anj, anj_dm_fw_update_entity_ctx_t *entity_ctx, anj_dm_fw_update_result_t result)

Detailed Description

Default implementation of the LwM2M Firmware Update Object (/5).

Declares states, results, and handler callbacks for firmware update support. Supports both Push (Package) and Pull (Package URI) delivery modes depending on compile-time configuration.

Typedef Documentation

anj_dm_fw_update_get_name_t

typedef const char * anj_dm_fw_update_get_name_t(void *user_ptr)

Returns the name of downloaded firmware package.

The name will be exposed in the data model as the PkgName Resource. If this callback returns NULL or is not implemented at all (with the corresponding field set to NULL), PkgName Resource will contain an empty string.

It only makes sense for this handler to return non-NULL values if there is a valid package already downloaded. The library will not call this handler in any state other than Downloaded.

The library expects that the returned pointer will remain valid until the next call to this handler, or until the State Resource changes to a value other than Downloaded.

Parameters

user_ptr

Opaque pointer to user data, as passed to anj_dm_fw_update_object_install.

Returns

The callback shall return a pointer to a null-terminated string containing the package name, or NULL if it is not currently available.

anj_dm_fw_update_get_version_t

typedef const char * anj_dm_fw_update_get_version_t(void *user_ptr)

Returns the version of downloaded firmware package.

The version will be exposed in the data model as the PkgVersion Resource. If this callback returns NULL or is not implemented at all (with the corresponding field set to NULL), PkgVersion Resource will contain an empty string.

It only makes sense for this handler to return non-NULL values if there is a valid package already downloaded. The library will not call this handler in any state other than Downloaded.

The library expects that the returned pointer will remain valid until the next call to this handler, or until the State Resource changes to a value other than Downloaded.

Parameters

user_ptr

Opaque pointer to user data, as passed to anj_dm_fw_update_object_install.

Returns

The callback shall return a pointer to a null-terminated string containing the package version, or NULL if it is not currently available.

anj_dm_fw_update_package_write_finish_t

typedef anj_dm_fw_update_result_t anj_dm_fw_update_package_write_finish_t(void *user_ptr)

Finalizes the process of writing firmware package chunks. This method is called once, after the last chunk of data hsa been passed to anj_dm_fw_update_package_write_t.

If this callback returns ANJ_DM_FW_UPDATE_RESULT_SUCCESS, the State Resource will be set to Downloaded and the library will wait for the execution of Update Resource by the LwM2M Server to proceed with the actual firmware update.

Warning

This handler must be implemented if ANJ_FOTA_WITH_PUSH_METHOD is enabled.

Parameters

user_ptr

Opaque pointer to user data, as passed to anj_dm_fw_update_object_install.

Returns

The callback should return:

• ANJ_DM_FW_UPDATE_RESULT_INITIAL if the download process has been successfully finalized,
• other anj_dm_fw_update_result_t value, accordingly to the reason of failure.

anj_dm_fw_update_package_write_start_t

typedef anj_dm_fw_update_result_t anj_dm_fw_update_package_write_start_t(void *user_ptr)

Initates the Push-mode download of a firmware package. The library calls this function when a LwM2M Server performs a Write on Package Resource.

If this callback returns ANJ_DM_FW_UPDATE_RESULT_SUCCESS, it will be followed by a series of calls to anj_dm_fw_update_package_write_t that pass the actual firmware package.

Warning

This handler must be implemented if ANJ_FOTA_WITH_PUSH_METHOD is enabled.

Parameters

user_ptr

Opaque pointer to user data, as passed to anj_dm_fw_update_object_install.

Returns

The callback should return:

• ANJ_DM_FW_UPDATE_RESULT_INITIAL if the download process can be initiated,
• other anj_dm_fw_update_result_t value, accordingly to the reason of failure.

anj_dm_fw_update_package_write_t

typedef anj_dm_fw_update_result_t anj_dm_fw_update_package_write_t(void *user_ptr, const void *data, size_t data_size)

Passes parts of firmware package written by a LwM2M Server to the Package Resource. This method is called for each chunk of data, in order.

If this callback returns a value other than ANJ_DM_FW_UPDATE_RESULT_SUCCESS, the download process will be aborted.

Warning

This handler must be implemented if ANJ_FOTA_WITH_PUSH_METHOD is enabled.

Parameters

user_ptr	Opaque pointer to user data, as passed to anj_dm_fw_update_object_install.
data	Pointer to the data chunk.
data_size	Size of the data chunk.

Returns

The callback should return:

• ANJ_DM_FW_UPDATE_RESULT_INITIAL if part of firmware package has been successfully processed,
• other anj_dm_fw_update_result_t value, accordingly to the reason of failure.

anj_dm_fw_update_reset_t

typedef void anj_dm_fw_update_reset_t(void *user_ptr)

Aborts any ongoing firmware package download process, either at the request of the server (by writing an empty value to Package or Package URI Resources), or after a failed download (indicated by returning an error value by other callbacks involved in download process).

The user should ensure that any temporary resources used during the download are released, and that any ongoing download is aborted.

Warning

Note, that this function may be called without previously calling anj_dm_fw_update_package_write_finish_t, so it shall also close the currently open download stream and free any temporary resources.

Parameters

user_ptr

Opaque pointer to user data, as passed to anj_dm_fw_update_object_install.

anj_dm_fw_update_update_start_t

typedef int anj_dm_fw_update_update_start_t(void *user_ptr)

Schedules the actual upgrade with previously downloaded package.

Will be called at request of the server, after a package has been downloaded (by executing Update Resource when State Resource is Downloaded).

User code should initiate the actual upgrade process. If this callback returns ANJ_DM_FW_UPDATE_RESULT_SUCCESS, the State Resource will be set to Updating. The library will wait for the call to anj_dm_fw_update_object_set_update_result to set the State Resource back to Idle and set the Result Resource accordingly, to notify the server about the outcome of the upgrade.

Warning

Most users will want to implement firmware update in a way that involves a reboot. In such case, it is expected that this callback will only schedule the upgrade and return, while the upgrade process and reboot will be performed later. In such case, the user must ensure that anj_dm_fw_update_object_set_update_result is called IMMEDIATELY AFTER installing the Firmware Update Object.

The Execute operation is a Confirmable CoAP request, so the LwM2M server expects an acknowledgement. Additionally, the Server might track State and Update Result Resources. It's recommended to delay the reboot until the response and Notifications are sent by the client.

Parameters

user_ptr

Opaque pointer to user data, as passed to anj_dm_fw_update_object_install.

Returns

0 on success, a non-zero value in case of an error.

anj_dm_fw_update_uri_write_t

typedef anj_dm_fw_update_result_t anj_dm_fw_update_uri_write_t(void *user_ptr, const char *uri)

Initiates the Pull-mode download of a firmware package by providing the URI written by a LwM2M Server to the Package URI Resource.

User code should start the download of the firmware package from the given URI. If this callback returns ANJ_DM_FW_UPDATE_RESULT_SUCCESS, the State Resource will be set to Downloading and the library will wait for the call to anj_dm_fw_update_object_set_download_result to proceed.

Warning

This handler must be implemented if ANJ_FOTA_WITH_PULL_METHOD is enabled.

Parameters

user_ptr	Opaque pointer to user data, as passed to anj_dm_fw_update_object_install.
uri	Null-terminated string containing the URI to the firmware package.

Returns

The callback should return:

• ANJ_DM_FW_UPDATE_RESULT_INITIAL if the download process can be initiated,
• other anj_dm_fw_update_result_t value, accordingly to the reason of failure.

Enumeration Type Documentation

anj_dm_fw_update_result_t

enum anj_dm_fw_update_result_t

Numeric values of the Update Result resource

Note

See OMA LwM2M Core Specification v1.2.2 [OMA-TS-LightweightM2M_Core-V1_2_2-20240613-A] §E.6 for details.

Warning

The values of this enum are incorporated error codes defined in the LwM2M documentation, but actual code logic introduces a variation in the interpretation of the success code ANJ_DM_FW_UPDATE_RESULT_SUCCESS. While the LwM2M documentation specifies it as a success code for the overall firmware update process (when paired with State Resource set to Idle), in this implementation, it is used in other contexts, mainly to signalize success at individual stages of the process. User should be mindful of this distinction and adhere to the return code descriptions provided for each function in this file.

Enumerator
ANJ_DM_FW_UPDATE_RESULT_INITIAL
ANJ_DM_FW_UPDATE_RESULT_SUCCESS
ANJ_DM_FW_UPDATE_RESULT_NOT_ENOUGH_SPACE
ANJ_DM_FW_UPDATE_RESULT_OUT_OF_MEMORY
ANJ_DM_FW_UPDATE_RESULT_CONNECTION_LOST
ANJ_DM_FW_UPDATE_RESULT_INTEGRITY_FAILURE
ANJ_DM_FW_UPDATE_RESULT_UNSUPPORTED_PACKAGE_TYPE
ANJ_DM_FW_UPDATE_RESULT_INVALID_URI
ANJ_DM_FW_UPDATE_RESULT_FAILED
ANJ_DM_FW_UPDATE_RESULT_UNSUPPORTED_PROTOCOL

anj_dm_fw_update_state_t

enum anj_dm_fw_update_state_t

Numeric values of the Firmware Update Protocol Support Resource (/5/0/8).

Note

See OMA LwM2M Core Specification v1.2.2 [OMA-TS-LightweightM2M_Core-V1_2_2-20240613-A] §E.6 for details.

Enumerator
ANJ_DM_FW_UPDATE_STATE_IDLE
ANJ_DM_FW_UPDATE_STATE_DOWNLOADING
ANJ_DM_FW_UPDATE_STATE_DOWNLOADED
ANJ_DM_FW_UPDATE_STATE_UPDATING

Function Documentation

anj_dm_fw_update_object_install()

int anj_dm_fw_update_object_install	(	anj_t *	anj,
		anj_dm_fw_update_entity_ctx_t *	entity_ctx,
		anj_dm_fw_update_handlers_t *	handlers,
		void *	user_ptr
	)

Installs Firmware Update Object in data model.

Parameters

anj	Anjay object.
entity_ctx	Pointer to a variable that will hold the state of the Object.
handlers	Pointer to a set of handler functions that handle platform-specific parts of firmware update process.
user_ptr	Opaque pointer that will be passed to all callbacks.

Returns

0 on success, a non-zero value in case of an error.

anj_dm_fw_update_object_set_download_result()

int anj_dm_fw_update_object_set_download_result	(	anj_t *	anj,
		anj_dm_fw_update_entity_ctx_t *	entity_ctx,
		anj_dm_fw_update_result_t	result
	)

Sets the result of firmware download process in Pull mode.

For details on the expected usage of this function see description of anj_dm_fw_update_uri_write_t callback.

Warning

Calling this function in states other than ANJ_DM_FW_UPDATE_STATE_DOWNLOADING is an error.

Parameters

anj	Anjay object.
entity_ctx	Firmware Update Object state.
result	Result of the download process. If the process is successful, the value must be set to ANJ_DM_FW_UPDATE_RESULT_SUCCESS.

Returns

0 on success, a non-zero value in case of an error.

anj_dm_fw_update_object_set_update_result()

void anj_dm_fw_update_object_set_update_result	(	anj_t *	anj,
		anj_dm_fw_update_entity_ctx_t *	entity_ctx,
		anj_dm_fw_update_result_t	result
	)

Sets the result of upgrade process.

For details on the expected usage of this function see description of anj_dm_fw_update_update_start_t callback.

Warning

This function MUST NOT be called in states other than ANJ_DM_FW_UPDATE_STATE_IDLE or ANJ_DM_FW_UPDATE_STATE_UPDATING. Calling this function in other states is an undefined behavior.

Parameters

anj	Anjay object.
entity_ctx	Firmware Update Object state.
result	Result of the upgrade process. If the process is successful, the value must be set to ANJ_DM_FW_UPDATE_RESULT_SUCCESS.