Crash reports with ESP-IDF

Prerequisites

Before you start integrating your device with Spotflow, make sure you:

• have development environment with ESP-IDF 5.0+ installed,
• have established a connection to the internet from the device,
• have a Spotflow ingest key.

Alternatively, you can follow the Quickstart: ESP-IDF Integration Guide to integrate Spotflow using sample application, instead of adding the spotflow module to an existing project.

Install Spotflow Device Module

Add the spotflow module as a dependency to your idf_component.yml file.

dependencies:
    spotflow:
        git: https://github.com/spotflow-io/device-sdk.git
        path: esp_idf/spotflow
        version: main

Update Configuration

Enable Spotflow coredump collection, configure device authentication, and tell ESP-IDF to use a custom partition table:

CONFIG_SPOTFLOW_DEVICE_ID="esp-device-001" # Set unique identifier of your device
CONFIG_SPOTFLOW_INGEST_KEY="{your-ingest-key}" # Set your Spotflow ingest key

# Enable Spotflow coredump collection
CONFIG_SPOTFLOW_COREDUMP_BACKEND=y

# Include a build identifier so Spotflow can link crashes to uploaded symbols
CONFIG_SPOTFLOW_USE_BUILD_ID=y

# Use a partition table with a coredump partition
CONFIG_PARTITION_TABLE_CUSTOM=y
CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"
CONFIG_PARTITION_TABLE_FILENAME="partitions.csv"

# Recommended: avoid slowing down coredump writes and triggering watchdogs
CONFIG_ESP_COREDUMP_LOGS=n

The CONFIG_SPOTFLOW_INGEST_KEY is a secret key that allows your device to authenticate with Spotflow. You can manage your ingest keys on the ingest keys page.

See details about the Spotflow-specific options later in this doc.

Define Core Dump Flash Partition

ESP-IDF stores the core dump in a dedicated flash partition before Spotflow uploads it after reboot. Add a coredump data partition to your custom partition table:

# Name,   Type, SubType, Offset,  Size
nvs,      data, nvs,     0x9000,  0x6000
phy_init, data, phy,     0xf000,  0x1000
factory,  app,  factory, 0x10000, 0x150000
coredump, data, coredump,,        256K

If Flash Encryption is enabled on the device, mark the core dump partition as encrypted:

coredump, data, coredump,,        256K, encrypted

Initialize Spotflow

Include spotflow.h and call spotflow_init() after your network connection is established. On startup, spotflow_init() starts the Spotflow MQTT client and checks whether an ESP-IDF core dump is available for upload.

#include "spotflow.h"

void app_main(void)
{
    // Initialize NVS, networking, Wi-Fi, and connect to the internet first.

    spotflow_init();
}

Upload ELF File with Symbols

To unlock advanced crash analysis features, upload the ELF file containing debug symbols to Spotflow.

The Spotflow ESP-IDF module can include the ESP-IDF application ELF SHA-256 value as the build ID in the uploaded core dump metadata. Spotflow uses that build ID to link the crash report with the matching firmware symbols.

You can upload symbol files to firmwares to enable automatic analysis.

See dedicated Firmware Management page for information about managing firmwares and symbol files.

Wait for or Simulate a Crash

ESP-IDF creates the core dump when a fatal error occurs. After the device reboots and reconnects, Spotflow uploads the stored core dump.

To simulate a crash, call esp_system_abort() from task context:

#include "esp_system.h"

static void simulate_crash(void)
{
    esp_system_abort("Deliberate crash for Spotflow coredump test");
}

The SDK also includes a complete coredump example that triggers a crash from the board's BOOT button.

Press BOOT only after the application has booted and connected; do not press RESET/EN. On ESP32-C6 boards, the example expects the BOOT button on GPIO9. If your board uses a different button GPIO, update the example's GPIO_INPUT_IO_0 definition.

To create a project from the example, run:

idf.py create-project-from-example "spotflow/device_sdk:coredump"

Analyze Crash Reports in the Web Application

Once your device is integrated, you can analyze crash reports and core dumps in the web application.

You can list the crash reports in the Events page, which gives you a comprehensive view of all events collected from your devices. There, you can filter crash reports by their content, device ID and other metadata.

Automatic Analysis

We automatically analyse each crash report to give you a quick insight into the issue. For precise results, we extract data directly from the core dump (stack traces, register values, etc.), decompile the firmware binary, and review relevant documentation. Our proprietary AI agent then investigates the crash, leveraging all available data. The result is available in the detail view of each crash report.

Detailed insights are available for each crash report.

The full analysis includes a detailed description of the root cause and suggestions for fixing the issue. Also, for complete transparency, we include references to all documentation pages used, allowing you to explore further.

Detailed description of the crash and suggested fixes.

We also provide all the raw data extracted from the core dump, so you can dive deeper into the issue if needed. This includes:

• Stack traces of one or more threads.
• Register values and local variables for individual stack frames. If a register value is available, it can be also casted to several types.
• State of global variables at the time of the crash.