Declare dependency on the library

brick-control-lab uses Maven Central for distribution. To use brick-control-lab with Maven, add the following to your pom:

<dependency>
  <groupId>org.chabala.brick</groupId>
  <artifactId>brick-control-lab</artifactId>
  <version>0.2.1</version>
</dependency>

For syntax for other dependency management systems, see Dependency Information.

Working with ControlLab

The entrypoint to using the library is the ControlLab interface. Obtain an instance via newControlLab():

ControlLab controlLab = ControlLab.newControlLab();

Next the control lab needs to be bound to a serial port. This could be a hard coded or user defined value, but there is also a method that queries the underlying serial library to find what ports are available, based on some heuristics for port names. This might be useful for populating a configuration dialog. Here we’ll take the first port returned and bind it to the control lab:

List<String> availablePorts = controlLab.getAvailablePorts();
controlLab.open(availablePorts.get(0));

There is a fluent style for controlling output ports (motors, lights, etc).

controlLab.getOutput(OutputId.A).turnOn();
controlLab.getOutput(OutputId.B).setPowerLevel(PowerLevel.P4).turnOn();
controlLab.getOutput(OutputId.C).setDirection(Direction.LEFT).turnOn();

The reference for an output can be retained and reused.

Output outputA = controlLab.getOutput(OutputId.A);
outputA.turnOn();
outputA.setPowerLevel(PowerLevel.P4)
outputA.reverseDirection();
outputA.turnOff();

Outputs can also be operated on as a group.

controlLab.getOutput(EnumSet.range(OutputId.A, OutputId.D)).setPowerLevel(PowerLevel.P4).turnOn();
controlLab.getOutput(OutputId.ALL).turnOff();

There are also non-fluent style methods that are closer to the underlying protocol used by the interface hardware.

controlLab.turnOutputOn(OutputId.ALL);
controlLab.setOutputDirection(Direction.LEFT, EnumSet.of(OutputId.E, OutputId.F));

Input handling from the control lab is based on callback listeners. The stop button can be considered a special type of input, as it supports pressed and released events.

controlLab.getStopButton().addListener(new StopButtonListener() {
    @Override
    public void stopButtonPressed(StopButtonEvent stopButtonEvent) {
        System.out.println("Stopped");
    }
    
    @Override
    public void stopButtonReleased(StopButtonEvent stopButtonEvent) {
        System.out.println("Running");
    }
});

The release event has a default no-op implementation, so if one is only interested in the inital stop event, lambdas can be used instead:

controlLab.getStopButton().addListener(stopButtonEvent -> System.out.println("Stopped"));

Listeners can be added to other inputs, either as the raw values returned by the hardware, or specific sensor subclasses that attempt to interpret the values. Improvements are needed in this area, but the touch sensor is well understood:

controlLab.getInput(InputId.I1).addListener(new TouchSensorListener() {
    @Override
    public void touchSensorEventReceived(TouchSensorEvent sensorEvent) {
        System.out.println(sensorEvent.getValue().touchStatus());
    }
});

Every operation that involves the serial connection can potentially throw IOException, so one will need to catch those exceptions and determine how to recover. Once opened, the control lab needs to be closed in order to release the serial port and associated resources. Recommended usage is with try-finally or try-with-resources blocks to ensure proper closure.

ControlLab controlLab = ControlLab.newControlLab();
List<String> availablePorts = controlLab.getAvailablePorts();
try {
    controlLab.open(availablePorts.get(0));
    controlLab.getOutput(OutputId.A).setPowerLevel(PowerLevel.P4).turnOn();
} catch (IOException e) {
    e.printStackTrace();
} finally {
    try {
        controlLab.close();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

Refer to the javadoc for further details on using ControlLab and related classes.

For more usage examples, examine the integration tests ControlLabIT and MultipleControlLabIT.