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:  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
031import com.pi4j.util.NativeLibraryLoader;
032
033/**
034 * <p>
035 * WiringPi includes a simplified serial port handling library. It can use the on-board serial port,
036 * or any USB serial device with no special distinctions between them. You just specify the device
037 * name in the initial open function.
038 * </p>
039 * 
040 * <p>
041 * Note: The file descriptor (fd) returned is a standard Linux filehandle. You can use the standard
042 * read(), write(), etc. system calls on this filehandle as required. E.g. you may wish to write a
043 * larger block of binary data where the serialPutchar() or serialPuts() function may not be the
044 * most appropriate function to use, in which case, you can use write() to send the data.
045 * </p>
046 * 
047 * <p>
048 * Before using the Pi4J library, you need to ensure that the Java VM in configured with access to
049 * the following system libraries:
050 * <ul>
051 * <li>pi4j</li>
052 * <li>wiringPi</li>
053 * </ul>
054 * <blockquote> This library depends on the wiringPi native system library.</br> (developed by
055 * Gordon Henderson @ <a href="https://projects.drogon.net/">https://projects.drogon.net/</a>)
056 * </blockquote>
057 * </p>
058 * 
059 * @see <a href="http://www.pi4j.com/">http://www.pi4j.com/</a>
060 * @see <a
061 *      href="https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/">https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/</a>
062 * @author Robert Savage (<a
063 *         href="http://www.savagehomeautomation.com">http://www.savagehomeautomation.com</a>)
064 */
065public class Serial {
066
067    /**
068     * The default hardware COM port provided via the Raspberry Pi GPIO header.
069     * 
070     * @see #serialOpen(String,int)
071     */
072    public static final String DEFAULT_COM_PORT = "/dev/ttyAMA0";
073
074    // private constructor 
075    private Serial() {
076        // forbid object construction 
077    }
078    
079    static {
080        // Load the platform library
081        NativeLibraryLoader.load("pi4j", "libpi4j.so");
082    }
083
084    /**
085     * <p>int serialOpen (char *device, int baud);</p>
086     * 
087     * <p>
088     * This opens and initializes the serial device and sets the baud rate. It sets the port into
089     * raw mode (character at a time and no translations), and sets the read timeout to 10 seconds.
090     * The return value is the file descriptor or -1 for any error, in which case errno will be set
091     * as appropriate.
092     * </p>
093     * 
094     * <p>
095     * (ATTENTION: the 'device' argument can only be a maximum of 128 characters.)
096     * </p>
097     * 
098     * @see #DEFAULT_COM_PORT
099     * @see <a
100     *      href="https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/">https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/</a>
101     * 
102     * @param device The device address of the serial port to access. You can use constant
103     *            'DEFAULT_COM_PORT' if you wish to access the default serial port provided via the
104     *            GPIO header.
105     * @param baud The baud rate to use with the serial port.
106     * @return The return value is the file descriptor or -1 for any error, in which case errno will
107     *         be set as appropriate.
108     */
109    public static native int serialOpen(String device, int baud);
110
111    /**
112     * <p>void serialClose (int fd);</p>
113     * 
114     * <p>
115     * Closes the device identified by the file descriptor given.
116     * </p>
117     * @see <a
118     *      href="https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/">https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/</a>
119     * @param fd <p>
120     *            The file descriptor of the serial port.
121     *            </p>
122     */
123    public static native void serialClose(int fd);
124
125    /**
126     * <h1>void serialFlush (int fd);</h1>
127     * 
128     * <p>This discards all data received, or waiting to be send down the given device.</p>
129     * 
130     * @see <a
131     *      href="https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/">https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/</a>
132     * @param fd The file descriptor of the serial port.
133     */
134    public static native void serialFlush(int fd);
135
136    /**
137     * <p>void serialPutchar (int fd, unsigned char c);</p>
138     * 
139     * <p>Sends the single byte to the serial device identified by the given file descriptor.</p>
140     * 
141     * @see <a
142     *      href="https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/">https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/</a>
143     * @param fd The file descriptor of the serial port.
144     * @param data The character to transmit to the serial port.
145     */
146    public static native void serialPutchar(int fd, char data);
147
148    /**
149     * <p>void serialPuts (int fd, char *s);</p>
150     * 
151     * <p>Sends the nul-terminated string to the serial device identified by the given file descriptor.</p>
152     * 
153     * <p>(ATTENTION: the 'data' argument can only be a maximum of 1024 characters.)</p>
154     * 
155     * @see <a
156     *      href="https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/">https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/</a>
157     * @param fd The file descriptor of the serial port.
158     * @param data The data string to transmit to the serial port.
159     */
160    public static native void serialPuts(int fd, String data);
161
162    /**
163     * <p>void serialPuts (int fd, String data, String...arguments);</p>
164     * 
165     * <p>
166     * Sends the nul-terminated formatted string to the serial device identified by the given file
167     * descriptor.
168     * </p>
169     * 
170     * <p>(ATTENTION: the 'data' argument can only be a maximum of 1024 characters.)</p>
171     * 
172     * @see <a
173     *      href="https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/">https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/</a>
174     * @param fd The file descriptor of the serial port.
175     * @param data The formatted data string to transmit to the serial port.
176     * @param args Arguments to the format string.
177     */
178    public static void serialPuts(int fd, String data, String... args) {
179        serialPuts(fd, String.format(data, (Object[]) args));
180    }
181
182    /**
183     * <p>int serialDataAvail (int fd);</p>
184     * 
185     * Returns the number of characters available for reading, or -1 for any error condition, in
186     * which case errno will be set appropriately.
187     * 
188     * @see <a
189     *      href="https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/">https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/</a>
190     * @param fd The file descriptor of the serial port.
191     * @return Returns the number of characters available for reading, or -1 for any error
192     *         condition, in which case errno will be set appropriately.
193     */
194    public static native int serialDataAvail(int fd);
195
196    /**
197     * <p>int serialGetchar (int fd);</p>
198     * 
199     * <p>Returns the next character available on the serial device. This call will block for up to 10
200     * seconds if no data is available (when it will return -1)</p>
201     * 
202     * @see <a
203     *      href="https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/">https://projects.drogon.net/raspberry-pi/wiringpi/serial-library/</a>
204     * @param fd The file descriptor of the serial port.
205     * @return Returns the next character available on the serial device. This call will block for
206     *         up to 10 seconds if no data is available (when it will return -1)
207     */
208    public static native int serialGetchar(int fd);
209}