Module com.pi4j.crowpi
Package com.pi4j.crowpi.components

Class ButtonMatrixComponent

java.lang.Object
com.pi4j.crowpi.components.Component
com.pi4j.crowpi.components.ButtonMatrixComponent
public class ButtonMatrixComponent extends Component
Implementation of the CrowPi button matrix using GPIO with Pi4J

The button matrix consists of two separate components: - the selectors, one or more GPIO pins which can be pulled LOW to activate a column - the buttons, one or more GPIO pins which can be used to check a button within the currently active column This means that retrieving the state of all buttons requires looping over all buttons with each selector once pulled LOW. To achieve this, the button matrix component uses an internal poller which gets started by default for polling the buttons. This component requires DIP switches 1-1, 1-2, 1-3, 1-4, 1-5, 1-6, 1-7, 1-8 to be on.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final int[]
    DEFAULT_BUTTON_PINS
    Default GPIO pins used as buttons for the button matrix.
    protected static final long
    DEFAULT_POLLER_PERIOD_MS
    Default period in milliseconds of button state poller.
    protected static final int[]
    DEFAULT_SELECTOR_PINS
    Default GPIO pins used as selectors for the button matrix.
    protected static final int[]
    DEFAULT_STATE_MAPPINGS
    Default mapping of button number (= array index) to the respective state index.

    Fields inherited from class com.pi4j.crowpi.components.Component

    logger

  • Constructor Summary

    Constructors
    Constructor
    Description
    ButtonMatrixComponent(com.pi4j.context.Context pi4j)
    Creates a new button matrix component using the default setup.
    ButtonMatrixComponent(com.pi4j.context.Context pi4j, int[] selectorPins, int[] buttonPins, int[] stateMappings, long pollerPeriodMs)
    Creates a new button matrix component with custom selector/button pins, state mapping and poller period.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected static com.pi4j.io.gpio.digital.DigitalInputConfig
    buildDigitalInputConfig(com.pi4j.context.Context pi4j, int address)
    Builds a new DigitalInput configuration for a button matrix button.
    protected static com.pi4j.io.gpio.digital.DigitalOutputConfig
    buildDigitalOutputConfig(com.pi4j.context.Context pi4j, int address)
    Builds a new DigitalOutput configuration for a button matrix selector.
    protected ScheduledFuture<?>
    getPoller()
    Returns the internal scheduled future for the poller thread or null if currently stopped.
    int[]
    getPressedButtons()
    Returns a list of all buttons which were pressed during the last poll cycle.
    ButtonComponent.ButtonState
    getState(int number)
    Returns the state of the button with the given number (starting at 1) during the last poll cycle.
    boolean
    isDown(int number)
    Checks if the button with the given number (starting at 1) was pressed during the last poll cycle.
    boolean
    isUp(int number)
    Checks if the button with the given number (starting at 1) was NOT pressed during the last poll cycle.
    void
    onDown(int number, SimpleEventHandler handler)
    Sets or disables the handler for the onDown of the given button.
    void
    onUp(int number, SimpleEventHandler handler)
    Sets or disables the handler for the onUp of the given button.
    int
    readBlocking()
    Idle-waits until a button is pressed and released and then returns the button number.
    int
    readBlocking(long timeoutMs)
    Idle-waits until a button is pressed and released and then returns the button number.
    void
    startPoller(long pollerPeriodMs)
    (Re-)starts the poller with the desired time period in milliseconds.
    void
    stopPoller()
    Stops the poller immediately, therefore causing the button states to be no longer refreshed.

    Methods inherited from class com.pi4j.crowpi.components.Component

    sleep, triggerSimpleEvent

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DEFAULT_SELECTOR_PINS

      protected static final int[] DEFAULT_SELECTOR_PINS
      Default GPIO pins used as selectors for the button matrix. A selector pin can either be a row or a column and gets pulled low to analyze all the button pins. CrowPi Board Pins: 22, 37, 35, 33 (pins down below are BCM)

    • DEFAULT_BUTTON_PINS

      protected static final int[] DEFAULT_BUTTON_PINS
      Default GPIO pins used as buttons for the button matrix. A button pin does not refer to a single physical button and instead depends on which selector is pulled low. CrowPi Board Pins: 13, 15, 29, 31 (pins down below are BCM)

    • DEFAULT_STATE_MAPPINGS

      protected static final int[] DEFAULT_STATE_MAPPINGS
      Default mapping of button number (= array index) to the respective state index. The state array is represented [selector * buttonCount + button] and the following mapping works for the CrowPi.

    • DEFAULT_POLLER_PERIOD_MS

      protected static final long DEFAULT_POLLER_PERIOD_MS
      Default period in milliseconds of button state poller. The poller will be run in a separate thread and executed every X milliseconds.
      See Also:

  • Constructor Details

    • ButtonMatrixComponent

      public ButtonMatrixComponent(com.pi4j.context.Context pi4j)
      Creates a new button matrix component using the default setup.
      Parameters:
      pi4j - Pi4J context

    • ButtonMatrixComponent

      public ButtonMatrixComponent(com.pi4j.context.Context pi4j, int[] selectorPins, int[] buttonPins, int[] stateMappings, long pollerPeriodMs)
      Creates a new button matrix component with custom selector/button pins, state mapping and poller period.
      Parameters:
      pi4j - Pi4J context
      selectorPins - BCM pins to be used as selectors (digital output)
      buttonPins - BCM pins to be used as buttons (digital input)
      stateMappings - Array of state mappings with same length as total button count
      pollerPeriodMs - Period of poller in milliseconds

  • Method Details

    • startPoller

      public void startPoller(long pollerPeriodMs)
      (Re-)starts the poller with the desired time period in milliseconds. If the poller is already running, it will be cancelled and rescheduled with the given time. The first poll happens immediately in a separate thread and does not get delayed.
      Parameters:
      pollerPeriodMs - Polling period in milliseconds

    • stopPoller

      public void stopPoller()
      Stops the poller immediately, therefore causing the button states to be no longer refreshed. If the poller is already stopped, this method will silently return and do nothing.

    • getPoller

      protected ScheduledFuture<?> getPoller()
      Returns the internal scheduled future for the poller thread or null if currently stopped.
      Returns:
      Active poller instance or null

    • readBlocking

      public int readBlocking()
      Idle-waits until a button is pressed and released and then returns the button number. If more than one button is pressed, the first one based on its state index is taken. This loop will wait 10 milliseconds between each check and waits indefinitely.
      Returns:
      Number of pressed button or -1 if failed

    • readBlocking

      public int readBlocking(long timeoutMs)
      Idle-waits until a button is pressed and released and then returns the button number. If more than one button is pressed, the first one based on its state index is taken. No result will be returned until the button gets released, so it may also timeout while waiting for the button to be released. This loop will wait 10 milliseconds between each check and times out after the given time.
      Parameters:
      timeoutMs - Timeout in milliseconds or 0 for infinite
      Returns:
      Number of pressed button or -1 if failed (e.g. timeout)

    • getPressedButtons

      public int[] getPressedButtons()
      Returns a list of all buttons which were pressed during the last poll cycle. This can be used for building an idle-wait loop until one or more keys are pressed.
      Returns:
      Array of currently pressed buttons

    • getState

      public ButtonComponent.ButtonState getState(int number)
      Returns the state of the button with the given number (starting at 1) during the last poll cycle. Please note that this value will only update while the poller is running.
      Parameters:
      number - Button number to check, starting at 1
      Returns:
      Current button state

    • isDown

      public boolean isDown(int number)
      Checks if the button with the given number (starting at 1) was pressed during the last poll cycle. Please note that this value will only update while the poller is running.
      Parameters:
      number - Button number to check
      Returns:
      True if button is pressed

    • isUp

      public boolean isUp(int number)
      Checks if the button with the given number (starting at 1) was NOT pressed during the last poll cycle. Please note that this value will only update while the poller is running.
      Parameters:
      number - Button number to check, starting at 1
      Returns:
      True if button is not pressed

    • onDown

      public void onDown(int number, SimpleEventHandler handler)
      Sets or disables the handler for the onDown of the given button. This event gets triggered whenever the given button is pressed. Only a single event handler per button can be registered at once.
      Parameters:
      number - Button number to check, starting at 1
      handler - Event handler to call or null to disable

    • onUp

      public void onUp(int number, SimpleEventHandler handler)
      Sets or disables the handler for the onUp of the given button. This event gets triggered whenever the given button is released. Only a single event handler per button can be registered at once.
      Parameters:
      number - Button number to check, starting at 1
      handler - Event handler to call or null to disable

    • buildDigitalOutputConfig

      protected static com.pi4j.io.gpio.digital.DigitalOutputConfig buildDigitalOutputConfig(com.pi4j.context.Context pi4j, int address)
      Builds a new DigitalOutput configuration for a button matrix selector.
      Parameters:
      pi4j - Pi4J context
      address - BCM pin of selector
      Returns:
      DigitalOutputConfig configuration

    • buildDigitalInputConfig

      protected static com.pi4j.io.gpio.digital.DigitalInputConfig buildDigitalInputConfig(com.pi4j.context.Context pi4j, int address)
      Builds a new DigitalInput configuration for a button matrix button.
      Parameters:
      pi4j - Pi4J context
      address - BCM pin of button
      Returns:
      DigitalInput configuration