001package com.pi4j.wiringpi;
002
003/*
004 * #%L
005 * **********************************************************************
006 * ORGANIZATION  :  Pi4J
007 * PROJECT       :  Pi4J :: Java Library (Core)
008 * FILENAME      :  GpioUtil.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 - 2021 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>This utility class is provided to export, unexport, and manipulate pin direction.</p>
037 *
038 * <p>
039 * Before using the Pi4J library, you need to ensure that the Java VM in configured with access to
040 * the following system libraries:
041 * <ul>
042 * <li>pi4j</li>
043 * <li>wiringPi</li>
044 * </ul>
045 * <blockquote> This library depends on the wiringPi native system library.</br> (developed by
046 * Gordon Henderson @ <a href="http://wiringpi.com/">http://wiringpi.com/</a>)
047 * </blockquote>
048 * </p>
049 *
050 * @see <a href="https://www.pi4j.com/">https://www.pi4j.com/</a>
051 * @see <a
052 *      href="http://wiringpi.com/">http://wiringpi.com/</a>
053 * @author Robert Savage (<a
054 *         href="http://www.savagehomeautomation.com">http://www.savagehomeautomation.com</a>)
055 */
056public class GpioUtil {
057    // private constructor
058    private GpioUtil() {
059        // forbid object construction
060    }
061
062    static {
063        // Load the platform library
064        NativeLibraryLoader.load("libpi4j.so", "pi4j");
065    }
066
067    /**
068     * <p>GPIO PIN DIRECTION</p>
069     * <p>
070     * GPIO pin constant for IN direction for reading pin states
071     * </p>
072     *
073     * @see #export(int,int)
074     * @see #setDirection(int,int)
075     * @see #getDirection(int)
076     */
077    public static final int DIRECTION_IN = 0;
078
079    /**
080     * <p>GPIO PIN DIRECTION</p>
081     * <p>
082     * GPIO pin constant for OUT direction for writing digital pin states (0/1).
083     * </p>
084     *
085     * @see #export(int,int)
086     * @see #setDirection(int,int)
087     * @see #getDirection(int)
088     */
089    public static final int DIRECTION_OUT = 1;
090
091    /**
092     * <p>GPIO PIN DIRECTION</p>
093     * <p>
094     * GPIO pin constant for OUT direction with an initial default HIGH value for writing digital pin states (0/1).
095     * </p>
096     *
097     * @see #export(int,int)
098     * @see #setDirection(int,int)
099     * @see #getDirection(int)
100     */
101    public static final int DIRECTION_HIGH = 2;
102
103    /**
104     * <p>GPIO PIN DIRECTION</p>
105     * <p>
106     * GPIO pin constant for OUT direction with an initial default LOW value for writing digital pin states (0/1).
107     * </p>
108     *
109     * @see #export(int,int)
110     * @see #setDirection(int,int)
111     * @see #getDirection(int)
112     */
113    public static final int DIRECTION_LOW= 3;
114
115    /**
116     * <p>GPIO PIN EDGE DETECTION</p>
117     * <p>
118     * This constant is provided as an edge detection mode for use with the 'edge' method. This
119     * constants instructs the edge detection to be disabled.
120     * </p>
121     *
122     * @see #setEdgeDetection(int,int)
123     */
124    public static final int EDGE_NONE = 0;
125
126    /**
127     * <p>GPIO PIN EDGE DETECTION</p>
128     * <p>
129     * This constant is provided as an edge detection mode for use with the 'edge' method. This
130     * constants instructs the edge detection to only look for rising and falling pins states; pins
131     * changing from LOW to HIGH or HIGH to LOW.
132     * </p>
133     *
134     * @see #setEdgeDetection(int,int)
135     */
136    public static final int EDGE_BOTH = 1;
137
138    /**
139     * <p>GPIO PIN EDGE DETECTION</p>
140     * <p>
141     * This constant is provided as an edge detection mode for use with the 'edge' method. This
142     * constants instructs the edge detection to only look for rising pins states; pins changing
143     * from LOW to HIGH.
144     * </p>
145     *
146     * @see #setEdgeDetection(int,int)
147     */
148    public static final int EDGE_RISING = 2;
149
150    /**
151     * <p>GPIO PIN EDGE DETECTION</p>
152     * <p>
153     * This constant is provided as an edge detection mode for use with the 'edge' method. This
154     * constants instructs the edge detection to only look for falling pins states; pins changing
155     * from HIGH to LOW.
156     * </p>
157     *
158     * @see #setEdgeDetection(int,int)
159     */
160    public static final int EDGE_FALLING = 3;
161
162    /**
163     * <p>
164     * This method will export the selected GPIO pin.
165     * </p>
166     * <p>
167     * This method required root permissions access.
168     * </p>
169     *
170     * @see #DIRECTION_IN
171     * @see #DIRECTION_OUT
172     *
173     * @param pin GPIO pin number (not header pin number; not wiringPi pin number)
174     * @param direction pin direction
175     */
176    public static native void export(int pin, int direction) throws RuntimeException;
177
178    /**
179     * <p>This method will unexport the selected GPIO pin.</p>
180     * <p>This method required root permissions access.</p>
181     *
182     * @param pin GPIO pin number (not header pin number; not wiringPi pin number)
183     */
184    public static native void unexport(int pin) throws RuntimeException;
185
186    /**
187     * <p>This method determines if the requested GPIO pin is already exported.</p>
188     *
189     * @param pin GPIO pin number (not header pin number; not wiringPi pin number)
190     * @return A return value of '0' represents that the pin is not exported. </br> A return value
191     *         of '1' represents that the pin is exported.
192     */
193    public static native boolean isExported(int pin) throws RuntimeException;
194
195    /**
196     * <p>This method will set the selected GPIO pin's edge detection. Edge detection instructs when
197     * the hardware GPIO changes raise interrupts on the system.</p>
198     * <p>
199     * NOTE: Calling this method will automatically export the pin and set the pin direction to
200     * INPUT.</br> This method required root permissions access.
201     * </p>
202     *
203     * @see #EDGE_NONE
204     * @see #EDGE_BOTH
205     * @see #EDGE_RISING
206     * @see #EDGE_FALLING
207     *
208     * @param pin GPIO pin number (not header pin number; not wiringPi pin number)
209     * @param edge The edge condition to detect: none, rising, falling, or both. </br>The following
210     *            constants are provided for use with this parameter:
211     *            <ul>
212     *            <li>EDGE_NONE</li>
213     *            <li>EDGE_BOTH</li>
214     *            <li>EDGE_RISING</li>
215     *            <li>EDGE_FALLING</li>
216     *            </ul>
217     * @return A return value of '0' represents success. Errors are returned as negative numbers.
218     */
219    public static native boolean setEdgeDetection(int pin, int edge) throws RuntimeException;
220
221    /**
222     * <p>This method will get the selected GPIO pin's edge detection setting. Edge detection instructs
223     * when the hardware GPIO changes raise interrupts on the system.
224     * </p>
225     *
226     * @see #EDGE_NONE
227     * @see #EDGE_BOTH
228     * @see #EDGE_RISING
229     * @see #EDGE_FALLING
230     *
231     * @param pin GPIO pin number (not header pin number; not wiringPi pin number)
232     * @return The edge condition detected on the selected pin: none, rising, falling, or both.
233     *         </br>The following constants are provided for use with this parameter:
234     *         <ul>
235     *         <li>EDGE_NONE</li>
236     *         <li>EDGE_BOTH</li>
237     *         <li>EDGE_RISING</li>
238     *         <li>EDGE_FALLING</li>
239     *         </ul>
240     */
241    public static native int getEdgeDetection(int pin) throws RuntimeException;
242
243    /**
244     * <p>This method will set the selected GPIO pin's export direction.</p>
245     *
246     * @see #DIRECTION_IN
247     * @see #DIRECTION_OUT
248     *
249     * @param pin GPIO pin number (not header pin number; not wiringPi pin number)
250     * @param direction
251     *            The export direction to apply: IN, OUT. </br>The following constants are provided
252     *            for use with this parameter:
253     *            <ul>
254     *            <li>DIRECTION_IN</li>
255     *            <li>DIRECTION_OUT</li>
256     *            </ul>
257     * @return A return value of '0' represents success. Errors are returned as negative numbers.
258     */
259    public static native boolean setDirection(int pin, int direction) throws RuntimeException;
260
261    /**
262     * <p>
263     * This method will get the selected GPIO pin's export direction.
264     * </p>
265     *
266     * @see #DIRECTION_IN
267     * @see #DIRECTION_OUT
268     *
269     * @param pin GPIO pin number (not header pin number; not wiringPi pin number)
270     * @return The GPIO pin's configured export direction is returned: IN (0), OUT (1). </br>The
271     *         following constants are provided for use with this parameter:
272     *         <ul>
273     *         <li>DIRECTION_IN</li>
274     *         <li>DIRECTION_OUT</li>
275     *         </ul>
276     */
277    public static native int getDirection(int pin) throws RuntimeException;
278
279    /**
280     * <p>
281     * This method will return a value of '1' if the pin is supported
282     * </p>
283     *
284     * @param pin pin number
285     * @return '1' is the pin is supported, else '0'
286     */
287    public static native int isPinSupported(int pin) throws RuntimeException;
288
289    /**
290     * <p>
291     * This method will return a value of '1' if Privileged access is required.
292     * This method will return a value of '0' if Privileged access is NOT required.
293     * Privileged access is required if any of the the following conditions are not met:
294     *    - You are running with Linux kernel version 4.1.7 or greater
295     *    - The Device Tree is enabled
296     *    - The 'bcm2835_gpiomem' kernel module loaded.
297     *    - Udev rules are configured to permit write access to '/sys/class/gpio/**'
298     *
299     * </p>
300     *
301     * @return 'true' if privileged access is required; else returns 'false'.
302     */
303    public static native boolean isPrivilegedAccessRequired() throws RuntimeException;
304
305    /**
306     * <p>
307     *  This method is used to enable non-privileged access to the GPIO pins on
308     *  to system.  This method will throw a runtime exception if privileged access
309     *  is required.  You can test for required access using the 'isPrivilegedAccessRequired()'
310     *  method.
311     *
312     *  Please note when non-privileged access is enabled, you will not be able to
313     *  use any hardware PWM or CLOCK functions.
314     * </p>
315     */
316    public static native void enableNonPrivilegedAccess() throws RuntimeException;
317}