Sense.I.9

uint8_t tile_sense_i_9_find(tiles_pal_t* hal, uint8_t instance)

Performs an address-level probe only (no register reads).

hal

Platform HAL handle

instance

Instance index (0 = default, see mapping table)

Returns 1 if device ACKs, 0 otherwise

void tile_sense_i_9_init(tiles_pal_t* hal, uint8_t instance, tile_t* tile, const sense_i_9_cfg_t *cfg)

Performs a soft reset, verifies WHO_AM_I, wakes the device, enables all accel + gyro axes, enables I2C bypass for direct magnetometer access, and starts the magnetometer in continuous 100 Hz mode. Pass cfg=NULL for defaults.

hal

Platform HAL handle

instance

Instance index (0 = default, see mapping table)

tile

Pointer to tile handle (populated by this function)

cfg

Optional config, or NULL for defaults

• Blocks for ~50 ms during reset. Call once at startup.

void tile_sense_i_9_sleep(tile_t* tile)

Stops all sensor sampling. Current draw drops to ~8 µA. Call tile_sense_i_9_wake() to resume.

tile

Pointer to tile handle

void tile_sense_i_9_wake(tile_t* tile)

Restores auto clock selection. Previously configured ranges and ODRs are preserved across sleep/wake cycles.

tile

Pointer to tile handle

void tile_sense_i_9_reset(tile_t* tile)

Resets all registers to defaults. Blocks for ~50 ms. You must call tile_sense_i_9_init() again after reset.

tile

Pointer to tile handle

uint8_t tile_sense_i_9_data_ready(tile_t* tile)

Reads the ICM-20948 interrupt status register.

tile

Pointer to tile handle

Returns 1 if new data is available, 0 otherwise

void tile_sense_i_9_set_accel_range(tile_t* tile, sense_i_9_accel_range_t range)

Set the accelerometer full-scale range.

tile

Pointer to tile handle

range

One of the sense_i_9_accel_range_t values

void tile_sense_i_9_set_gyro_range(tile_t* tile, sense_i_9_gyro_range_t range)

Set the gyroscope full-scale range.

tile

Pointer to tile handle

range

One of the sense_i_9_gyro_range_t values

void tile_sense_i_9_set_mag_mode(tile_t* tile, sense_i_9_mag_mode_t mode)

Set the magnetometer operating mode.

tile

Pointer to tile handle

mode

One of the sense_i_9_mag_mode_t values

• Switching modes resets the AK09916 measurement cycle.

void tile_sense_i_9_set_accel_odr(tile_t* tile, uint16_t divider)

ODR = 1125 / (1 + divider) Hz. Examples: divider = 0 → 1125 Hz divider = 4 → 225 Hz divider = 10 → ~102 Hz divider = 44 → 25 Hz

tile

Pointer to tile handle

divider

11-bit sample rate divider (0–4095)

void tile_sense_i_9_set_gyro_odr(tile_t* tile, uint8_t divider)

ODR = 1100 / (1 + divider) Hz.

tile

Pointer to tile handle

divider

8-bit sample rate divider (0–255)

void tile_sense_i_9_get_raw_accels(tile_t* tile, int16_t* buffer)

Returns signed 16-bit ADC counts. Convert to milli-g using the sensitivity for the configured range (e.g. ±2 G → 1 LSB ≈ 0.061 mg).

tile

Pointer to tile handle

buffer

Output array, minimum 3 × int16_t [X, Y, Z]

void tile_sense_i_9_get_raw_gyros(tile_t* tile, int16_t* buffer)

Returns signed 16-bit ADC counts. Convert to °/s using the sensitivity for the configured range (e.g. ±250 DPS → 131 LSB/°/s).

tile

Pointer to tile handle

buffer

Output array, minimum 3 × int16_t [X, Y, Z]

void tile_sense_i_9_get_raw_6dof(tile_t* tile, int16_t* buffer)

More efficient than calling get_raw_accels + get_raw_gyros separately (one I2C transaction instead of two). Data is time-coherent.

tile

Pointer to tile handle

buffer

Output array, minimum 6 × int16_t [AX, AY, AZ, GX, GY, GZ]

void tile_sense_i_9_get_raw_mags(tile_t* tile, int16_t* buffer)

Returns signed 16-bit ADC counts from the AK09916. Sensitivity: 0.15 µT/LSB on all axes (factory-trimmed; the AK09916 has no per-axis ASA / FUSE ROM correction — see datasheet §11).

tile

Pointer to tile handle

buffer

Output array, minimum 3 × int16_t [X, Y, Z]

• Automatically reads the ST2 register to release the magnetometer data lock, enabling the next measurement.

uint8_t tile_sense_i_9_mag_overflowed(tile_t* tile)

The AK09916 raises HOFL in ST2 when the sum |HX|+|HY|+|HZ| exceeds 4912 µT (the chip's measurement range). Readings during overflow appear valid in the data registers but are not — for compass-grade work, discard samples where this returns 1. Reading this releases the AK09916 data-lock the same way tile_sense_i_9_get_raw_mags() does, so it can be used standalone after a non-locking peek.

tile

Pointer to tile handle

Returns 1 if HOFL was set after the most recent measurement, 0 otherwise

int16_t tile_sense_i_9_get_temperature(tile_t* tile)

Convert raw value to °C: temp_degC = (raw / 333.87) + 21.0

tile

Pointer to tile handle

Returns Raw signed 16-bit temperature value

uint8_t tile_sense_i_9_is_face_up(tile_t* tile)

Reads the accelerometer and returns 1 when the Z-axis is close to +1 g (i.e. gravity is pulling down through the back of the tile). The acceptance band is roughly ±30° of true face-up; the X/Y axes must each read below ~0.5 g for the test to pass, so tilted-but-mostly-up orientations also count as face-up. thresholds remain proportional (band is in fractions of full-scale) so behaviour is unaffected.

tile

Initialized tile handle

Returns 1 if face-up, 0 otherwise

• Assumes the accel range is the default ±2 g configured by

uint8_t tile_sense_i_9_is_face_down(tile_t* tile)

Mirror of @ref tile_sense_i_9_is_face_up — Z-axis close to −1 g.

tile

Initialized tile handle

Returns 1 if face-down, 0 otherwise

uint8_t tile_sense_i_9_is_moving(tile_t* tile, uint16_t threshold_mg)

Reads the accelerometer and reports whether |‖a‖ − 1 g| exceeds `threshold_mg`. At rest in any orientation the magnitude is ≈ 1 g, so this captures linear acceleration regardless of which face is up. Use ~50–100 mg for "is being handled" and ~300–500 mg for "is being shaken". Implementation uses an integer approximation of the magnitude comparison: it checks the squared deviation against the squared threshold to avoid a square root.

tile

Initialized tile handle

threshold_mg

Deviation from 1 g, in milli-g

Returns 1 if moving, 0 if at rest

• Assumes ±2 g range (init default). Other ranges still work but the noise floor scales with full-scale.

void tile_sense_i_9_read_tilt_centi_degrees(tile_t* tile, uint8_t axis, int16_t* out_centi_deg)

Returns the angle (in 0.01° units) between the requested axis and the gravity vector. Range is −18000..+18000 centi-degrees (−180.00°..+180.00°). Computed from `atan2(other_components, axis)` using an integer approximation; absolute accuracy is roughly ±1° in the noise-free case. Axis selector: 0 = X axis (pitch around Y, with the chip lying on its back) 1 = Y axis (roll around X) 2 = Z axis (deviation from horizontal — 0 = face-up, 180 = face-down)

tile

Initialized tile handle

axis

0/1/2 selecting X, Y, or Z

out_centi_deg

Output tilt in 0.01° units (signed)

void tile_sense_i_9_read_heading_centi_degrees(tile_t* tile, uint16_t* out_centi_deg)

Returns the bearing of the +X axis relative to magnetic north in 0.01° units, range 0..35999 (0.00°..359.99°). 0° means +X is pointing along magnetic north; angle increases clockwise viewed from above. Computed as `atan2(−mag_y, mag_x)` from the AK09916 raw counts (no per-axis trim is needed — the AK09916 has no FUSE ROM and is factory-trimmed at 0.15 µT/LSB). accurate when the tile is held roughly level (within a few degrees of horizontal). When tilted, the heading drifts because the horizontal projection of the magnetic field changes with orientation. A tilt-compensated heading needs both accel data (to recover the gravity-aligned frame) and a 3D rotation — that is left to a later tier-3 helper or the Studio DSL. skew the result. For best accuracy, calibrate the sensor in its final enclosure before relying on the heading.

tile

Initialized tile handle

out_centi_deg

Output heading in 0.01° units (0..35999)

uint8_t tile_sense_i_9_wait_for_motion(tile_t* tile, uint32_t timeout_ms)

Polls @ref tile_sense_i_9_get_int_status every ~5 ms and returns 1 as soon as the WoM bit is observed. Returns 0 if `timeout_ms` elapses without an event. The poll cadence is chosen as a compromise: low enough to keep wake latency under ~5 ms but slow enough that the I2C bus isn't saturated by status reads.

tile

Initialized tile handle

timeout_ms

Maximum time to wait, in milliseconds

Returns 1 if motion was detected, 0 on timeout

• Wake-on-Motion must be configured (@ref tile_sense_i_9_wom_config) and enabled (@ref tile_sense_i_9_wom_enable) before this call. INT-pin routing (@ref tile_sense_i_9_int_wom) is optional — this function reads the status register directly.
• This call blocks. For non-blocking use, drive @ref tile_sense_i_9_get_int_status from your own loop.

void tile_sense_i_9_fifo_config(tile_t* tile, sense_i_9_fifo_mode_t mode, uint8_t accel, uint8_t gyro, uint8_t temp)

Enables FIFO operation in USER_CTRL and selects the data sources. Always sets FIFO_MODE = stream when enabling. Disables FIFO entirely if accel, gyro and temp are all 0.

tile

Initialized tile handle

mode

FIFO operating mode (stream or snapshot)

accel

1 to write all 3 accel axes

gyro

1 to write all 3 gyro axes

temp

1 to write the temperature sample

void tile_sense_i_9_fifo_flush(tile_t* tile)

Reset the FIFO contents (clears all queued samples).

tile

Initialized tile handle

uint16_t tile_sense_i_9_fifo_count(tile_t* tile)

Note this is bytes, not packets. A standard accel+gyro packet is 12 bytes. Read FIFO_COUNTL first to latch both bytes (handled internally).

tile

Initialized tile handle

Returns Bytes available in the FIFO (0–512)

void tile_sense_i_9_fifo_read_packet_flat(tile_t* tile, int32_t* out)

Drops the struct in favor of a positional int[6] array — the DSL doesn't have a struct ABI yet, so the per-field outputs come back indexed. Layout: out[0..2] = accel x,y,z (raw int16 widened to int32) out[3..5] = gyro x,y,z (raw int16 widened to int32) Drops the success bool — call fifo_count() first to know whether there's data. On an empty FIFO, the slots are left untouched.

tile

Initialized tile handle.

out

Output buffer (6 int32_t slots).

void tile_sense_i_9_int_config(tile_t* tile, uint8_t flags)

Sets polarity (active low/high), drive (push-pull/open-drain), mode (pulsed/latched), and the auto-clear-on-any-read bit. OR together flags from sense_i_9_int_flags_t.

tile

Initialized tile handle

flags

OR of SENSE_I_9_INT_* flags

• INT_PIN_CFG bit 1 (BYPASS_EN) is preserved by this call — the driver needs bypass mode to talk to the AK09916.

void tile_sense_i_9_int_data_ready(tile_t* tile, uint8_t enabled)

Route the data-ready interrupt to the INT pin.

tile

Initialized tile handle

enabled

1 to enable, 0 to disable

void tile_sense_i_9_int_wom(tile_t* tile, uint8_t enabled)

Route the wake-on-motion interrupt to the INT pin.

tile

Initialized tile handle

enabled

1 to enable, 0 to disable

void tile_sense_i_9_int_fifo_overflow(tile_t* tile, uint8_t enabled)

Route the FIFO overflow interrupt to the INT pin.

tile

Initialized tile handle

enabled

1 to enable for any sensor, 0 to disable all

void tile_sense_i_9_int_fifo_watermark(tile_t* tile, uint8_t enabled)

Route the FIFO watermark interrupt to the INT pin.

tile

Initialized tile handle

enabled

1 to enable for any sensor, 0 to disable all

uint8_t tile_sense_i_9_get_int_status(tile_t* tile)

Read INT_STATUS (WoM / DMP / I2C-master / PLL-ready) and clear it.

Returns 8-bit raw register value (use ICM20948_INT_WOM etc. masks)

uint8_t tile_sense_i_9_get_int_status_fifo_overflow(tile_t* tile)

Read INT_STATUS_2 (FIFO overflow per sensor) and clear it.

Returns 5-bit FIFO_OVERFLOW_INT[4:0]; non-zero means overflow occurred

uint8_t tile_sense_i_9_get_int_status_fifo_watermark(tile_t* tile)

Read INT_STATUS_3 (FIFO watermark per sensor) and clear it.

Returns 5-bit FIFO_WM_INT[4:0]; non-zero means watermark crossed

void tile_sense_i_9_wom_config(tile_t* tile, uint16_t thr_mg, sense_i_9_wom_mode_t mode)

The chip-wide threshold is one 8-bit value at 4 mg/LSB (range 0–1020 mg). Compared independently against |X|, |Y|, |Z|; any axis crossing the threshold raises WOM_INT.

tile

Initialized tile handle

thr_mg

Threshold in mg (clamped to 1020 mg / 0xFF LSB)

mode

Compare against initial sample or previous sample

• Requires accel running. Mag and gyro can be off.

void tile_sense_i_9_wom_enable(tile_t* tile)

Call after wom_config(). Routes to the INT pin only if int_wom() was also enabled.

tile

Initialized tile handle

void tile_sense_i_9_wom_disable(tile_t* tile)

Disable Wake-on-Motion logic.

tile

Initialized tile handle

uint8_t tile_sense_i_9_self_test(tile_t* tile, uint8_t* accel_pass, uint8_t* gyro_pass)

Drives the accel and gyro through their factory-stored self-excitation routine and compares the response to the stored reference values in SELF_TEST_*_GYRO/ACCEL (Bank 1). Per TDK app-note AN-000150 the pass criterion is that each axis's self-test response is within 50%–150% of the factory reference. Blocks for ~250 ms. The chip is left in a fresh-init state on exit; ranges/ODRs you set before this call may need to be reapplied.

tile

Initialized tile handle

accel_pass

Output: bit 0/1/2 = X/Y/Z accel pass (1 = pass)

gyro_pass

Output: bit 0/1/2 = X/Y/Z gyro pass (1 = pass)

Returns 1 if every accel axis and every gyro axis passed, 0 otherwise

uint8_t tile_sense_i_9_mag_self_test(tile_t* tile)

Triggers the AK09916's internal magnetic-source self-excitation. The pass criterion is the per-axis range table from the AK09916 datasheet rev 015007392-E-02 §9.4.4.2: −200 ≤ HX ≤ 200, −200 ≤ HY ≤ 200, −1000 ≤ HZ ≤ −200 Blocks for ~10 ms. Leaves the AK09916 in power-down — call tile_sense_i_9_set_mag_mode() afterwards to resume measurements.

tile

Initialized tile handle

Returns 1 if all three axes were within spec, 0 otherwise

uint8_t tile_sense_i_9_dmp_start_quat9(tile_t* tile, uint16_t output_period_ms)

Wires the chip up to compute a fused (accel+gyro+mag) orientation quaternion at the requested period and stream it to the FIFO. Equivalent to InvenSense's "ROTATION_VECTOR" Android sensor. Requires dmp_load() to have succeeded since the last reset. Side effects: - Switches AK09916 access from bypass to I2C-master mode (see the mag-access-mode rule comment block above this function). - Reconfigures accel + gyro to 56.25 Hz ODR (DMP-recommended) and ±4 g / ±2000 dps full-scale (also DMP-recommended). - Resets and enables the FIFO; old packets are discarded. Internally maps to a divider against the DMP's ~225 Hz base ODR.

tile

Initialized tile handle (DMP firmware loaded).

output_period_ms

DMP output period, in ms (clamped to 10–1000 ms).

Returns 1 on success, 0 if firmware isn't loaded or a bus error occurred.

void tile_sense_i_9_dmp_stop(tile_t* tile)

Clears DMP_EN, disables the I2C master, drops the data-output feature masks, and re-enables BYPASS_EN. After this call the four mag helpers (get_raw_mags / set_mag_mode / mag_overflowed / mag_self_test) work again — but you'll need to re-issue set_mag_mode() to put the AK09916 back into a continuous mode (DMP leaves it in single-measurement). Idempotent — safe to call when the DMP is already stopped.

tile

Initialized tile handle.

uint8_t tile_sense_i_9_dmp_data_ready(tile_t* tile)

Reads the FIFO byte-count register and returns 1 when at least one full Quat9 packet (header + payload + accuracy = 16 bytes) is available. Cheap (a single 2-byte register read).

tile

Initialized tile handle.

Returns 1 if a packet can be read, 0 otherwise.

uint8_t tile_sense_i_9_dmp_read_quat9(tile_t* tile, int32_t out_q[4], uint16_t* out_accuracy)

Pulls a header + 14-byte Quat9 payload from the FIFO and decodes: out_q[0] = q0 (scalar / w) — recovered as sqrt(1 − q1² − q2² − q3²) out_q[1] = q1 (vector / x) out_q[2] = q2 (vector / y) out_q[3] = q3 (vector / z) Components are Q30 fixed-point — divide by 2^30 (1073741824) to get a unit-quaternion float. The accuracy field is the DMP's heading accuracy estimate (chip-internal scale; treat smaller = better). On a header mismatch (FIFO content isn't a Quat9 packet) the FIFO is reset and the function returns 0 — this can happen briefly after dmp_start_quat9() while the pipeline drains its first sample.

tile

Initialized tile handle.

out_q

Output array, 4 × int32_t [q0, q1, q2, q3] in Q30.

out_accuracy

Output: DMP heading-accuracy estimate.

Returns 1 if a packet was decoded, 0 if FIFO didn't have one ready.

uint8_t tile_sense_i_9_dmp_load(tile_t* tile)

Performs the full eMD load sequence: chunked write of the 14301-byte blob to DMP RAM (handling the 0x100-byte bank-page crossings), then a chunked read-back compare. Idempotent — repeated calls re-verify but don't reload. Blocks for ~250 ms on a 400 kHz I²C bus (chunk size = 16 bytes, one bank-select write per crossing). The DMP is left in the loaded-but-disabled state. Enabling output (DMP_EN in USER_CTRL + feature configuration) is a separate step, shipped in a follow-up phase.

tile

Initialized tile handle.

Returns 1 on successful load + verify, 0 on bus error or verify mismatch.

uint8_t tile_sense_i_9_dmp_is_loaded(tile_t* tile)

Tracks driver-side state set by dmp_load(). A chip reset clears the DMP RAM but doesn't auto-clear this flag — call after reset() to know whether you need to reload.

tile

Initialized tile handle.

Returns 1 if dmp_load() has succeeded since the driver last cleared its state.