NAME

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

SYNOPSIS

    No matter which import option you choose, before you can start making
    calls, you must initialize the software by calling one of the setup*()
    routines.

        # 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;

DESCRIPTION

    This is an XS-based module, and requires wiringPi <http://wiringpi.com>
    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 <http://wiringpi.com> 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 number mapping scheme to wiringPi.

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

    Each setup function has benefits and drawbacks. Please refer to the
    wiringPi setup functions <http://wiringpi.com/reference/setup> for
    details.

    See pinout.xyz <https://pinout.xyz/pinout/wiringpi> for a pin number
    conversion chart, or on the command line, run gpio readall.

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

    This setup routine 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.

 setup_phys()

    Maps to int wiringPiSetupPhys()

    Sets the pin mapping to use the physical pin position number on the
    board.

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

 setup_gpio()

    Maps to int wiringPiSetupGpio()

    Sets the pin numbering scheme to GPIO.

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

 pin_mode($pin, $mode)

    Maps to void pinMode(int pin, int mode)

    Puts the pin in either INPUT or OUTPUT mode.

    Parameters:

        $pin

    Mandatory: The pin number, in the pin numbering scheme dictated by
    whichever setup*() routine you used.

        $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 pin number, in the pin numbering scheme dictated by
    whichever setup*() routine you used.

 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 pin number, in the pin numbering scheme dictated by
    whichever setup*() routine you used.

        $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 pin number, in the pin numbering scheme dictated by
    whichever setup*() routine you used.

        $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 pin number, in the pin numbering scheme dictated by
    whichever setup*() routine you used.

        $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 pin number, in the pin numbering scheme dictated by
    whichever setup*() routine you used.

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 pin number, in the pin numbering scheme dictated by
    whichever setup*() routine you used.

 phys_to_gpio($pin_num)

    Maps to int physPinToGpio(int pin)

    Converts the pin number on the physical board to the GPIO
    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 <http://wiringpi.com/dev-lib/lcd-library/> 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: 2 or 4
            cols => $num,       # number of columns. eg: 16 or 20
            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().

        $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().

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

        $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 58, 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, in the pin numbering scheme dictated by
    whichever setup*() routine you used.

        $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

    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.

POD ERRORS

    Hey! The above document had some coding errors, which are explained
    below:

    Around line 448:

      Non-ASCII character seen before =encoding in '58,'. Assuming UTF-8

