Reader Cloud C SDK

Prebuilt device-side cloud client for JustRead. This release targets ESP32-S3 (Xtensa LX7) with ESP-IDF 6.1.x and ships a C static library, public headers, an ESP-IDF component wrapper, a small example, and the corresponding source snapshot.

The SDK implements the embedded client. It does not contain or replace the hosted Reader Cloud server. Its API covers account login and QR pairing, book metadata/progress synchronization, plugin and lock-screen markets, silent delivery, and WordMachine catalog/progress synchronization.

Package contents

• lib/esp32s3/libreader_cloud.a — precompiled static library.
• include/reader_cloud.h — cloud-client API and public data structures.
• source/ — source snapshot used for this build, including the QR encoder.
• CMakeLists.txt and idf_component.yml — ESP-IDF component wrapper.
• examples/basic/main.c — minimal asynchronous API example.
• BUILD_INFO.json — target, build version, source hashes, archive size, and SHA-256.

Integration

Use ESP-IDF 6.1.x, set IDF_TARGET=esp32s3, and copy this directory to components/reader_cloud_sdk/. Add it to the calling component:

idf_component_register(SRCS "main.c" INCLUDE_DIRS "." REQUIRES reader_cloud_sdk)

The consuming application must provide these JustRead platform components:

• reader_wifi — Wi-Fi state and wait functions.
• reader_ota — canonical CDN-origin validation.
• reader_support — the stable device model identifier.
• reader_wordmachine — local word-list storage, validation, import, and review-event merge.

The project also needs ESP-IDF HTTP/TLS, cJSON, PSA/mbedTLS, NVS, FATFS, eFuse/HMAC, FreeRTOS, timer, and app-description components. The wrapper declares these dependencies. If your app uses different platform components, provide compatible components with the same component names and C ABI, or rebuild the source snapshot with your own adapters.

Initialize NVS, Wi-Fi, and the SD-card filesystem mounted at /sdcard before calling reader_cloud_init(). The cloud configuration is read from /sdcard/.justread/cloud/config.ini. Start operations with the asynchronous *_start() functions, then poll status getters from the UI/main loop; do not wait for HTTP work on the UI thread.

#include "reader_cloud.h"

void cloud_menu_open(void) {
    esp_err_t err = reader_cloud_init();
    if (err == ESP_OK) err = reader_cloud_market_refresh_start();
    if (err != ESP_OK) {
        /* Show a recoverable startup error. */
    }
}

void app_tick(void) {
    reader_cloud_status_t status = {0};
    reader_cloud_get_status(&status);
    /* Render status.busy, status.success, done/total, and message. */
}

examples/basic/main.c shows initialization. The API header documents ownership rules for book arrays and credentials. A successful *_start() only means the worker was created; read the status structure to determine the network result. Only one cloud worker operation runs at a time.

Platform and security notes

• The canonical service origin is https://cdn.xmoa.smn.icu; the SD configuration loader retains migration support for older origins.
• New account binding derives the device identity from the ESP32-S3 Bluetooth MAC. A compatibility fallback can use the legacy HMAC_UP eFuse identity for devices provisioned by older firmware. New binding does not write eFuse.
• Passwords are used for the login request and cleared from the worker buffer afterward. Never log passwords, access tokens, QR pairing codes, device signatures, or eFuse material.
• Account-bound operations require the configured cloud device credential and an initialized hardware crypto backend. SD-card operations require a mounted FAT filesystem at /sdcard.
• Calls are task-context APIs, not ISR-safe. The SDK uses heap/PSRAM where available and performs network work asynchronously.

Build provenance and verification

The binary is built from the JustRead cloud component with ESP-IDF 6.1.x and cloud support enabled. BUILD_INFO.json records the source revision and source/header hashes; the source/ tree is included so the implementation corresponding to the archive can be reviewed. To rebuild with the supported JustRead platform components, use the firmware repository's tools/build_reader_cloud_sdk.py --build-firmware script. The SHA-256 in BUILD_INFO.json is the integrity check for the archive.

This package is licensed under Apache-2.0. The bundled Nayuki QR encoder is MIT-licensed; see THIRD_PARTY_NOTICES.md.