DOCS/TRACE DOMAINS/STM32WB SIX-AXIS IMU
BKPT DEBUG & VIEWALYZER RS
STM32WB six-axis IMU
Sensor samples, configuration and consumption rate reveal a stalled reader, bus errors or a reader falling behind the sensor.
Download domain JSON · GitHub source · Domain catalog
Probe sampled · Descriptor com.bkpt.imu-6dof · version 0.2.0 · domain API 1.
Purpose and prerequisites
For the STM32WB5MM-DK with ISM330DHCX and the matching FreeRTOS IMU demo. Requires the matching ELF and its imu_*/app_heartbeat mirrors; I2C3 additionally needs STM32WB55_CM4 SVD registers and the RCC guard. The debug host reads mirrors rather than taking ownership of the sensor bus. The recorder is optional for these observations and provides separate RTOS lanes when enabled.
Engineering interpretation
Separate three rates: the configured accelerometer ODR, the application consumption rate, and host polling. Faster polling cannot recover motion samples overwritten between reads. The demo switches 104/26 Hz ODR and deliberately parks its reader for five seconds during its repeating scenario, so stall/rate findings can be expected demonstration behavior. Flat axes may mean stationary motion or stale firmware values; sample_count and heartbeat distinguish those cases. A failed configuration or mirror read also increments the BSP error count. This is the only actual sensor domain in the catalog; the IMU styling example has no firmware producer or acquisition.
Acquisition and validity
The descriptor declares 13 inputs and 6 derived channels, with a requested default of 1000 Hz per input. Unsupported/unsafe rows remain unavailable. The achieved poll rate depends on the probe and selected inputs.
SVD device: STM32WB55_CM4. Target prefix: STM32WB5.
Inputs are sampled separately while firmware runs. DWARF paths require the exact Debug ELF; unresolved or null pointers produce unavailable values. A readable object is not proof that it has finished initialization. Firmware can update or reuse it between reads. Missing observations propagate to dependent fields and checks.
Cards with a capacity reference show value / capacity, not a percentage. Both readings must be available, capacity must be positive, and the value must lie between zero and capacity. Otherwise the card is unavailable. Individual fields retain their raw values in traces. Saved observations describe their acquisition time, not fresh target state.
Cards and tables
Motion
Firmware-retained sensor samples. The six axes start graphed; each can be selected independently.
| CARD OR ROW | READING AND SIGNIFICANCE | UNIT |
|---|---|---|
Acceleration X · imu.acc_x | Latest successfully consumed X acceleration from the BSP in milligravity (1000 mg = 1 g). The value is already scaled by firmware; a stationary axis can include gravity. | mg |
Acceleration Y · imu.acc_y | Latest successfully consumed Y acceleration from the BSP in milligravity (1000 mg = 1 g). The value is already scaled by firmware; a stationary axis can include gravity. | mg |
Acceleration Z · imu.acc_z | Latest successfully consumed Z acceleration from the BSP in milligravity (1000 mg = 1 g). The value is already scaled by firmware; a stationary axis can include gravity. | mg |
Angular velocity X · imu.gyro_x | Latest successfully consumed X angular velocity from the BSP in millidegrees/s (1000 mdps = 1 degree/s). The value is already scaled; stationary bias can remain. | mdps |
Angular velocity Y · imu.gyro_y | Latest successfully consumed Y angular velocity from the BSP in millidegrees/s (1000 mdps = 1 degree/s). The value is already scaled; stationary bias can remain. | mdps |
Angular velocity Z · imu.gyro_z | Latest successfully consumed Z angular velocity from the BSP in millidegrees/s (1000 mdps = 1 degree/s). The value is already scaled; stationary bias can remain. | mdps |
Stream
Host observation rate and sensor output rate differ. A lower achieved poll rate cannot reconstruct intermediate motion samples.
| CARD OR ROW | READING AND SIGNIFICANCE | UNIT |
|---|---|---|
Observed consumption rate · imu.sample_rate | Interval average of application-consumed successful sample pairs. It is not host poll rate and cannot reconstruct every intermediate axis sample. | samples/s |
Configured sensor output rate · imu.odr_hz | Nominal accelerometer output data rate mapped from CTRL1_XL; not measured sample production. Unknown codes pass through and must not be treated as valid Hz. | Hz |
Samples consumed · imu.sample_count | Successful paired accelerometer/gyroscope reads consumed by the application. Increments only after both BSP reads succeed; it is not sensor-produced sample count. No wrapping policy is declared. | Raw value / decoded state |
Application heartbeat · app.heartbeat | Application-loop progress counter used as a liveness reference. It is not CPU utilization or a scheduler switch count. | Raw value / decoded state |
Sensor configuration
Decoded configuration and raw codes. Firmware owns the I2C sensor and refreshes this mirror.
| CARD OR ROW | READING AND SIGNIFICANCE | UNIT |
|---|---|---|
Accelerometer full scale · imu.acc_fs_g | Mapped accelerometer full-scale magnitude in g: 2, 16, 4 or 8. The sensor range is plus/minus that magnitude; no gyro range is decoded. | g |
Raw configuration / CTRL1_XL firmware mirror · imu.ctrl1_xl | Firmware mirror of the accelerometer CTRL1_XL register, reread after configuration changes. A failed mirror read can leave zero; inspect the error count before treating that as power-down. | Raw value / decoded state |
Raw configuration / Output data rate code · imu.odr_code | CTRL1_XL bits 7:4, the accelerometer output-data-rate code. No gyroscope ODR register is sampled. | Raw value / decoded state |
Raw configuration / Full scale code · imu.acc_fs_code | CTRL1_XL bits 3:2, accelerometer full-scale selection code. | Raw value / decoded state |
Bus and access limits
Only guarded I2C controller state and existing firmware values are sampled. Sensor identity and FIFO status remain unsupported through the debug port.
| CARD OR ROW | READING AND SIGNIFICANCE | UNIT |
|---|---|---|
I2C peripheral enabled · imu.bus_enabled | I2C3 PE bit: OFF (0) or ON (1). ON does not prove the sensor acknowledges or returns valid measurements. Values. | Raw value / decoded state |
Bus errors · imu.bus_errs | Count of failed BSP operations, including initialization, configuration and data reads. It is broader than electrical I2C transaction failures and does not count every possible failure path. | Raw value / decoded state |
Raw register / I2C control register · imu.bus_cr1 | I2C3 control register. Clock gating must pass before reading; PE bit 0 only indicates controller enable. | Raw value / decoded state |
Unavailable through debug port / Sensor identity (not directly accessible) · imu.whoami | Unsupported: sensor identity is behind firmware-owned I2C and is not debug-addressable without a firmware mirror. | Raw value / decoded state |
Unavailable through debug port / Sensor FIFO level (not directly accessible) · imu.fifo_level | Unsupported: this descriptor has no sensor FIFO-level mirror. It does not measure FIFO occupancy. | Raw value / decoded state |
Every sampled input
All paths below come from the downloadable definition. Integer types specify width and signedness. No scaling is applied to a raw read. A field without a declared unit is a code, count, address or raw register; its engineering meaning is explained above or below.
| INPUT | SOURCE / ADDRESS PATH | TYPE | INTERPRETATION / ACCESS |
|---|---|---|---|
imu.sample_count | imu_sample_count | u32 | See its card/table above. |
imu.acc_x | imu_acc_x_mg | i32 | See its card/table above. |
imu.acc_y | imu_acc_y_mg | i32 | See its card/table above. |
imu.acc_z | imu_acc_z_mg | i32 | See its card/table above. |
imu.gyro_x | imu_gyro_x_mdps | i32 | See its card/table above. |
imu.gyro_y | imu_gyro_y_mdps | i32 | See its card/table above. |
imu.gyro_z | imu_gyro_z_mdps | i32 | See its card/table above. |
imu.ctrl1_xl | imu_ctrl1_xl | u32 | See its card/table above. |
imu.bus_errs | imu_i2c_errs | u32 | See its card/table above. |
app.heartbeat | app_heartbeat | u32 | See its card/table above. |
imu.bus_cr1 | I2C3.CR1 | u32 | See its card/table above. Guard: (RCC.APB1ENR1 & 0x00800000) = 0x00800000. I2C3 clock disabled: registers read zero, not data |
imu.whoami | sensor-internal register behind the application's I2C bus; the debug port cannot address the sensor | u32 | See its card/table above. sensor-internal register behind the application's I2C bus; the debug port cannot address the sensor |
imu.fifo_level | sensor-internal FIFO status behind the application's I2C bus; observe a firmware mirror instead | u32 | See its card/table above. sensor-internal FIFO status behind the application's I2C bus; observe a firmware mirror instead |
Derived fields and rates
| CHANNEL | CALCULATION | MEANING | UNIT |
|---|---|---|---|
imu.odr_code | (imu.ctrl1_xl >> 4) & 0xF | CTRL1_XL bits 7:4, the accelerometer output-data-rate code. No gyroscope ODR register is sampled. | Code / state |
imu.odr_hz | Map imu.odr_code | Nominal accelerometer output data rate mapped from CTRL1_XL; not measured sample production. Unknown codes pass through and must not be treated as valid Hz. Values. | Hz |
imu.acc_fs_code | (imu.ctrl1_xl >> 2) & 0x3 | CTRL1_XL bits 3:2, accelerometer full-scale selection code. | Code / state |
imu.acc_fs_g | Map imu.acc_fs_code | Mapped accelerometer full-scale magnitude in g: 2, 16, 4 or 8. The sensor range is plus/minus that magnitude; no gyro range is decoded. Values. | g |
imu.sample_rate | max(0, change in imu.sample_count / elapsed seconds) | Interval average of application-consumed successful sample pairs. It is not host poll rate and cannot reconstruct every intermediate axis sample. | samples/s |
imu.bus_enabled | (imu.bus_cr1 >> 0) & 0x1 | I2C3 PE bit: OFF (0) or ON (1). ON does not prove the sensor acknowledges or returns valid measurements. Values. | Code / state |
Rates need two valid samples at increasing timestamps and are interval averages. Gaps break the calculation. A negative raw delta is clamped to zero by the rate calculation; do not infer an instantaneous event rate from a reset. Unknown map keys pass through numerically; an unmapped code is not a validated physical measurement.
Findings
Consumer behind the sensor
warning · imu-rate-below-odr. imu.sample_rate < 0.8 × imu.odr_hz for 2000 ms of observations.
Consumption stayed below 80% of nominal accelerometer ODR for two seconds of samples. Investigate reader period/priority and bus bandwidth. This is evidence of under-consumption; the domain does not measure exactly how many sensor samples were overwritten.
Evidence: imu.sample_rate, imu.odr_hz, imu.sample_count.
IMU stream stalled
error · imu-stream-stalled. imu.sample_count does not increase over 1000 ms while app.heartbeat advances by at least 1.
Sample consumption stopped while the rest of the application kept running. Check whether the reader task is blocked, starved, or deleted, and whether the sensor still asserts data-ready.
Evidence: imu.sample_count, app.heartbeat, imu.odr_hz.
IMU bus errors
error · imu-bus-errors. imu.bus_errs increases between valid samples.
The firmware failure counter increased. Check the failed BSP operation, initialization/configuration, I2C contention and electrical conditions. The counter is not restricted to bus-transaction failures.
Evidence: imu.bus_errs, imu.sample_rate.
Value dictionaries
These are the exact value mappings in this version of the descriptor. Unlisted status codes remain numeric; they are not implicitly success. Decode a value in the context of its field and validity.
Value map 1
| RAW VALUE | DECODED LABEL / MAPPED VALUE |
|---|---|
0 | OFF |
1 | ON |
Value map 2
| RAW VALUE | DECODED LABEL / MAPPED VALUE |
|---|---|
0 | 0 |
1 | 12.5 |
2 | 26 |
3 | 52 |
4 | 104 |
5 | 208 |
6 | 416 |
7 | 833 |
8 | 1660 |
9 | 3330 |
10 | 6660 |
Value map 3
| RAW VALUE | DECODED LABEL / MAPPED VALUE |
|---|---|
0 | 2 |
1 | 16 |
2 | 4 |
3 | 8 |
Definition and contribution
Verified against the demo Core/Src/imu.c and heartbeat loop, the ISM330DHCX BSP axis conversion/configuration code, sampled-source declarations, and the shared field/map/rate and finding implementations.
View or propose changes to the canonical JSON. Contribution guide.
Download SHA-256: 16390e87207b4171a017a2dae246808e62da7e5aa98613f081187877ed6c2c9c.