Package com.pi4j.wiringpi

Class Gpio

  • public class Gpio
extends Object

    WiringPi GPIO Control

    Some of the functions in the WiringPi library are designed to mimic those in the Arduino Wiring system. They are relatively easy to use and should present no problems for anyone used to the Arduino system, or C programming in-general.

    The main difference is that unlike the Arduino system, the main loop of the program is not provided for you and you need to write it yourself. This is often desirable in a Linux system anyway as it can give you access to command-line arguments and so on. See the examples page for some simple examples and a Makefile to use.

    Before using the Pi4J library, you need to ensure that the Java VM is configured with access to the following system libraries:

    • pi4j
    • wiringPi
    This library depends on the wiringPi native system library. (developed by Gordon Henderson @ http://wiringpi.com/)
    Author:
    Robert Savage (http://www.savagehomeautomation.com)
    See Also:
    https://pi4j.com/, http://wiringpi.com/reference/

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int ALT0
      GPIO constant to define pin ALT modes
      static int ALT1  
      static int ALT2  
      static int ALT3  
      static int ALT4  
      static int ALT5  
      static int GPIO_CLOCK
      GPIO pin constant for GPIO_CLOCK pin mode
      static int HIGH
      GPIO pin state constant for HIGH/ON/+3.3VDC
      static int INPUT
      GPIO pin constant for INPUT direction for reading pin states
      static int INT_EDGE_BOTH  
      static int INT_EDGE_FALLING  
      static int INT_EDGE_RISING  
      static int INT_EDGE_SETUP
      GPIO constants to define interrupt levels
      static int LOW
      GPIO pin state constant for LOW/OFF/0VDC
      static int NUM_PINS
      The total number of GPIO pins available in the WiringPi library.
      static int OUTPUT
      GPIO pin constant for OUTPUT direction for writing digital pin states (0/1)
      static int PUD_DOWN
      GPIO constant to enable the pull-down resistor mode on a GPIO pin.
      static int PUD_OFF
      GPIO constant to disable the pull-up or pull-down resistor mode on a GPIO pin.
      static int PUD_UP
      GPIO constant to enable the pull-up resistor mode on a GPIO pin.
      static int PWM_MODE_BAL
      GPIO constant to define PWM balanced mode.
      static int PWM_MODE_MS
      GPIO constant to define PWM mark:space mode.
      static int PWM_OUTPUT
      GPIO pin constant for PWM_OUTPUT direction for writing analog pin states

    • Method Detail

      • wiringPiSetup

        public static int wiringPiSetup()

        Setup Functions

        This initializes the wiringPi system and assumes that the calling program is going to be using the wiringPi pin numbering scheme. This is a simplified numbering scheme which provides a mapping from virtual pin numbers 0 through 16 to the real underlying Broadcom GPIO pin numbers. See the pins page for a table which maps the wiringPi pin number to the Broadcom GPIO pin number to the physical location on the edge connector.

        This function needs to be called with root privileges.

        Returns:
        If this function returns a value of '-1' then an error has occurred and the initialization of the GPIO has failed. A return value of '0' indicates a successful GPIO initialization.
        See Also:
        http://wiringpi.com/reference/setup/

      • wiringPiSetupSys

        public static int wiringPiSetupSys()

        Setup Functions

        This initializes the wiringPi system but uses the /sys/class/gpio interface rather than accessing the hardware directly. This can be called as a non-root user provided the GPIO pins have been exported before-hand using the gpio program. Pin number in this mode is the native Broadcom GPIO numbers.

          Note:
        In this mode you can only use the pins which have been exported via the /sys/class/gpio interface. You must export these pins before you call your program. You can do this in a separate shell-script, or by using the system() function from inside your program.

        Also note that some functions (noted below) have no effect when using this mode as they're not currently possible to action unless called with root privileges.

        Returns:
        If this function returns a value of '-1' then an error has occurred and the initialization of the GPIO has failed. A return value of '0' indicates a successful GPIO initialization.
        See Also:
        http://wiringpi.com/reference/setup/

      • wiringPiSetupGpio

        public static int wiringPiSetupGpio()

        Setup Functions

        This setup function is identical to wiringPiSetup(), however it allows the calling programs to use the Broadcom GPIO pin numbers directly with no re-mapping.

        This function needs to be called with root privileges.

        Returns:
        If this function returns a value of '-1' then an error has occurred and the initialization of the GPIO has failed. A return value of '0' indicates a successful GPIO initialization.
        See Also:
        http://wiringpi.com/reference/setup/

      • wiringPiSetupPhys

        public static int wiringPiSetupPhys()

        Setup Functions

        This setup function is identical to wiringPiSetup(), however it allows the calling programs to use the physical header pin numbers on the board GPIO header.

        This function needs to be called with root privileges.

        Returns:
        If this function returns a value of '-1' then an error has occurred and the initialization of the GPIO has failed. A return value of '0' indicates a successful GPIO initialization.
        See Also:
        http://wiringpi.com/reference/setup/

      • pinMode

        public static void pinMode​(int pin,
                           int mode)

        Core Functions

        This sets the mode of a pin to either INPUT, OUTPUT, PWM_OUTPUT or GPIO_CLOCK. Note that only wiringPi pin 1 (BCM_GPIO 18) supports PWM output and only wiringPi pin 7 (BCM_GPIO 4) supports CLOCK output modes.

        This function has no effect when in Sys mode.

        Parameters:
        pin - The GPIO pin number. (Depending on how wiringPi was initialized, this may be the wiringPi pin number, the Broadcom GPIO pin number, or the board header pin number.)
        mode - Pin mode/direction to apply to the selected pin.The following constants are provided for use with this parameter:
        • INPUT
        • OUTPUT
        • PWM_OUTPUT
        • GPIO_CLOCK
        See Also:
        INPUT, OUTPUT, PWM_OUTPUT, http://wiringpi.com/reference/core-functions/

      • pinModeAlt

        public static void pinModeAlt​(int pin,
                              int mode)

        Core Functions

        This method is an undocumented method in the WiringPi library that allows you to configure any PIN to any MODE.

        Parameters:
        pin - pin number
        mode - Pin mode/direction to apply to the selected pin.The following constants are provided for use with this parameter:
        • INPUT
        • OUTPUT
        • ALT0
        • ALT1
        • ALT2
        • ALT3
        • ALT4
        • ALT5

      • pullUpDnControl

        public static void pullUpDnControl​(int pin,
                                   int pud)

        Core Functions

        This sets the pull-up or pull-down resistor mode on the given pin, which should be set as an input. Unlike the Arduino, the BCM2835 has both pull-up an down internal resistors. The parameter pud should be; PUD_OFF, (no pull up/down), PUD_DOWN (pull to ground) or PUD_UP (pull to 3.3v) This function has no effect when in Sys mode (see above) If you need to activate a pull-up/pull-down, then you can do it with the gpio program in a script before you start your program.
        Parameters:
        pin - The GPIO pin number. (Depending on how wiringPi was initialized, this may be the wiringPi pin number or the Broadcom GPIO pin number.)
        pud - Pull Up/Down internal pin resistance.The following constants are provided for use with this parameter:
        • PUD_OFF
        • PUD_DOWN
        • PUD_UP
        See Also:
        PUD_OFF, PUD_DOWN, PUD_UP, http://wiringpi.com/reference/core-functions/

      • digitalWrite

        public static void digitalWrite​(int pin,
                                int value)

        Core Functions

        Writes the value HIGH or LOW (1 or 0) to the given pin which must have been previously set as an output. WiringPi treats any non-zero number as HIGH, however 0 is the only representation of LOW.

        Parameters:
        pin - The GPIO pin number. (Depending on how wiringPi was initialized, this may be the wiringPi pin number or the Broadcom GPIO pin number.)
        value - The pin state to write to the selected pin.The following constants are provided for use with this parameter:
        • HIGH
        • LOW
        See Also:
        HIGH, LOW, http://wiringpi.com/reference/core-functions/

      • digitalWrite

        public static void digitalWrite​(int pin,
                                boolean value)

        Core Functions

        Writes the value HIGH or LOW ('true' or 'false') to the given pin which must have been previously set as an output.

        Parameters:
        pin - The GPIO pin number. (Depending on how wiringPi was initialized, this may be the wiringPi pin number or the Broadcom GPIO pin number.)
        value - The pin boolean state to write to the selected pin.
        See Also:
        http://wiringpi.com/reference/core-functions/

      • pwmWrite

        public static void pwmWrite​(int pin,
                            int value)

        Core Functions

        Writes the value to the PWM register for the given pin. The value must be between 0 and 1024. (Again, note that only pin 1 supports PWM: )

        This function has no effect when in Sys mode

        Parameters:
        pin - The GPIO pin number. (Depending on how wiringPi was initialized, this may be the wiringPi pin number or the Broadcom GPIO pin number.)
        value - The analog value to write to the selected pin. (The value must be between 0 and 1024.)
        See Also:
        http://wiringpi.com/reference/core-functions/

      • digitalRead

        public static int digitalRead​(int pin)

        Core Functions

        This function returns the value read at the given pin. It will be HIGH or LOW (1 or 0) depending on the logic level at the pin.

        Parameters:
        pin - The GPIO pin number. (Depending on how wiringPi was initialized, this may be the wiringPi pin number or the Broadcom GPIO pin number.)
        Returns:
        If the selected GPIO pin is HIGH, then a value of '1' is returned; else of the pin is LOW, then a value of '0' is returned.
        See Also:
        http://wiringpi.com/reference/core-functions/

      • analogRead

        public static int analogRead​(int pin)

        Core Functions

        This returns the value read on the supplied analog input pin. You will need to register additional analog modules to enable this function for devices such as the Gertboard, quick2Wire analog board, etc.

        Parameters:
        pin - The GPIO pin number. (Depending on how wiringPi was initialized, this may be the wiringPi pin number or the Broadcom GPIO pin number.)
        Returns:
        Analog value of selected pin.
        See Also:
        http://wiringpi.com/reference/core-functions/

      • analogWrite

        public static void analogWrite​(int pin,
                               int value)

        Core Functions

        This writes the given value to the supplied analog pin. You will need to register additional analog modules to enable this function for devices such as the Gertboard.

        Parameters:
        pin - The GPIO pin number. (Depending on how wiringPi was initialized, this may be the wiringPi pin number or the Broadcom GPIO pin number.)
        value - The analog value to assign to the selected pin number.
        See Also:
        http://wiringpi.com/reference/core-functions/

      • delay

        public static void delay​(long howLong)

        Timing Functions

        This causes program execution to pause for at least howLong milliseconds. Due to the multi-tasking nature of Linux it could be longer. Note that the maximum delay is an unsigned 32-bit integer or approximately 49 days.

        Parameters:
        howLong - The number of milliseconds to delay the main program thread.
        See Also:
        http://wiringpi.com/reference/timing/

      • millis

        public static long millis()

        Timing Functions

        This returns a number representing the number if milliseconds since your program called one of the wiringPiSetup functions. It returns an unsigned 32-bit number which wraps after 49 days.

        Returns:
        The number if milliseconds since the program called one of the wiringPi setup functions.
        See Also:
        http://wiringpi.com/reference/timing/

      • micros

        public static long micros()

        Timing Functions

        This returns a number representing the number of microseconds since your program called one of the wiringPiSetup functions. It returns an unsigned 32-bit number which wraps after approximately 71 minutes.

        Returns:
        The number if microseconds since the program called one of the wiringPi setup functions.
        See Also:
        http://wiringpi.com/reference/timing/

      • delayMicroseconds

        public static void delayMicroseconds​(long howLong)

        Timing Functions

        This causes program execution to pause for at least howLong microseconds. Due to the multi-tasking nature of Linux it could be longer. Note that the maximum delay is an unsigned 32-bit integer microseconds or approximately 71 minutes. Delays under 100 microseconds are timed using a hard-coded loop continually polling the system time, Delays over 100 microseconds are done using the system nanosleep() function – You may need to consider the implications of very short delays on the overall performance of the system, especially if using threads.

        Parameters:
        howLong - The number of microseconds to delay the main program thread.
        See Also:
        http://wiringpi.com/reference/timing/

      • piHiPri

        public static int piHiPri​(int priority)

        Priority, Interrupt and Thread Functions

        This attempts to shift your program (or thread in a multi-threaded program) to a higher priority and enables a real-time scheduling. The priority parameter should be from 0 (the Default) to 99 (the maximum). This won't make your program go any faster, but it will give it a bigger slice of time when other programs are running. The priority parameter works relative to others and so you can make one program priority 1 and another priority 2 and it will have the same effect as setting one to 10 and the other to 90 (as long as no other programs are running with elevated priorities)

        The return value is 0 for success and -1 for error. If an error is returned, the program should then consult the errno global variable, as per the usual conventions.

        Note: Only programs running as root can change their priority. If called from a non-root program then nothing happens.

        Parameters:
        priority - The priority parameter should be from 0 (the Default) to 99 (the maximum)
        Returns:
        The return value is 0 for success and -1 for error. If an error is returned, the program should then consult the errno global variable, as per the usual conventions.
        See Also:
        http://wiringpi.com/reference/priority-interrupts-and-threads/

      • waitForInterrupt

        public static int waitForInterrupt​(int pin,
                                   int timeout)
        Deprecated.
        Note: Jan 2013: The waitForInterrupt() function is deprecated – you should use the newer and easier to use wiringPiISR() function.

        Priority, Interrupt and Thread Functions

        With a newer kernel patched with the GPIO interrupt handling code, you can now wait for an interrupt in your program. This frees up the processor to do other tasks while you're waiting for that interrupt. The GPIO can be set to interrupt on a rising, falling or both edges of the incoming signal.

        int waitForInterrupt (int pin, int timeOut)

        When called, it will wait for an interrupt event to happen on that pin and your program will be stalled. The timeOut parameter is given in milliseconds, or can be -1 which means to wait forever.

        Before you call waitForInterrupt, you must first initialize the GPIO pin and at present the only way to do this is to use the gpio program, either in a script, or using the system() call from inside your program.

        e.g. We want to wait for a falling-edge interrupt on GPIO pin 0, so to setup the hardware, we need to run: 

         gpio edge 0 falling

        Parameters:
        pin - The GPIO pin number. (Depending on how wiringPi was initialized, this may be the wiringPi pin number or the Broadcom GPIO pin number.)
        timeout - The number of milliseconds to wait before timing out. A value of '-1' will disable the timeout.
        Returns:
        The return value is -1 if an error occurred (and errno will be set appropriately), 0 if it timed out, or 1 on a successful interrupt event.
        See Also:
        http://wiringpi.com/reference/priority-interrupts-and-threads/

      • wiringPiISR

        public static int wiringPiISR​(int pin,
                              int edgeType,
                              GpioInterruptCallback callback)

        Priority, Interrupt and Thread Functions

        This function registers a function to received interrupts on the specified pin. The edgeType parameter is either INT_EDGE_FALLING, INT_EDGE_RISING, INT_EDGE_BOTH or INT_EDGE_SETUP. If it is INT_EDGE_SETUP then no initialisation of the pin will happen – it’s assumed that you have already setup the pin elsewhere (e.g. with the gpio program), but if you specify one of the other types, then the pin will be exported and initialised as specified. This is accomplished via a suitable call to the gpio utility program, so it need to be available

        The pin number is supplied in the current mode – native wiringPi, BCM_GPIO, physical or Sys modes.

        This function will work in any mode, and does not need root privileges to work.

        The function will be called when the interrupt triggers. When it is triggered, it’s cleared in the dispatcher before calling your function, so if a subsequent interrupt fires before you finish your handler, then it won’t be missed. (However it can only track one more interrupt, if more than one interrupt fires while one is being handled then they will be ignored)

        This function is run at a high priority (if the program is run using sudo, or as root) and executes concurrently with the main program. It has full access to all the global variables, open file handles and so on.

        Parameters:
        pin - The GPIO pin number. (Depending on how wiringPi was initialized, this may be the wiringPi pin number or the Broadcom GPIO pin number.)
        edgeType - The type of pin edge event to watch for: INT_EDGE_FALLING, INT_EDGE_RISING, INT_EDGE_BOTH or INT_EDGE_SETUP.
        callback - The callback interface implemented by the consumer. The 'callback' method of this interface will be invoked when the wiringPiISR issues a callback signal.
        Returns:
        The return value is -1 if an error occurred (and errno will be set appropriately), 0 if it timed out, or 1 on a successful interrupt event.
        See Also:
        http://wiringpi.com/reference/priority-interrupts-and-threads/

      • wiringPiClearISR

        public static void wiringPiClearISR​(int pin)
        Clear all WiringPiISR callbacks for this GPIO pin.
        Parameters:
        pin - The GPIO pin number. (Depending on how wiringPi was initialized, this may be the wiringPi pin number or the Broadcom GPIO pin number.)

      • piBoardRev

        public static int piBoardRev()

        [Hardware]

        This method provides the board revision as determined by the wiringPi library.

        Returns:
        The return value represents the major board revision version. A -1 will be returned if the board revision cannot be determined.
        See Also:
        http://wiringpi.com/reference/raspberry-pi-specifics/

      • wpiPinToGpio

        public static int wpiPinToGpio​(int wpiPin)

        [Hardware]

        This method provides the edge GPIO pin number for the requested wiringPi pin number.

        Returns:
        The return value represents the RaspberryPi GPIO (edge) pin number. A -1 will be returned for an invalid pin number.
        See Also:
        http://wiringpi.com/reference/raspberry-pi-specifics/

      • physPinToGpio

        public static int physPinToGpio​(int physPin)

        [Hardware]

        This returns the BCM_GPIO pin number of the supplied physical pin on the board header connector.

        Returns:
        The return value represents the RaspberryPi GPIO (edge) pin number. A -1 will be returned for an invalid pin number.
        See Also:
        http://wiringpi.com/reference/raspberry-pi-specifics/

      • digitalWriteByte

        public static void digitalWriteByte​(int value)

        This writes the 8-bit byte supplied to the first 8 GPIO pins. It’s the fastest way to set all 8 bits at once to a particular value, although it still takes two write operations to the Pi’s GPIO hardware.

        See Also:
        http://wiringpi.com/reference/raspberry-pi-specifics/

      • pwmSetMode

        public static void pwmSetMode​(int mode)

        [PWM]

        The PWM generator can run in 2 modes – balanced and mark:space. The mark:space mode is traditional, however the default mode in the Pi is balanced. You can switch modes by supplying the parameter: PWM_MODE_BAL or PWM_MODE_MS.

        See Also:
        http://wiringpi.com/reference/raspberry-pi-specifics/

      • setPadDrive

        public static void setPadDrive​(int group,
                               int value)

        [Hardware]

        This sets the strength of the pad drivers for a particular group of pins. There are 3 groups of pins and the drive strength is from 0 to 7. Do not use this unless you know what you are doing.

        See Also:
        http://wiringpi.com/reference/raspberry-pi-specifics/