6.2. Basic implementation

6.2.1. Project structure

We shall start with the code from Notifications support chapter. In the end, our project structure would look as follows:

├── CMakeLists.txt
└── src
    ├── firmware_update.c
    ├── firmware_update.h
    ├── main.c
    ├── time_object.c
    └── time_object.h

Note the firmware_update.c and firmware_update.h are introduced in this chapter.

6.2.2. Installing the Firmware Update module

In order to install the module, we are going to use:

int anjay_fw_update_install(
        anjay_t *anjay,
        const anjay_fw_update_handlers_t *handlers,
        void *user_arg,
        const anjay_fw_update_initial_state_t *initial_state);

The important arguments for us at this point are anjay, handlers and user_arg.

We already discussed handlers structure in API in Anjay, and we will shortly provide simple implementations of required callbacks.


The user_arg is a pointer passed to every callback, when Anjay actually calls it. This pointer can be used by the callback implementation to store any kind of context to operate on. Alternatively, the implementation may set it to NULL and rely on the use of global variables.

In our code, firmware update module installation will be taken care of by the function declared in firmware_update.h:

#include <anjay/anjay.h>
#include <anjay/fw_update.h>

 * Buffer for the endpoint name that will be used when re-launching the client
 * after firmware upgrade.
extern const char *ENDPOINT_NAME;

 * Installs the firmware update module.
 * @returns 0 on success, negative value otherwise.
int fw_update_install(anjay_t *anjay);


We invoke it in main.c by performing two (highlighted) modifications:

#include <anjay/anjay.h>
#include <anjay/security.h>
#include <anjay/server.h>
#include <avsystem/commons/avs_log.h>

#include "firmware_update.h"
#include "time_object.h"

typedef struct {
    anjay_t *anjay;
    const anjay_dm_object_def_t **time_object;
} notify_job_args_t;

// Periodically notifies the library about Resource value changes
static void notify_job(avs_sched_t *sched, const void *args_ptr) {
    const notify_job_args_t *args = (const notify_job_args_t *) args_ptr;

    time_object_notify(args->anjay, args->time_object);

    // Schedule run of the same function after 1 second
    AVS_SCHED_DELAYED(sched, NULL, avs_time_duration_from_scalar(1, AVS_TIME_S),
                      notify_job, args, sizeof(*args));

// Installs Security Object and adds and instance of it.
// An instance of Security Object provides information needed to connect to
// LwM2M server.
static int setup_security_object(anjay_t *anjay) {
    if (anjay_security_object_install(anjay)) {
        return -1;

    static const char PSK_IDENTITY[] = "identity";
    static const char PSK_KEY[] = "P4s$w0rd";

    anjay_security_instance_t security_instance = {
        .ssid = 1,
        .server_uri = "coaps://eu.iot.avsystem.cloud:5684",
        .security_mode = ANJAY_SECURITY_PSK,
        .public_cert_or_psk_identity = (const uint8_t *) PSK_IDENTITY,
        .public_cert_or_psk_identity_size = strlen(PSK_IDENTITY),
        .private_cert_or_psk_key = (const uint8_t *) PSK_KEY,
        .private_cert_or_psk_key_size = strlen(PSK_KEY)

    // Anjay will assign Instance ID automatically
    anjay_iid_t security_instance_id = ANJAY_ID_INVALID;
    if (anjay_security_object_add_instance(anjay, &security_instance,
                                           &security_instance_id)) {
        return -1;

    return 0;

// Installs Server Object and adds and instance of it.
// An instance of Server Object provides the data related to a LwM2M Server.
static int setup_server_object(anjay_t *anjay) {
    if (anjay_server_object_install(anjay)) {
        return -1;

    const anjay_server_instance_t server_instance = {
        // Server Short ID
        .ssid = 1,
        // Client will send Update message often than every 60 seconds
        .lifetime = 60,
        // Disable Default Minimum Period resource
        .default_min_period = -1,
        // Disable Default Maximum Period resource
        .default_max_period = -1,
        // Disable Disable Timeout resource
        .disable_timeout = -1,
        // Sets preferred transport to UDP
        .binding = "U"

    // Anjay will assign Instance ID automatically
    anjay_iid_t server_instance_id = ANJAY_ID_INVALID;
    if (anjay_server_object_add_instance(anjay, &server_instance,
                                         &server_instance_id)) {
        return -1;

    return 0;

int main(int argc, char *argv[]) {
    if (argc != 2) {
        avs_log(tutorial, ERROR, "usage: %s ENDPOINT_NAME", argv[0]);
        return -1;

    ENDPOINT_NAME = argv[1];

    const anjay_configuration_t CONFIG = {
        .endpoint_name = ENDPOINT_NAME,
        .in_buffer_size = 4000,
        .out_buffer_size = 4000,
        .msg_cache_size = 4000

    anjay_t *anjay = anjay_new(&CONFIG);
    if (!anjay) {
        avs_log(tutorial, ERROR, "Could not create Anjay object");
        return -1;

    int result = 0;
    // Setup necessary objects
    if (setup_security_object(anjay) || setup_server_object(anjay)
            || fw_update_install(anjay)) {
        result = -1;

    const anjay_dm_object_def_t **time_object = NULL;
    if (!result) {
        time_object = time_object_create();
        if (time_object) {
            result = anjay_register_object(anjay, time_object);
        } else {
            result = -1;

    if (!result) {
        // Run notify_job the first time;
        // this will schedule periodic calls to itself via the scheduler
        notify_job(anjay_get_scheduler(anjay), &(const notify_job_args_t) {
                                                   .anjay = anjay,
                                                   .time_object = time_object

        result = anjay_event_loop_run(
                anjay, avs_time_duration_from_scalar(1, AVS_TIME_S));

    return result;


As you may see, there is also an additional ENDPOINT_NAME global variable that now stores the command line argument. As we will use the same kind of program binary as the update image, we will need this to properly launch it as part of the upgrade process.

This is usually not necessary in production code, as the endpoint name is usually either hard-coded, or configured through other means.

6.2.3. Implementing handlers and installation routine

First, let’s think about what would we need to implement I/O operations required to download the firmware. The approach we could take is to open a FILE during a call to the stream_open callback, write to it in stream_write, and close it in stream_finish. The only detail remaining is: how are we going to share FILE * pointer between all of these?

We can use a globally allocated structure and pack entire shared state into it. In firmware_update.c it looks like this:

#include "./firmware_update.h"

#include <assert.h>
#include <errno.h>
#include <stdio.h>
#include <sys/stat.h>
#include <unistd.h>

static struct fw_state_t { FILE *firmware_file; } FW_STATE;


The numerous headers included will be useful in further stages of the development.

Having the global state structure, we can proceed with implementation of: fw_stream_open, fw_stream_write and fw_stream_finish, keeping in mind our brief discussion at the beginning of the section:

static struct fw_state_t { FILE *firmware_file; } FW_STATE;

static const char *FW_IMAGE_DOWNLOAD_NAME = "/tmp/firmware_image.bin";

static int fw_stream_open(void *user_ptr,
                          const char *package_uri,
                          const struct anjay_etag *package_etag) {
    // For a moment, we don't need to care about any of the arguments passed.
    (void) user_ptr;
    (void) package_uri;
    (void) package_etag;

    // It's worth ensuring we start with a NULL firmware_file. In the end
    // it would be our responsibility to manage this pointer, and we want
    // to make sure we never leak any memory.
    assert(FW_STATE.firmware_file == NULL);
    // We're about to create a firmware file for writing
    FW_STATE.firmware_file = fopen(FW_IMAGE_DOWNLOAD_NAME, "wb");
    if (!FW_STATE.firmware_file) {
        fprintf(stderr, "Could not open %s\n", FW_IMAGE_DOWNLOAD_NAME);
        return -1;
    // We've succeeded
    return 0;

static int fw_stream_write(void *user_ptr, const void *data, size_t length) {
    (void) user_ptr;
    // We only need to write to file and check if that succeeded
    if (fwrite(data, length, 1, FW_STATE.firmware_file) != 1) {
        fprintf(stderr, "Writing to firmware image failed\n");
        return -1;
    return 0;

static int fw_stream_finish(void *user_ptr) {
    (void) user_ptr;
    assert(FW_STATE.firmware_file != NULL);

    if (fclose(FW_STATE.firmware_file)) {
        fprintf(stderr, "Closing firmware image failed\n");
        FW_STATE.firmware_file = NULL;
        return -1;
    FW_STATE.firmware_file = NULL;
    return 0;

Next in queue is fw_reset, which is called when something on the Client or the Server side goes wrong, or if the Server decides to not perform firmware update. We can implement it as follows:

static void fw_reset(void *user_ptr) {
    // Reset can be issued even if the download never started.
    if (FW_STATE.firmware_file) {
        // We ignore the result code of fclose(), as fw_reset() can't fail.
        (void) fclose(FW_STATE.firmware_file);
        // and reset our global state to initial value.
        FW_STATE.firmware_file = NULL;
    // Finally, let's remove any downloaded payload

And finally, fw_perform_upgrade as well as fw_update_install are to be implemented. However, up to this point, we did not specify what would the format of a downloaded image be, nor how would it be applied.

In our simplified example, we can require from the image to be an executable, and then in fw_perform_upgrade we could be using execl() to start a new (downloaded) version of our Client.


In a more realistic scenario, one would be doing things such as:

  • firmware verification,

  • saving it to some persistent storage (e.g. flash), rather than to /tmp,

  • other platform specific stuff.

The other important thing to consider is this: how’s the newly running client going to know it was upgraded? After all, it would be nice if the Client could report this information to the Server for it to know the update actually succeeded.

The simplest solution here is to use a “marker” file, indicating the client successfully upgraded. Specifically, the idea is as follows:

  • just before performing the upgrade, a “marker” file is created,

  • the logic in the Client can check for the existence of the “marker” and conclude, if the upgrade was performed or not,

  • finally, the “marker” gets removed.

The code is self explanatory:

// A part of a rather simple logic checking if the firmware update was
// successfully performed.
static const char *FW_UPDATED_MARKER = "/tmp/fw-updated-marker";

static int fw_perform_upgrade(void *user_ptr) {
    if (chmod(FW_IMAGE_DOWNLOAD_NAME, 0700) == -1) {
                "Could not make firmware executable: %s\n",
        return -1;
    // Create a marker file, so that the new process knows it is the "upgraded"
    // one
    FILE *marker = fopen(FW_UPDATED_MARKER, "w");
    if (!marker) {
        fprintf(stderr, "Marker file could not be created\n");
        return -1;

    // If the call below succeeds, the firmware is considered as "upgraded",
    // and we hope the newly started client registers to the Server.
    fprintf(stderr, "execl() failed: %s\n", strerror(errno));
    // If we are here, it means execl() failed. Marker file MUST now be removed,
    // as the firmware update failed.
    return -1;

static const anjay_fw_update_handlers_t HANDLERS = {
    .stream_open = fw_stream_open,
    .stream_write = fw_stream_write,
    .stream_finish = fw_stream_finish,
    .reset = fw_reset,
    .perform_upgrade = fw_perform_upgrade

const char *ENDPOINT_NAME = NULL;

int fw_update_install(anjay_t *anjay) {
    anjay_fw_update_initial_state_t state;
    memset(&state, 0, sizeof(state));

    if (access(FW_UPDATED_MARKER, F_OK) != -1) {
        // marker file exists, it means firmware update succeded!
        state.result = ANJAY_FW_UPDATE_INITIAL_SUCCESS;
    // install the module, pass handlers that we implemented and initial state
    // that we discovered upon startup
    return anjay_fw_update_install(anjay, &HANDLERS, NULL, &state);