Embedded SDK API Reference

Complete API documentation for the Zelta embedded SDK.

Initialization

zelta_init

Initialize the Zelta SDK with configuration.

int zelta_init(const zelta_config_t *config);

Parameters:

• config: Pointer to configuration structure

Returns:

• ZELTA_OK on success
• ZELTA_ERR_INVALID_PARAM if config is NULL or invalid
• ZELTA_ERR_NO_MEMORY if memory allocation failed

Example:

zelta_config_t config = {
    .server_url = "https://project.supabase.co/functions/v1",
    .api_key = "your-api-key",
    .device_id = "device-001",
    .current_version = "1.0.0",
};

if (zelta_init(&config) != ZELTA_OK) {
    LOG_ERR("Failed to initialize Zelta");
}

zelta_deinit

Clean up and release Zelta resources.

void zelta_deinit(void);

Update Operations

zelta_check_update

Check if a firmware update is available.

int zelta_check_update(zelta_update_info_t *info);

Parameters:

• info: Pointer to update info structure (filled on success)

Returns:

• ZELTA_UPDATE_AVAILABLE if update is available
• ZELTA_NO_UPDATE if current version is latest
• ZELTA_ERR_NETWORK on network error
• ZELTA_ERR_AUTH if API key is invalid

Update Info Structure:

typedef struct {
    char version[32];           // New version string
    char sha256[65];            // SHA-256 hash (hex)
    char signature[256];        // Base64 signature
    char download_url[512];     // Signed download URL
    size_t size;                // Firmware size in bytes
    char release_notes[256];    // Optional release notes
} zelta_update_info_t;

Example:

zelta_update_info_t update;
int ret = zelta_check_update(&update);

switch (ret) {
    case ZELTA_UPDATE_AVAILABLE:
        LOG_INF("Update available: %s (%zu bytes)", 
                update.version, update.size);
        break;
    case ZELTA_NO_UPDATE:
        LOG_INF("Firmware is up to date");
        break;
    default:
        LOG_ERR("Check failed: %d", ret);
}

zelta_download_firmware

Download firmware to flash storage.

int zelta_download_firmware(const zelta_update_info_t *info);

Parameters:

• info: Update info from zelta_check_update

Returns:

• ZELTA_OK on success
• ZELTA_ERR_NETWORK on download error
• ZELTA_ERR_STORAGE on flash write error
• ZELTA_ERR_HASH_MISMATCH if hash verification failed
• ZELTA_ERR_SIGNATURE_INVALID if signature verification failed

zelta_download_and_apply

Download, verify, and apply update in one call.

int zelta_download_and_apply(const zelta_update_info_t *info);

Parameters:

• info: Update info from zelta_check_update

Returns:

• ZELTA_OK on success (reboot required)
• Same errors as zelta_download_firmware

Example:

zelta_update_info_t update;
if (zelta_check_update(&update) == ZELTA_UPDATE_AVAILABLE) {
    if (zelta_download_and_apply(&update) == ZELTA_OK) {
        LOG_INF("Update applied, rebooting...");
        sys_reboot(SYS_REBOOT_COLD);
    }
}

zelta_report_status

Report update status to server.

int zelta_report_status(const char *firmware_id, 
                        zelta_update_status_t status,
                        const char *error_message);

Parameters:

• firmware_id: Firmware ID from update info
• status: Status code
• error_message: Optional error message (can be NULL)

Status Codes:

typedef enum {
    ZELTA_UPDATE_STATUS_STARTED,
    ZELTA_UPDATE_STATUS_DOWNLOADING,
    ZELTA_UPDATE_STATUS_VERIFYING,
    ZELTA_UPDATE_STATUS_APPLYING,
    ZELTA_UPDATE_STATUS_COMPLETED,
    ZELTA_UPDATE_STATUS_FAILED,
    ZELTA_UPDATE_STATUS_ROLLED_BACK,
} zelta_update_status_t;

Verification

zelta_verify_hash

Verify SHA-256 hash of firmware in flash.

int zelta_verify_hash(const char *expected_hash);

Parameters:

• expected_hash: Expected SHA-256 hash (64 hex characters)

Returns:

• ZELTA_OK if hash matches
• ZELTA_ERR_HASH_MISMATCH if hash doesn't match

zelta_verify_signature

Verify ECDSA signature of firmware.

int zelta_verify_signature(const uint8_t *hash,
                           size_t hash_len,
                           const char *signature_base64);

Parameters:

• hash: SHA-256 hash of firmware (32 bytes)
• hash_len: Hash length (32)
• signature_base64: Base64-encoded ECDSA signature

Returns:

• ZELTA_OK if signature is valid
• ZELTA_ERR_SIGNATURE_INVALID if verification failed

Utility Functions

zelta_get_current_version

Get the currently running firmware version.

const char *zelta_get_current_version(void);

zelta_get_device_id

Get the configured device ID.

const char *zelta_get_device_id(void);

zelta_set_progress_callback

Set callback for download progress updates.

void zelta_set_progress_callback(zelta_progress_cb callback);

Callback Signature:

typedef void (*zelta_progress_cb)(size_t downloaded, size_t total);

Error Codes

| Code | Value | Description | |------|-------|-------------| | ZELTA_OK | 0 | Success | | ZELTA_UPDATE_AVAILABLE | 1 | Update available | | ZELTA_NO_UPDATE | 2 | No update needed | | ZELTA_ERR_INVALID_PARAM | -1 | Invalid parameter | | ZELTA_ERR_NO_MEMORY | -2 | Memory allocation failed | | ZELTA_ERR_NETWORK | -3 | Network error | | ZELTA_ERR_AUTH | -4 | Authentication failed | | ZELTA_ERR_STORAGE | -5 | Flash storage error | | ZELTA_ERR_HASH_MISMATCH | -6 | Hash verification failed | | ZELTA_ERR_SIGNATURE_INVALID | -7 | Signature verification failed | | ZELTA_ERR_TIMEOUT | -8 | Operation timed out | | ZELTA_ERR_LIMIT_EXCEEDED | -9 | Rate limit exceeded |

Thread Safety

The Zelta SDK is not thread-safe by default. If you need to call Zelta functions from multiple threads:

1. Use a mutex to protect all Zelta calls
2. Or enable CONFIG_ZELTA_THREAD_SAFE=y (uses internal mutex)

// Manual mutex protection
K_MUTEX_DEFINE(zelta_mutex);

void check_for_updates(void) {
    k_mutex_lock(&zelta_mutex, K_FOREVER);
    // Zelta calls here
    k_mutex_unlock(&zelta_mutex);
}