MARS Utilities documentation

mars-utils is a library of miscellaneous bits of code and a few utilities that were used to build MARS robots.

Control Manager

ControlManager was created to reduce the amount of boiler plate when creating multiple “control modes” for a robot. Essentially, each driver wants their own set of controls. For MagicRobot is is very easy, as each controlmanager mode can be a component that then has variables injected. However, adding all the control modes to the dashboard with a nice chooser, detecting and handling changes can lead to a lot of boilerplate.

ControlManager allows us to reduce boilerplate by subclassing ControlInterface and then initializing ControlManager with the control interfaces, and it creates the chooser.

For even more code reducing magic, see decorator.with_ctrl_manager() which when used with MagicRobot, completely removes all boilerplate by managing the creation of a ControlManager and dispatching event calls.

class marsutils.controlmanager.ControlInterface

Bases: object

ControlInterface is the base class that all interfaces must subclass to be used with ControlManager.

You must define a _DISPLAY_NAME. This value will be displayed in the dashboard chooser. Optionally, you can define a _SORT value. The larger the value, the higher priority it will be given in the chooser.

disabled()

enabled()

teleopPeriodic()

class marsutils.controlmanager.ControlManager(*interfaces, dashboard_key: Optional[str] = 'Control Mode')

This class manages creating a dashboard chooser and the periodic calling of a series of “control interface” components.

Each control interface must subclass ControlInterface and define _DISPLAY_NAME.

Once this has been initalized with the list of interfaces, you must manually call every event function you want your components to recive, like “teleopPeridic” and “teleopInit” and they will be forwarded to the active interface

You can optionally define a _SORT value for your interfaces. The larger the value, the higher priority it will be given in the chooser.

If dashboard_key is None, then the control chooser will not be added automatically, use this if you are using the Shuffleboard API or want a different root path. The control chooser can be accessed from control_chooser

setup_listener(dashboard_key)

If you construct the ControlManager with a None dashboard_key, you must call this function with the full networktables path to connect the callback for the mode to be properly updated

Utility decorators

The deocrator module provides several decorators to make certain things easier or possible.

marsutils.decorator.with_ctrl_manager(klass)

A decorator to be used with MagicRobot robot classes which automatically processes ControlInterface members

Any ControlInterface with a _DISPLAY_NAME variable defined will be added to a chooser on the dashboard and its associated methods will be automatically called

If the _CONTROL_CHOOSER_KEY class variable is set, that value will be provided to the ControlManager

marsutils.decorator.with_setup(klass)

As the MagicRobot class uses the robotInit() method, this decorator provides MagicRobot classes with a setup() function that is called after the createObjects() function is called

For more information, see robotpy/robotpy-wpilib-utilities#21

Math

The math module provides a few simple functions that provide common but important operations:

marsutils.math.signed_square(value)

A tiny function that returns the square of value but with the same sign.

>>> signed_square(-2)
-4

>>> signed_square(2)
2

marsutils.math.two_way_clamp(lower, upper, value)

A function that accepts a lower and upper bound and a value and will return the value if it is between the bounds, or it will return the clamped value.

>>> two_way_clamp(100, 500, 250)
250

>>> two_way_clamp(100, 500, -40)
100

>>> two_way_clamp(-100, -500, 0)
-100

Indices and tables

• Index
• Module Index