DroneOdometryModel3D Class Reference

IOdometryModel3D implementation for quadcopters/drones using motor percentages. More...

#include <DroneOdometryModel3D.h>

Inheritance diagram for DroneOdometryModel3D:

Collaboration diagram for DroneOdometryModel3D:

Public Member Functions
void	registerCallback (void(*callback)(void *), void *userData) override
	Register a callback to be invoked on relevant events (e.g., input change).
	DroneOdometryModel3D (float maxVz=5.0f, float maxRollRate=200.0f, float maxPitchRate=200.0f, float maxYawRate=100.0f)
	Construct a DroneOdometryModel3D with configurable max rates.
void	setMotorPercent (int motor, float percent)
	Set the percentage (0..100) for a given motor (0..3).
virtual void	registerCallback (void(*callback)(void *), void *userData)
	Register a callback to be invoked on relevant events (e.g., input change, update).
virtual void	getLinearVelocity (float &vx, float &vy, float &vz) const =0
	Get the current linear velocity (vx, vy, vz) in m/s (robot frame).
virtual void	getAngularVelocity (float &wx, float &wy, float &wz) const =0
	Get the current angular velocity (wx, wy, wz) in rad/s (robot frame).
Public Member Functions inherited from MessageHandler
virtual bool	onMessage (const Message< float > &msg)=0
	Handle an incoming message (pure virtual).
virtual bool	onMessage (const Message< Coordinate< float > > &msg)
virtual bool	onMessage (const Message< GPSCoordinate > &msg)
virtual bool	onMessage (const Message< MotionState3D > &msg)

Static Public Attributes
static constexpr int	NUM_MOTORS = 4

Protected Member Functions
bool	onMessage (const Message< float > &msg)
	Handle incoming motor speed messages (MessageContent::MotorSpeed, origin_id = motor index).
void	getLinearVelocity (float &vx, float &vy, float &vz) const override
	Compute linear velocity (vx, vy, vz) in m/s (body frame). Only vz is modeled (vertical climb/descent), vx and vy are zero.
void	getAngularVelocity (float &wx, float &wy, float &wz) const override
	Compute angular velocity (wx, wy, wz) in rad/s (body frame). Roll and pitch rates are proportional to left/right and front/back motor differences. Yaw rate is proportional to diagonal differences (simplified torque model).

Static Protected Member Functions
static float	clamp (float v, float min, float max)

Protected Attributes
void(*	callback )(void *) = nullptr
void *	userData = nullptr
std::array< float, NUM_MOTORS >	motorPercent
float	maxVz
float	maxRollRate
float	maxPitchRate
float	maxYawRate

Detailed Description

IOdometryModel3D implementation for quadcopters/drones using motor percentages.

This model computes linear and angular velocities for a quadcopter based on the percentage output (0-100%) of each motor. It assumes a standard X-configuration quadcopter with four motors:

• Motor 0: Front Left
• Motor 1: Front Right
• Motor 2: Rear Right
• Motor 3: Rear Left

Features

• Maps motor percentages to body-frame velocities for odometry integration.
• Supports message-driven control via onMessage() (handles MessageContent::MotorSpeed with origin_id 0..3).
• All input values are clamped to 0..100%.
• Suitable for simulation, estimation, or as a reference model for real-time control.

Notes

• This model is designed for extensibility and realism, supporting multi-motor drones and robust unit-safe arithmetic.
• The mapping logic is as follows:
  • Vertical velocity (vz) is proportional to the average of all motor percentages and scaled by maxVz.
  • Roll and pitch rates are proportional to left/right and front/back motor differences, scaled by maxRollRate and maxPitchRate.
  • Yaw rate is proportional to diagonal (CW vs CCW) motor differences, scaled by maxYawRate.
• All control input values are clamped to the range 0..100% for safety and realism.
• The model is message-driven: it integrates with the communication framework and updates motor percentages via MessageContent::MotorSpeed messages (origin_id 0..3).
• Default parameters (maxVz, maxRollRate, maxPitchRate, maxYawRate) are chosen to be realistic for typical quadcopters, but can be configured for other drone types.
• See the README and documentation for integration and usage examples.

Usage Example

DroneOdometryModel3D model;
model.setMotorPercent(0, 60); // Front Left
model.setMotorPercent(1, 60); // Front Right
model.setMotorPercent(2, 60); // Rear Right
model.setMotorPercent(3, 60); // Rear Left
float vx, vy, vz, wx, wy, wz;
model.getLinearVelocity(vx, vy, vz);
model.getAngularVelocity(wx, wy, wz);

Constructor & Destructor Documentation

DroneOdometryModel3D()

DroneOdometryModel3D ( float  maxVz = 5.0f, float  maxRollRate = 200.0f, float  maxPitchRate = 200.0f, float  maxYawRate = 100.0f  )

inline

Construct a DroneOdometryModel3D with configurable max rates.

Parameters

maxVz	Maximum vertical speed (m/s) at 100% throttle. Typical: 5 m/s.
maxRollRate	Maximum roll rate (deg/s, converted to rad/s). Typical: 200 deg/s.
maxPitchRate	Maximum pitch rate (deg/s, converted to rad/s). Typical: 200 deg/s.
maxYawRate	Maximum yaw rate (deg/s, converted to rad/s). Typical: 100 deg/s.

Member Function Documentation

getAngularVelocity()

void getAngularVelocity ( float &  wx, float &  wy, float &  wz  ) const

inlineoverrideprotectedvirtual

Compute angular velocity (wx, wy, wz) in rad/s (body frame). Roll and pitch rates are proportional to left/right and front/back motor differences. Yaw rate is proportional to diagonal differences (simplified torque model).

Implements IOdometryModel3D.

getLinearVelocity()

void getLinearVelocity ( float &  vx, float &  vy, float &  vz  ) const

inlineoverrideprotectedvirtual

Compute linear velocity (vx, vy, vz) in m/s (body frame). Only vz is modeled (vertical climb/descent), vx and vy are zero.

Implements IOdometryModel3D.

onMessage()

bool onMessage ( const Message< float > &  msg )

inlineprotectedvirtual

Handle incoming motor speed messages (MessageContent::MotorSpeed, origin_id = motor index).

Implements MessageHandler.

registerCallback()

void registerCallback ( void(*)(void *)  callback, void *  userData  )

inlineoverridevirtual

Register a callback to be invoked on relevant events (e.g., input change).

Reimplemented from IOdometryModel3D.

---

The documentation for this class was generated from the following file:

• src/TinyRobotics/odometry/DroneOdometryModel3D.h