Modules

Modules are the most basic element of ATALibJ. Modules are defined as 'things that do things'. In essence, almost everything you will write is a Module. The only comparably important concept is Commands.

So what is and isn't a module? It comes down to a pretty basic question:

Does the class I'm writing have a state?

In other words, is it possible to consider the class "on" or "off"? The essence of a module is that it can be enabled and disabled. It is not a good idea to limit your thinking to that functionality though. In fact, most of what a module is is not state dependent. The primary quality of modules is that they allow the user to treat the code modular, which is to say that everything is separate. This is pretty easy to conceptualize using a robot. Your shooter is a completely different element than your drivetrain. They aren't related in many ways. In the same way, your shooter has separate elements as well. You might have a sensor, a motor and a winch. All of these different elements are modules.

###Why use modules? Using the module interface lets the programmer treat everything as some kind of basic element. It allows for things like saying "turn everything off" and "what happens when this is off?". There are functions of modules that allow them to be very flexible, standard and robust. It doesn't add much boilerplate code or useless functionality - it changes the fundamental way of dealing with your robot. Once you use modules, it is difficult to go back.

###So, how do I make elements? 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.