001package com.pi4j.wiringpi; 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 com.pi4j.util.NativeLibraryLoader; 034 035/** 036 * <p> 037 * WiringPi includes a simplified serial port handling library. It can use the on-board serial port, 038 * or any USB serial device with no special distinctions between them. You just specify the device 039 * name in the initial open function. 040 * </p> 041 * 042 * <p> 043 * Note: The file descriptor (fd) returned is a standard Linux filehandle. You can use the standard 044 * read(), write(), etc. system calls on this filehandle as required. E.g. you may wish to write a 045 * larger block of binary data where the serialPutchar() or serialPuts() function may not be the 046 * most appropriate function to use, in which case, you can use write() to send the data. 047 * </p> 048 * 049 * <p> 050 * Before using the Pi4J library, you need to ensure that the Java VM in configured with access to 051 * the following system libraries: 052 * <ul> 053 * <li>pi4j</li> 054 * <li>wiringPi</li> 055 * </ul> 056 * <blockquote> This library depends on the wiringPi native system library.</br> (developed by 057 * Gordon Henderson @ <a href="http://wiringpi.com/">http://wiringpi.com/</a>) 058 * </blockquote> 059 * </p> 060 * 061 * @see <a href="https://www.pi4j.com/">https://www.pi4j.com/</a> 062 * @see <a 063 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 064 * @author Robert Savage (<a 065 * href="http://www.savagehomeautomation.com">http://www.savagehomeautomation.com</a>) 066 */ 067public class Serial { 068 069 /** 070 * The default hardware COM port provided via the Raspberry Pi GPIO header. 071 * 072 * @see #serialOpen(String,int) 073 */ 074 public static final String DEFAULT_COM_PORT = "/dev/ttyAMA0"; 075 076 // private constructor 077 private Serial() { 078 // forbid object construction 079 } 080 081 static { 082 // Load the platform library 083 NativeLibraryLoader.load("libpi4j.so"); 084 } 085 086 /** 087 * <p>int serialOpen (char *device, int baud);</p> 088 * 089 * <p> 090 * This opens and initializes the serial device and sets the baud rate. It sets the port into 091 * raw mode (character at a time and no translations), and sets the read timeout to 10 seconds. 092 * The return value is the file descriptor or -1 for any error, in which case errno will be set 093 * as appropriate. 094 * </p> 095 * 096 * <p> 097 * (ATTENTION: the 'device' argument can only be a maximum of 128 characters.) 098 * </p> 099 * 100 * @see #DEFAULT_COM_PORT 101 * @see <a 102 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 103 * 104 * @param device The device address of the serial port to access. You can use constant 105 * 'DEFAULT_COM_PORT' if you wish to access the default serial port provided via the 106 * GPIO header. 107 * @param baud The baud rate to use with the serial port. 108 * @return The return value is the file descriptor or -1 for any error, in which case errno will 109 * be set as appropriate. 110 */ 111 public synchronized static native int serialOpen(String device, int baud); 112 113 /** 114 * <p>void serialClose (int fd);</p> 115 * 116 * <p> 117 * Closes the device identified by the file descriptor given. 118 * </p> 119 * @see <a 120 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 121 * @param fd <p> 122 * The file descriptor of the serial port. 123 * </p> 124 */ 125 public synchronized static native void serialClose(int fd); 126 127 /** 128 * <h1>void serialFlush (int fd);</h1> 129 * 130 * <p>This discards all data received, or waiting to be send down the given device.</p> 131 * 132 * @see <a 133 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 134 * @param fd The file descriptor of the serial port. 135 */ 136 public synchronized static native void serialFlush(int fd); 137 138 /** 139 * <p>void serialPutByte (int fd, unsigned char c);</p> 140 * 141 * <p>Sends the single byte to the serial device identified by the given file descriptor.</p> 142 * 143 * @see <a 144 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 145 * @param fd The file descriptor of the serial port. 146 * @param data The byte to transmit to the serial port. 147 */ 148 public synchronized static native void serialPutByte(int fd, byte data); 149 150 /** 151 * <p>void serialPutchar (int fd, char c);</p> 152 * 153 * <p>Sends a single character () to the serial device identified by the given file descriptor.</p> 154 * 155 * @deprecated Use the serialPutByte() method instead. 156 * 157 * @see <a 158 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 159 * @param fd The file descriptor of the serial port. 160 * @param data The byte to transmit to the serial port. 161 */ 162 @Deprecated 163 public synchronized static void serialPutchar(int fd, char data){ 164 serialPutByte(fd, (byte)data); 165 } 166 167 /** 168 * <p>void serialPutBytes (int fd, byte[] data);</p> 169 * 170 * <p>Sends any array of bytes to the serial device identified by the given file descriptor.</p> 171 * 172 * @see <a 173 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 174 * @param fd The file descriptor of the serial port. 175 * @param data The byte array to transmit to the serial port. 176 * @param length The number of bytes from the byte array to transmit to the serial port. 177 */ 178 public synchronized static native void serialPutBytes(int fd, byte[] data, int length); 179 180 /** 181 * <p>void serialPutBytes (int fd, byte[] data);</p> 182 * 183 * <p>Sends any array of bytes to the serial device identified by the given file descriptor.</p> 184 * 185 * @see <a 186 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 187 * @param fd The file descriptor of the serial port. 188 * @param data The byte array to transmit to the serial port. 189 */ 190 public synchronized static void serialPutBytes(int fd, byte ... data){ 191 serialPutBytes(fd, data, data.length); 192 } 193 194 /** 195 * <p>void serialPuts (int fd, char *s);</p> 196 * 197 * <p>Sends the nul-terminated string to the serial device identified by the given file descriptor.</p> 198 * 199 * <p>(ATTENTION: the 'data' argument can only be a maximum of 1024 characters.)</p> 200 * 201 * @see <a 202 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 203 * @param fd The file descriptor of the serial port. 204 * @param data The data string to transmit to the serial port. 205 */ 206 public synchronized static native void serialPuts(int fd, String data); 207 208 /** 209 * <p>void serialPuts (int fd, String data, String...arguments);</p> 210 * 211 * <p> 212 * Sends the nul-terminated formatted string to the serial device identified by the given file 213 * descriptor. 214 * </p> 215 * 216 * <p>(ATTENTION: the 'data' argument can only be a maximum of 1024 characters.)</p> 217 * 218 * @see <a 219 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 220 * @param fd The file descriptor of the serial port. 221 * @param data The formatted data string to transmit to the serial port. 222 * @param args Arguments to the format string. 223 */ 224 public synchronized static void serialPuts(int fd, String data, String... args) { 225 serialPuts(fd, String.format(data, (Object[]) args)); 226 } 227 228 /** 229 * <p>int serialDataAvail (int fd);</p> 230 * 231 * Returns the number of characters available for reading, or -1 for any error condition, in 232 * which case errno will be set appropriately. 233 * 234 * @see <a 235 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 236 * @param fd The file descriptor of the serial port. 237 * @return Returns the number of characters available for reading, or -1 for any error 238 * condition, in which case errno will be set appropriately. 239 */ 240 public synchronized static native int serialDataAvail(int fd); 241 242 /** 243 * <p>byte serialGetByte (int fd);</p> 244 * 245 * <p>Returns the next byte available on the serial device. This call will block for up to 10 246 * seconds if no data is available (when it will return -1)</p> 247 * 248 * @see <a 249 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 250 * @param fd The file descriptor of the serial port. 251 * @return Returns the next byte available on the serial device. This call will block for 252 * up to 10 seconds if no data is available (when it will return NULL) 253 */ 254 public synchronized static native byte serialGetByte(int fd); 255 256 /** 257 * <p>int serialGetBytes (int fd, int length);</p> 258 * 259 * <p>Returns the length of bytes available on the serial device.</p> 260 * 261 * @see <a 262 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 263 * @param fd The file descriptor of the serial port. 264 * @param length The number of bytes to get from the serial port. This number must not be higher than the number of available bytes. 265 * @return Returns the length of byte available on the serial device. 266 */ 267 public synchronized static native byte[] serialGetBytes(int fd, int length); 268 269 /** 270 * <p>int serialGetAvailableBytes (int fd);</p> 271 * 272 * <p>Returns on array of bytes currently available on the serial device.</p> 273 * 274 * @see <a 275 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 276 * @param fd The file descriptor of the serial port. 277 * @return Returns the current bytes available on the serial device. 278 */ 279 public synchronized static native byte[] serialGetAvailableBytes(int fd); 280 281 /** 282 * <p>int serialGetchar (int fd);</p> 283 * 284 * <p>Returns the next byte available on the serial device. This call will block for up to 10 285 * seconds if no data is available (when it will return -1)</p> 286 * 287 * @deprecated Use the serialGetByte() method instead. 288 * 289 * @see <a 290 * href="http://wiringpi.com/reference/serial-library/">http://wiringpi.com/reference/serial-library/</a> 291 * @param fd The file descriptor of the serial port. 292 * @return Returns the next byte available on the serial device. This call will block for 293 * up to 10 seconds if no data is available (when it will return -1) 294 */ 295 @Deprecated 296 public synchronized static native int serialGetchar(int fd); 297 298}