001package com.pi4j.io.serial;
002
003/*
004 * #%L
005 * **********************************************************************
006 * ORGANIZATION  :  Pi4J
007 * PROJECT       :  Pi4J :: Java Library (Core)
008 * FILENAME      :  Serial.java
009 *
010 * This file is part of the Pi4J project. More information about
011 * this project can be found here:  https://www.pi4j.com/
012 * **********************************************************************
013 * %%
014 * Copyright (C) 2012 - 2019 Pi4J
015 * %%
016 * This program is free software: you can redistribute it and/or modify
017 * it under the terms of the GNU Lesser General Public License as
018 * published by the Free Software Foundation, either version 3 of the
019 * License, or (at your option) any later version.
020 *
021 * This program is distributed in the hope that it will be useful,
022 * but WITHOUT ANY WARRANTY; without even the implied warranty of
023 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
024 * GNU General Lesser Public License for more details.
025 *
026 * You should have received a copy of the GNU General Lesser Public
027 * License along with this program.  If not, see
028 * <http://www.gnu.org/licenses/lgpl-3.0.html>.
029 * #L%
030 */
031
032
033import java.io.Closeable;
034import java.io.IOException;
035import java.io.InputStream;
036import java.io.OutputStream;
037
038/**
039 * <p>This interface provides a set of functions for 'Serial' communication.</p>
040 *
041 * <p>
042 * Before using the Pi4J library, you need to ensure that the Java VM in configured with access to
043 * the following system libraries:
044 * <ul>
045 * <li>pi4j</li>
046 * <li>wiringPi</li>
047 * </ul>
048 * <blockquote> This library depends on the wiringPi native system library.</br> (developed by
049 * Gordon Henderson @ <a href="http://wiringpi.com/">http://wiringpi.com/</a>)
050 * </blockquote>
051 * </p>
052 *
053 * @see com.pi4j.io.serial.SerialFactory
054 * @see com.pi4j.io.serial.SerialDataEvent
055 * @see SerialDataEventListener
056 *
057 * @see <a href="https://www.pi4j.com/">https://www.pi4j.com/</a>
058 * @author Robert Savage (<a
059 *         href="http://www.savagehomeautomation.com">http://www.savagehomeautomation.com</a>)
060 */
061@SuppressWarnings("unused")
062public interface Serial extends SerialDataReader, SerialDataWriter, AutoCloseable {
063
064    /**
065     * The default hardware COM port provided via the Raspberry Pi GPIO header.
066     *
067     * @see #open(String, int)
068     */
069    public static final String DEFAULT_COM_PORT = RaspberryPiSerial.DEFAULT_COM_PORT;
070    public static final String FIRST_USB_COM_PORT = "/dev/ttyUSB0";
071    public static final String SECOND_USB_COM_PORT = "/dev/ttyUSB1";
072
073    /**
074     * <p>
075     * This opens and initializes the serial port/device and sets the communication parameters.
076     * It sets the port into raw mode (character at a time and no translations).
077     * </p>
078     *
079     * <p>
080     * (ATTENTION: the 'device' argument can only be a maximum of 128 characters.)
081     * </p>
082     *
083     * @see #DEFAULT_COM_PORT
084     *
085     * @param device
086     *          The device address of the serial port to access. You can use constant
087     *          'DEFAULT_COM_PORT' if you wish to access the default serial port provided via the
088     *          GPIO header.
089     * @param baud
090     *          The baud rate to use with the serial port. (Custom baud rate are not supported)
091     * @param dataBits
092     *          The data bits to use for serial communication. (5,6,7,8)
093     * @param parity
094     *          The parity setting to use for serial communication. (None, Event, Odd, Mark, Space)
095     * @param stopBits
096     *          The stop bits to use for serial communication. (1,2)
097     * @param flowControl
098     *          The flow control option to use for serial communication. (none, hardware, software)
099     *
100     * @throws IOException thrown on any error.
101     */
102    public void open(String device, int baud, int dataBits, int parity, int stopBits, int flowControl)
103            throws IOException;
104
105
106    /**
107     * <p>
108     * This opens and initializes the serial port/device and sets the communication parameters.
109     * It sets the port into raw mode (character at a time and no translations).
110     *
111     * This method will use the following default serial configuration parameters:
112     *  - DATA BITS    = 8
113     *  - PARITY       = NONE
114     *  - STOP BITS    = 1
115     *  - FLOW CONTROL = NONE
116     *
117     * </p>
118     *
119     * <p>
120     * (ATTENTION: the 'device' argument can only be a maximum of 128 characters.)
121     * </p>
122     *
123     * @see #DEFAULT_COM_PORT
124     *
125     * @param device
126     *          The device address of the serial port to access. You can use constant
127     *          'DEFAULT_COM_PORT' if you wish to access the default serial port provided via the
128     *          GPIO header.
129     * @param baud
130     *          The baud rate to use with the serial port.
131     *
132     * @throws IOException thrown on any error.
133     */
134    public void open(String device, int baud) throws IOException;
135
136    /**
137     * <p>
138     * This opens and initializes the serial port/device and sets the communication parameters.
139     * It sets the port into raw mode (character at a time and no translations).
140     * </p>
141     *
142     * <p>
143     * (ATTENTION: the 'device' argument can only be a maximum of 128 characters.)
144     * </p>
145     *
146     * @see #DEFAULT_COM_PORT
147     *
148     * @param device
149     *          The device address of the serial port to access. You can use constant
150     *          'DEFAULT_COM_PORT' if you wish to access the default serial port provided via the
151     *          GPIO header.
152     * @param baud
153     *          The baud rate to use with the serial port.
154     * @param dataBits
155     *          The data bits to use for serial communication. (5,6,7,8)
156     * @param parity
157     *          The parity setting to use for serial communication. (None, Event, Odd, Mark, Space)
158     * @param stopBits
159     *          The stop bits to use for serial communication. (1,2)
160     * @param flowControl
161     *          The flow control option to use for serial communication. (none, hardware, software)
162     *
163     * @throws IOException thrown on any error.
164     */
165    public void open(String device, Baud baud, DataBits dataBits, Parity parity, StopBits stopBits,
166                     FlowControl flowControl) throws IOException;
167
168    /**
169     * <p>
170     * This opens and initializes the serial port/device and sets the communication parameters.
171     * It sets the port into raw mode (character at a time and no translations).
172     * </p>
173     *
174     * <p>
175     * (ATTENTION: the 'device' argument can only be a maximum of 128 characters.)
176     * </p>
177     *
178     * @see #DEFAULT_COM_PORT
179     *
180     * @param serialConfig
181     *          A serial configuration object that contains the device, baud rate, data bits, parity,
182     *          stop bits, and flow control settings.
183     *
184     * @throws IOException thrown on any error.
185     */
186    public void open(SerialConfig serialConfig) throws IOException;
187
188    /**
189     * This method is called to close a currently open open serial port.
190     *
191     * @throws IllegalStateException thrown if the serial port is not already open.
192     * @throws IOException thrown on any error.
193     */
194    public void close() throws IllegalStateException, IOException;
195
196    /**
197     * This method is called to determine if the serial port is already open.
198     *
199     * @see #open(String, int)
200     * @return a value of 'true' is returned if the serial port is already open.
201     */
202    public boolean isOpen();
203
204    /**
205     * This method is called to determine if the serial port is already closed.
206     *
207     * @see #open(String, int)
208     * @return a value of 'true' is returned if the serial port is already in the closed state.
209     */
210    public boolean isClosed();
211
212    /**
213     * <p>
214     *     Forces the transmission of any remaining data in the serial port transmit buffer.
215     *     Please note that this does not force the transmission of data, it discards it!
216     * </p>
217     *
218     * @throws IllegalStateException thrown if the serial port is not already open.
219     * @throws IOException thrown on any error.
220     */
221    public void flush() throws IllegalStateException, IOException;
222
223    /**
224     * <p>
225     *     Discards any data in the serial receive (input) buffer.
226     *     Please note that this does not force the transmission of data, it discards it!
227     * </p>
228     *
229     * @throws IllegalStateException thrown if the serial port is not already open.
230     * @throws IOException thrown on any error.
231     */
232    public void discardInput() throws IllegalStateException, IOException;
233
234    /**
235     * <p>
236     *     Discards any data in the serial transmit (output) buffer.
237     *     Please note that this does not force the transmission of data, it discards it!
238     * </p>
239     *
240     * @throws IllegalStateException thrown if the serial port is not already open.
241     * @throws IOException thrown on any error.
242     */
243    public void discardOutput() throws IllegalStateException, IOException;
244
245    /**
246     * <p>
247     *     Discards any data in  both the serial receive and transmit buffers.
248     *     Please note that this does not force the transmission of data, it discards it!
249     * </p>
250     *
251     * @throws IllegalStateException thrown if the serial port is not already open.
252     * @throws IOException thrown on any error.
253     */
254    public void discardAll() throws IllegalStateException, IOException;
255
256    /**
257     * <p>
258     *     Send a BREAK signal to connected device.
259     * </p>
260     *
261     * @param duration
262     *          The length of time (milliseconds) to send the BREAK signal
263     * @throws IllegalStateException thrown if the serial port is not already open.
264     * @throws IOException thrown on any error.
265     */
266    public void sendBreak(int duration) throws IllegalStateException, IOException;
267
268    /**
269     * <p>
270     *     Send a BREAK signal to connected device for at least 0.25 seconds, and not more than 0.5 seconds
271     * </p>
272     *
273     * @throws IllegalStateException thrown if the serial port is not already open.
274     * @throws IOException thrown on any error.
275     */
276    public void sendBreak() throws IllegalStateException, IOException;
277
278    /**
279     * <p>
280     *     Send a constant BREAK signal to connected device. (Turn break on/off)
281     *     When enabled this will send a steady stream of zero bits.
282     *     When enabled, no (other) data transmitting is possible.
283     * </p>
284     *
285     * @param enabled
286     *          The enable or disable state to control the BREAK signal
287     * @throws IllegalStateException thrown if the serial port is not already open.
288     * @throws IOException thrown on any error.
289     */
290    public void setBreak(boolean enabled) throws IllegalStateException, IOException;
291
292    /**
293     * <p>
294     *     Control the RTS (request-to-send) pin state.
295     *     When enabled this will set the RTS pin to the HIGH state.
296     * </p>
297     *
298     * @param enabled
299     *          The enable or disable state to control the RTS pin state.
300     * @throws IllegalStateException thrown if the serial port is not already open.
301     * @throws IOException thrown on any error.
302     */
303    public void setRTS(boolean enabled) throws IllegalStateException, IOException;
304
305    /**
306     * <p>
307     *     Control the DTR (data-terminal-ready) pin state.
308     *     When enabled this will set the DTR pin to the HIGH state.
309     * </p>
310     *
311     * @param enabled
312     *          The enable or disable state to control the RTS pin state.
313     * @throws IllegalStateException thrown if the serial port is not already open.
314     * @throws IOException thrown on any error.
315     */
316    public void setDTR(boolean enabled) throws IllegalStateException, IOException;
317
318    /**
319     * <p>
320     *     Get the RTS (request-to-send) pin state.
321     * </p>
322     *
323     * @throws IllegalStateException thrown if the serial port is not already open.
324     * @throws IOException thrown on any error.
325     */
326    public boolean getRTS() throws IllegalStateException, IOException;
327
328    /**
329     * <p>
330     *     Get the DTR (data-terminal-ready) pin state.
331     * </p>
332     *
333     * @throws IllegalStateException thrown if the serial port is not already open.
334     * @throws IOException thrown on any error.
335     */
336    public boolean getDTR() throws IllegalStateException, IOException;
337
338    /**
339     * <p>
340     *     Get the CTS (clean-to-send) pin state.
341     * </p>
342     *
343     * @throws IllegalStateException thrown if the serial port is not already open.
344     * @throws IOException thrown on any error.
345     */
346    public boolean getCTS() throws IllegalStateException, IOException;
347
348    /**
349     * <p>
350     *     Get the DSR (data-set-ready) pin state.
351     * </p>
352     *
353     * @throws IllegalStateException thrown if the serial port is not already open.
354     * @throws IOException thrown on any error.
355     */
356    public boolean getDSR() throws IllegalStateException, IOException;
357
358    /**
359     * <p>
360     *     Get the RI (ring-indicator) pin state.
361     * </p>
362     *
363     * @throws IllegalStateException thrown if the serial port is not already open.
364     * @throws IOException thrown on any error.
365     */
366    public boolean getRI() throws IllegalStateException, IOException;
367
368    /**
369     * <p>
370     *     Get the CD (carrier-detect) pin state.
371     * </p>
372     *
373     * @throws IllegalStateException thrown if the serial port is not already open.
374     * @throws IOException thrown on any error.
375     */
376    public boolean getCD() throws IllegalStateException, IOException;
377
378
379    // ----------------------------------------
380    // EVENT OPERATIONS
381    // ----------------------------------------
382
383    /**
384     * <p>
385     * Java consumer code can call this method to register itself as a listener for serial data
386     * events.
387     * </p>
388     *
389     * @see SerialDataEventListener
390     * @see com.pi4j.io.serial.SerialDataEvent
391     *
392     * @param listener  A class instance that implements the SerialListener interface.
393     */
394    public void addListener(SerialDataEventListener... listener);
395
396    /**
397     * <p> Java consumer code can call this method to unregister itself as a listener for serial data
398     * events. </p>
399     *
400     * @see SerialDataEventListener
401     * @see com.pi4j.io.serial.SerialDataEvent
402     *
403     * @param listener A class instance that implements the SerialListener interface.
404     */
405    public void removeListener(SerialDataEventListener... listener);
406
407
408    // ----------------------------------------
409    // FILE OPERATIONS
410    // ----------------------------------------
411
412    /**
413     * This method returns the serial device file descriptor
414     * @return fileDescriptor file descriptor
415     */
416    public int getFileDescriptor();
417
418    /**
419     * This method returns the input data stream for the serial port's receive buffer
420     * @return InputStream input stream
421     */
422    public InputStream getInputStream();
423
424    /**
425     * This method returns the output data stream for the serial port's transmit buffer
426     * @return OutputStream output stream
427     */
428    public OutputStream getOutputStream();
429
430    /**
431     * This method returns the buffering state for data received from the serial device/port.
432     * @return 'true' if buffering is enabled; else 'false'
433     */
434    public boolean isBufferingDataReceived();
435
436    /**
437     * <p>
438     *     This method controls the buffering state for data received from the serial device/port.
439     * </p>
440     * <p>
441     *   If the buffering state is enabled, then all data bytes received from the serial port will
442     *   get copied into a data receive buffer.  You can use the 'getInputStream()' or and of the 'read()'
443     *   methods to access this data.  The data will also be available via the 'SerialDataEvent' event.
444     *   It is important to know that if you are using data buffering, the data will continue to grow
445     *   in memory until your program consume it from the data reader/stream.
446     * </p>
447     * <p>
448     *   If the buffering state is disabled, then all data bytes received from the serial port will NOT
449     *   get copied into the data receive buffer, but will be included in the 'SerialDataEvent' event's
450     *   data payload.  If you program does not care about or use data received from the serial port,
451     *   then you should disable the data buffering state to prevent memory waste/leak.
452     * </p>
453     *
454     * @param enabled
455     *   Sets the buffering behavior state.
456     *
457     */
458    public void setBufferingDataReceived(boolean enabled);
459
460}