The Units Library

I mentioned earlier the usefulness of the units library in WPILib. It allows us to clarify the unit we are using in our variables and even handles conversions between types automatically.

How to use the library

Include the library

To use a unit variable in your code, you must first include the specific units:: library, depending on which kind of units you need.

For example, if you wanted to use degrees or radians, you could type #include <units/angle.h> at the top of your code.

Some additional examples:

• acceleration.h
• velocity.h
• time.h

Use the right class

Next, you need to find the proper class for the unit you're looking for. To start, type units:: because all the units are located inside the "units" namespace. Then, try typing the name of your unit. For example, for degree, you might type units::degree. At this point, VSCode should automatically come up with options to select from (if it doesn't, try building the code first): select the option that ends in _t. For our example, you would select units::degree_t.

Here are some additional examples:

• units::meters_per_second_t
• units::radians_per_second_t

Initialize your variable

Finally, you need to set a value for your variable. This step is tricky because you can't just set the variable equal to an int or double; you have to explicitly declare that you are providing that unit for your variable. There are 3 ways to do this: using the class constructor, using implicit construction (brackets), or using unit literals.

For our previous of example of units::degree_t:

1. units::degree_t var_1 = units::degree_t(30); // This utilizes the constructor to make a degree_t from the int of 30
2. units::degree_t var_2{30}; // This is equivalent to the line above but utilizes implicit construction.
3. units::degree_t = 30_deg; // This is using unit literals.

The first 2 methods should hopefully look familiar from our lesson on objects, while #3 is explained below.

Unit literals

Unit literals are yet another thing that WPILib includes to make our life easier. Each "units" library comes with "literals" to help us write units that are easier to read.

• _mps = meters_per_second
• _mps_sq = meters_per_second_squared
• _fps = feet_per_second
• _deg = degree
• _rad = radian
• _m = meter
• _ft = foot
• _in = inch
• _s = second
• _ms = millisecond

The list goes on and on, but you get the point. Just plop these onto the end of a number (int or double), and you are good to go!

Unit conversion

One more awesome thing about the WPILib library is being able to convert between variables of similar type. For example, you could do units::radian_t = 30_deg or units::meter_t = 5_ft.

In addition, you can set variables of different types equal to each other.

units::meters_per_second_t MAX_SPEED = 2_mps;

units::feet_per_second_t HALF_SPEED = MAX_SPEED / 2; // Automatically converts to feet per second

Getting the raw value

Now the units library is great, but unfortunately it doesn't fit very well when working with other libraries, like other FRC libraries or the C++ standard library. For these cases, you have to convert the variable back to an integer or double.

The easiest way to do this is with a function included in all unit classes: .value(). This function returns the raw value contained inside the variable.

units::meters_per_second_t MAX_SPEED = 2_mps;

MAX_SPEED.value(); // Returns 2

units::radian_t angle = 30_deg;

angle.value(); // Returns PI/6

Extra Resources

Read more about the Units library from WPILIB themselves: https://docs.wpilib.org/en/stable/docs/software/basic-programming/cpp-units.html