File syn_ota.c

FileList > src > syntropic > system > syn_ota.c

Go to the source code of this file

Secure Streaming OTA Orchestrator implementation.

• #include "../util/syn_assert.h"
• #include "syn_ota.h"
• #include <string.h>

Classes

Type	Name
struct	LwM2M_FwCtx LwM2M Firmware object internal layout for state synchronization.

Public Types

Type	Name
enum	LwM2M_FwResult LwM2M Firmware Update Result enumeration (Object 5 Resource 5).
enum	LwM2M_FwState LwM2M Firmware State enumeration (Object 5 Resource 3).

Public Functions

Type	Name
void	syn_ota_abort (SYN_OTA_Manager * mgr, SYN_OTA_ErrorCode err) Abort an active or failed OTA session.
SYN_Status	syn_ota_apply (SYN_OTA_Manager * mgr) Mark the verified slot as ready for immediate boot on next system restart.
SYN_Status	syn_ota_begin (SYN_OTA_Manager * mgr, uint32_t expected_total_sz, uint32_t target_version, uint32_t expected_crc) Begin a new OTA firmware update session.
SYN_Status	syn_ota_bind_lwm2m (SYN_OTA_Manager * mgr, void * lwm2m_fw_ctx) Bind an OMA LwM2M Object 5 (Firmware Update) context to the OTA manager.
SYN_Status	syn_ota_finish (SYN_OTA_Manager * mgr, const uint8_t * expected_sig_or_tag, size_t sig_len) Finalize and verify the downloaded firmware image.
SYN_OTA_ErrorCode	syn_ota_get_last_error (const SYN_OTA_Manager * mgr) Get last recorded error code.
SYN_Status	syn_ota_get_progress (const SYN_OTA_Manager * mgr, uint32_t * out_written, uint32_t * out_total, uint8_t * out_percent) Query current OTA download and flash write progress.
SYN_OTA_State	syn_ota_get_state (const SYN_OTA_Manager * mgr) Get current OTA lifecycle state.
SYN_Status	syn_ota_init (SYN_OTA_Manager * mgr, SYN_FwBootManager * boot_mgr, uint32_t slot_size, uint8_t * page_buf, size_t page_buf_sz) Initialize the OTA manager.
SYN_Status	syn_ota_set_aes_gcm_params (SYN_OTA_Manager * mgr, const uint8_t * key, size_t key_len, const uint8_t * iv, size_t iv_len) Configure AES-GCM decryption key and IV for encrypted updates.
SYN_Status	syn_ota_set_target_slot (SYN_OTA_Manager * mgr, uint8_t slot_idx) Configure target flash slot (explicit slot index or automatic selection).
SYN_Status	syn_ota_set_verification_key (SYN_OTA_Manager * mgr, SYN_OTA_CryptoMode mode, const uint8_t * key, size_t key_len) Configure cryptographic verification key.
void	syn_ota_sync_lwm2m (SYN_OTA_Manager * mgr) Synchronize OTA state and results into bound LwM2M Object 5 context.
SYN_Status	syn_ota_write_chunk (SYN_OTA_Manager * mgr, const uint8_t * chunk, size_t chunk_sz) Write a chunk of incoming firmware stream into the target flash slot.

Public Static Functions

Type	Name
uint32_t	syn_ota_bytes_ingested (const SYN_OTA_Manager * mgr) Calculate total bytes ingested across flash and in-memory page buffer.

Public Types Documentation

enum LwM2M_FwResult

LwM2M Firmware Update Result enumeration (Object 5 Resource 5).

enum LwM2M_FwResult {
    LWM2M_FW_RES_DEFAULT = 0,
    LWM2M_FW_RES_SUCCESS = 1,
    LWM2M_FW_RES_NO_FLASH = 2,
    LWM2M_FW_RES_OUT_OF_RAM = 3,
    LWM2M_FW_RES_CONN_LOST = 4,
    LWM2M_FW_RES_INTEGRITY_FAIL = 5,
    LWM2M_FW_RES_BAD_PKG_TYPE = 6,
    LWM2M_FW_RES_INVALID_URI = 7
};

---

enum LwM2M_FwState

LwM2M Firmware State enumeration (Object 5 Resource 3).

enum LwM2M_FwState {
    LWM2M_FW_STATE_IDLE = 0,
    LWM2M_FW_STATE_DOWNLOADING = 1,
    LWM2M_FW_STATE_DOWNLOADED = 2,
    LWM2M_FW_STATE_UPDATING = 3
};

---

Public Functions Documentation

function syn_ota_abort

Abort an active or failed OTA session.

void syn_ota_abort (
    SYN_OTA_Manager * mgr,
    SYN_OTA_ErrorCode err
) 

Invalidate the target flash slot header and resets state to SYN_OTA_STATE_IDLE or ERROR.

Parameters:

• mgr OTA manager instance.
• err Error code triggering the abort.

---

function syn_ota_apply

Mark the verified slot as ready for immediate boot on next system restart.

SYN_Status syn_ota_apply (
    SYN_OTA_Manager * mgr
) 

Promotes OTA state to SYN_OTA_STATE_APPLIED and synchronizes LwM2M Object 5.

Parameters:

• mgr OTA manager instance.

Returns:

SYN_OK on success, SYN_ERROR if not in READY_TO_APPLY state.

---

function syn_ota_begin

Begin a new OTA firmware update session.

SYN_Status syn_ota_begin (
    SYN_OTA_Manager * mgr,
    uint32_t expected_total_sz,
    uint32_t target_version,
    uint32_t expected_crc
) 

Resolves target slot, erases initial flash sector, primes running digests, and enters SYN_OTA_STATE_DOWNLOADING.

Parameters:

• mgr OTA manager instance.
• expected_total_sz Total expected firmware binary size (excl header).
• target_version Version code for the incoming firmware.
• expected_crc Expected CRC-32 checksum (0 to compute dynamically).

Returns:

SYN_OK on success, error code on flash erase or configuration failure.

---

function syn_ota_bind_lwm2m

Bind an OMA LwM2M Object 5 (Firmware Update) context to the OTA manager.

SYN_Status syn_ota_bind_lwm2m (
    SYN_OTA_Manager * mgr,
    void * lwm2m_fw_ctx
) 

Allows automatic bidirectional synchronization between OTA progress/states and LwM2M.

Parameters:

• mgr OTA manager instance.
• lwm2m_fw_ctx Pointer to SYN_LwM2M_FirmwareContext instance.

Returns:

SYN_OK on success.

---

function syn_ota_finish

Finalize and verify the downloaded firmware image.

SYN_Status syn_ota_finish (
    SYN_OTA_Manager * mgr,
    const uint8_t * expected_sig_or_tag,
    size_t sig_len
) 

Flushes page buffers, verifies CRC-32 and cryptographic signature / HMAC / GCM tag, and writes the new image header to mark the slot as SYN_FW_STATE_NEW.

Parameters:

• mgr OTA manager instance.
• expected_sig_or_tag Expected signature, HMAC, or GCM tag (NULL if CRC-32 only).
• sig_len Length of expected signature / tag buffer.

Returns:

SYN_OK on successful verification, SYN_ERROR on verification failure.

---

function syn_ota_get_last_error

Get last recorded error code.

SYN_OTA_ErrorCode syn_ota_get_last_error (
    const SYN_OTA_Manager * mgr
) 

Parameters:

• mgr OTA manager instance.

Returns:

Last SYN_OTA_ErrorCode.

---

function syn_ota_get_progress

Query current OTA download and flash write progress.

SYN_Status syn_ota_get_progress (
    const SYN_OTA_Manager * mgr,
    uint32_t * out_written,
    uint32_t * out_total,
    uint8_t * out_percent
) 

Parameters:

• mgr OTA manager instance.
• out_written [out] Bytes written so far (optional, may be NULL).
• out_total [out] Total expected bytes (optional, may be NULL).
• out_percent [out] Integer percentage 0..100 (optional, may be NULL).

Returns:

SYN_OK on success, SYN_INVALID_PARAM on NULL mgr.

---

function syn_ota_get_state

Get current OTA lifecycle state.

SYN_OTA_State syn_ota_get_state (
    const SYN_OTA_Manager * mgr
) 

Parameters:

• mgr OTA manager instance.

Returns:

Current SYN_OTA_State.

---

function syn_ota_init

Initialize the OTA manager.

SYN_Status syn_ota_init (
    SYN_OTA_Manager * mgr,
    SYN_FwBootManager * boot_mgr,
    uint32_t slot_size,
    uint8_t * page_buf,
    size_t page_buf_sz
) 

Parameters:

• mgr OTA manager instance to initialize.
• boot_mgr Dual-bank boot manager instance.
• slot_size Maximum firmware capacity per slot in bytes.
• page_buf Caller-provided page-aligned flash write buffer.
• page_buf_sz Size of page buffer (must match flash write granularity).

Returns:

SYN_OK on success, SYN_INVALID_PARAM on NULL or invalid inputs.

---

function syn_ota_set_aes_gcm_params

Configure AES-GCM decryption key and IV for encrypted updates.

SYN_Status syn_ota_set_aes_gcm_params (
    SYN_OTA_Manager * mgr,
    const uint8_t * key,
    size_t key_len,
    const uint8_t * iv,
    size_t iv_len
) 

Parameters:

• mgr OTA manager instance.
• key AES key (16, 24, or 32 bytes).
• key_len Key length in bytes.
• iv 12-byte initialization vector / nonce.
• iv_len Length of IV (must be 12).

Returns:

SYN_OK on success, SYN_INVALID_PARAM or SYN_ERROR if AES-GCM disabled.

---

function syn_ota_set_target_slot

Configure target flash slot (explicit slot index or automatic selection).

SYN_Status syn_ota_set_target_slot (
    SYN_OTA_Manager * mgr,
    uint8_t slot_idx
) 

If set to SYN_OTA_SLOT_AUTO, syn_ota_begin() will automatically pick the currently inactive slot based on boot_mgr->active_slot.

Parameters:

• mgr OTA manager instance.
• slot_idx SYN_FW_SLOT_A (0), SYN_FW_SLOT_B (1), or SYN_OTA_SLOT_AUTO (0xFF).

Returns:

SYN_OK on success, SYN_INVALID_PARAM on invalid slot index.

---

function syn_ota_set_verification_key

Configure cryptographic verification key.

SYN_Status syn_ota_set_verification_key (
    SYN_OTA_Manager * mgr,
    SYN_OTA_CryptoMode mode,
    const uint8_t * key,
    size_t key_len
) 

Parameters:

• mgr OTA manager instance.
• mode Cryptographic verification mode.
• key Secret key or public key buffer.
• key_len Length of key buffer.

Returns:

SYN_OK on success, SYN_INVALID_PARAM or SYN_ERROR on unsupported mode.

---

function syn_ota_sync_lwm2m

Synchronize OTA state and results into bound LwM2M Object 5 context.

void syn_ota_sync_lwm2m (
    SYN_OTA_Manager * mgr
) 

Parameters:

• mgr OTA manager instance.

---

function syn_ota_write_chunk

Write a chunk of incoming firmware stream into the target flash slot.

SYN_Status syn_ota_write_chunk (
    SYN_OTA_Manager * mgr,
    const uint8_t * chunk,
    size_t chunk_sz
) 

Parameters:

• mgr OTA manager instance.
• chunk Incoming data chunk buffer.
• chunk_sz Length of chunk in bytes.

Returns:

SYN_OK on success, SYN_ERROR on flash write failure, overflow, or invalid state.

---

Public Static Functions Documentation

function syn_ota_bytes_ingested

Calculate total bytes ingested across flash and in-memory page buffer.

static inline uint32_t syn_ota_bytes_ingested (
    const SYN_OTA_Manager * mgr
) 

Parameters:

• mgr OTA manager instance.

Returns:

Total ingested bytes.

---

---

The documentation for this class was generated from the following file src/syntropic/system/syn_ota.c