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:  http://www.pi4j.com/
012 * **********************************************************************
013 * %%
014 * Copyright (C) 2012 - 2015 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
033/**
034 * <p>This interface provides a set of functions for 'Serial' communication.</p>
035 * 
036 * <p>
037 * Before using the Pi4J library, you need to ensure that the Java VM in configured with access to
038 * the following system libraries:
039 * <ul>
040 * <li>pi4j</li>
041 * <li>wiringPi</li>
042 * </ul>
043 * <blockquote> This library depends on the wiringPi native system library.</br> (developed by
044 * Gordon Henderson @ <a href="http://wiringpi.com/">http://wiringpi.com/</a>)
045 * </blockquote>
046 * </p>
047 * 
048 * @see com.pi4j.io.serial.SerialFactory
049 * @see com.pi4j.io.serial.SerialDataEvent
050 * @see com.pi4j.io.serial.SerialDataListener
051 * 
052 * @see <a href="http://www.pi4j.com/">http://www.pi4j.com/</a>
053 * @author Robert Savage (<a
054 *         href="http://www.savagehomeautomation.com">http://www.savagehomeautomation.com</a>)
055 */
056@SuppressWarnings("unused")
057public interface Serial {
058
059    /**
060     * The default hardware COM port provided via the Raspberry Pi GPIO header.
061     * 
062     * @see #open(String, int)
063     */
064    public static final String DEFAULT_COM_PORT = "/dev/ttyAMA0";
065    public static final int DEFAULT_MONITOR_INTERVAL = 100; // milliseconds
066
067    /**
068     * This method is call to open a serial port for communication.
069     * 
070     * @see #DEFAULT_COM_PORT
071     * 
072     * @param device The device address of the serial port to access. You can use constant
073     *            'DEFAULT_COM_PORT' if you wish to access the default serial port provided via the
074     *            GPIO header.
075     * @param baudRate The baud rate to use with the serial port.
076     *            
077     * @throws SerialPortException Exception thrown on any error.
078     */
079    public void open(String device, int baudRate) throws SerialPortException;
080
081    /**
082     * This method is called to close a currently open open serial port.
083     */
084    public void close() throws IllegalStateException;
085
086    /**
087     * This method is called to determine if the serial port is already open.
088     * 
089     * @see #open(String, int)
090     * @return a value of 'true' is returned if the serial port is already open.
091     */
092    public boolean isOpen();
093
094    /**
095     * This method is called to determine if the serial port is already closed.
096     * 
097     * @see #open(String, int)
098     * @return a value of 'true' is returned if the serial port is already in the closed state.
099     */
100    public boolean isClosed();
101    
102    /**
103     * This method is called to immediately flush the serial data transmit buffer and force any
104     * pending data to be sent to the serial port immediately.
105     */
106    public void flush() throws IllegalStateException;
107
108    /**
109     * <p>This method will read the next character available from the serial port receive buffer.</p>
110     * <p>
111     * <b>NOTE: If a serial data listener has been implemented and registered with this class, then
112     * this method should not be called directly. A background thread will be running to collect
113     * received data from the serial port receive buffer and the received data will be available on
114     * via the event.</b>
115     * </p>
116     * 
117     * @return next available character in the serial data buffer
118     */
119    public char read() throws IllegalStateException;
120
121    /**
122     * This method is called to submit a single character of data to the serial port transmit
123     * buffer.
124     * 
125     * @param data A single character to be transmitted.
126     */
127    public void write(char data) throws IllegalStateException;
128
129    /**
130     * This method is called to submit a character array of data to the serial port transmit buffer.
131     * 
132     * @param data  A character array of data to be transmitted.
133     */
134    public void write(char data[]) throws IllegalStateException;
135
136    /**
137     * This method is called to submit a single byte of data to the serial port transmit buffer.
138     * 
139     * @param data  A single byte to be transmitted.
140     */
141    public void write(byte data) throws IllegalStateException;
142
143    /**
144     * This method is called to submit a byte array of data to the serial port transmit buffer.
145     * 
146     * @param data A byte array of data to be transmitted.
147     */
148    public void write(byte data[]) throws IllegalStateException;
149
150    /**
151     * This method is called to submit a string of data to the serial port transmit buffer.
152     * 
153     * @param data  A string of data to be transmitted.
154     */
155    public void write(String data) throws IllegalStateException;
156
157    /**
158     * This method is called to submit a string of data with trailing CR + LF characters to the
159     * serial port transmit buffer.
160     * 
161     * @param data  A string of data to be transmitted.
162     */
163    public void writeln(String data) throws IllegalStateException;
164
165    /**
166     * This method is called to submit a string of formatted data to the serial port transmit
167     * buffer.
168     * 
169     * @param data  A string of formatted data to be transmitted.
170     * @param args  A series of arguments that can be included for the format string variable
171     *            replacements.
172     */
173    public void write(String data, String... args) throws IllegalStateException;
174
175    /**
176     * This method is called to submit a string of formatted data with trailing CR + LF characters
177     * to the serial port transmit buffer.
178     * 
179     * @param data  A string of formatted data to be transmitted.
180     * @param args  A series of arguments that can be included for the format string variable
181     *            replacements.
182     */
183    public void writeln(String data, String... args) throws IllegalStateException;
184
185    /**
186     * This method is called to determine if and how many bytes are available on the serial received
187     * data buffer.
188     * 
189     * @return The number of available bytes pending in the serial received buffer is returned.
190     */
191    public int availableBytes() throws IllegalStateException;
192
193    /**
194     * <p>
195     * Java consumer code can call this method to register itself as a listener for serial data
196     * events.
197     * </p>
198     * 
199     * @see com.pi4j.io.serial.SerialDataListener
200     * @see com.pi4j.io.serial.SerialDataEvent
201     * 
202     * @param listener  A class instance that implements the SerialListener interface.
203     */
204    public void addListener(SerialDataListener... listener);
205
206    /**
207     * <p> Java consumer code can call this method to unregister itself as a listener for serial data
208     * events. </p>
209     * 
210     * @see com.pi4j.io.serial.SerialDataListener
211     * @see com.pi4j.io.serial.SerialDataEvent
212     * 
213     * @param listener A class instance that implements the SerialListener interface.
214     */
215    public void removeListener(SerialDataListener... listener);
216        
217    /**
218     * This method returns TRUE if the serial interface has been shutdown.
219     * 
220     * @return shutdown state
221     */
222    public boolean isShutdown();
223    
224    
225    /**
226     * This method can be called to forcefully shutdown all serial data monitoring threads.
227     */
228    public void shutdown();
229
230    /**
231     * This method returns the serial data receive monitor delay interval in milliseconds.
232     * @return interval milliseconds
233     */
234    public int getMonitorInterval();
235
236    /**
237     * This method set the serial data receive monitor delay interval in milliseconds.
238     *
239     * @param interval number of milliseconds
240     */
241    public void setMonitorInterval(int interval);
242}