# FICUS UART capture firmware

**Reference sample — build with nRF Connect SDK; not CI-built here.** Default target intent: nRF54LM20 DK application CPU. No sensor is assumed to be fitted. Without a ready `capture-sensor` alias this emits a deterministic triangular signal named `synthetic_signal`; synthetic rows are not sensor evidence.

## Build and connect

Use an installed nRF Connect SDK version that supports your board revision. Confirm with `west boards`. Current Zephyr documents the B-revision qualifier below; an older SDK or an A-revision board may differ.

```sh
west build -b nrf54lm20dk/nrf54lm20b/cpuapp ./capture-firmware
west flash
```

Flashing replaces the current application. Back up anything needed and authorize flashing first. The example configures the devicetree `zephyr,console` UART at **115200 baud, 8 data bits, no parity, 1 stop bit, no flow control**. Use the DK debugger's virtual COM port. If runtime UART configuration is not supported in your SDK, set the console UART's `current-speed = <115200>` in a local board overlay and adjust the initialization deliberately. No shell or other firmware output may share this stream; boot banner and logging are disabled.

In Reflex Lab choose a project → Data → Capture, request the serial port, record, label and save a dataset. Web Serial needs a supporting browser and a secure context or localhost. Browser permissions are user-controlled. Close other terminal applications using the port first.

## Exact stream format

The optional header and all rows use this exact grammar:

```text
# ficus-capture v1 channels=synthetic_signal rate_hz=50
0,-1.000000
20,-0.960000
40,-0.920000
```

The timestamps above illustrate the format; actual timestamps are `k_uptime_get()` milliseconds since boot. A row is `<t_ms>,<v0>,<v1>,...`, with finite numeric values, comma separators, decimal points and a newline. Header channel order is the value order. There is no CSV column-name row, label or class ID in this device stream. The browser applies recording metadata and labels separately. This is NOT the Field monitor's `t_ms,class_id,path_id` decision-log protocol.

## Add a real sensor

The source uses Zephyr's generic `sensor_sample_fetch`, `sensor_channel_get` and `sensor_value_to_double` APIs. In a local overlay, add a `capture-sensor` alias pointing at an enabled supported sensor node, enable its driver in `prj.conf`, and wire it according to its datasheet. The provided channel is `SENSOR_CHAN_AMBIENT_TEMP` in degrees Celsius, named `temperature_c`. Internal die temperature is not necessarily ambient temperature; if you select it, change the channel and header to match its semantics. For an accelerometer, explicitly change the channel to `SENSOR_CHAN_ACCEL_XYZ`, emit three values, and name all three channels with their actual units. Never assume a generic DK includes an IMU.

Sensor failures skip rows without silently changing the signal to synthetic; timestamps expose the gaps. The requested 50 Hz is a reference setting, not a measured timing guarantee. UART transmission and driver latency can miss deadlines. Verify timestamp differences and channel order before training. Sampling raw values does not implement the processed-feature contract of an existing Reflex card. Define windowing, units and float32 conversion in Prepare and reproduce them in the deployed application.

## Scope and checks

Check compilation warnings, resolved Kconfig, UART speed, actual board/revision, sensor readiness and a short captured file before a long recording. No SDK build, flashing or physical UART test was performed for this reference. It is a starting point, not measured firmware. Keep capture and verbose logs outside any PPK2 C1 decision window.

References reviewed 6 November 2026: https://docs.zephyrproject.org/latest/boards/nordic/nrf54lm20dk/doc/index.html and https://docs.zephyrproject.org/latest/hardware/peripherals/sensor/index.html .
