SwerveModule
SwerveModule
A swerve module combines a drive motor with a steering actuator. EasyStack’s SwerveModule uses an EasyMotor for traction and an EasyCRServo for steering. The servo wrapper supplies the current angle and performs its own angle control when update() is called.
Creating a module
The constructor takes driveMotor, steeringServo, offset, and maxSpeed. Configure the motor and the steering angle feedback before constructing the module. Those hardware setup APIs are outside the supplied files.
import dev.easyfamily.easystack.drivebase.swerve.coaxial
.SwerveModule;
import dev.easyfamily.easystack.geometry.Vector2d;
SwerveModule module = new SwerveModule(
driveMotor,
steeringServo,
tangentialOffset,
3.0
);For a meter based setup, maxSpeed is in meters per second. The module converts requested speed into a motor power fraction using this value. It does not read wheel speed or close a drive velocity loop itself.
How the offset is used
The implementation stores offset.norm() as moduleRadius and offset.angle() as tangentialAngle. calculateVectorRobotCentric() builds the rotational contribution in that stored direction, with magnitude moduleRadius multiplied by omega, then adds the chassis translation vector.
The code does not rotate the offset direction by 90 degrees. With conventional Cartesian Vector2d semantics, passing a physical position (x, y) directly would make the rotation contribution point radially. To represent positive counterclockwise rotation, the setup on the next page passes the tangential vector (−y, x), whose magnitude is the same as the module’s radius.
The constructor rejects null hardware, a null offset, and maxSpeed values less than or equal to zero.
Swerve module geometry
Position and tangential direction
Use robot X forward and robot Y left. For a module physically located at (x, y), positive counterclockwise rotation produces a velocity component in direction (−y, x). The supplied module uses the passed vector directly as this direction, so the example makes that conversion explicitly.
double halfLength = wheelBase / 2.0;
double halfWidth trackWidth / 2.0;
Vector2d frontRightOffset
new Vector2d(halfWidth, halfLength);
Vector2d frontLeftOffset
new Vector2d(-halfWidth, halfLength);
Vector2d backLeftOffset
new Vector2d(-halfWidth, -halfLength);
Vector2d backRightOffset
new Vector2d(halfWidth, -halfLength);These variables are effective tangential offsets for this implementation. They are not the physical position vectors. This distinction follows from how SwerveModule uses offset.angle(); verify the underlying Vector2d convention if that class differs from standard Cartesian vectors.
Combining translation and rotation
ChassisSpeed request new ChassisSpeed(1.@, 0.0, 0.5);
Vector2d wheelVelocity
module.calculateVectorRobotCentric(request);
module.updateModuleWithVelocity(wheelVelocity);calculateVectorRobotCentric() only returns a vector. It does not change the module target or apply motor power. updateModuleWithVelocity() stores the provided vector and immediately updates the module.
The SwerveDrivetrain constructor’s trackWidth and wheelBase values are used to derive maximum angular speed. They do not overwrite module offsets or configure their directions. Keep the drivetrain dimensions and module geometry consistent.
Swerve module updates
Setting and applying a target
setTargetVelocity() stores a wheel velocity vector. updateModule() then reads the steering angle, optimizes the desired direction, calculates traction power, and calls the steering controller. Use both in the active loop, or use the combined method.
module.setTargetVelocity(new Vector2d(1.0, 0.0));
module.updateModule();
// equivalent Immediate update for the same target.
module.updateModuleWithVelocity(new Vector2d(1.0, 0.0));The steering angle and target direction are handled in radians. The module normalizes angular error to a wrapped interval ending at positive π, so it can choose a short turn across the angular boundary.
Wheel flip optimization
If the requested steering change is greater than 90 degrees, the module rotates the target direction by π radians and reverses traction power. The wheel can then produce the same motion with less steering travel. A change of exactly 90 degrees does not activate this branch.
After optimization, power is calculated from requested speed divided by maxSpeed and multiplied by cos(angleError). This reduces traction while the wheel is misaligned. A flipped wheel receives the opposite sign, and the result is clamped to −1 through 1.
= module.getAngleError();
boolean reversed module.isWheelFlipped();
double currentAngle = module.getCurrentAngle();getAngleError() and isWheelFlipped() describe the most recent update. getCurrentAngle() asks the steering wrapper for its angle. The module does not implement a zero speed angle hold: a zero vector is still processed through angle() and the steering update. The exact zero vector angle depends on Vector2d.
Swerve module configuration and stopping
Hardware access and caching
getDriveMotor() and getSteeringServo() return the actual hardware wrapper references. Use them when you need access to hardware configuration, while avoiding competing control code that writes another command after the module update.
double maximumSpeed = module.getMaxSpeed();
= module.getModuleRadius();
= module.getTangentialAngle();setCachingTolerance() forwards the first value to the drive motor’s setPowerCacheTolerance() and the second to the steering servo’s setCachingTolerance(). The precise caching behavior belongs to those wrappers. This setting does not configure a steering angle tolerance, PID gains, or a drive velocity tolerance in SwerveModule.
getModuleRadius() and getTangentialAngle() expose the values derived from the constructor vector. getMaxSpeed() returns the configured speed used to convert wheel velocity to power.
Target ownership
getTargetVelocity() returns the stored target reference, and setTargetVelocity() stores the supplied reference without copying it. If Vector2d is mutable in your project, avoid modifying that object elsewhere while the module is using it. Create a fresh vector for each independent request when ownership is uncertain.
Stopping a module
module.stop();stop() sets drive motor power to zero and calls steeringServo.stop(). It does not clear targetVelocity, angleError, or wheelFlipped. A later updateModule() resumes processing the previously stored target.
To stay stopped, keep the normal update path disabled until you intentionally resume control. To resume with a new movement, submit the new target before updating. A zero target requests no traction, but it can still command a steering angle.
Última actualización 2026-11-16