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}