---
name: ficus-ncs-integration
description: Integrate a verified FICUS Reflex card C99 package into an nRF Connect SDK application, check float32 feature order, replay probes on a Nordic DK, and prepare a scoped PPK2 measurement.
---

# Integrate a Reflex card into nRF Connect SDK

Use this skill with Claude Code, Cursor, Copilot-style coding agents or any agent that can read repository instructions. It is an integration guide, not an installer or a compiler service. Ask the user to approve SDK installation, flashing, wiring changes and any dataset transfer. Do not upload private rows or release keys.

## Prerequisites and first checks

Locate the user's existing nRF Connect SDK workspace, its version, west environment and board revision. Use the SDK-supported toolchain. Run `west boards` and choose the target matching the actual DK; current Zephyr documents `nrf54lm20dk/nrf54lm20b/cpuapp`. Older SDKs or A-revision boards may use a different qualifier. Never infer support from a similar core name. The default target intent is the nRF54LM20 DK application CPU.

Get a verified generated package and its matching local training/feature manifest. New generation needs the private FICUS compiler service; an integration skill cannot replace it. Inspect hashes before executing generated code. Do not trust a self-consistent archive hash as independent release authentication.

## Inspect the actual layout and calling convention

The standalone exact-ordinal ZIP contains `<runtime_name>_legal_flash.c`, `<runtime_name>_legal_runtime.h`, `model.json`, `release.json`, `job.json`, `README.md`, and a `host_only/` object. The object is compiled for the host, NOT the Nordic MCU. Read the header and obtain `runtime_name` from the job/explanation rather than inventing a symbol or renaming only the header.

The reviewed standalone declaration is:

```c
#include <stdint.h>
uint16_t ficus_card_legal_predict(const float *features);
```

Here `ficus_card` is an EXAMPLE runtime stem. Replace it with the literal stem in your generated header. There is no exported feature-count macro, checked length argument, status code or path-ID function in this ABI. The caller must supply a non-null, correctly sized array of finite IEEE-754 binary32 values. Return value is a class ID, not a score or path ID. Equality follows the low branch of `feature > threshold`.

Other packages differ. Numeric learning exports `int <runtime_name>_predict(const float *, uint32_t, double *, uint32_t, int32_t *)`; stateful packages add state and reset semantics. Instinct exports explicit group/card routing. Stop and follow the actual header if the package is not standalone exact-ordinal. Do not adapt by guessing.

## Add CMake and Kconfig

Copy only the matching source/header to `cards/`. Preserve generated files unchanged. Add after the existing Zephyr project declaration:

```cmake
target_sources(app PRIVATE cards/ficus_card_legal_flash.c)
target_include_directories(app PRIVATE cards)
target_compile_options(app PRIVATE -fno-fast-math -ffp-contract=off)
```

Use the actual filenames. Enable `CONFIG_FPU=y` for the intended M33 target. For debug output enable `CONFIG_SERIAL=y`, `CONFIG_CONSOLE=y`, `CONFIG_UART_CONSOLE=y`, `CONFIG_PRINTK=y`. Floating-point printk requires `CONFIG_CBPRINTF_FP_SUPPORT=y`; integer class/cycle logs do not. Select a stack reservation and then measure stack high-water use; a reservation is not measured peak SRAM. Existing SDK configurations can override these settings. Review the resolved `.config`.

## Lock feature order and class mapping

Take feature names and class labels from the manifest matching this exact card. Record index, unit, preprocessing/window definition and float32 conversion. Names alone do not establish matching units. Never sort columns alphabetically or include target, timestamp, session ID or metadata as features unless explicitly part of the trained contract. Define application-owned counts and a label table. Fill `const float features[]` in manifest order, reject nonfinite values before calling, and bounds-check the returned class before indexing labels. For Arduino/C++ callers, wrap the generated header in `extern "C"`; the reviewed header has no C++ linkage guard.

## Verify on the DK before live sensor use

Find probe vectors and expected classes in the release/validation artifacts or matching probe report. The archive does not guarantee a separate `probes.h`. If vectors are absent, request them; do not treat an all-zero event as a probe. Generate a small test fixture without modifying the card. Replay every supplied finite vector on the DK, compare its returned class with the expected class and fail the build acceptance on any mismatch. Include equality and adjacent-float32 threshold cases when supplied. Host GCC replay is useful but not a replacement for DK replay. Class parity is not task accuracy, universal proof or board energy.

Build with `west build -b <verified-board-qualifier> <app-path>`, review warnings and memory map, then flash only after approval with `west flash`. Record SDK/compiler version, flags, board revision, card/firmware hashes and test results. Capture real errors; never mark an unbuilt example as passed.

## Time and measure the declared boundary

Use `k_cycle_get_32()` around the intended decision work and `k_cyc_to_us_floor64()` for integer microseconds. Retain raw cycles because short decisions can truncate to zero microseconds. Counter wrap and clock frequency matter. Batch calls and publish the result outside the timed interval; ensure the compiler cannot remove the work.

For PPK2, verify supply mode, isolated DUT rail, common ground, safe logic reference and marker pin. A GPIO can mark a batch of repeated decisions; individual sub-microsecond calls cannot be reliably resolved by a low-rate current trace. Document calls per window and subtract a measured baseline only in a separately named idle-corrected result. Keep serial/radio/sensor work outside a C1 window. C1 is processed float features in RAM to published class, CPU only. Measure end-to-end acquisition/DSP separately.

The reference PPK2 runner integrates current to charge. Energy is charge times voltage only for a justified constant rail. Label an assumed 3.0 V as assumed; a configured supply value is not a voltage measurement. New cards inherit no published benchmark evidence.

## Common errors and repairs

- Undefined predictor: check runtime stem, source list, header and C/C++ linkage; do not link `host_only/*.o`.
- Correct build, wrong classes: compare feature order, units, preprocessing, class map and float32 threshold ties against the exact manifest.
- Missing board target: use an SDK supporting that board/revision; do not silently substitute an nRF54L15.
- NaN, infinity or short input array: validate every field and the manifest count before the unchecked standalone call.
- Zero microseconds: retain cycles and batch calls; do not claim zero execution cost.
- Implausible PPK2 energy: check rail bypass, marker edges, call count, sample continuity, baseline, instrument filtering and voltage evidence.
- Missing paths in field logs: the predictor returns only classes. Add a reviewed trace adapter bound to the same graph before emitting `t_ms,class_id,path_id`; never use class ID as path ID.

Finish with a concise integration report: files changed, actual ABI, ordered feature contract, build and DK replay outcome, firmware identity, measurement boundary and remaining blockers.

## References

API checked against `backend/reflex_adapter/runtime_artifact.py` and `docs/CONNECTED_BUILD_WORKFLOW.md`, 6 November 2026. Board target reference: https://docs.zephyrproject.org/latest/boards/nordic/nrf54lm20dk/doc/index.html . PPK2 reference: https://github.com/IRNAS/ppk2-api-python . This skill is available; the generated integration and hardware results remain project-specific.
