ferrite-sdk

Firmware observability for ARM Cortex-M — crashes, metrics, and logs with zero alloc.

---

Live Demo

ferrite.shanifaas.com — 5 real boards reporting telemetry.

Board	Stack	Transport
ESP32-C3	Embassy (esp-hal)	WiFi → HTTP
STM32L4A6	Embassy (embassy-stm32)	USB CDC
STM32WL55	RTIC 2.x	LPUART VCP
STM32H563	Embassy (embassy-stm32)	Ethernet
nRF5340	Zephyr 4.1 (C + FFI)	BLE GATT

Login: admin / HdNka6HvI5FfqG8TOT1SiQ

Demo data resets every 2 hours.

---

What It Does

ferrite-sdk captures everything you need to debug embedded devices in the field:

• HardFault capture — all Cortex-M registers, CFSR/HFSR, 64-byte stack snapshot
• Reboot reason tracking — power-on, watchdog, fault, brownout, software reset
• Metrics — counters, gauges, histograms in a fixed-capacity ring buffer
• Trace logs — defmt output captured and uploaded as binary fragments
• Transport agnostic — UART, BLE, LoRa, USB CDC, HTTP — implement one trait
• Chunk encryption — AES-128-CCM for untrusted transports
• RLE compression — bandwidth-efficient chunk encoding for constrained links
• OTA negotiation — firmware update coordination via chunk protocol

Data survives reboots via retained RAM. The companion server stores, decodes, and symbolicates everything.

The platform includes a full-stack observability pipeline: an edge gateway for BLE/USB/LoRa bridging, an ingestion server with alerting, Prometheus metrics, and role-based access control, and a web dashboard for real-time fleet monitoring.

Memory Footprint

Default configuration: ~1.7 KB RAM, ~6 KB flash. No alloc, no std, no panics.

Quickstart (Embassy + nRF52840)

1. Add dependencies:

[dependencies]
ferrite-sdk = { version = "0.1", features = ["cortex-m", "defmt", "embassy"] }
ferrite-embassy = "0.1"

2. Add linker fragment (see linker/nrf52840-retained.x)

3. Initialize the SDK:

ferrite_sdk::init(SdkConfig {
    device_id: "sensor-42",
    firmware_version: env!("CARGO_PKG_VERSION"),
    build_id: 0,
    ticks_fn: || embassy_time::Instant::now().as_ticks(),
    ram_regions: &[RamRegion { start: 0x20000000, end: 0x20040000 }],
});

4. Record telemetry:

ferrite_sdk::metric_gauge!("temperature", 23.5);
ferrite_sdk::metric_increment!("packets_sent");
defmt::info!("system started");

5. Upload periodically:

#[embassy_executor::task]
async fn upload(transport: MyUart) -> ! {
    ferrite_embassy::upload_task::upload_loop(transport, Duration::from_secs(60)).await
}

Supported Targets

Target	Architecture	Example
nRF52840	Cortex-M4F	examples/embassy-nrf52840
STM32F4	Cortex-M4F	Linker script included
RP2040	Cortex-M0+	Linker script included

All thumbv7m-none-eabi, thumbv7em-none-eabi, and thumbv7em-none-eabihf targets are supported.

Repository Structure

Crate	Description
ferrite-sdk	Core no_std SDK — crashes, metrics, trace, chunks, encryption, compression
ferrite-embassy	Embassy async upload task
ferrite-rtic	RTIC resource wrapper + blocking upload
ferrite-ffi	C FFI static library for Zephyr/FreeRTOS
ferrite-server	Ingestion server — auth, alerting, Prometheus, groups, OTA, rate limiting
ferrite-dashboard	Dioxus WASM dashboard — fleet view, metrics charts, fault diagnostics
ferrite-gateway	Edge gateway — BLE/USB/LoRa chunk forwarding with offline buffering
ferrite-ble-nrf	nRF52840 BLE transport (SoftDevice, excluded from workspace)

Build

# Host tests (no embedded toolchain needed)
cargo build -p ferrite-sdk --no-default-features
cargo test -p ferrite-sdk --no-default-features
cargo test -p ferrite-server

# Cross-compile for Cortex-M
rustup target add thumbv7em-none-eabihf
cargo build -p ferrite-sdk --features cortex-m,defmt,embassy --target thumbv7em-none-eabihf

# Run the server (uses .env for config, see .env.example)
cargo run -p ferrite-server

# Run the dashboard (proxies API to localhost:4000)
cd ferrite-dashboard && dx serve

# Build the edge gateway
cargo build -p ferrite-gateway

# Docs site
cd docs && npm install && npm run dev

Documentation

Full documentation is available at the VitePress docs site, covering:

• Architecture & design
• Transport layer (UART, BLE, USB CDC, HTTP, LoRa)
• Security & encryption (AES-128-CCM, RBAC, API keys)
• Binary chunk wire format
• Server configuration (auth, alerting, retention, Prometheus)
• Dashboard guide (fleet view, metrics, faults, exports)
• Gateway setup (BLE/USB/LoRa edge bridging)
• C FFI API reference
• Integration guides (Embassy, RTIC, bare-metal, Zephyr, FreeRTOS)
• Target platform setup (nRF52840, RP2040, STM32F4)

License

Licensed under the MIT License.