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 - 2013 Pi4J
015 * %%
016 * Licensed under the Apache License, Version 2.0 (the "License");
017 * you may not use this file except in compliance with the License.
018 * You may obtain a copy of the License at
019 * 
020 *      http://www.apache.org/licenses/LICENSE-2.0
021 * 
022 * Unless required by applicable law or agreed to in writing, software
023 * distributed under the License is distributed on an "AS IS" BASIS,
024 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
025 * See the License for the specific language governing permissions and
026 * limitations under the License.
027 * #L%
028 */
029
030
031/**
032 * <p>This interface provides a set of functions for 'Serial' communication.</p>
033 * 
034 * <p>
035 * Before using the Pi4J library, you need to ensure that the Java VM in configured with access to
036 * the following system libraries:
037 * <ul>
038 * <li>pi4j</li>
039 * <li>wiringPi</li>
040 * </ul>
041 * <blockquote> This library depends on the wiringPi native system library.</br> (developed by
042 * Gordon Henderson @ <a href="https://projects.drogon.net/">https://projects.drogon.net/</a>)
043 * </blockquote>
044 * </p>
045 * 
046 * @see #SerialFactory
047 * @see #SerialDataEvent
048 * @see #SerialDataListener
049 * 
050 * @see <a href="http://www.pi4j.com/">http://www.pi4j.com/</a>
051 * @author Robert Savage (<a
052 *         href="http://www.savagehomeautomation.com">http://www.savagehomeautomation.com</a>)
053 */
054public interface Serial {
055
056    /**
057     * The default hardware COM port provided via the Raspberry Pi GPIO header.
058     * 
059     * @see #serialOpen(String,int)
060     */
061    public static final String DEFAULT_COM_PORT = "/dev/ttyAMA0";
062
063    /**
064     * This method is call to open a serial port for communication.
065     * 
066     * @see #DEFAULT_COM_PORT
067     * 
068     * @param device The device address of the serial port to access. You can use constant
069     *            'DEFAULT_COM_PORT' if you wish to access the default serial port provided via the
070     *            GPIO header.
071     * @param baudRate The baud rate to use with the serial port.
072     *            
073     * @return The return value is the file descriptor.
074     * @throws SerialPortException Exception thrown on any error.
075     */
076    void open(String device, int baudRate) throws SerialPortException;
077
078    /**
079     * This method is called to close a currently open open serial port.
080     */
081    void close() throws IllegalStateException;
082
083    /**
084     * This method is called to determine if the serial port is already open.
085     * 
086     * @see #open(String, int)
087     * @return a value of 'true' is returned if the serial port is already open.
088     */
089    boolean isOpen();
090
091    /**
092     * This method is called to determine if the serial port is already closed.
093     * 
094     * @see #open(String, int)
095     * @return a value of 'true' is returned if the serial port is already in the closed state.
096     */
097    boolean isClosed();
098    
099    /**
100     * This method is called to immediately flush the serial data transmit buffer and force any
101     * pending data to be sent to the serial port immediately.
102     */
103    void flush() throws IllegalStateException;
104
105    /**
106     * <p>This method will read the next character available from the serial port receive buffer.</p>
107     * <p>
108     * <b>NOTE: If a serial data listener has been implemented and registered with this class, then
109     * this method should not be called directly. A background thread will be running to collect
110     * received data from the serial port receive buffer and the received data will be available on
111     * via the event.</b>
112     * </p>
113     * 
114     * @return next available character in the serial data buffer
115     */
116    char read() throws IllegalStateException;
117
118    /**
119     * This method is called to submit a single character of data to the serial port transmit
120     * buffer.
121     * 
122     * @param data A single character to be transmitted.
123     */
124    void write(char data) throws IllegalStateException;
125
126    /**
127     * This method is called to submit a character array of data to the serial port transmit buffer.
128     * 
129     * @param data  A character array of data to be transmitted.
130     */
131    void write(char data[]) throws IllegalStateException;
132
133    /**
134     * This method is called to submit a single byte of data to the serial port transmit buffer.
135     * 
136     * @param data  A single byte to be transmitted.
137     */
138    void write(byte data) throws IllegalStateException;
139
140    /**
141     * This method is called to submit a byte array of data to the serial port transmit buffer.
142     * 
143     * @param data A byte array of data to be transmitted.
144     */
145    void write(byte data[]) throws IllegalStateException;
146
147    /**
148     * This method is called to submit a string of data to the serial port transmit buffer.
149     * 
150     * @param data  A string of data to be transmitted.
151     */
152    void write(String data) throws IllegalStateException;
153
154    /**
155     * This method is called to submit a string of data with trailing CR + LF characters to the
156     * serial port transmit buffer.
157     * 
158     * @param data  A string of data to be transmitted.
159     */
160    void writeln(String data) throws IllegalStateException;
161
162    /**
163     * This method is called to submit a string of formatted data to the serial port transmit
164     * buffer.
165     * 
166     * @param data  A string of formatted data to be transmitted.
167     * @param args  A series of arguments that can be included for the format string variable
168     *            replacements.
169     */
170    void write(String data, String... args) throws IllegalStateException;
171
172    /**
173     * This method is called to submit a string of formatted data with trailing CR + LF characters
174     * to the serial port transmit buffer.
175     * 
176     * @param data  A string of formatted data to be transmitted.
177     * @param args  A series of arguments that can be included for the format string variable
178     *            replacements.
179     */
180    void writeln(String data, String... args) throws IllegalStateException;
181
182    /**
183     * This method is called to determine if and how many bytes are available on the serial received
184     * data buffer.
185     * 
186     * @return The number of available bytes pending in the serial received buffer is returned.
187     */
188    int availableBytes() throws IllegalStateException;
189
190    /**
191     * <p>
192     * Java consumer code can call this method to register itself as a listener for serial data
193     * events.
194     * </p>
195     * 
196     * @see #SerialListener
197     * @see #SerialDataEvent
198     * 
199     * @param listener  A class instance that implements the SerialListener interface.
200     */
201    void addListener(SerialDataListener... listener);
202
203    /**
204     * <p> Java consumer code can call this method to unregister itself as a listener for serial data
205     * events. </p>
206     * 
207     * @see #SerialListener
208     * @see #SerialDataEvent
209     * 
210     * @param listener A class instance that implements the SerialListener interface.
211     */
212    void removeListener(SerialDataListener... listener);
213        
214    /**
215     * This method returns TRUE if the serial interface has been shutdown.
216     * 
217     * @return shutdown state
218     */    
219    boolean isShutdown();
220    
221    
222    /**
223     * This method can be called to forcefully shutdown all serial data monitoring threads.
224     */    
225    void shutdown();
226}