/ 
RPi-WiringPi-1.00
River stage one • 1 direct dependent • 1 total dependent
/ RPi::WiringPi

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