Measures wheel rotation and computes per-wheel distance and speed using encoder ticks for mobile robots. More...

#include <WheelEncoder.h>

Inheritance diagram for WheelEncoder:

Collaboration diagram for WheelEncoder:

[legend]

Public Member Functions
	WheelEncoder (size_t numWheels=1)
	Default constructor. Wheel diameter and ticks per revolution must be set before use.

	WheelEncoder (Distance wheelDiameterM, int ticksPerRevolution=1, size_t numWheels=1)
	Constructor with wheel diameter and ticks per revolution.

void	setWheelDiameter (Distance wheelDiameter)
	Set the wheel diameter using a Distance object.

void	setWheelDiameter (float diameter, DistanceUnit unit=DistanceUnit::M)
	Set the wheel diameter using a float value and unit.

void	setTicksPerRevolution (int ticks)
	Set the number of encoder ticks per wheel revolution.

void	setReportingFrequencyMs (uint16_t ms)
	Defines the reporint frequency for distance and speed messages.

float	getDistanceM (size_t motor=0) const
	Get the total distance traveled since last reset.

float	getDistance (DistanceUnit unit, size_t motor=0) const
	Get the total distance traveled in the specified unit.

float	getDistanceForTicksM (size_t ticks) const
	Get the distance corresponding to a given number of ticks (in meters).

float	getDistanceForTicks (size_t ticks, DistanceUnit unit) const
	Get the distance for a given number of ticks in the specified unit.

bool	begin ()
	Resets the encoder counts and distance.

void	setTick (size_t motor=0)
	To be called by the pin interrupt handler when a tick is detected.

Speed	getSpeed (uint8_t motor=0) const override
	Get the current speed.

Speed	updateSpeed (uint32_t deltaTimeMs, uint8_t motor=0) override
	Just provide the last reported speed without inertia modeling.

void	sendMessage ()
	Trigger sending messages for distance and speed.

void	setSlipFactor (float slipFactor)
	Set the slip correction factor.

void	calibrateSlip (float actualDistanceM)
	Calibrate slip by providing a known actual distance.

float	getSlipFactor () const
	Get the slip correction factor.

float	getRawDistanceM (size_t motor=0) const
	Get the raw (uncorrected) distance in meters from the encoder.

void	setThrottlePercent (float value, uint8_t motor=0) override
	Not used.

size_t	getMotorCount () const override

Public Member Functions inherited from MessageSource
void	subscribe (MessageHandler &handler, MessageOrigin origin=MessageOrigin::Undefined, MessageContent content=MessageContent::Undefined)
	Subscribe a message handler to this source, with optional filtering.

void	unsubscribeAll ()
	Remove all registered message handlers.

void	sendMessage (Message< float > &msg)
	Publish a message to all registered handlers.

void	sendMessage (const Message< Coordinate< float > > &msg)
	Publish a message to all registered handlers.

void	sendMessage (const Message< GPSCoordinate > &msg)
	Publish a message to all registered handlers.

void	sendMessage (const Message< MotionState3D > &msg)
	Overload for MotionState3D messages.

virtual Speed	getSpeed (uint8_t motor=0) const =0
	Get the current speed.

virtual void	setThrottlePercent (float value, uint8_t motor=0)=0
	Publish actual speed for a specific motor.

virtual Speed	updateSpeed (uint32_t deltaTimeMs, uint8_t motor=0)=0
	For sources with inertia, call this in your main loop with the elapsed time (in milliseconds) to update the speed estimate for a specific motor.

virtual size_t	getMotorCount () const =0

Protected Member Functions
Distance	getDistance (size_t motor=0) const

float	getSpeedMPS (size_t motor=0)
	Calculate speed in meters per second based on distance traveled since last calculation and elapsed time.

Static Protected Member Functions
static void	sendMessageCB (void *ref)
	Static callback for the reporting scheduler to send messages.

Protected Attributes
std::vector< float >	speedMPS

std::vector< float >	distanceM

float	wheelDiameterM = 0.0f

float	distancePerTickM = 0.0f

std::vector< float >	lastDistanceM

float	slipFactor = 1.0f

uint32_t	ticksPerRevolution = 0

std::vector< uint32_t >	lastSpeedCalcTimeMs

Scheduler	reportingScheduler

size_t	numWheels = 1

Protected Attributes inherited from MessageSource
std::vector< MessageHandlerEntry >	messageHandlers_

Detailed Description

Measures wheel rotation and computes per-wheel distance and speed using encoder ticks for mobile robots.

The WheelEncoder class provides a multi-wheel, vectorized interface for tracking the movement of a robot's wheels using incremental encoders. It accumulates encoder ticks for each wheel to estimate the distance traveled and calculates speed based on tick timing, supporting robust odometry for differential, skid-steer, and multi-motor vehicles.

Key features:

Supports any number of wheels (configurable at construction).
Vectorized state for distance, speed, and tick timing per wheel.
Interface-compliant with ISpeedSource for modular odometry integration.
Configurable wheel diameter and ticks per revolution for accurate distance estimation.
Periodic reporting of distance and speed via the MessageSource interface.
Slip calibration support to compensate for wheel slip or surface effects.
Designed for use with interrupt-driven tick updates (call setTick() in your ISR, specifying the wheel index).

Usage:

Create a WheelEncoder instance, specifying the number of wheels if needed, and configure the wheel diameter and ticks per revolution.
Call begin() to reset and start periodic reporting.
In your encoder interrupt handler, call setTick(motor) to update the encoder state for the correct wheel.
Use getDistanceM(motor), getSpeedMPS(motor), or getDistance(unit, motor) to retrieve odometry data for each wheel.
Optionally, calibrate slip using calibrateSlip() if you observe systematic odometry errors.

Example:

WheelEncoder encoder(2); // Two wheels (differential drive)
encoder.setWheelDiameter(0.065); // 65mm wheel
encoder.setTicksPerRevolution(20);
encoder.begin();
// In your interrupt:
encoder.setTick(0); // Left wheel
encoder.setTick(1); // Right wheel
// In your main loop:
float leftDistance = encoder.getDistanceM(0);
float rightDistance = encoder.getDistanceM(1);
float leftSpeed = encoder.getSpeedMPS(0);
float rightSpeed = encoder.getSpeedMPS(1);

This class is intended for embedded robotics applications (Arduino, ESP32, etc.) and integrates with the TinyRobotics messaging framework. It is suitable for use as a modular speed/distance source in extensible odometry pipelines.

Constructor & Destructor Documentation

◆ WheelEncoder()

WheelEncoder	(	Distance	wheelDiameterM,
		int	ticksPerRevolution = `1`,
		size_t	numWheels = `1`
	)

inline

Constructor with wheel diameter and ticks per revolution.

Parameters

wheelDiameterM	The diameter of the wheel (Distance object).
ticksPerRevolution	Number of encoder ticks per full wheel revolution.

Member Function Documentation

◆ begin()

bool begin ( )

inline

Resets the encoder counts and distance.

Also starts periodic reporting if not already active.

Returns: true if the encoder is properly configured (wheel diameter and ticks per revolution are set).

◆ calibrateSlip()

void calibrateSlip ( float actualDistanceM )

inline

Calibrate slip by providing a known actual distance.

Call this after moving the robot a known distance and accumulating encoder ticks. The slip factor will be set to (actual_distance / encoder_distance).

Parameters

actualDistanceM The actual distance traveled in meters.

◆ getDistance()

float getDistance	(	DistanceUnit	unit,
		size_t	motor = `0`
	)		const

inline

Get the total distance traveled in the specified unit.

Parameters

unit	The distance unit.

Returns: Distance in the specified unit.

◆ getDistanceForTicks()

float getDistanceForTicks	(	size_t	ticks,
		DistanceUnit	unit
	)		const

inline

Get the distance for a given number of ticks in the specified unit.

Parameters

ticks	Number of encoder ticks.
unit	The distance unit.

Returns: Distance in the specified unit.

◆ getDistanceForTicksM()

float getDistanceForTicksM ( size_t ticks ) const

inline

Get the distance corresponding to a given number of ticks (in meters).

Parameters

ticks Number of encoder ticks.

Returns: Distance in meters.

◆ getDistanceM()

float getDistanceM ( size_t motor = 0 ) const

inline

Get the total distance traveled since last reset.

Returns: Distance object representing the traveled distance in meters.

Get the total distance traveled in meters.

Returns: Distance in meters.

◆ getMotorCount()

size_t getMotorCount ( ) const

inlineoverridevirtual

Implements ISpeedSource.

◆ getRawDistanceM()

float getRawDistanceM ( size_t motor = 0 ) const

inline

Get the raw (uncorrected) distance in meters from the encoder.

Returns: Raw encoder distance in meters.

◆ getSlipFactor()

float getSlipFactor ( ) const

inline

Get the slip correction factor.

Returns: The slip factor (1.0 = no slip, <1.0 = slip present).

◆ getSpeed()

Speed getSpeed ( uint8_t motor = 0 ) const

inlineoverridevirtual

Get the current speed.

Returns: Speed value (with units)

Implements ISpeedSource.

◆ getSpeedMPS()

float getSpeedMPS ( size_t motor = 0 )

inlineprotected

Calculate speed in meters per second based on distance traveled since last calculation and elapsed time.

Returns: Speed in meters per second.

◆ sendMessage()

void sendMessage ( )

inline

Trigger sending messages for distance and speed.

Sends the current distance and speed as messages.

◆ sendMessageCB()

static void sendMessageCB ( void * ref )

inlinestaticprotected

Static callback for the reporting scheduler to send messages.

Parameters

ref	Pointer to the WheelEncoder instance.

◆ setReportingFrequencyMs()

void setReportingFrequencyMs ( uint16_t ms )

inline

Defines the reporint frequency for distance and speed messages.

Parameters

ms	Reporting interval in milliseconds.

◆ setSlipFactor()

void setSlipFactor ( float slipFactor )

inline

Set the slip correction factor.

The slip factor is used to correct encoder-based distance and speed estimates. It should be set to (actual_distance / encoder_distance) after calibration. Default is 1.0 (no slip).

Parameters

slipFactor The slip correction factor (typically <= 1.0).

◆ setThrottlePercent()

void setThrottlePercent	(	float	value,
		uint8_t	motor = `0`
	)

inlineoverridevirtual

Not used.

Implements ISpeedSource.

◆ setTick()

void setTick ( size_t motor = 0 )

inline

To be called by the pin interrupt handler when a tick is detected.

Updates the distance and triggers reporting if needed.

◆ setTicksPerRevolution()

void setTicksPerRevolution ( int ticks )

inline

Set the number of encoder ticks per wheel revolution.

Parameters

ticks Number of ticks per revolution.

◆ setWheelDiameter() [1/2]

void setWheelDiameter ( Distance wheelDiameter )

inline

Set the wheel diameter using a Distance object.

Parameters

wheelDiameter The wheel diameter.

◆ setWheelDiameter() [2/2]

void setWheelDiameter	(	float	diameter,
		DistanceUnit	unit = `DistanceUnit::M`
	)

inline

Set the wheel diameter using a float value and unit.

Parameters

diameter	The wheel diameter value.
unit	The unit of the diameter (default: meters).

◆ updateSpeed()

Speed updateSpeed	(	uint32_t	deltaTimeMs,
		uint8_t	motor = `0`
	)

inlineoverridevirtual

Just provide the last reported speed without inertia modeling.

Implements ISpeedSource.

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

src/TinyRobotics/odometry/WheelEncoder.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ WheelEncoder()

Member Function Documentation

◆ begin()

◆ calibrateSlip()

◆ getDistance()

◆ getDistanceForTicks()

◆ getDistanceForTicksM()

◆ getDistanceM()

◆ getMotorCount()

◆ getRawDistanceM()

◆ getSlipFactor()

◆ getSpeed()

◆ getSpeedMPS()

◆ sendMessage()

◆ sendMessageCB()

◆ setReportingFrequencyMs()

◆ setSlipFactor()

◆ setThrottlePercent()

◆ setTick()

◆ setTicksPerRevolution()

◆ setWheelDiameter() [1/2]

◆ setWheelDiameter() [2/2]

◆ updateSpeed()