Skip to content

Getting Started

Jump to bottom
Joel Gallant edited this page May 30, 2013 · 10 revisions

ATALibJ programs start at GamePeriods. The only code inside of GamePeriods that the programmer should write is the modes array. Simply put one instance of every RobotMode inside of the array. At least one RobotMode is needed for the code to run. Small note: The wpilibj currently (as of May 30, 2013) contains a bug that makes the SmartDashboard not display the robot selector. If you want control over your robot, you will need to write your own selection process and implement it in GamePeriods.

Writing Robot Modes

There are 6 options for robot modes.

The base interface of all other robot modes. You should use this interface if you will take advantage of every method inside of it. It contains Iterative style methods.

An exception-safe executor of robot modes. You can't extend this class, and it every mode is wrapped in it by default in GamePeriods. There isn't many cases where you would want to use this mode.

The base of an iterative-style robot. Contains init, periodic and end methods for every mode. The init method is called once before starting the mode, the periodic method is called in a periodic loop every 20ms during the mode and the end method is called once at the very end of the mode.

An adapter class that lets you choose which methods you need and implement them in your robot mode. If you are not using every method in IterativeRobot, you should be using this class.

The base of a simple-style robot. Contains one method per mode, and executes it once when the mode starts. Every method should loop until the mode is over, doing whatever is necessary in that mode.

An adapter class that lets you choose which methods you need and implement them in your robot mode. If you are not using every method in SimpleRobot, you should be using this class.

Writing Modules

A Module is an element of the robot that performs a function. It has init(), enable(), disable() and isEnabled() methods. These do pretty much what they describe.

Before writing your module, make sure you're not re-inventing the wheel. Check the edu.first.module package to ensure there is not a module already made for the purpose you need. Almost all wpilibj classes are wrapped as modules, as well as some highly-used controllers like bang-bang.

Structure of a Module

Most modules should be able to take advantage of StandardModule. The only reason why it wouldn't is if you need to extend another class. In that cass, implement Module yourself. Be sure to adhere to the contracts set in its documentation.

Standard Structure

Modules should emulate the structure of the ATALibJ modules. A standard module looks like this:

public class ExampleModule extends Module.StartardModule {

    public void init() {
        // Performs functions to ensure the module can be enabled and functional
    }

    public void enableModule() {
        // Performs functions to allow the module to work
    }

    public void disableModule() {
        // Performs the functions to reverse `enableModule()`
    }

    public void foo() {
        // Use `ensureEnabled()` when the function requires the module to be enabled (manipulates the module)
        ensureEnabled();
    }

    public void changeSetting(double setting) {
        // Changes setting
        // Changing settings of a module should not use `ensureEnabled()` simply because it does not do anything harmful
    }
}

Module contract

The general contract for all modules is as follows:

  • Modules contain methods specific to their purpose, but do not expose their composed instances for security reasons

  • Modules are "ready" to work when init() has been called, and its functions will work after enable() is called.

  • "Settings" of a module, AKA its internal state, are changeable even when disabled.

  • Between calling enable() and disable(), isEnabled() will return true. Only enable() and disable() can effect the output of isEnabled()

  • If a function is called while the module is disabled, the function should throw an IllegalStateException.

  • Calling any of the methods more than once in a row will not behave differently because of it.

  • The state of isEnabled() should be thread-safe and only return true when it is completely enabled.

Writing Subsystems

A Subsystem is a collection of modules that performs some kind of function.

Subsystems look like this:

public class ExampleSubsystem extends Subsystem {
    private final ExampleModule module;
    private final ExampleModule module2;

    public ExampleSubsystem(ExampleModule module, ExampleModule module2) {
        super(new Module[] {module, module2});
        this.module = module;
        this.module2 = module2;
    }

    public void foo() {
        module.foo();
        module2.foo();
    }
}

The subsystem combines two ExampleModule instances to perform foo() on both of them. This is an example of the "group" structure for subsystems. Groups take multiple modules and performs functions on all instances.

Clone this wiki locally