This issue is a sample of what sort of documentation would be provided to a developer for implementing a new piece of functionality. In particular, we will pick a complex, closed-loop design for a west-coast style drivetrain.
Content
Basic Description
Create a new class to control the drivetrain of the robot.
In each mode, the drivetrain must accept commands from another class via setter methods. This source of data may be a driver, a vision system, an autonomous system, or something else. In every mode, the drivetrain must use the inputs to send commands to motor controllers.
Mechanically, the drivetrain is a rigid frame with a set of motors, chain, sprockets, and wheels on the left and right sides. Powering each set of motors causes the respective wheels to rotate. The rotation is measured by an encoder.
Hardware-wise, four Talon SRX motor controllers will be used - two for the left wheels, two for the right wheels. Each side of the drivetrain is chained together such that the speed is mechanically the same across all wheels and motors on that side. There will be one encoder per side of the drivetrain, connected to that side`s "Master" SRX. The other SRX should be set to Slave mode and follow the Master. Always use the provided Talon SRX class when interfacing with these controllers.
Additionally, a Gyroscope will be mounted on the rigid frame of the drivetrain. Use to read the present angle of the drivetrain.
Control Strategy
The drivetrain will have four distinct modes of operation:
Disabled
Open-Loop
Closed-Loop Velocity
Closed-Loop Velocity with Desired Heading
Disabled
All motors are to be turned off. No motion should occur.
This will primarily be used during Disabled mode to ensure the robot is not moving, nor intends to move.
Open-Loop
Outside system will provide "percent Vbus" commands for the left and right sides of the drivetrain. Set these to the motor controllers.
This will primarily be used during teleop, when the driver controls the robot with joysticks.
Closed-loop velocity
Outside system will provide "Desired Speed" commands in units of RPM for the left and right sides of the drivetrain. Configure the Talon SRX to run in closed loop (PIDF) mode, and pass the RPM commands to the controllers. The P,I,D, and F gains for each side of the drivetrain should be exposed as Calibrations.
This will primarily be used during autonomous, when we need the motors to run a certain speed.
Closed-loop velocity with Desired Heading
Outside system will provide both desired speed commands (as before), but additionally provide a desired heading (in degrees). Configure the SRX`s to run in PIDF closed loop as before. However, implement a simple P controller to compare the current heading (read from gyro) to the desired heading, calculate the error, multiply it by a positive Calibratable gain, add it to each side of the drivetrain (or subtract, as appropriate) and pass it to each side of the drivetrain.
This will primarily be used during autonomous or vision alignment, when we know both a speed and direction to point the robot in.
Interface
Main Methods
The class shall implement the following public methods:
void init(...)
This method will get called once at robot Init, and should be init all objects used by the drivetrain
void update()
This method will get called once per main control loop for the drivetrain (at a regular rate). This is the method where the values to pass to the Talon SRX should be calculated and actually sent. It is also any changes in the operational mode of the drivetrain are detected, and where any needed SRX reconfiguration happens.
void setDisabled(void)
This method should cause the drivetrain to enter disabled mode, and not command any motor commands.
This method should cause the drivetrain to start running in closed loop mode (wheel RPM only, no gyro). It should record the commanded speeds, and make sure they are sent to the Talon SRXs next time theupdate()` function is called.
This (overloaded) method should start the drivetrain running in closed loop mode with gyro, saving all three commands and then using them in the next update() call to set values to the Talon SRX`s
These getters should return the present state of the drivetrain. Mostly useful for debugging (printing stuff to webpage, log file, etc.). They should always return something meaningful, regardless of the operational mode of the drivetrain.
These getters should return the setpoints in use right now. They will be useful for debugging and tuning closed loop
void calGyro()void resetGyro()
These commands cause the gyro to recalibrate itself, or re-orient such that the present heading is 0. Cal is intended only to be called during disabled mode (as calibrating the gyro requires the robot be still). Reset may get called at any time (probably on a driver command, after squaring up to the wall).
Sample Introduction
This issue is a sample of what sort of documentation would be provided to a developer for implementing a new piece of functionality. In particular, we will pick a complex, closed-loop design for a west-coast style drivetrain.
Content
Basic Description
Create a new class to control the drivetrain of the robot.
In each mode, the drivetrain must accept commands from another class via setter methods. This source of data may be a driver, a vision system, an autonomous system, or something else. In every mode, the drivetrain must use the inputs to send commands to motor controllers.
Mechanically, the drivetrain is a rigid frame with a set of motors, chain, sprockets, and wheels on the left and right sides. Powering each set of motors causes the respective wheels to rotate. The rotation is measured by an encoder.
Hardware-wise, four Talon SRX motor controllers will be used - two for the left wheels, two for the right wheels. Each side of the drivetrain is chained together such that the speed is mechanically the same across all wheels and motors on that side. There will be one encoder per side of the drivetrain, connected to that side`s "Master" SRX. The other SRX should be set to Slave mode and follow the Master. Always use the provided Talon SRX class when interfacing with these controllers.
Additionally, a Gyroscope will be mounted on the rigid frame of the drivetrain. Use to read the present angle of the drivetrain.
Control Strategy
The drivetrain will have four distinct modes of operation:
Disabled
All motors are to be turned off. No motion should occur.
This will primarily be used during Disabled mode to ensure the robot is not moving, nor intends to move.
Open-Loop
Outside system will provide "percent Vbus" commands for the left and right sides of the drivetrain. Set these to the motor controllers.
This will primarily be used during teleop, when the driver controls the robot with joysticks.
Closed-loop velocity
Outside system will provide "Desired Speed" commands in units of RPM for the left and right sides of the drivetrain. Configure the Talon SRX to run in closed loop (PIDF) mode, and pass the RPM commands to the controllers. The P,I,D, and F gains for each side of the drivetrain should be exposed as Calibrations.
This will primarily be used during autonomous, when we need the motors to run a certain speed.
Closed-loop velocity with Desired Heading
Outside system will provide both desired speed commands (as before), but additionally provide a desired heading (in degrees). Configure the SRX`s to run in PIDF closed loop as before. However, implement a simple P controller to compare the current heading (read from gyro) to the desired heading, calculate the error, multiply it by a positive Calibratable gain, add it to each side of the drivetrain (or subtract, as appropriate) and pass it to each side of the drivetrain.
This will primarily be used during autonomous or vision alignment, when we know both a speed and direction to point the robot in.
Interface
Main Methods
The class shall implement the following public methods:
void init(...)This method will get called once at robot Init, and should be init all objects used by the drivetrain
void update()This method will get called once per main control loop for the drivetrain (at a regular rate). This is the method where the values to pass to the Talon SRX should be calculated and actually sent. It is also any changes in the operational mode of the drivetrain are detected, and where any needed SRX reconfiguration happens.
void setDisabled(void)This method should cause the drivetrain to enter disabled mode, and not command any motor commands.
void setOpenLoopCmd(double left_cmd, double right_cmd)This method should cause the drivetrain to start running in open-loop mode with the commanded percent-vbus motor commands. The commands should be sent
void setClosedLoopCmd(double left_rpm, double right_rpm)This method should cause the drivetrain to start running in closed loop mode (wheel RPM only, no gyro). It should record the commanded speeds, and make sure they are sent to the Talon SRX
s next time theupdate()` function is called.void setClosedLoopCmd(double left_rpm, double right_rpm, double heading_deg)This (overloaded) method should start the drivetrain running in closed loop mode with gyro, saving all three commands and then using them in the next
update()call to set values to the Talon SRX`sUtility/Debug Methods
double getLeftSpeedRPM()double getRightSpeedRPM()double getLeftCurentA()double getRightCurrentA()double getLeftVoltageV()double getRightVoltageV()double getHeadingDeg()String getMode()These getters should return the present state of the drivetrain. Mostly useful for debugging (printing stuff to webpage, log file, etc.). They should always return something meaningful, regardless of the operational mode of the drivetrain.
double getDesiredLeftSpeedRPM()double getDesiredRightSpeedRPM()double getDesiredHeadingDeg()These getters should return the setpoints in use right now. They will be useful for debugging and tuning closed loop
void calGyro()void resetGyro()These commands cause the gyro to recalibrate itself, or re-orient such that the present heading is 0. Cal is intended only to be called during disabled mode (as calibrating the gyro requires the robot be still). Reset may get called at any time (probably on a driver command, after squaring up to the wall).