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 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 softPwmCreate softPwmWrite softPwmStop sr595Setup 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 soft_pwm_create soft_pwm_write soft_pwm_stop shift_reg_setup 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 for details. See pinout.xyz 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 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 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. SOFT PWM METHODS Software Pulse Width Modulation is not the same as hardware PWM. It should not be used for critical things as it's frequency isn't 100% stable. This software PWM allows you to use PWM on ANY GPIO pin, not just the single hardware pin available. soft_pwm_create($pin, $initial_value, $range) Creates a new software PWM thread that runs outside of your main application. Parameters: $pin Mandatory: The pin number, in the pin numbering scheme dictated by whichever `setup*()' routine you used. $initial_value Optional: A value between `0' and `$range'. $range Optional: Look at this like a dial. We start at `0' and the dial has turned completely when we hit the `$range' integer. If not sent in, defaults to `1023'. soft_pwm_write($pin, $value) Sets the `HIGH' frequency on `pin' to whatever is in `$value'. The value must be lower than what was set in the `$range' parameter to `soft_pwm_create()'. soft_pwm_stop($pin) Turns off software PWM on the `$pin'. 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. SHIFT REGISTER FUNCTIONS Shift registers allow you to add extra output pins by multiplexing a small number of GPIO. Currently, we support the SR74HC595 unit, which provides eight outputs by using only three GPIO. To further, this particular unit can be daisy chained up to four wide to provide an additional 32 outputs using the same three GPIO pins. shift_reg_setup This function configures the Raspberry Pi to use a shift register (The SR74HC595 is currently supported). Parameters: $pin_base Mandatory: Signed integer, higher than that of all existing GPIO pins. This parameter registers pin 0 on the shift register to an internal GPIO pin number. For example, setting this to 100, you will be able to access the first output on the register as GPIO 100 in all other functions. $num_pins Mandatory: Signed integer, the number of outputs on the shift register. For a single SR74HC595, this is eight. If you were to daisy chain two together, this parameter would be 16. $data_pin Mandatory: Integer, the GPIO pin number connected to the register's `DS' pin (14). Can be any GPIO pin capable of output. $clock_pin Mandatory: Integer, the GPIO pin number connected to the register's `SHCP' pin (11). Can be any GPIO pin capable of output. $latch_pin Mandatory: Integer, the GPIO pin number connected to the register's `STCP' pin (12). Can be any GPIO pin capable of output. head1 AUTHOR Steve Bertrand, 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.