chinmay-02/firmware_sentry

Readme

# Firmware Sentry — ESP32 Crash Reporting

**AI-diagnosed crash reporting for ESP32.** Like Sentry.io, but for
microcontrollers.

When your device crashes in the field, Firmware Sentry captures the fault
registers, stack, and breadcrumb trail *before* the reboot, sends the report
to the cloud once WiFi is back, resolves the program counter to an exact
function/file/line via your ELF's DWARF info, and returns a plain-English
root cause — plus a ready-to-paste prompt for Cursor/Copilot.

- **Free** for up to 10 devices
- **10-minute integration** — one `idf_component.yml` line, no rewiring
- Open source (Apache 2.0)
- Dashboard: [firmwaresentry.io](https://firmwaresentry.io)

## Install

> **Note:** the exact command below depends on the namespace you register on
> [components.espressif.com](https://components.espressif.com) when you
> publish (e.g. `chinmay02/firmware_sentry`) — `compote registry login` sets
> this. Update this line once you've registered; `firmware_sentry` alone is
> a placeholder, not a confirmed published name.

```bash
idf.py add-dependency "firmware_sentry"
```

Or add directly to your project's `idf_component.yml`:

```yaml
dependencies:
  firmware_sentry:
    version: "^1.0.1"
```

## Quick start

Developer mode — single device, hardcoded key, evaluate in 5 minutes
(see `examples/esp32_developer` in the main repo for the full working
version, including WiFi setup and crash-send handling):

```c
#include "nvs_flash.h"
#include "firmware_sentry.h"

void app_main(void)
{
    nvs_flash_init();

    // Installs the panic handler (wraps esp_panic_handler)
    fs_core_init(&g_fs_hal_esp32, &g_fs_transport_https);

    // One-time: store the device's API key from Dashboard -> Groups ->
    // Developer -> Add Device. Idempotent — no-op on later boots.
    if (!fs_is_provisioned()) {
        fs_provision("YOUR_DEVICE_API_KEY");
    }

    // ... connect WiFi ...

    fs_log_event("boot");   // optional breadcrumb, ISR/thread-safe

    if (fs_has_pending_dump()) {
        fs_send_pending();   // sends the previous boot's crash, if any
    }
}
```

For production fleets, use zero-touch provisioning instead of a hardcoded
key — `fs_auto_provision(FS_BURN_SECRET)` registers each device against a
group's burn secret on first boot and persists a unique key per device.
See the full API doc comment in `core/fs_core.h`, or the
`examples/esp32_zero_touch` and `examples/esp32_air_gapped` projects in
the main repo.

Your project's top-level `CMakeLists.txt` needs the wrap flag propagated to
the final `.elf` — this component adds it via an `INTERFACE` link option
automatically, but if you see unresolved `__wrap_esp_panic_handler` symbols,
add explicitly:

```cmake
target_link_options(${CMAKE_PROJECT_NAME}.elf PRIVATE
    -Wl,--wrap=esp_panic_handler
)
```

## Supported targets

`esp32`, `esp32s2`, `esp32s3`, `esp32c3` — see `idf_component.yml` for the
current verified `IDF` version floor.

## Also available for

STM32 (Cortex-M, hardware-validated on NUCLEO-L476RG) and Zephyr
(experimental) — via the amalgamated two-file drop-in distribution rather
than this registry, since those aren't ESP-IDF projects. See the
[full repository](https://github.com/chinmay-02/firmware-sentry-sdk) for
platform details, the STM32 UART transport + gateway script, and the MCP
server for querying crashes from Claude Code / Cursor.

## License

Apache 2.0 — see [LICENSE](https://github.com/chinmay-02/firmware-sentry-sdk/blob/main/LICENSE).