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.

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 modules do none of these things.

This module also calls the setup initialization routines automatically, where in the component modules, you have to do this manually. You also need to clean up after yourself.

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.

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.

Parameters:

setup => $value

Optional. This option specifies which GPIO pin mapping (numbering scheme) to use. wiringPi for wiringPi's mapping, physical to use the pin numbers labelled on the board itself, or gpio use the Broadcom (BCM) pin numbers. You can also specify none for testing purposes. This will bypass running the setup routines.

system will also use BCM pin numbering, but in this setup mode, we don't require root privileges to run. This is the default.

See wiringPi setup reference for important details on the differences.

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