gps/soc/software/steval_mki217v1_test/README.md

STEVAL-MKI217V1 INT1 data-ready test (Genesys2)

This standalone bare-metal application reads the LSM6DSOX on the STEVAL-MKI217V1 over the existing Genesys2 PMOD SPI peripheral and uses INT1 for data-ready interrupts. The LIS2MDL magnetometer on the module is not enabled; 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
INT1	JC9	active-high data-ready interrupt
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 routed through the FPGA 3FF synchronizer to PLIC device 11.

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:

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:

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:

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.