Yggdrasil is the name of the reusable FRC Java libraries which FRC 3161 provides, free of charge and open to any usage (as permitted by the BSD 2-clause license), based upon the software developed by 3161 for the 2014 season. For more information about the team, or the robot for which this code was originally written, please visit 3161’s Homepage.
Development for Yggdrasil happens on our GitHub.
Versions 0.8 and up are compatible with the 2015 FRC Control Systems Update (or subsequent yearly updates - strict 2015 compatibility is not guaranteed) and Java 8+. If for some reason you need to remain compatible with the previous Java 1.4 Micro Edition environment and the cRIO, you will need to use an older 0.2.x version of Yggdrasil.
Yggdrasil is the name of the library which FRC 3161 uses and publishes for other teams to use as they please.
This project is intended as a collection of reusable modules, with no specific robot hardware configuration or design in mind. Each package provided by 3161 has the prefix ca.team3161.lib, and all classes reside within these packages. Each such class aims to have at least skeleton documentation explaining its purpose, but for ease of reference and a high-level overview, this document will explain the concepts behind the Yggdrasil libraries.
Please note that the basis of Yggdrasil was written in the cRIO days of FRC, and many additions were added the first year that the RoboRIO was introduced. At that time, (the author(s) felt that) WPILibJ was lacking functionality in some ways or defined its various interfaces and classes in a way that made extensibility difficult. More recent versions of WPILib have corrected many of the perceived flaws from earlier years, so parts of Yggdrasil have become redundant. These will eventually be marked as deprecated.
For an example of this, please see Nidhoggr. Javadocs for this project are available on GitHub Pages. A pre-built archive can be found at GitHub Releases, or Yggdrasil can be easily consumed with Maven or Gradle via Jitpack.
./gradlew javadoc will produce Javadocs within build/docs/javadoc.
You can open the index.html in that directory with your web browser of choice.
Do you want to help contribute to Yggdrasil? Awesome! Please visit our GitHub. From there you can fork Yggdrasil, make changes to your copy, and submit pull requests. Please give us your name and team number (if applicable) when you submit your pull request so we can give you proper credit!
The design intended by these libraries are a main robot class, subclassed from Titanbot, which defines the robot’s behaviour in autonomous, teleoperated, and disabled modes, in a manner very similar to the standard IterativeRobot provided by FRC. This base class provides for a robot’s autonomous routine to be performed in a separate thread from the main robot thread, allowing for a simpler, more straight-forward action scripting style, without having to rely on myriad Timer objects.
Major component groups of the robot can be modelled as Subsystem subclasses, which allows for components to be monitored and controlled in the background by a new thread or a shared threadpool. This allows physical safety to be ensured, for example, by having a background thread monitor a limit switch to ensure that a motor controller shuts off, even if the main robot class' logic fails to check for this condition.
Late in the 2014 season, 3161 forked Team 254’s CheesyVision library, and began to experiment with using this functionality to enhance our own autonomous routine with hotgoal detection. Parts of this forked repository are included in this repository, as cheesyvision.py in the root and the src/com/team254 source directory. These have been modified from Team 254’s originally published versions.
The main, starting-point package.
A subclass of IterativeRobot. Autonomous is run in a new Thread, leaving the main robot thread responsible (generally) solely for handling FMS events, Watchdog, etc. This allows autonomous scripts to use convenient semantics such as Thread sleeping rather than periodically checking Timer objects. A method "waitFor" is supplied which should be used in favour of Thread.sleep as it provides assurances that the autonomous script will not run over the length of the autonomous period. As a replacement for teleopPeriodic, the new method teleopRoutine should be used. Use of this method ensures that the autonomous background thread and the main robot thread (running teleop code) will not coexist, which would cause indeterminate runtime behaviour.
Interfaces and implementations for controllers for human operators to use
An interface defining a physical gamepad type controller. These are expected to have two thumbsticks, a directional pad, and an assortment of buttons. They may have additional functionality as well, but this is the minimal set. The thumbsticks' Y-axes may optionally be inverted. Gamepad implementations, such as LogitechDualAction and LogitechAttack3, are actually a type of Subsystem, and as such can be used in a more 'declarative' fashion than you may be accustomed to. Using the 'bind' or 'map' methods of a Gamepad, along with 'enableBindings' and 'disableBindings', it is possible to have button presses and control stick movements on your gamepad trigger events on your robot, without having to manually check the state of each button and stick in teleopPeriodic, for example. See the main robot class in Fenrir for an example.
A Gamepad implementation modelling the Logitech DualAction USB gamepad. In addition to the methods required by the Gamepad interface, this class offers convenience methods to check the "bumpers" and "triggers" (shoulder buttons) on the controller.
A Gamepad implementation modelling the Logitech Attack 3 USB Joystick. In addition to the methods required by the Gamepad interface, this class offers deadzone filtering, can be inverted, etc.
An abstract base class for concrete implementations, modelling real-world gamepad or joystick controllers, to build upon.
Represents various functions and input curve shaping which can be applied to joystick values from actual joystick controllers, or thumbsticks on gamepads.
A JoystickMode which applies the square rooting function (x → x\^1/2) to its inputs.
Assertions, PWM value validation, floating point rounding, etc.
Assertions. Contains static methods which take a boolean condition and throw an exception if these conditions do not hold. Useful for debugging and during development.
PWM value 'normalization' (truncating into the range [-1.0, 1.0]), non-negativity assertions, and other small snippets of code.
Classes which implement ComposedComponent do so to indicate that this is a "virtual" component, wrapped around some other type of component, which may also be virtual. At some point however, there should be a "concrete" component. An example of a "virtual" component might be a RampingSpeedController, in which case its composed, concrete component might be a Talon or a Victor.
PID control libraries. If you don’t know what PID is or what it’s for, take a look at Team 3161’s Resources page.
An interface representing a sensor used for PID control. Encoders, Gyros, Potentiometers, Accelerometers, and Rangefinders are examples of backing sensors that can be usefully wrapped by a class implementing PIDSrc.
A PID loop, which uses a PIDSrc and a set of constants to iteratively determine output values with which a system can reach and maintain a target value.
|
Warning
|
Using PID control rather than operator control places the physical safety and wellbeing of your robot and anybody near it in the hands of the correctness of your PID system. Please ensure that your constants are the correct sign (positive vs negative) and of reasonable order (start very, very small) before using a PID-controlled system. |
An abstract base class for concrete PID implementations to build upon.
|
Warning
|
Using PID control rather than operator control places the physical safety and wellbeing of your robot and anybody near it in the hands of the correctness of your PID system. Please ensure that your constants are the correct sign (positive vs negative) and of reasonable order (start very, very small) before using a PID-controlled system. |
A simple PID implementation with no frills or fancy features.
|
Warning
|
Using PID control rather than operator control places the physical safety and wellbeing of your robot and anybody near it in the hands of the correctness of your PID system. Please ensure that your constants are the correct sign (positive vs negative) and of reasonable order (start very, very small) before using a PID-controlled system. |
A PID loop for the specific application of an inverted pendulum system. This works the same as a standard PID, but with an additional "Feed Forward" term, which is used to compensate for gravity pulling on the pendulum.
|
Warning
|
Using PID control rather than operator control places the physical safety and wellbeing of your robot and anybody near it in the hands of the correctness of your PID system. Please ensure that your constants are the correct sign (positive vs negative) and of reasonable order (start very, very small) before using a PID-controlled system. |
A PIDRateValueSrc which provides its rates by measuring the rotational rate of an encoder.
A PIDSrc which provides an integer value by measuring the rotations of an encoder.
A PIDRateValueSrc which provides its rates by measuring the rotational rate of a gyroscope.
A PIDAngleValueSrc which provides an angle value representing the current rotational offset as measured by a gyroscope.
An AnglePIDSrc that uses two known points (voltage, angle) of a rotary potentiometer and is able to then convert measured voltages into corresponding angles. Generally the two known points will be the endpoints of the degrees of freedom of whatever system this sensor is monitoring. The angles are arbitrarily defined by the user, and all returned angles will simply scale between these end points, so long as the arbitrarily defined endpoint angles have correctly measured corresponding voltages.
|
Warning
|
Be absolutely sure that you have correctly measured and entered the range of motion endpoints of your physical system. Depending on the potentiometer you use and the way it is mounted, your "higher angle" may actually have a lower voltage. This is not a problem and you should not try to correct it by swapping the voltages between endpoints when you instantiate a PotentiometerPidSrc, as this would result in your system moving in reverse. |
A SpeedController implementation which wraps around another SpeedController and provides functionality to limit the maximum rate of change of this speed controller - in other words, adding velocity ramps.
A SpeedController implementation which combines another SpeedController (for example, a Jaguar) with an Encoder and some parameters about the speed of the robot drivetrain. When set to 0.5, for example, the VelocityController will then use a PID loop to attempt to dynamically set Jaguar output so that the Encoder reads 50% of maximal rotational speed.
Higher level components and control systems defining major pieces of a robot.
A system allowing Subsystems to safely operate concurrently without using the same resources (such as SpeedControllers, sensors, relays) and being interrupted by other subsystems. Any Subsystem will, before running its task, attempt to acquire all resources listed using require() in its defineResources() method. If any of these resources cannot be acquired in a timely fashion, the task skips this iteration and retries again later. If only a subset of its required resources were acquired, or if the task successfully runs, then it releases all resources until its next run. Resources may fail to be required if they are currently held by other running Subsystem tasks.
Subsystems are objects that model major physical component subsystems on robots. Subsystems have a list of required resources and a task that they run in the background. This task can be run once or periodically. If being run periodically, the wait time between iterations is configurable. A Subsystem might be given references to, or contain instances of, PID objects and SpeedControllers, and could then be used to implement PID-controlled driving, without having to rely on using any timers or explicitly writing any looping behaviour to iteratively calculate PID targets. Subsystem is an abstract class and so a Subsystem’s actual concrete behaviour can vary greatly between different subclasses.
|
Warning
|
Failure to require() the correct resources in defineResources() may lead to concurrency issues and indeterminate behaviour. Ensure that all of your Subsystems require() all of their resources. |
An abstract base class implementing the shared behaviour of all subsystems whose tasks are run in an independent, separate thread from all other subsystems.
An abstract base class implementing the shared behaviour of all subsystems whose tasks are run in a threadpool. Compared to an independent subsystem this conserves system resources, but may exhibit longer and/or less consistent latency between task runs in some situations.
A subsystem whose task is run only once per invocation of "start", on a separate independent thread.
A subsystem whose task is run only once per invocation of "start", on a shared thread with all other pooled subsystems.
A subsystem whose task is run periodically on a separate, independent thread.
Robot-side utilities.
Drivetrain components.
An abstract base class which defines a Drivetrain as a Subsystem, with one additional action: stopping the drivetrain completely, which is intended to stop all motor controllers managed by the drivetrain.
A class containing static helper methods to get instances of various drivetrain implementations.
A container object which groups heterogenous SpeedControllers and allows them to be managed as a unit. For example, a robot might use two Victors and two Talons to control its drive motors. Two SpeedControllerGroup objects could then be constructed, each controlling one side of the robot, and managing one Victor and one Talon. These SpeedControllerGroup objects can then be used in the robot code in the same manner as a Talon or Victor would be, but now only one method call needs to be performed rather than two for each change required to each side of the robot’s drive controllers.
A drivetrain controller that uses PID objects and is able to accurately drive straight and turn by degrees. In particular, two SpeedController instances are controlled, with two Encoders used to measure travelled distance, and a Gyro used to ensure a straight course while driving. The Gyro can also be used to orient the robot to face a specific direction.
A simple drivetrain which simply manages two SpeedControllers and manages them as the left-side and right-side of the robot, using left and right rate targets.
Classes which can be used for tracking the motion of the robot around the field.
An abstract base upon which other position estimators can be built. Allows integration of sensors, gyroscopes, and accelerometers, along with physical characteristics of the robot chassis, producing an estimated total displacement from the initial position of the robot.