NAME

    RPi::WiringPi - Perl interface to Raspberry Pi's board, GPIO, LCDs and
    other various items

SYNOPSIS

        use RPi::WiringPi;
        use RPi::WiringPi::Constant qw(:all);
    
        my $pi = RPi::WiringPi->new;
    
        # board
    
        my $board = $pi->board;
        my $revision = $pi->rev;
        print "Raspberry Pi board revision: $revision"\n";
    
        # pin
    
        my $pin = $pi->pin(5);
        $pin->mode(OUTPUT);
        $pin->write(ON);
    
        my $num = $pin->num;
        my $mode = $pin->mode;
        my $state = $pin->read;
    
        # LCD
    
        my $lcd = $pi->lcd;
    
        $lcd->init(...);
    
        # first column, first row
        
        $lcd->position(0, 0); 
        $lcd->print("Pi rev: $revision");
    
        # first column, second row
        
        $lcd->position(0, 1);
        $lcd->print("pin $num... mode: $mode, state: $state");
    
        $lcd->clear;
        $lcd->display(OFF);
    
        $pi->cleanup;

DESCRIPTION

    WARNING: Until version 1.00 is released, the API and other
    functionality of this module may change, and things may break from
    time-to-time.

    IMPORTANT (root vs sudo):

    Using this software requires root privileges. There are two separate
    modes you can select from... one where you must run your scripts as
    root, the other where you can use a non-root user. For the latter, we
    do make a few calls with sudo, so when in this mode, your user account
    must have password-less sudo access to at minimum the gpio command line
    utility. The default user account (pi) on Raspbian OS has this right by
    default. We default to the non-root configuration. See the details in
    the new method below for further details.

    This is the root module for the RPi::WiringPi system. It interfaces to
    a Raspberry Pi board, its accessories and its GPIO pins via the
    wiringPi <http://wiringpi.com> library through the Perl wrapper
    WiringPi::API <https://metacpan.org/pod/WiringPi::API> module.

    This module is essentially a 'manager' for the sub-modules (ie.
    components). You can use the component modules directly, but retrieving
    components through this module instead has many benefits. We maintain a
    registry of pins and other data. We also trap $SIG{__DIE__} and
    $SIG{INT}, so that in the event of a crash, we can reset the Pi back to
    default settings, so components are not left in an inconsistent state.
    Component modules do none of these things.

    There are a basic set of constants that can be imported. See
    RPi::WiringPi::Constant.

    wiringPi <http://wiringpi.com> must be installed prior to
    installing/using this module.

    It's handy to have access to a pin mapping conversion chart. There's an
    excellent pin scheme map for reference at pinout.xyz
    <https://pinout.xyz/pinout/wiringpi>. You can also run gpio readall at
    the command line to get a pin chart.

OPERATIONAL METHODS

    See RPi::WiringPi::Util for utility/helper methods that are imported
    into an RPi::WiringPi object.

 new(%args)

    Returns a new RPi::WiringPi object. Calls setup() by default, setting
    pin numbering scheme to WPI (wiringPi scheme).

    Parameters:

    setup => $value

      Optional. This option specifies which pin mapping (numbering scheme)
      to use.

          wiringPi:   wiringPi's numbering
          physical:   physical pin numbering
          gpio:       GPIO numbering
          system:     GPIO numbering (root not required in this mode)

      You can also specify none for testing purposes. This will bypass
      running the setup routines.

      !!! system mode uses sudo !!!

      system mode is the only mode where you do not need to run your
      application as the root user. To this end, in wiringPi when using
      system mode, you have to export and manually manipulate the pins with
      the gpio application prior to using them. I have wrapped around this
      limitation by making these calls with sudo for you, so that you don't
      have to do anything different no matter the mode you're using.

      When using system mode, the user running your application should be
      able to at minimum call the <c>gpio</c> application without supplying
      a password. The default Raspberry Pi user pi can do this by default.

      See wiringPi setup reference <http://wiringpi.com/reference/setup>
      for important details on the differences.

      There's an excellent pin scheme map for reference at pinout.xyz
      <https://pinout.xyz/pinout/wiringpi>.

    fatal_exit => $bool

      Optional: We trap all die() calls and clean up for safety reasons. If
      a call to die() is trapped, by default, we clean up, and then exit().
      Set fatal_exit to false (0) to perform the cleanup, and then continue
      running your script. This is for unit testing purposes only.

 pin($pin_num)

    Returns a RPi::WiringPi::Pin object, mapped to a specified GPIO pin.

    Parameters:

    $pin_num

      Mandatory: The pin number to attach to.

 board()

    Returns a RPi::WiringPi::Board object which has access to various
    attributes of the Raspberry Pi physical board itself.

 lcd()

    Returns a RPi::WiringPi::LCD object, which allows you to fully
    manipulate LCD displays connected to your Raspberry Pi.

 interrupt($pin, $edge, $callback)

    Returns a RPi::WiringPi::Interrupt object, which allows you to act when
    certain events occur (eg: a button press). This module is better used
    through the RPi::WiringPi::Pin object.

IMPORTANT NOTES

    - wiringPi <http://wiringpi.com> must be installed prior to
    installing/using this module.

    - By default, we use BCM interpretation of GPIO pin mapping. See new
    method to change this behaviour.

    - This module hijacks fatal errors with $SIG{__DIE__}, as well as
    $SIG{INT}. This is so that in the case of a fatal error, the Raspberry
    Pi pins are never left in an inconsistent state. By default, we trap
    the die(), reset all pins to their default (INPUT, LOW), then we
    exit(). Look at the fatal_exit param in new() to change the behaviour.

AUTHOR

    Steve Bertrand, <steveb@cpan.org>

COPYRIGHT AND LICENSE

    Copyright (C) 2016 by Steve Bertrand

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.18.2 or, at
    your option, any later version of Perl 5 you may have available.

