RobotPy-Characterization is now FRC-Characterization, part of WPILib

I’m glad to announce that the RobotPy Characterization Toolsuite has been rebranded - it is now the FRC Characterization Toolsuite, and is an official part of WPILib.

The FRC Characterization Toolsuite can be found here:

Github
PyPI

For the moment, usage documentation can be found in the github readme, but it will be moved to frc-docs by the time build season rolls around.

We hope to eventually include video tutorials, as well as end-to-end guides for autonomous movement from drivetrain characterization through pathfollowing.

Feel free to submit your suggestions and feature requests as github issues!

9 Likes

I have said this to many others in the past couple of years, but I seriously believe contributions like this will push FRC to completely new levels across the board. Once we get to a point with documentation that a team with only 1 software mentor can work on stuff like this, it will spread like fire. Exciting stuff and great work to you and the WPILIB team.

4 Likes

Rookie question -

What do you mean by “characterize”?

2 Likes

Per the readme, it determines best-fit parameters to a voltage-balance equation of the form:

V = kS \cdot sgn(\dot{d}) + kV \cdot \dot{d} + kA \cdot \ddot{d}

Or some similar variant thereof, where d is the mechanism displacement.

It can then also use those parameters to “bootstrap” a reasonable guess at “optimal” PD gains for a feedback controller via LQR, given user-supplied optimality constraints (i.e. max control effort and max acceptable errors).

In layman’s terms, the process of “characterization” measures how your drivetrain responds to voltage applied (or really, how much voltage it needs to start moving, how much voltage it needs to have applied to maintain a given speed, and how much voltage on top of that is needed to induce a given acceleration). It does this by measuring three coefficients.

kS in @Oblarg’s equation is the voltage needed to overcome your drivetrain’s static friction, or in other words to just barely get it moving; it turns out that this static friction (because it’s, well, static) constantly has the same effect on the motor power needed. That is, no matter what speed you’re going or what voltage you’ve applied to your motors, about 1 volt of that voltage (give or take depending on your drivetrain torque and the specific assembly) will be going towards overcoming the static friction in your gears, bearings, etc; this value is your kS.

kV describes how much voltage your drivetrain needs to hold (or “cruise”) at a given constant velocity while overcoming the electromagnetic resistance in the motor and any additional friction that increases with speed. The relationship between speed and voltage required is almost entirely linear (with FRC components, anyway) because of how motors work, so if you take a bunch of measurements of velocity with different voltages (and little to no acceleration), you can perform a linear regression and find the ratio between velocity and voltage applied. This is your kV. You can also calculate a theoretical value from your motors/gear ratio/wheel size, but this isn’t particularly useful or accurate EDIT: isn’t quite as accurate because robots are hard. (It does work in a pinch.)

kA describes the voltage needed to induce a given acceleration while overcoming the robot’s inertia (and also some electromagnetic forces in the motor IIRC). Same deal as kV, it’s pretty linear, and you can calculate it by accelerating to a given speed, measuring your robot’s acceleration and voltage, and subtracting the component of voltage related to static friction and velocity (which you can do because you know kV and kA). Also, like kV, you can calculate a theoretical value; however, it isn’t that useful because robots are hard especially with regard to acceleration.

With these three coefficients, and given a desired velocity and acceleration for (one side of) your drivetrain, you can use Oblarg’s equation to calculate the voltage you should apply. (It also works, albeit not as well, with just velocity.) This is very useful not just for, say, following a motion profile, but also for making your drivetrain more controllable in open-loop driving because your joystick inputs will more closely match the actual robot velocity.

TL:DR: Find a set of three numbers (kS, kV, kA) that describe your drivetrain’s performance and can be used to control it more accurately.

9 Likes

A slight correction: empirical values for kV usually agree fairly well with the theoretical values - it’s the other two where you really need empirical measurements.

In a pinch, the following approximation works well (for brushed motors):

kS: Approximately 1 volt
kV: ~100-110% of theoretical
kA: ~130-150% of theoretical

Note that inefficiency causes the regression coefficients to get bigger, as more voltage is needed.

5 Likes

Good point, I’ve edited that paragraph.

This is ground breaking stuff! The control of running a robot autonomously for given distances has always been done with pure PID loops. PID loops by their very nature are REACTIVE CONTROLS and are not the best solution. With the formula listed above, the control becomes partially PREDICTIVE or a FEED FORWARD control system. If you do a good search on Feed Forward control systems you will see some good tutorials on how all this works and about how fast they respond!

Characterization definitely hits the sweet spot between complexity and performance in terms of controls. We characterized manually last year with our own code for voltage ramping and analyzed the data in logger pro, but we’ll definitely be using this for 2020. Combined with the motion profiling implementation in WPILib, getting advanced controls on a robot will be easier than ever

1 Like

I hate nitpicking, but “what” this characterization tool is takes a bit of searching, since the README goes straight into how the tool works rather than dealing with characterization at all. Even something early on that references the “data analysis” chapter (which is where the equations come from) would be helpful for high school students.

This is perfect. Thanks for the explanation! I can point students to these bullet points. Any chance they could make their way onto the README?

1 Like

The README is being converted onto a frc-docs section under WPILib Tools. I’ll take any comments here into consideration when porting the current content.

1 Like

If you want to incorporate my explanation (or a cleaned-up version) into frc-docs let me know and I’ll be glad to help out.

Hi, we tried this tool out and we ran into some issues. Our graphs look very partial compared to the graphs in the README file, and we don’t know if the outputted parameters are correct.
We tried the characterization on a field carpet, for a distance of at least ~13 feet for each run, and the robot seemed to drive smoothly.

A few relevant stuff:

  • Here is our Robot.java file
  • Here is our JSON file
  • Here are our graphs and configs & final parameters.

Also, we wanted to ask whether there’s an option to calculate the parameters for each side because currently, we are getting only one set of parameters for both sides. Sometimes there are differences between the left and right sides of the drivetrain and it will be very helpful if we could have two sets of parameters to counter these differences.

Lastly, many thanks for this great tool and thank you @robinsonz for your comprehensible explanation.

Your data look perfectly fine. You can select which subset of the data to analyze with the “subset” drop down menu in the top right hand corner of the analyzer GUI.

While the data might look “clipped” in the time-domain plots, this is simply because you ended your tests a bit sooner than the ones in the readme and waited a fair amount of time between tests. The voltage-domain plots will be extremely similar.

1 Like

OK, thank you. Sorry for my late response.
And, is it possible to add characterization for each side?

Yes. Use the “subset” option in the top right hand corner.

Oh OK, I misunderstood your previous reply. Thank you!