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}