# STEVAL-MKI217V1 polling test (Genesys2)

This standalone bare-metal application reads the LSM6DSOX on the
STEVAL-MKI217V1 over the existing Genesys2 PMOD SPI peripheral. It does not
use INT1/INT2. The LIS2MDL magnetometer on the module is not enabled in this
first electrical/readout smoke test; it is internally reachable through the
LSM6DSOX sensor hub and will be integrated separately after the IMU link is
verified.

## Wiring

| STEVAL-MKI217V1 | Genesys2 | Function |
|---|---|---|
| CS | JC1 | active-low chip select |
| SDA | JC2 | SPI MOSI / SDI |
| SDO | JC3 | SPI MISO |
| SCL | JC4 | SPI clock / SPC |
| VDD | 3.3 V | sensor supply |
| VDDIO | 3.3 V | digital I/O supply |
| GND | GND | common ground |

`CS` is mandatory for four-wire SPI. Never feed 5 V to VDDIO. JC9 is the
optional sensor interrupt pin but is deliberately unused here.

## Hardware bring-up results (2026-07-13)

The Genesys2/Rocket ELF was loaded over GDB and the UART output was captured
on `/dev/ttyUSB0`. All eight identity reads returned `0xff` instead of the
expected `0x6c`. In that trial SCL, SDA, SDO, VDDIO, VDD and GND were connected
but CS was not. An all-`0xff` response is therefore the expected open/unselected
SPI-bus result, not a valid sensor sample.

After CS was connected to JC1, all eight identity reads returned `0x6c` and
configuration read-back returned `CTRL1_XL=0x40`, `CTRL2_G=0x40`,
`CTRL3_C=0x44` and `STATUS=0x07`.

The original FPGA SPI implementation sampled MISO on the data-change edge.
A first 60-second diagnostic log consequently contained about 68.4% bit-shifted
samples. The generic SPI control register was extended with independent CPOL
and CPHA bits while retaining the single/quad-width bit. Mode 0 is selected by
this driver and has been verified on hardware. A Mode-3 probe returned an
incorrect identity byte (`0x28`), so the CPHA=1 path is not yet production
validated.

One additional LSM6DSOX-specific issue was found: a 14-byte burst crossing the
`OUT_TEMP_H` to `OUTX_L_G` internal output-block boundary shifted the remaining
stream by one bit. Delaying between bytes did not help. The permanent readout
therefore uses a 2-byte temperature burst followed by one coherent 12-byte
gyro+accelerometer burst. This is not sample filtering or post-processing; it
matches the sensor's output block structure and preserves BDU coherence.

The final real-hardware capture is
`../fusion/logs/steval_mki217v1_clean_60s.csv`:

- 6349 samples over 59.994462 seconds (105.810 Hz measured)
- sequence discontinuities: 0
- bit-shifted, saturated or invalid samples: 0
- maximum timestamp gap: 4742 CLINT ticks (9.484 ms)
- acceleration norm: 9.94245 +/- 0.00687 m/s^2
- gyro mean XYZ: +0.20395, -0.07578, -0.27628 deg/s
- gyro standard deviation XYZ: 0.02600, 0.02379, 0.02630 deg/s
- temperature: 25.909 +/- 0.056 degC

These measurements are for the stationary board in its test orientation. The
nonzero gyro mean is startup bias to be estimated by stationary calibration,
not angular motion.

## Build and load

From the repository root:

```sh
make FPGA_BOARD=genesys2 fpga-elf-flash-image \
  APP=steval_mki217v1_test

make FPGA_BOARD=genesys2 fpga-debug-load \
  APP=steval_mki217v1_test
```

The default run is 104 Hz for 60 seconds. Alternatives can be passed through
the application directory build:

```sh
make -C soc/software/steval_mki217v1_test \
  BUILD_DIR=../../out/software/steval_mki217v1_test \
  LSM6DSOX_ODR_HZ=52 CAPTURE_DURATION_S=60
```

Supported smoke-test ODR values are 52, 104 and 208 Hz. At 115200 baud, use
52 or 104 Hz for loss-free line-oriented logging. The firmware verifies
`WHO_AM_I=0x6c`, selects SPI mode 0, resets the device, enables
block-data-update and register auto-increment, and configures +/-2 g and
+/-250 dps. The FPGA SPI controller exposes CPOL/CPHA independently from its
single/quad data-width selection.

## UART/replay format

Each sample is timestamped from the local CLINT/CPU time domain before its SPI
burst and emitted without floating-point formatting:

```text
IMU_META,LSM6DSOX,tick_hz=500000,odr_hz=104,accel_ug_lsb=61,gyro_udps_lsb=8750,temp_lsb_c=256,temp_offset_millic=25000
IMU_RAW,LSM6DSOX,0,12345678,ax,ay,az,gx,gy,gz,temp
```

Scale factors are 61 ug/LSB, 8750 udps/LSB and 256 LSB/degC with a 25 degC
offset. `fusion/fusion_eskf.py` accepts this raw format directly, so a captured
log can be replayed with an existing GPS UART capture. Sequential GPS and IMU
captures are meaningful only for a stationary test. A moving-platform replay
requires GPS and IMU samples stamped in the same firmware/run.