Device agent

MCU install (ESP-IDF / FreeRTOS)

The public Meshanics MCU SDK includes an ESP-IDF component for ESP32-S3. It runs as a FreeRTOS task and uses the same schema-v2 signed release verifier and anti-rollback decisions as the Zephyr port.

Supported profile. This guide covers ESP-IDF on ESP32-S3 with the partition layout and rollback configuration below. Qualify the exact board, bootloader, flash-security settings, network transport and recovery behavior used by your product before a production rollout. Other vendor FreeRTOS BSPs are outside this support profile.

What the integration provides

Device mTLS registration, heartbeat and delivery
Signed manifests bound to the product, release payload and rollout
Local artifact, hardware profile and optional product checks
Streaming SHA-256 verification before the image is armed
ESP-IDF A/B application staging
NVS-backed applied, pending and failed anti-rollback state
On-device P-256 key generation, CSR claim and tenant manifest-key pinning
Customer health callback before first-boot confirmation
Automatic return to the prior application when confirmation fails

Create a batch under Devices -> + Microcontroller batch, select ESP-IDF with FreeRTOS, and download the provisioning JSON. Use its claim_url, claim_token, artifact_base_url, fleet_base_url, server_ca_pem, artifact_name, target_profile and optional product_id as the runtime configuration. Install the bundle through a protected manufacturing path. On first boot, the device generates its own private key, claims its device certificate, fetches the tenant manifest key over mTLS and stores the resulting identity in NVS. Production products must enable NVS encryption. The SDK does not persist the claim token.

Build requirements

ESP-IDF 5.3 or newer
An ESP32-S3 partition table with otadata and two OTA application slots
CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE=y
CONFIG_MBEDTLS_X509_CREATE_C=y
CONFIG_MBEDTLS_X509_CSR_WRITE_C=y
Networking and NVS initialized before the Meshanics task starts

Add the component directory in your top-level CMakeLists.txt:

set(EXTRA_COMPONENT_DIRS "/path/to/mcu-sdk/ports/esp-idf")
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_device)

The component refuses to compile when bootloader rollback is disabled. A health check without a recovery path is not presented as rollback.

Start the agent

Load the protected provisioning material after WiFi or Ethernet is connected:

#include <meshanics/esp_idf.h>

static bool application_health(void *unused)
{
    (void)unused;
    return sensor_ready() && control_task_running();
}

static meshanics_esp_idf_config config = {
    .firmware_version = "1.0.0",
    .health = application_health,
    .health_attempts = 12,
    .health_delay_ms = 5000,
};

static meshanics_provision_bundle bundle;
if (meshanics_provision_bundle_parse(protected_bundle_json, &bundle) != 0 ||
    meshanics_esp_idf_apply_bundle(&config, &bundle) != MESHANICS_OK) {
    abort();
}
meshanics_esp_idf_start(&config);

The provisioning storage must remain valid while the agent task runs. Do not compile production credentials into a generic firmware image. Production devices must enable NVS encryption before the claimed identity is stored.

The defaults make 12 health attempts with a 5 second delay before rejecting a new image. Set both fields to match the product's bounded startup time.

Boot and recovery sequence

The agent verifies the Ed25519 release authorization and its schema-v2 bindings.
Firmware is streamed into the inactive application partition.
The downloaded bytes are checked against the signed SHA-256 digest.
Pending release state is committed to NVS before the boot partition changes.
After reboot, registration and the application health callback must succeed.
The application is confirmed and the anti-rollback counter is promoted.
If confirmation fails, ESP-IDF marks the candidate invalid and boots the prior application.

Production device security

ESP-IDF Secure Boot v2 supplies the customer-owned image-signing boundary that MCUboot supplies on Zephyr. Flash encryption and encrypted NVS protect device credentials at rest. These eFuse operations must be part of a controlled manufacturing procedure, so the SDK sample does not enable them automatically.

Without Secure Boot v2, the signed Meshanics manifest and digest still authorize the exact bytes delivered, but the device must not be described as enforcing two independent firmware signatures.

Product qualification

Before production use, exercise the complete signed update and recovery path on the product hardware. Confirm a successful update, a deliberately failed health callback, automatic bootloader fallback, and the resulting device state in the control panel. Repeat this qualification whenever the board, partition table, bootloader policy or manufacturing security configuration changes.