1 /*
2 * Copyright © 2016 Greg Chabala
3 *
4 * This file is part of brick-control-lab.
5 *
6 * brick-control-lab is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU Lesser General Public License as
8 * published by the Free Software Foundation, either version 3 of the
9 * License, or (at your option) any later version.
10 *
11 * brick-control-lab is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public License
17 * along with brick-control-lab. If not, see http://www.gnu.org/licenses/.
18 */
19 package org.chabala.brick.controllab;
20
21 import org.slf4j.LoggerFactory;
22
23 import java.io.Closeable;
24 import java.io.IOException;
25 import java.lang.invoke.MethodHandles;
26 import java.util.List;
27 import java.util.Set;
28
29 /**
30 * This is the main interface for interacting with the LEGO® control lab, instances of
31 * which can be created with {@link org.chabala.brick.controllab.ControlLab#newControlLab()}.
32 *
33 * <p>Usage example: <pre class="prettyprint lang-java">
34 * ControlLab controlLab = ControlLab.newControlLab();
35 * {@code List<String>} availablePorts = controlLab.getAvailablePorts();
36 * try {
37 * controlLab.open(availablePorts.get(0));
38 * controlLab.getOutput(OutputId.A).setPowerLevel(PowerLevel.P4).turnOn();
39 * } catch (IOException e) {
40 * e.printStackTrace();
41 * } finally {
42 * try {
43 * controlLab.close();
44 * } catch (IOException e) {
45 * e.printStackTrace();
46 * }
47 * }</pre>
48 * <script src="https://cdn.jsdelivr.net/gh/google/code-prettify@master/loader/run_prettify.js"></script>
49 */
50 public interface ControlLab extends Closeable {
51
52 /**
53 * Returns a new ControlLab instance.
54 * @return a new ControlLab instance
55 */
56 static ControlLab newControlLab() {
57 return new ControlLabImpl(
58 LoggerFactory.getLogger(MethodHandles.lookup().lookupClass()));
59 }
60
61 /**
62 * List available serial ports on this machine. May change over time due to
63 * hot pluggable USB serial port adapters and the like.
64 *
65 * @return a list of system specific string identifiers for serial ports
66 */
67 List<String> getAvailablePorts();
68
69 /**
70 * Opens a connection to the control lab on the specified port.
71 * @param portName system specific serial port identifier
72 * @throws IOException if any number of possible communication issues occurs
73 */
74 void open(String portName) throws IOException;
75
76 /**
77 * Returns the system specific serial port identifier the control lab is
78 * connected to, or empty string if not connected.
79 * @return system specific serial port identifier or empty string
80 */
81 String getConnectedPortName();
82
83 /**
84 * Stops sending power to the specified outputs.
85 * @param outputs outputs to stop
86 * @throws IOException if any number of possible communication issues occurs
87 */
88 void turnOutputOff(Set<OutputId> outputs) throws IOException;
89
90 /**
91 * Starts sending power to the specified outputs.
92 * @param outputs outputs to start
93 * @throws IOException if any number of possible communication issues occurs
94 */
95 void turnOutputOn(Set<OutputId> outputs) throws IOException;
96
97 /**
98 * Sets the {@link Direction} of the specified outputs. Direction may be changed
99 * while the outputs are powered or unpowered.
100 * @param direction desired direction
101 * @param outputs which outputs to change
102 * @throws IOException if any number of possible communication issues occurs
103 */
104 void setOutputDirection(Direction direction, Set<OutputId> outputs) throws IOException;
105
106 /**
107 * Sets the {@link PowerLevel} of the specified outputs. Power level may be changed
108 * while the outputs are powered or unpowered.
109 * @param powerLevel desired power level
110 * @param outputs which outputs to change
111 * @throws IOException if any number of possible communication issues occurs
112 */
113 void setOutputPowerLevel(PowerLevel powerLevel, Set<OutputId> outputs) throws IOException;
114
115 /**
116 * Return a handle for the output specified on this control lab instance.
117 * @param outputId identifier of the desired output port
118 * @return handle for the output specific to this control lab instance
119 */
120 Output getOutput(OutputId outputId);
121
122 /**
123 * Return a handle for multiple outputs on this control lab instance.
124 * @param outputs identifiers of the desired output ports
125 * @return handle for the outputs specific to this control lab instance
126 */
127 Output getOutput(Set<OutputId> outputs);
128
129 /**
130 * Return a handle for the stop button on this control lab instance.
131 * @return handle for the stop button on this control lab instance
132 */
133 StopButton getStopButton();
134
135 /**
136 * Return a handle for the input specified on this control lab instance.
137 * @param inputId identifier of the desired input port
138 * @return handle for the input specific to this control lab instance
139 */
140 Input getInput(InputId inputId);
141
142 /**
143 * Disconnects from the control lab and releases any resources.
144 * @throws IOException if any number of possible communication issues occurs
145 */
146 @Override
147 void close() throws IOException;
148 }