fw_update.h File Reference

#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_repr_t
struct	anj_dm_fw_update_entity_ctx_t

Macros
#define	ANJ_DM_FW_UPDATE_URI_MAX_LEN   255

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 , ANJ_DM_FW_UPDATE_STATE_DOWNLOADED , ANJ_DM_FW_UPDATE_STATE_UPDATING }
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)

Macro Definition Documentation

ANJ_DM_FW_UPDATE_URI_MAX_LEN

#define ANJ_DM_FW_UPDATE_URI_MAX_LEN   255

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 will not attempt to deallocate the returned pointer. User code must assure that the pointer will remain valid.

Parameters

user_ptr

Opaque pointer to user data, as passed to anj_dm_fw_update_object_install in entity_ctx->repr.user_ptr

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 will not attempt to deallocate the returned pointer. User code must assure that the pointer will remain valid.

Parameters

user_ptr

Opaque pointer to user data, as passed to anj_dm_fw_update_object_install in entity_ctx->repr.user_ptr

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)

Finitializes the operation of writing FW package chunks. The library informs the application that the last call of anj_dm_fw_update_package_write_t was the final one. If this function returns 0, FOTA State Machine goes to Downloaded state and waits for LwM2M Server to execute Update resource.

Note

This handler has to 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 in entity_ctx->repr.user_ptr

Returns

The callback shall return ANJ_DM_FW_UPDATE_RESULT_SUCCESS if successful or an appropriate reason for the write failure: 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_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 FW package. The library calls this function when an LwM2M Server performs a Write on Package resource and is immediately followed with series of anj_dm_fw_update_package_write_t callback calls that pass the actual binary data of the downloaded image if it returns ANJ_DM_FW_UPDATE_RESULT_SUCCESS.

Note

This handler has to 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 in entity_ctx->repr.user_ptr

Returns

The callback shall return ANJ_DM_FW_UPDATE_RESULT_INITIAL if successful or an appropriate reason for the write failure: 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_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 the binary data written by an LwM2M Server to the Package resource in chunks as they come in a block transfer. If it returns a value other than ANJ_DM_FW_UPDATE_RESULT_SUCCESS , it is set as Result resource and subsequent chunks coming from the server are rejected.

Note

This handler has to 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 in entity_ctx->repr.user_ptr
data	Pointer to the data chunk
data_size	Size of the data chunk

Returns

The callback shall return ANJ_DM_FW_UPDATE_RESULT_SUCCESS if successful or an appropriate reason for the write failure: 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_reset_t

typedef void anj_dm_fw_update_reset_t(void *user_ptr)

Resets the firmware update state and performs any applicable cleanup of temporary storage, including aborting any ongoing FW package download.

Will be called at request of the server, or after a failed download. Note that it may be called without previously calling anj_dm_fw_update_package_write_finish_t, so it shall also close the currently open download stream, if any.

Parameters

user_ptr

Opaque pointer to user data, as passed to anj_dm_fw_update_object_install in entity_ctx->repr.user_ptr

anj_dm_fw_update_update_start_t

typedef int anj_dm_fw_update_update_start_t(void *user_ptr)

Schedules performing the actual upgrade with previously downloaded package.

Will be called at request of the server, after a package has been downloaded. Since performing an upgrade can be a relatively long operation and this handler is called directly from the LwM2M Request processing context, it is recommended that it schedules the update and returns so that the library can send an appropriate response to this request on time.

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 do either one of the following:

• perform firmware upgrade, terminate outermost event loop and return, call reboot
• perform the firmware upgrade internally and then reboot, it means that the return will never happen (although the library won't be able to send the acknowledgement to execution of Update resource)

Regardless of the method, the Update result should be set with a call to anj_dm_fw_update_object_set_update_result

Parameters

user_ptr

Opaque pointer to user data, as passed to anj_dm_fw_update_object_install in entity_ctx->repr.user_ptr

Returns

0 for success, non-zero for an internal failure (Result resource will be set to ANJ_DM_FW_UPDATE_RESULT_FAILED).

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)

Informs the application that an LwM2M Server initiated FOTA in Pull mode by writing Package URI Resource. If this function return 0, library goes into Downloading state and waits for anj_dm_fw_update_object_set_download_result call.

Download abort with a '\0' write to Package URI is handled internally and other callback, anj_dm_fw_update_reset_t is called then.

Note

This handler has to 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 in entity_ctx->repr.user_ptr
uri	Null-terminated string containing the URI of FW package

Returns

The callback shall return ANJ_DM_FW_UPDATE_RESULT_SUCCESS if successful or an appropriate reason for the write failure: ANJ_DM_FW_UPDATE_RESULT_UNSUPPORTED_PACKAGE_TYPE ANJ_DM_FW_UPDATE_RESULT_INVALID_URI ANJ_DM_FW_UPDATE_RESULT_UNSUPPORTED_PROTOCOL

Enumeration Type Documentation

anj_dm_fw_update_result_t

enum anj_dm_fw_update_result_t

Numeric values of the Firmware Update Result resource. See LwM2M specification for details.

IMPORTANT NOTE: 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 an overall success code, in this implementation, it is used in other contexts, mainly to signalize success at every stage 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

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 the Firmware Update Object in an DM.

Parameters

anj	Anjay object to operate on.
entity_ctx	Objects entity context that shall be alocated by the user. Please refer to anj_dm_fw_update_entity_ctx_t documentation for more details.
handlers	Pointer to a set of handler functions that handle the platform-specific part of firmware update process. Note: Contents of the structure are NOT copied, so it needs to remain valid for the lifetime of the object.
user_ptr	Opaque user pointer that will be copied to entity_ctx->repr.user_ptr

Returns

0 in case of success, negative value in case of 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 FW download in FOTA with PULL method and reports to the observation module about it.

Parameters

anj	Anjay object to operate on.
entity_ctx	Objects entity context initilized previously with anj_dm_fw_update_object_install.
result	Result of the downloading. To comply with LwM2M specification should be one of the following: 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_UNSUPPORTED_PROTOCOL

Returns

0 in case of success, negative value in case of calling the function in other state than ANJ_DM_FW_UPDATE_STATE_DOWNLOADING.

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 FW update triggered with /5/0/2 execution and reports to the observation module about it.

This function sets /5/0/5 Result to the value passed through argument and /5/0/3 State to IDLE. If FW upgrade is performed with reboot, this function should be called right after installing FW Update object.

Parameters

anj	Anjay object to operate on.
entity_ctx	Objects entity context initilized previously with anj_dm_fw_update_object_install.
result	Result of the FW update. To comply with LwM2M specification should be one of the following: ANJ_DM_FW_UPDATE_RESULT_SUCCESS ANJ_DM_FW_UPDATE_RESULT_INTEGRITY_FAILURE ANJ_DM_FW_UPDATE_RESULT_FAILED