File syn_ota.h

FileList > src > syntropic > system > syn_ota.h

Go to the source code of this file

Secure Streaming OTA Orchestrator — zero-heap, transport-agnostic. More...

• #include "../common/syn_defs.h"
• #include "syn_fwboot.h"
• #include "syn_fwimage.h"
• #include "syn_fwupdate.h"
• #include <stdbool.h>
• #include <stddef.h>
• #include <stdint.h>

Classes

Type	Name
struct	SYN_OTA_Manager Zero-heap Streaming OTA Manager context.

Public Types

Type	Name
enum	SYN_OTA_CryptoMode Cryptographic verification mode for the OTA image.
enum	SYN_OTA_ErrorCode OTA Error Codes.
enum	SYN_OTA_State OTA update lifecycle states.

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.

Macros

Type	Name
define	SYN_OTA_SLOT_AUTO 0xFFU Automatic slot selection constant.

Detailed Description

Coordinates streaming firmware updates across heterogeneous transports (CoAP Block2, HTTP, BLE, LwM2M Object 5, UART/YMODEM) directly into flash.

Integrates dual-bank flash slot selection (syn_fwboot), streaming page flushing and flash sector management (syn_fwupdate), cryptographic verification (CRC-32, HMAC-SHA256, Ed25519, AES-GCM), and LwM2M Object 5 lifecycle state sync.

** **

static uint8_t page_buf[256];
SYN_FwBootManager boot_mgr;
SYN_OTA_Manager ota;

syn_fwboot_init(&boot_mgr, SLOT_A_ADDR, SLOT_B_ADDR);
syn_ota_init(&ota, &boot_mgr, SLOT_SIZE, page_buf, sizeof(page_buf));

// Optional: configure cryptographic verification (e.g. Ed25519)
syn_ota_set_verification_key(&ota, SYN_OTA_CRYPTO_ED25519, pubkey, 32U);

// Begin OTA session
syn_ota_begin(&ota, fw_total_len, new_version_code, expected_crc32);

// Stream incoming chunks from transport
while (receiving_chunks) {
    syn_ota_write_chunk(&ota, chunk_data, chunk_len);
}

// Finish and verify signature
if (syn_ota_finish(&ota, expected_signature, 64U) == SYN_OK) {
    syn_ota_apply(&ota); // Ready to reboot into new image
}

Public Types Documentation

enum SYN_OTA_CryptoMode

Cryptographic verification mode for the OTA image.

enum SYN_OTA_CryptoMode {
    SYN_OTA_CRYPTO_NONE = 0,
    SYN_OTA_CRYPTO_HMAC_SHA256,
    SYN_OTA_CRYPTO_ED25519,
    SYN_OTA_CRYPTO_AES_GCM
};

---

enum SYN_OTA_ErrorCode

OTA Error Codes.

enum SYN_OTA_ErrorCode {
    SYN_OTA_ERR_NONE = 0,
    SYN_OTA_ERR_INVALID_PARAM,
    SYN_OTA_ERR_NO_FLASH_SLOT,
    SYN_OTA_ERR_FLASH_ERASE,
    SYN_OTA_ERR_FLASH_WRITE,
    SYN_OTA_ERR_OUT_OF_SPACE,
    SYN_OTA_ERR_INTEGRITY_CHECK,
    SYN_OTA_ERR_UNSUPPORTED_CRYPTO,
    SYN_OTA_ERR_INVALID_STATE
};

---

enum SYN_OTA_State

OTA update lifecycle states.

enum SYN_OTA_State {
    SYN_OTA_STATE_IDLE = 0,
    SYN_OTA_STATE_DOWNLOADING,
    SYN_OTA_STATE_DOWNLOADED,
    SYN_OTA_STATE_VERIFYING,
    SYN_OTA_STATE_READY_TO_APPLY,
    SYN_OTA_STATE_APPLIED,
    SYN_OTA_STATE_ERROR
};

---

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.

---

Macro Definition Documentation

define SYN_OTA_SLOT_AUTO

Automatic slot selection constant.

#define SYN_OTA_SLOT_AUTO `0xFFU`

---

---

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