Motors

Control motors with ease using the Echo's integrated drivers and simplified EchoLib functions.

Quick Start

The MotorControllers class provides a high-level interface for managing multiple motors simultaneously. It acts as a centralized controller that can coordinate operations across up to 6 motors, offering both individual motor control and synchronized group operations.

Hardware Configuration

The class is configured for 6 motors with the following pin assignments:

Motor ID	Pin 1	Pin 2	MCPWM Unit	Timer
1	38	37	UNIT_0	TIMER_0
2	40	39	UNIT_0	TIMER_1
3	42	41	UNIT_0	TIMER_2
4	2	1	UNIT_1	TIMER_0
5	5	4	UNIT_1	TIMER_1
6	7	6	UNIT_1	TIMER_2

Overview

Method/Constructor	Description
MotorControllers()	Initializes all six motor objects with their assigned MCPWM units, timers and pin mappings. Automatically prepares the controller for use.
void shutDown()	Stops all motors and fully disables PWM output for every motor. Use this when powering down or entering a safe state. Note: Calling this would require a complete reset to re-enable PWM
void setAll(float percentage)	Sets the speed of all motors at once using a percentage from -100(full reverse) to 100(full forward).
void stopAll()	Immediately stops all motors (sets their speed to zero). Does not disable PWM.
void set(int motor, float percentage)	Sets the speed of a specific motor by ID (1–6)
void reverseAll()	Reverses the rotation direction of all motors until reversed again.
void reverse(int motor)	Reverses the direction of a single motor by ID.
void setCoast()	Sets all motors to coast mode, allowing free spinning without resistance.
void setBrake()	Sets all motors to brake mode, causing active electrical braking.
Motor* getMotorById(int id)	Returns a pointer to the motor with the given ID (1–6), or nullptr if invalid. Useful for custom low-level motor access.

Constructor

MotorControllers()

Purpose: Initializes all 6 motors with their respective pin configurations and MCPWM settings.

Behavior:

• Creates Motor objects for each of the 6 configured motors

• Assigns unique IDs (1-6) to each motor

• Distributes motors across two MCPWM units for optimal performance

---

System Control

void shutDown()

Purpose: Safely shuts down the entire motor system.

Behavior:

• Stops all motors (sets speed to 0)

• Disables PWM on all motor channels

• Should be called before system power down or reset

Example:

motorControllers.shutDown();

---

Group Motor Control

void setAll(float percentage)

Purpose: Sets the speed of all motors to the same percentage value.

Parameters:

• percentage: Speed value from -100 to 100

  • Positive values: Forward direction

  • Negative values: Reverse direction

  • 0: Stop

Example:

motorControllers.setAll(75);    // All motors at 75% forward
motorControllers.setAll(-50);   // All motors at 50% reverse

void stopAll()

Purpose: Immediately stops all motors by setting their speed to 0.

Example:

motorControllers.stopAll();

void reverseAll()

Purpose: Reverses the direction of all motors without changing their speed.

Behavior: Calls reverseDirection() on each motor, which toggles their direction state.

Example:

motorControllers.reverseAll();  // All motors now spin opposite direction

---

Individual Motor Control

void set(int motor, float percentage)

Purpose: Sets the speed of a specific motor.

Parameters:

• motor: Motor ID (1-6)

• percentage: Speed value from -100 to 100

Behavior:

• Finds the motor by ID

• If motor exists, sets its speed

• If motor ID is invalid, operation is silently ignored

Example:

motorControllers.set(1, 80);    // Motor 1 at 80% forward
motorControllers.set(3, -60);   // Motor 3 at 60% reverse

void reverse(int motor)

Purpose: Reverses the direction of a specific motor.

Parameters:

• motor: Motor ID (1-6)

Example:

motorControllers.reverse(2);    // Reverse motor 2's direction

Note: All motors by default run at a ramp rate, meaning that the .set() method will not immediatly set the motor to that speed, however, the ramp rate is small enough that it is unoticable. This ramp rate is set to avoid brownouts

---

Mode Control

void setCoast()

Purpose: Sets all motors to coast mode.

Behavior: When motors are stopped in coast mode, they spin freely without active braking.

void setBrake()

Purpose: Sets all motors to brake mode.

Behavior: When motors are stopped in brake mode, they actively resist rotation.

---

Utility Methods

Motor* getMotorById(int id)

Purpose: Retrieves a pointer to a specific motor object.

Parameters:

• id: Motor ID (1-6)

Returns:

• Pointer to Motor object if ID is valid

• nullptr if ID is invalid

Example:

Motor* motor1 = motorControllers.getMotorById(1);
if (motor1) {
    // Direct motor operations
    motor1->setSpeed(200);
}

Private Methods

int percentToCycle(int percentage)

Purpose: Converts percentage values (-100 to 100) to PWM duty cycle values (0-255).

Implementation: (percentage * 255) / 100

Note: This method handles the conversion from user-friendly percentage values to the internal PWM representation.

Usage Examples

Full Example

#include <EchoLib.h>

MotorControllers motorsControllers;

void setup() {
  Serial.begin(115200);
  delay(1000);
}

void loop() {
  motorControllers.set(1, 80);    // Motor 1 at 80% forward
  motorControllers.set(3, -60);   // Motor 3 at 60% reverse
  delay(1000);// Runs for 1 second
  motorControllers.set(1,0);//stops motors
  motorControllers.set(3,0);
  delay(1000);//waits 1 second
}

Design Notes

MCPWM Distribution

Motors are distributed across two MCPWM units:

• UNIT_0: Motors 1, 2, 3 (Timers 0, 1, 2)

• UNIT_1: Motors 4, 5, 6 (Timers 0, 1, 2)

This distribution ensures optimal PWM performance and avoids resource conflicts.

Error Handling

• Invalid motor IDs are handled gracefully (operations are ignored)

• Null pointer checks protect against invalid motor access

• No exceptions are thrown, making the interface safe for embedded use

Performance Considerations

• Motor lookup uses STL algorithms for efficiency

• Vector storage provides fast iteration for group operations

• PWM conversion is optimized for integer arithmetic

Thread Safety

Warning: This class is not thread-safe. If used in a multi-threaded environment, external synchronization is required to prevent race conditions during motor operations.