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 library through the Perl wrapper 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 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.

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

There's an excellent pin scheme map for reference at pinout.xyz.

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

cpanm RPi::WiringPi

perl -MCPAN -e shell
install RPi::WiringPi