NAME

WiringPi::API - Direct access to Raspberry Pi's wiringPi API, with optional Perl OO access

SYNOPSIS

# import the API functions directly

use WiringPi::API qw(:wiringPi)

# import the Perl wrapped functions

use WiringPi::API qw(:perl)

# import both versions

use WiringPi::API qw(:all)

# use as a base class with OO functionality

use parent 'WiringPi::API';

# use in the traditional Perl OO way

use WiringPi::API;

my $api = WiringPi::API->new;

# !!!
# regardless of using OO or functional style, one of the C<setup*()>
# functions MUST be called prior to doing anything
# !!!

# OO

$api->setup;

# functional

setup();

DESCRIPTION

This is an XS-based module, and requires wiringPi to be installed. The wiringPiDev shared library is also required (for the LCD functionality), but it's installed by default with wiringPi.

This module allows you to import the wiringPi's functions directly as-is, use it as a Perl base class, export the Perl wrapped functions, or use it in a traditional Perl OO way.

See the documentation on the wiringPi website for a more in-depth description of most of the functions it provides. Some of the functions we've wrapped are not documented, they were just selectively plucked from the C code itself.

EXPORT_OK

Exported with the :wiringPi tag, these XS functions map directly to the wiringPi functions with their original names. Note that setInterrupt is not a direct wrapper, it's a custom C wrapper for wiringPiISR() in order to make it functional here.

wiringPiSetup wiringPiSetupSys wiringPiSetupGpio wiringPiSetupPhys
pinMode pullUpDnControl digitalRead digitalWrite digitalWriteByte
pwmWrite getAlt piBoardDev wpiToGpio physPinToGpio pwmSetRange lcdInit
lcdHome lcdClear lcdDisplay lcdCursor lcdCursorBlink lcdSendCommand
lcdPosition lcdCharDef lcdPutChar lcdPuts setInterrupt

Exported with the :perl tag. Perl wrapper functions for the XS functions.

setup setup_sys setup_phys setup_gpio pin_mode pull_up_down read_pin
write_pin pwm_write get_alt board_rev wpi_to_gpio phys_to_gpio 
pwm_set_range lcd_init lcd_home lcd_clear lcd_display lcd_cursor
lcd_cursor_blink lcd_send_cmd lcd_position lcd_char_def lcd_put_char
lcd_puts set_interrupt

EXPORT_TAGS

:wiringPi

See EXPORT_OK

:perl

See EXPORT_OK

:all

Exports all available exportable functions.

CORE METHODS

new()

NOTE: After an object is created, one of the setup* methods must be called to initialize the Pi board.

Returns a new WiringPi::API object.

setup()

Maps to int wiringPiSetup()

Sets the pin numbering scheme to WPI (wiringPi numbers).

Each setup function has benefits and drawbacks. Please refer to the wiringPi setup functions for details.

This one requires you to run your script as the root user.

Note that only one of the setup*() methods can be called per program run.

setup_sys()

Maps to int wiringPiSetupSys()

Sets the pin numbering scheme to BCM (Broadcom numbers).

Each setup function has benefits and drawbacks. Please refer to the wiringPi setup functions for details.

This one does NOT require running as root, but you have to manually export the pins yourself with the gpio command line utility prior to using the pins.

Note that only one of the setup*() methods can be called per program run.

setup_phys()

Maps to int wiringPiSetupPhys()

Sets the pin numbering scheme to PHYS (physical board numbers).

Each setup function has benefits and drawbacks. Please refer to the wiringPi setup functions for details.

This one requires you to run your script as the root user.

Note that only one of the setup*() methods can be called per program run.

setup_gpio()

Maps to int wiringPiSetupGpio()

Sets the pin numbering scheme to BCM (Broadcom numbers).

Each setup function has benefits and drawbacks. Please refer to the wiringPi setup functions for details.

This one requires you to run your script as the root user.

Note that only one of the setup*() methods can be called per program run.

pin_mode($pin, $mode)

Maps to void pinMode(int pin, int mode)

Puts the GPIO pin in either INPUT or OUTPUT mode.

Parameters:

$pin

Mandatory: The GPIO pin number, using your currently in-use numbering scheme (BCM aka GPIO by default).

$mode

Mandatory: 0 for INPUT, 1 OUTPUT, 2 PWM_OUTPUT and 3 GPIO_CLOCK.

read_pin($pin);

Maps to int digitalRead(int pin)

Returns the current state (HIGH/on, LOW/off) of a given pin.

Parameters:

$pin

Mandatory: The GPIO pin number, using your currently in-use numbering scheme (BCM aka GPIO by default).

write_pin($pin, $state)

Maps to void digitalWrite(int pin)

Sets the state (HIGH/on, LOW/off) of a given pin.

Parameters:

$pin

Mandatory: The GPIO pin number, using your currently in-use numbering scheme (BCM aka GPIO by default).

$state

Mandatory: 1 to turn the pin on (HIGH), and 0 to turn it LOW (off).

pull_up_down($pin, $direction)

Maps to void pullUpDnControl(int pin, int pud)

Enable/disable the built-in pull up/down resistors for a specified pin.

Parameters:

$pin

Mandatory: The GPIO pin number, using your currently in-use numbering scheme (BCM aka GPIO by default).

$direction

Mandatory: 2 for UP, 1 for DOWN and 0 to disable the resistor.

pwm_write($pin, $value)

Maps to void pwmWrite(int pin, int value)

Sets the Pulse Width Modulation duty cycle (on-time) of the pin.

Parameters:

$pin

Mandatory: The GPIO pin number, using your currently in-use numbering scheme (BCM aka GPIO by default).

$value

Mandatory: 0 to 1023. 0 is 0% (off) and 1023 is 100% (fully on).

get_alt($pin)

Maps to int getAlt(int pin)

This returns the current mode of the pin (using getAlt() C call). Modes are INPUT 0, OUTPUT 1, PWM 2 and CLOCK 3.

Parameters:

$pin

Mandatory: The GPIO pin number, using your currently in-use numbering scheme (BCM aka GPIO by default).

BOARD METHODS

board_rev()

Maps to int piBoardRev()

Returns the Raspberry Pi board's revision.

wpi_to_gpio($pin_num)

Maps to int wpiPinToGpio(int pin)

Converts a wiringPi pin number to the Broadcom (BCM) representation, and returns it.

Parameters:

$pin_num

Mandatory: The GPIO pin number, using your currently in-use numbering scheme (BCM aka GPIO by default).

phys_to_gpio($pin_num)

Maps to int physPinToGpio(int pin)

Converts the pin number on the physical board to the Broadcom (BCM) representation, and returns it.

Parameters:

$pin_num

Mandatory: The pin number on the physical Raspberry Pi board.

phys_to_wpi($pin_num)

Maps to int physPinToWpi(int pin)

Converts the pin number on the physical board to the wiringPi numbering representation, and returns it.

Parameters:

$pin_num

Mandatory: The pin number on the physical Raspberry Pi board.

pwm_set_range($range);

Maps to void pwmSetRange(int range)

Sets the range register of the Pulse Width Modulation (PWM) functionality. It defaults to 1024 (0-1023).

Parameters:

$range

Mandatory: An integer between 0 and 1023.

LCD METHODS

There are several methods to drive standard Liquid Crystal Displays. See wiringPiDev LCD page for full details.

lcd_init(%args)

Maps to:

int lcdInit(
    rows, cols, bits, rs, strb,
    d0, d1, d2, d3, d4, d5, d6, d7
);

Initializes the LCD library, and returns an integer representing the handle handle (file descriptor) of the device. The return is supposed to be constant, so DON'T change it.

Parameters:

%args = (
    rows => $num,       # number of rows. eg: 16 or 20
    cols => $num,       # number of columns. eg: 2 or 4
    bits => 4|8,        # width of the interface (4 or 8)
    rs => $pin_num,     # pin number of the LCD's RS pin
    strb => $pin_num,   # pin number of the LCD's strobe (E) pin
    d0 => $pin_num,     # pin number for LCD data pin 1
    ...
    d7 => $pin_num,     # pin number for LCD data pin 8
);

Mandatory: All entries must have a value. If you're only using four (4) bit width, d4 through d7 must be set to 0.

Note: When in 4-bit mode, the d0 through 3 parameters actually map to pins d4 through d7 on the LCD board, so you need to connect those pins to their respective selected GPIO pins.

lcd_home($fd)

Maps to void lcdHome(int fd)

Moves the LCD cursor to the home position (top row, leftmost column).

Parameters:

$fd

Mandatory: The file descriptor integer returned by lcd_init().

lcd_clear($fd)

Maps to void lcdClear(int fd)

Clears the LCD display.

Parameters:

$fd

Mandatory: The file descriptor integer returned by lcd_init().

lcd_display($fd, $state)

Maps to void lcdDisplay(int fd, int state)

Turns the LCD display on and off.

Parameters:

$fd

Mandatory: The file descriptor integer returned by lcd_init().

$state

Mandatory: 0 to turn the display off, and 1 for on.

lcd_cursor($fd, $state)

Maps to void lcdCursor(int fd, int state)

Turns the LCD cursor on and off.

Parameters:

$fd

Mandatory: The file descriptor integer returned by lcd_init().=head2 lcd_clear($fd)

$state

Mandatory: 0 to turn the cursor off, 1 for on.

lcd_cursor_blink($fd, $state)

Maps to void lcdCursorBlink(int fd, int state)

Allows you to enable/disable a blinking cursor.

Parameters:

$fd

Mandatory: The file descriptor integer returned by lcd_init().=head2 lcd_clear($fd)

$state

Mandatory: 0 to stop blinking, 1 to enable.

lcd_send_cmd($fd, $command)

Maps to void lcdSendCommand(int fd, char command)

Sends any arbitrary command to the LCD.

Parameters:

$fd

Mandatory: The file descriptor integer returned by lcd_init().=head2 lcd_clear($fd)

$command

Mandatory: A command to submit to the LCD.

lcd_position($fd, $x, $y)

Maps to void lcdPosition(int fd, int x, int y)

Moves the cursor to the specified position on the LCD display.

Parameters:

$fd

Mandatory: The file descriptor integer returned by lcd_init().

$x

Mandatory: Column position. 0 is the left-most edge.

$y

Mandatory: Row position. 0 is the top row.

lcd_char_def($fd, $index, $data)

Maps to void lcdCharDef(int fd, unsigned char data [8])

This allows you to re-define one of the 8 user-definable characters in the display. The data array is 8 bytes which represent the character from the top-line to the bottom line. Note that the characters are actually 5×8, so only the lower 5 bits are used. The index is from 0 to 7 and you can subsequently print the character defined using the lcdPutchar() call.

Parameters:

$fd

Mandatory: The file descriptor integer returned by lcd_init().

$index

Mandatory: Index of the display character. Values are 0-7.

$data

Mandatory: See above description.

lcd_put_char($fd, $char)

Maps to void lcdPutChar(int fd, unsigned char data)

Writes a single ASCII character to the LCD display, at the current cursor position.

Parameters:

$fd

Mandatory: The file descriptor integer returned by lcd_init().

$char

Mandatory: A single ASCII character.

lcd_puts($fd, $string)

Maps to void lcdPuts(int fd, char *string)

Writes a string to the LCD display, at the current cursor position.

Parameters:

$fd

Mandatory: The file descriptor integer returned by lcd_init().

$string

Mandatory: A string to display.

INTERRUPT METHODS

set_interrupt($pin, $edge, $callback)

IMPORTANT: The interrupt functionality requires that your Perl can be used in pthreads. If you do not have a threaded Perl, the program will cause a segmentation fault.

Wrapper around wiringPi's wiringPiISR() that allows you to send in the name of a Perl sub in your own code that will be called if an interrupt is triggered.

Parameters:

$pin

Mandatory: The pin number to set the interrupt for. Must be in BCM numbering scheme.

$edge

Mandatory: 1 (lowering), 2 (raising) or 3 (both).

$callback

Mandatory: The string name of a subroutine previously written in your user code that will be called when the interrupt is triggered. This is your interrupt handler.

head1 AUTHOR

Steve Bertrand, <steveb@cpan.org>

COPYRIGHT AND LICENSE

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.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 672:: Non-ASCII character seen before =encoding in '5×8,'. Assuming UTF-8

To install WiringPi::API, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WiringPi::API

CPAN shell

perl -MCPAN -e shell
install WiringPi::API

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

EXPORT_OK

EXPORT_TAGS

:wiringPi

:perl

:all

CORE METHODS

new()

setup()

setup_sys()

setup_phys()

setup_gpio()

pin_mode($pin, $mode)

read_pin($pin);

write_pin($pin, $state)

pull_up_down($pin, $direction)

pwm_write($pin, $value)

get_alt($pin)

BOARD METHODS

board_rev()

wpi_to_gpio($pin_num)

phys_to_gpio($pin_num)

phys_to_wpi($pin_num)

pwm_set_range($range);

LCD METHODS

lcd_init(%args)

lcd_home($fd)

lcd_clear($fd)

lcd_display($fd, $state)

lcd_cursor($fd, $state)

lcd_cursor_blink($fd, $state)

lcd_send_cmd($fd, $command)

lcd_position($fd, $x, $y)

lcd_char_def($fd, $index, $data)

lcd_put_char($fd, $char)

lcd_puts($fd, $string)

INTERRUPT METHODS

set_interrupt($pin, $edge, $callback)

COPYRIGHT AND LICENSE

Module Install Instructions