Examples
Every wrapped peripheral has a minimal reference example. Each example carries a board.yaml, an annotated src/main.c, and a boards/ overlay directory — they double as tutorials. Comment density is ~50 % so the source teaches by itself.
Browse the full tree at alp-sdk/examples.
Build any example
cd alp-workspace
# Host smoke, no hardware — plain west (never retired):
west build -b native_sim/native/64 alp-sdk/examples/<category>/<name>
west build -t run
# Real silicon — the target comes from the example's board.yaml
# (`som.sku` + `preset`); `tan build` has no `-b` flag:
tan --project alp-sdk/examples/<category>/<name> build
tan --project alp-sdk/examples/<category>/<name> flash
tan is the SDK's sole user-facing CLI as of v0.12.0 (ADR 0020 Phase 4). The west alp-build / alp-flash / alp-size / alp-image / alp-clean / alp-renode extension commands were retired with the SDK-side build executor; west alp-migrate / alp-lock / alp-quality / alp-emit and plain west build / west flash all survive. Install tan from alplabai/tan-cli.
On native_sim most peripherals don't have emul controllers (only I²C / SPI / GPIO / UART do). Examples that target unwrapped peripherals exit after printing alp_last_error() — that's expected and proves the wrapper plumbing compiles + links cleanly.
Cross-family examples
Work on any conformant SoM. Pick som.sku to match your hardware.
| Example | What it shows |
|---|---|
| Hello World | The first program — boot path + printf heartbeat + the capability API; no peripherals at all |
| Blink | Start here, before anything else — one LED pad as a plain digital GPIO; builds unmodified on both EVKs |
| Board Self-Test | Run this first on a fresh board — SoM identity, SoC ping, power profile, I²C scan; SKIP is not FAIL |
| GPIO Button + LED | GPIO open + input/output basics |
| I²C Scanner | Walk an I²C bus, report ACK'ing devices |
| I²C Master | Read a known device (TMP112) at a known address through its chip driver |
| I²C Device Hub | Every populated device on the EVK sensor/power bus, one real chip driver each |
| I²C Slave (Target Mode) | Answer on the bus as a register-mapped target via <alp/i2c_regfile.h> |
| PWM LED Fade | PWM channel open + duty sweep |
| ADC Voltmeter | ADC sample + millivolt conversion |
| DAC Waveform | DAC sine generation (native DAC12 / GD32-bridged DAC0) |
| Vendor-Ext Composability | One pad, three ways — vendor extensions are additive, never exclusive |
| SPI Loopback | SPI master TX/RX loopback |
| SPI Master | Discrete master — write / transceive / read against an external target |
| SPI Slave (Target Mode) | alp_spi_target_* request/response, the bounded-wait pattern |
| UART Hello World | "printf via UART" — open any port by portable instance ID |
| UART Echo | UART TX + RX echo |
| UART RX Ring Buffer | Interrupt-driven UART RX with byte-granular ring buffer |
| Counter + Alarm | Counter open + alarm callback |
| Timer Periodic Interrupt | Periodic-out-of-one-shot alarm + the ISR-safety / flag-drain pattern (AEN) |
| Power-Managed Sensor | The cores.<id>.power: block — sleep_mode: deep + multi-source wakeup (AEN301) |
| Quadrature Encoder Readout | Quadrature-encoder position read |
| RTC Clock | Set + read SoC RTC |
| Watchdog Feed | Watchdog open + feed cadence |
| CAN Loopback | CAN frame send + receive in loopback |
| I²S Tone | I²S sine-tone playback |
| Audio Loopback | PDM mic in → I²S speaker out |
| Alp Console (example app) | Hosting the alp shell — console + CC3501E Wi-Fi/BLE + RGB LED in one slot0 app |
| Multi-Proc Mailbox | M55-HP / M55-HE mailbox round-trip on AEN (both peer images ship) |
| USB Host Storage | USB mass-storage host via <alp/usb.h> — build-verified on AEN401, xHCI bring-up bench-gated |
| Butterworth Low-Pass | Design a biquad + run tones through the <alp/dsp> IIR chain — pure compute, any SoM |
New to the SDK? Start at hello-world — it proves your toolchain, flash flow, and console before any peripheral is involved.
Third-party library examples
How to enable and use each optional library the SDK integrates, via board.yaml's libraries: key. One focused example per library; every one builds and runs on native_sim/native/64, so none needs hardware to try. Several decode or parse in a CPU/RAM-backed way on the host and document the hardware-backed path as a board.yaml swap.
All are [UNTESTED] on real silicon — read each page's banner before relying on it, since a few carry narrower claims than the rest.
| Example | Library | What it shows |
|---|---|---|
| ETL Fixed Containers | etl | etl::vector / etl::map — fixed-capacity, no heap, no STL |
| fmt Formatting | fmt | fmt::format_to into a fixed buffer — no allocation, no iostream |
| Catch2 Self-Test | Catch2 v3 | Host unit-test binary — TEST_CASEs over a pure helper |
| doctest Self-Test | doctest | Header-only host unit-test binary |
| littlefs Key/Value | littlefs | Mount a RAM-backed LFS; write / read / list a key-value file |
| jsmn JSON Parse | jsmn | Tokenize an embedded JSON config into a typed struct |
| nanopb Encode/Decode | nanopb | Protobuf message encode → buffer → decode round-trip |
| MQTT-SN Publish | coremqtt_sn | MQTT-SN PUBLISH buffer round-trip (hand-rolled wire format — see page) |
| CoAP Client GET | coap (in-tree) | Build a CoAP GET PDU + parse a response PDU with the real API |
| WebSocket Frame | libwebsockets | RFC 6455 masked frame round-trip (hand-rolled — see page) |
| Modbus Server | modbus (in-tree) | In-process client + server over RAW_ADU; the register model |
| minimp3 Decode | minimp3 | Decode an embedded MP3 blob → PCM; print sample count + RMS |
| u8g2 OLED Draw | u8g2 | Render to a RAM framebuffer; ASCII-dump it (HW = SSD1306) |
| gfx_compat Blit | gfx_compat (in-tree) | Fill + blit an RGB565 buffer through the SW-fallback shim |
V2N-specific examples
Exercise the V2N's on-module GD32 bridge + dual Ethernet + secure element.
| Example | What it shows |
|---|---|
| GD32 Bridge Ping | Continuous PING + GET_VERSION liveness over the 25 MHz SPI fast path |
| Board ID Readout | Read SoM EEPROM manifest + assert SKU |
| EEPROM Manifest Dump | Hexdump + decode the 128-byte EEPROM manifest |
| Dual Ethernet Bring-up | Bring up both RTL8211FDI PHYs; WoL configuration |
| RTC Multi-Alarm | Multi-source callbacks on the RV-3028-C7 dispatcher |
| Temperature Sensor | TMP112 read loop |
| PWM Fan Control | Ramp a GD32-side PWM channel along a fan curve |
| Secure-Element Sign | OPTIGA Trust M ECDSA-P256 sign via raw APDU |
| xSPI NOR Read/Write | Erase + write + verify on the on-module xSPI NOR |
| eMMC Block Stat | Read on-module eMMC geometry |
| GD32 SWD Flash | Host-driven SWD bit-bang — bridge firmware recovery |
| GD32 Bridge HIL Soak | Full-command-set pass/fail soak of the bridge (silicon-validated) |
| GD32 Bridge Functional | Value-asserting single pass over the bridge surfaces + a forever PWM7 scope staircase |
| GD32 Bridge Loopback (Jumpered) | Tier-B: three copper jumpers close DAC→ADC, PWM→QENC, PWM→capture (bench-only) |
| BRD_I2C Bring-up | Read-only scan + probe of all 8 management-bus ICs |
| Power Monitor | Live per-rail power table from the EVK's INA236 monitors (A55/Yocto user space, EVK-only) |
V2N-M1 (DEEPX DX-M1)
Both are [UNTESTED] — the DEEPX NPU has no Zephyr-side emulator, so verification gates on V2M HiL plus the customer-side dx_rt runtime.
| Example | What it shows |
|---|---|
| DEEPX DX-M1 Inference | NPU bring-up + one inference through the portable <alp/inference.h> surface |
| ROS 2 Perception Node | A55/Yocto ROS 2 node; detection on DEEPX, auto-fallback to DRP-AI3 on plain V2N |
AEN-specific examples
The v0.7 on-silicon bring-up of the E1M-AEN801 (Alif Ensemble E8) shipped a full bench suite — 15/17 aen-* apps PASS on real hardware. See E1M-AEN bench status.
| Example | What it shows |
|---|---|
| EdgeAI Vision (AEN) | Camera → ISP → Ethos-U inference → OLED overlay |
| NPU Inference (Ethos-U85) | Vela int8 model on the Ethos-U85; real person_detect MobileNet from MRAM (PASS) |
| CC3501E Bring-up | Power + PING the TI CC3501E Wi-Fi/BLE bridge over inter-chip SPI |
| CC3501E GPIO Proxy | Drive + read a proxied CC3501E GPIO and the camera LDOs over the bridge |
| CC3501E Companion Tour | The capstone: init → Wi-Fi scan/connect → TCP socket → BLE scan → proxied GPIO |
| CC3501E BLE GATT | Silicon-proven GATT-server advertise path through portable <alp/ble.h> (server-only bench) |
| CC3501E GATT Register | Dynamic GATT registration + register-before-advertise ordering guard (PASS/FAIL gate) |
| Ethernet Link | E8 GMAC up + DHCP lease (bench-verified; DMA buffers in SRAM0) |
| Analog Validate | DAC0 → ADC loopback with corrected E8 references (PASS) |
| EEPROM Manifest | Read + decode the 128-byte SoM manifest over SoC I²C2 |
| Dual-Core Boot & IPC | Boot both M55 cores; HE↔HP doorbell + shared-memory round-trips |
| Dual-Core RPC / RPMsg | OpenAMP RPMsg pingpong over MHUv2 (16/16 PASS) |
| Secure-Element Sign | OPTIGA Trust M ECDSA-P256 sign over LPI2C0 |
| Peripheral Regchecks | All 18 aen-*-regcheck on-silicon driver smoke tests, in one index |
| AEN bench + bring-up tools | The 29 non-regcheck bench apps — dual-core, TrustZone + SE, NPU, power, storage, peripheral bench |
| AEN Sim Vision | Vision + wake-word pipelines under the Renode --sim-mode simulator — real TFLM, software path (no NPU in sim) |
The AEN bench class
Beyond the catalog examples above, examples/aen/ holds ~47 bench and bring-up tools that carry no board.yaml — so they are outside the catalog and outside the portable-example contract by construction. They exist to validate E8 silicon, not as app templates. Two aggregate pages index the whole set:
- Peripheral Regchecks — the 18
aen-*-regcheckapps: functional checks, DT binding/staging checks, and the NPU presence probes. - AEN bench + bring-up tools — the remaining 29: dual-core boot + IPC, TrustZone + secure element, NPU + vision, power, storage + memory, and the peripheral bench.
Application demos (v0.5 showcase, [UNTESTED])
End-to-end demos that combine multiple chip drivers + library knobs + LVGL UIs. All marked [UNTESTED] — they compile and pass smoke tests, HiL bring-up arrives in v0.6 / v0.8.
Edge AI
| Demo | What it shows |
|---|---|
| AI Camera Viewer | OV5640 → Ethos-U person-detect → LVGL bbox overlay (AEN) |
| Realtime Object Detection | OV5640 → DEEPX DX-M1 YOLOv8-tiny → LVGL overlay (V2N-M1) |
| Vibration Anomaly Detection | LSM6DSO vibration window → 1D-CNN anomaly score (AEN) |
Edge AI — sensing & predictive maintenance (v0.9)
New verticals added in v0.9. Each ships DSP feature cores host-unit-tested on native_sim, a model stub with a deterministic fallback (no trained model shipped), and HiL bench-gated. Same source flips som.sku to E1M-V2M101 for the DEEPX DX-M1 path.
Their spectral and statistical maths run on the portable <alp/dsp.h> chain — an ALP_DSP_STAGE_FFT stage plus alp_dsp_stats_f32(), backed by CMSIS-DSP on the M55 and portable C on native_sim — rather than hand-rolled FFT/stats code. The one deliberate exception is acoustic-anomaly-wind-turbine, which keeps a single-bin Goertzel for a reason it explains on its page.
| Demo | What it shows |
|---|---|
| Visual Defect Detection | CSI camera → autoencoder reconstruction-error surface anomaly → PASS/FAIL (AEN) |
| Cold-Chain Monitor | BME280 → MKT / dewpoint / excursion metrics → 4-state integrity classifier |
| Multimodal Fusion PdM | Vibration + current + temperature fused → cross-modal fault hypothesis |
| Motor Current Signature | INA236 DC current window → 5-state motor classifier (OFF/NORMAL/INRUSH/OVERLOAD/STALL) |
| Wearable Activity + Fall | ICM-42670 IMU → activity classifier + rule-based 3-phase fall detector |
| Rail Predictive Maintenance | ICM-42670 vibration + NEO-M9N GNSS → geotagged rail-defect survey, one CSV/25 m |
Audio AI
| Demo | What it shows |
|---|---|
| Wake-Word ("Hey Alp") | Always-on KWS on AEN's low-power AI subsystem; ~1 mW continuous |
| Noise Suppression | Real-time spectral denoise (V2N) — headset / hearable / conferencing |
| Acoustic Safety Events | PDM mic → per-frame DSP → 4-class event classifier (AMBIENT/GLASS_BREAK/ALARM/SCREAM) |
| Acoustic Anomaly (Wind Turbine) | Nacelle mic → rotor-order normalised anomaly score at blade-pass harmonics |
Drone
| Demo | What it shows |
|---|---|
| Drone HUD | IMU + GNSS + battery + ST7789 attitude HUD with LVGL; Madgwick fusion via <alp/ahrs.h> |
| Drone Autopilot | Quadcopter flight controller — cascaded 1 kHz / 250 Hz / 25 Hz loops on the portable <alp/pid.h> |
IoT
| Demo | What it shows |
|---|---|
| MQTT Telemetry | Wi-Fi station + mqtts:// publish loop over the AEN801 CC3501E bridge — preview; CONFIG_MBEDTLS held off, so no TLS round-trip is exercised |
| IoT Dashboard | BME280 → MQTT/TLS publish + local LVGL dashboard |
| IoT Fleet OTA | Mender + MCUboot + OPTIGA-pinned ECDSA-P256 signed updates |
| Firmware Update Log | Tamper-evident, hash-chained firmware-update audit log (portable) |
LVGL UI
| Demo | What it shows |
|---|---|
| LVGL Widgets Demo | Headline LVGL widget showcase on ST7789 |
| LVGL Benchmark | Per-scene FPS comparison across SoMs — reveals what GPU2D / DMA2D buy you per SKU |
| LVGL Music Player | Upstream lv_demo_music() player UI (display-only — no audio path) |
| LVGL Dashboard (E1M-X EVK) | LVGL 9 on the V2N MIPI-DSI panel via Linux DRM/KMS — the A55-side counterpart |
The Zephyr LVGL examples all open their panel with alp_display_open() (<alp/display.h>) and bind LVGL via alp_gui_lvgl_attach() (<alp/gui.h>) with CONFIG_LV_Z_AUTO_INIT=n, rather than calling Zephyr's display_* APIs directly. lvgl-widgets-demo carries the reference init sequence. lvgl-dashboard-x-evk is the exception: on Linux the DRM stack is the portable surface, so it uses LVGL's DRM backend directly.
Heterogeneous-compute (v0.6 flagships)
One board.yaml, one orchestrator pass, two OSes — A-class Yocto + M-class Zephyr on the same SoM, talking through framed RPMsg via <alp/rpc.h>. Walkthrough at Heterogeneous Builds.
| Demo | What it shows |
|---|---|
rpmsg-v2n | V2N101 A55 (Yocto) ↔ M33-SM (Zephyr) pub/sub over RPMsg |
rpmsg-aen | AEN801 A32 (Yocto) ↔ M55-HP (Zephyr) with cacheable carve-out |
rpmsg-imx93 | iMX93 A55 (Yocto) ↔ M33 (Zephyr) |
heterogeneous-offload | A55 delegates FFT to the M33-SM peer via synchronous alp_rpc_call |
End-to-end reference applications
| Application | Stack |
|---|---|
| EdgeAI Vision (AEN) | Camera capture → ISP → Ethos-U inference → on-board OLED |
| IoT Connected Camera | Camera capture → DRP-AI inference → MQTT/TLS publish + LVGL UI |
| Production Deployment | The v1.0 integration flagship — factory provisioning → secure boot → OTA → remote attestation |
All three follow the same board.yaml workflow at a larger scale.
See also
- Quick start — first example end-to-end
- Firmware quickstart — per-SoM patterns
board.yamlreference