CTL_STATUS_t ctl_magnetometer_measure(CTL_MAGNETOMETER_t *self,
                                      float *sample);

ctl_magnetometer_measure samples the magnetometer self and reports the measured field strength in microtesla along about the x, y, and z axes in sample[0], sample[1] and sample[2] respectively.

The underlying magnetometer may be able to determine that the measurement along an axis has saturated. If the magnetometer can do this, the sample for all axes are set to NaN so that client code can reject temporary magnetic interference.

Note that the measurements returned are direct from the sensor. You will need to provide your own hard and soft iron effect calibration and compensation code.

Return Value

ctl_magnetometer_measure returns a standard status code. If the status indicates an error, the returned sample data is undefined.

Thread Safety

ctl_magnetometer_measure is thread-safe if the method measure is thread-safe. Typically, for SPI and I2C transports, you ensure thread safety by associating a mutex with the bus used by the transport.