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
    library through the Perl wrapper WiringPi::API module.

    The scripts you write using this software requires those scripts to be
    run as root (or with `sudo', if configured properly... see
    RPi::WiringPi::Tutorial.pod.

    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 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. 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.

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 for important details on the
            differences.

            There's an excellent pin scheme map for reference at pinout.xyz.
            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.

    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 module is better used
    through the RPi::WiringPi::Pin object.

  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.

