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}