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;
    
        my $board_revision = $pi->rev;
    
        # 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: $board_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

    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.

    The scripts you write using this software requires those scripts to be
    run as root, (with sudo if configured properly... see
    RPi::WiringPi::FAQ).

    By default, we set up using the GPIO numbering scheme for pins. See
    new() method for information on how to change this.

    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 moduls 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, or from the command line, run the
    pinmap command that was installed by this module, or wiringPi's gpio
    readall command.

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.

          wpi:    wiringPi's numbering
          phys:   physical pin numbering
          gpio:   GPIO numbering

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

      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>. You can also run the pinmap
      application that was included in this distribution from the command
      line to get a printout of pin mappings.

    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,
    which you can then perform operations on.

    Parameters:

    $pin_num

      Mandatory: The pin number to attach to.

 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 functionality is better
    used through the RPi::WiringPi::Pin object you created with pin().

 rev()

    Returns the revision of the Pi board.

 pwm_range($range)

    Changes the range of Pulse Width Modulation (PWM). The default is 0
    through 1023.

    Parameters:

        $range

    Mandatory: An integer specifying the high-end of the range. The range
    always starts at 0. Eg: if $range is 359, if you incremented PWM by 1
    every second, you'd rotate a step motor one complete rotation in
    exactly one minute.

RUNNING TESTS

    This distribution does not have a typical set of unit tests. This is
    because to ensure proper functionality, you need to be running on a
    Rasbperry Pi board that has a couple of very basic circuits set up.

    The tests are in individual Perl scripts inside of the test/ directory
    inside this distribution.

    Each test, when run without any command line arguments, will print out
    what you need to do. Most tests require a single LED connected to a
    single GPIO pin, then you select the test number to run (1-4) and pass
    that in as an argument.

    The number of the test correlates with a specific setup mode.

    Example:

        $ perl test/10-pwm.pl
    
        need test number as arg: 1-WPI, 2-GPIO, 3-PHYS, 4-SYS
    
        this test tests the pwm() pin function. Connect an LED to physical pin *12*.
        The LED should gradually get brighter for each test.

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.

