ota.h

Go to the documentation of this file.

/*
 * Copyright (c) 2022 Golioth, Inc.
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#pragma once
 
#include <stdint.h>
#include <golioth/golioth_status.h>
#include <golioth/client.h>
#include <golioth/config.h>
 
 
#define GOLIOTH_OTA_COMPONENT_HEX_HASH_LEN 64
#define GOLIOTH_OTA_COMPONENT_BIN_HASH_LEN 32
#define GOLIOTH_OTA_MAX_COMPONENT_URI_LEN \
    (CONFIG_GOLIOTH_OTA_MAX_PACKAGE_NAME_LEN + CONFIG_GOLIOTH_OTA_MAX_VERSION_LEN + 7)
 
enum golioth_ota_state
{
    GOLIOTH_OTA_STATE_IDLE,
    GOLIOTH_OTA_STATE_DOWNLOADING,
    GOLIOTH_OTA_STATE_DOWNLOADED,
    GOLIOTH_OTA_STATE_UPDATING,
};
 
enum golioth_ota_reason
{
    GOLIOTH_OTA_REASON_READY,
    GOLIOTH_OTA_REASON_FIRMWARE_UPDATED_SUCCESSFULLY,
    GOLIOTH_OTA_REASON_NOT_ENOUGH_FLASH_MEMORY,
    GOLIOTH_OTA_REASON_OUT_OF_RAM,
    GOLIOTH_OTA_REASON_CONNECTION_LOST,
    GOLIOTH_OTA_REASON_INTEGRITY_CHECK_FAILURE,
    GOLIOTH_OTA_REASON_UNSUPPORTED_PACKAGE_TYPE,
    GOLIOTH_OTA_REASON_INVALID_URI,
    GOLIOTH_OTA_REASON_FIRMWARE_UPDATE_FAILED,
    GOLIOTH_OTA_REASON_UNSUPPORTED_PROTOCOL,
    GOLIOTH_OTA_REASON_IO,
    GOLIOTH_OTA_REASON_AWAIT_RETRY,
};
 
struct golioth_ota_component
{
    char package[CONFIG_GOLIOTH_OTA_MAX_PACKAGE_NAME_LEN + 1];
    char version[CONFIG_GOLIOTH_OTA_MAX_VERSION_LEN + 1];
    int32_t size;
    uint8_t hash[GOLIOTH_OTA_COMPONENT_BIN_HASH_LEN];
    char uri[GOLIOTH_OTA_MAX_COMPONENT_URI_LEN + 1];
};
 
struct golioth_ota_manifest
{
    int32_t seqnum;
    struct golioth_ota_component components[CONFIG_GOLIOTH_OTA_MAX_NUM_COMPONENTS];
    size_t num_components;
};
 
enum golioth_status golioth_ota_payload_as_manifest(const uint8_t *payload,
                                                    size_t payload_size,
                                                    struct golioth_ota_manifest *manifest);
 
size_t golioth_ota_size_to_nblocks(size_t component_size);
 
const struct golioth_ota_component *golioth_ota_find_component(
    const struct golioth_ota_manifest *manifest,
    const char *package);
 
enum golioth_status golioth_ota_manifest_subscribe(struct golioth_client *client,
                                                   golioth_get_cb_fn callback,
                                                   void *arg);
 
enum golioth_status golioth_ota_get_manifest_async(struct golioth_client *client,
                                                   golioth_get_cb_fn callback,
                                                   void *arg);
 
enum golioth_status golioth_ota_blockwise_manifest_async(struct golioth_client *client,
                                                         size_t block_idx,
                                                         golioth_get_block_cb_fn block_cb,
                                                         golioth_end_block_cb_fn end_cb,
                                                         void *arg);
 
typedef enum golioth_status (*ota_component_block_write_cb)(
    const struct golioth_ota_component *component,
    uint32_t block_idx,
    const uint8_t *block_buffer,
    size_t block_buffer_len,
    bool is_last,
    size_t negotiated_block_size,
    void *arg);
 
typedef void (*ota_component_download_end_cb)(enum golioth_status status,
                                              const struct golioth_coap_rsp_code *rsp_code,
                                              const struct golioth_ota_component *component,
                                              uint32_t block_idx,
                                              void *arg);
 
enum golioth_status golioth_ota_download_component(struct golioth_client *client,
                                                   const struct golioth_ota_component *component,
                                                   uint32_t block_idx,
                                                   ota_component_block_write_cb block_cb,
                                                   ota_component_download_end_cb end_cb,
                                                   void *arg);
 
enum golioth_status golioth_ota_get_block_sync(struct golioth_client *client,
                                               const char *package,
                                               const char *version,
                                               size_t block_index,
                                               uint8_t *buf,
                                               size_t *block_nbytes,
                                               bool *is_last,
                                               int32_t timeout_s);
 
enum golioth_status golioth_ota_report_state_sync(struct golioth_client *client,
                                                  enum golioth_ota_state state,
                                                  enum golioth_ota_reason reason,
                                                  const char *package,
                                                  const char *current_version,
                                                  const char *target_version,
                                                  int32_t timeout_s);
 
enum golioth_ota_state golioth_ota_get_state(void);
 
 
#ifdef __cplusplus
}
#endif