AhrsController plus an M5Unified IMU_Class-compatible API. More...

#include <ahrs_imu.hpp>

Inheritance diagram for m5::imu::AhrsImu:

Classes
struct	imu_3d_t
	3-axis float vector, layout-compatible with m5::IMU_Class::imu_3d_t More...

struct	imu_data_t
	Merged accel/gyro/mag sample, layout-compatible with m5::IMU_Class::imu_data_t. More...

Public Types
enum	axis_t { axis_x_pos = 0 , axis_x_neg = 1 , axis_y_pos = 2 , axis_y_neg = 3 , axis_z_pos = 4 , axis_z_neg = 5 }
	A source axis with a sign, layout-compatible with m5::IMU_Class::axis_t. More...

Public Member Functions
bool	getAccel (float const ax, float const ay, float *const az) const
	Latest accelerometer reading (G)

bool	getGyro (float const gx, float const gy, float *const gz) const
	Latest gyroscope reading (dps)

bool	getMag (float const mx, float const my, float *const mz) const
	Latest magnetometer reading (uT)

bool	getTemp (float *const t) const
	Latest temperature reading (degC)

void	getImuData (imu_data_t *const data) const
	Copy the latest accel/gyro/mag sample into an imu_data_t.

const imu_data_t &	getImuData ()
	Latest accel/gyro/mag sample, by const reference.

void	getAhrsData (float const pitch, float const roll, float *const yaw) const
	Current fused attitude as aerospace Euler angles (degrees)

bool	getAccelData (float const ax, float const ay, float *const az) const
	Alias for getAccel()

bool	getGyroData (float const gx, float const gy, float *const gz) const
	Alias for getGyro()

bool	getGyroMag (float const mx, float const my, float *const mz) const
	Alias for getMag() (name mirrors m5::IMU_Class::getGyroMag)

bool	isEnabled () const
	Whether accelerometer and gyroscope sources are both registered.

void	setCalibration (const uint8_t accel_strength, const uint8_t gyro_strength, const uint8_t mag_strength)
	Set per-capability auto-calibration strength (0 = off, 1-255 = adjustment speed)

void	clearOffsetData ()
	Zero every capability's auto-calibration offset.

bool	setAxisOrder (const axis_t axis0, const axis_t axis1, const axis_t axis2)
	Assign which signed source axis feeds each output slot.

bool	setAxisOrderRightHanded (const axis_t axis0, const axis_t axis1)
	Assign the first two output axes; derive the third as a right-handed frame.

bool	setAxisOrderLeftHanded (const axis_t axis0, const axis_t axis1)
	Assign the first two output axes; derive the third as a left-handed frame.

Public Member Functions inherited from m5::imu::AhrsController
	AhrsController ()
	Construct with no sources and the default filter (Complementary)

	~AhrsController ()
	Destructor.

	AhrsController (const AhrsController &)=delete
	Copy construction is disabled (holds pointers to registered sources)

AhrsController &	operator= (const AhrsController &)=delete
	Copy assignment is disabled (holds pointers to registered sources)

bool	add (IMUDataSource &src)
	Register an IMU data source.

bool	writeAxisOrder (const IMUDataSource &src, const AxisOrder &order)
	Set the chip-frame-to-body-frame axis remap applied to one source's Accel/Gyro (and Temp) samples.

bool	readAxisOrder (const IMUDataSource &src, AxisOrder &out) const
	Read back the Accel/Gyro axis remap currently configured for one source.

bool	writeMagAxisOrder (const IMUDataSource &src, const AxisOrder &order)
	Set the chip-frame-to-body-frame axis remap applied to one source's Mag samples.

bool	readMagAxisOrder (const IMUDataSource &src, AxisOrder &out) const
	Read back the Mag-only axis remap currently configured for one source.

void	writeUserAxisOrder (const AxisOrder &order)
	Set a global user axis remap composed on top of every source's fixed order.

void	readUserAxisOrder (AxisOrder &out) const
	Read back the current global user axis remap.

void	writeAutoCalibration (const uint8_t accel, const uint8_t gyro, const uint8_t mag)
	Enable/disable continuous background auto-calibration per capability.

void	readAutoCalibration (uint8_t &accel, uint8_t &gyro, uint8_t &mag) const
	Read back the current auto-calibration strengths.

void	writeMagCalibrationRadius (const float radius_ut)
	Pin the field strength the magnetometer auto-calibration fits its samples to.

float	readMagCalibrationRadius () const
	Field strength the magnetometer auto-calibration is currently fitting to.

bool	calibrateGyro (const uint32_t duration_ms)
	Collect gyro samples for the given duration (real clock) and set the gyro offset to their mean.

bool	calibrateGyro (const uint32_t update_count, const float dt)
	Deterministic sibling of calibrateGyro(const uint32_t): explicit dt instead of the real clock.

bool	readCalibration (calibration_data_t &out) const
	Snapshot every capability's current auto-calibration offset.

bool	writeCalibration (const calibration_data_t &data)
	Overwrite every capability's auto-calibration offset from a snapshot.

bool	begin ()
	Prepare this controller for update()

Capability	update ()
	Drain every source and fuse newly-arrived samples, measuring dt from the real clock (m5::utility::micros())

Capability	update (const float dt)
	Drain every source and fuse newly-arrived samples using an explicit dt.

bool	sleep ()
	Put every added source into its lowest reversible power state.

bool	wakeup ()
	Bring every added source back from sleep()

bool	selectFilter (const FilterType type)
	Select and internally construct one of the built-in filters.

void	setFilter (AhrsFilterBase &filter)
	Inject an externally-owned filter.

AhrsFilterBase *	filter () const
	Currently active filter, or nullptr if none has been selected yet.

void	quaternion (float &w, float &x, float &y, float &z) const
	Current fused attitude.

void	euler (float &roll_deg, float &pitch_deg, float &yaw_deg) const
	Current fused attitude as aerospace ZYX Euler angles.

void	tareYaw ()
	Zero the publicly reported yaw at the current heading.

void	clearYawTare ()
	Remove a previously applied tareYaw() offset.

const imu_physical_data_t &	latest () const
	Most recently fused physical-unit sample.

bool	hasAccel () const
	Whether an accelerometer source has been registered (see add())

bool	hasGyro () const
	Whether a gyroscope source has been registered (see add())

bool	hasTemp () const
	Whether a temperature source has been registered (see add())

bool	hasValidMag () const
	Whether at least one valid magnetometer sample has been seen.

unsigned long	lastMicros () const
	Microsecond timestamp of the most recent self-clocked update()

Detailed Description

AhrsController plus an M5Unified IMU_Class-compatible API.

Use this in place of AhrsController when porting M5Unified M5.Imu code: it is-a AhrsController (so it plugs into presets, add(), selectFilter(), etc. unchanged) and additionally exposes getAccel/getGyro/getMag/getTemp/getImuData/getAhrsData/setCalibration. The getters read the already axis-corrected, offset-compensated latest() sample; setCalibration forwards to writeAutoCalibration(); getAhrsData() provides the attitude output for the getAhrsData() slot that M5Unified's IMU_Class declares but does not implement.

Member Enumeration Documentation

◆ axis_t

enum m5::imu::AhrsImu::axis_t

A source axis with a sign, layout-compatible with m5::IMU_Class::axis_t.

Bit 0 is the sign (1 = negated), bits 1-2 select the axis (0 = X, 1 = Y, 2 = Z).

Enumerator
axis_x_pos	+X
axis_x_neg	-X
axis_y_pos	+Y
axis_y_neg	-Y
axis_z_pos	+Z
axis_z_neg	-Z

Member Function Documentation

◆ clearOffsetData()

void m5::imu::AhrsImu::clearOffsetData ( )

inline

Zero every capability's auto-calibration offset.

Forwards to writeCalibration() with a default (all-zero) snapshot, mirroring m5::IMU_Class::clearOffsetData(). Auto-calibration strengths set via setCalibration() are left unchanged; only the accumulated offsets are cleared.

◆ getAccel()

bool m5::imu::AhrsImu::getAccel	(	float *const	ax,
		float *const	ay,
		float *const	az ) const

inline

Latest accelerometer reading (G)

Parameters

[out]	ax	Accelerometer X
[out]	ay	Accelerometer Y
[out]	az	Accelerometer Z

Returns: True if an accelerometer source is registered

◆ getAhrsData()

void m5::imu::AhrsImu::getAhrsData	(	float *const	pitch,
		float *const	roll,
		float *const	yaw ) const

inline

Current fused attitude as aerospace Euler angles (degrees)

Parameters

[out]	pitch	Pitch (Y axis)
[out]	roll	Roll (X axis)
[out]	yaw	Yaw (Z axis)

Forwards to euler(). Provides the getAhrsData() attitude output that M5Unified's IMU_Class declares but does not implement. Argument order matches M5Unified's planned signature (pitch, roll, yaw).

◆ getGyro()

bool m5::imu::AhrsImu::getGyro	(	float *const	gx,
		float *const	gy,
		float *const	gz ) const

inline

Latest gyroscope reading (dps)

Parameters

[out]	gx	Gyroscope X
[out]	gy	Gyroscope Y
[out]	gz	Gyroscope Z

Returns: True if a gyroscope source is registered

◆ getImuData() [1/2]

const imu_data_t & m5::imu::AhrsImu::getImuData ( )

inline

Latest accel/gyro/mag sample, by const reference.

Returns: Reference to an internal imu_data_t refreshed on each call

◆ getImuData() [2/2]

void m5::imu::AhrsImu::getImuData ( imu_data_t *const data ) const

inline

Copy the latest accel/gyro/mag sample into an imu_data_t.

Parameters

[out] data Destination (ignored if nullptr)

usec carries lastMicros(), i.e. the timestamp of the most recent self-clocked update(); it stays 0 when the controller is driven by update(const float dt) instead.

◆ getMag()

bool m5::imu::AhrsImu::getMag	(	float *const	mx,
		float *const	my,
		float *const	mz ) const

inline

Latest magnetometer reading (uT)

Parameters

[out]	mx	Magnetometer X
[out]	my	Magnetometer Y
[out]	mz	Magnetometer Z

Returns: True if at least one valid magnetometer sample has been seen; false on a 6-axis setup

◆ getTemp()

bool m5::imu::AhrsImu::getTemp ( float *const t ) const

inline

Latest temperature reading (degC)

Parameters

[out] t Temperature

Returns: True if a temperature source is registered

◆ isEnabled()

bool m5::imu::AhrsImu::isEnabled ( ) const

inline

Whether accelerometer and gyroscope sources are both registered.

Returns: True once begin() has an accel+gyro source, mirroring m5::IMU_Class::isEnabled()

◆ setAxisOrder()

bool m5::imu::AhrsImu::setAxisOrder	(	const axis_t	axis0,
		const axis_t	axis1,
		const axis_t	axis2 )

inline

Assign which signed source axis feeds each output slot.

Parameters

axis0	Source axis (with sign) for output X
axis1	Source axis (with sign) for output Y
axis2	Source axis (with sign) for output Z

Returns: False (and no change) if the three axes are not a permutation of X/Y/Z

Mirrors m5::IMU_Class::setAxisOrder. Converts the axis_t triplet to an AxisOrder and installs it as the global user remap via writeUserAxisOrder(), so it composes on top of every source's fixed board correction and applies to accel/gyro/mag alike.

◆ setAxisOrderLeftHanded()

bool m5::imu::AhrsImu::setAxisOrderLeftHanded	(	const axis_t	axis0,
		const axis_t	axis1 )

inline

Assign the first two output axes; derive the third as a left-handed frame.

Parameters

axis0	Source axis (with sign) for output X
axis1	Source axis (with sign) for output Y

Returns: False (and no change) if axis0 and axis1 share the same axis

Mirrors m5::IMU_Class::setAxisOrderLeftHanded (the right-handed third axis with its sign flipped).

◆ setAxisOrderRightHanded()

bool m5::imu::AhrsImu::setAxisOrderRightHanded	(	const axis_t	axis0,
		const axis_t	axis1 )

inline

Assign the first two output axes; derive the third as a right-handed frame.

Parameters

axis0	Source axis (with sign) for output X
axis1	Source axis (with sign) for output Y

Returns: False (and no change) if axis0 and axis1 share the same axis

Mirrors m5::IMU_Class::setAxisOrderRightHanded.

◆ setCalibration()

void m5::imu::AhrsImu::setCalibration	(	const uint8_t	accel_strength,
		const uint8_t	gyro_strength,
		const uint8_t	mag_strength )

inline

Set per-capability auto-calibration strength (0 = off, 1-255 = adjustment speed)

Parameters

accel_strength	Accelerometer strength
gyro_strength	Gyroscope strength
mag_strength	Magnetometer strength

Alias for writeAutoCalibration().

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ axis_t

Member Function Documentation

◆ clearOffsetData()

◆ getAccel()

◆ getAhrsData()

◆ getGyro()

◆ getImuData() [1/2]

◆ getImuData() [2/2]

◆ getMag()

◆ getTemp()

◆ isEnabled()

◆ setAxisOrder()

◆ setAxisOrderLeftHanded()

◆ setAxisOrderRightHanded()

◆ setCalibration()