NAME
WiringPi::API - API for wiringPi, providing access to the Raspberry Pi's board, GPIO and connected peripherals
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.
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 version 3.18+ to be installed. The wiringPiDev shared library is also required (for the LCD functionality), but it's installed by default with wiringPi.
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. Each mapped function lists which C function it is responsible for.
EXPORT_OK
Exported with the :all tag, or individually.
Perl wrapper functions for the XS functions. Not all of these are direct wrappers; several have additional/modified functionality than the wrapped versions, but are still 100% compatible. They are grouped below by purpose; within each group the names are listed alphabetically, except where a natural flow (eg. setup before its variants, or lcd_init before the rest) reads better.
Setup
setup setup_gpio
wiringpi_setup_pin_type wiringpi_setup_gpio_device
wiringpi_gpio_device_get_fd wiringpi_version
Pin
pin_mode pin_mode_alt get_alt
get_pin_mode_alt pull_up_down read_pin
write_pin digital_read_byte digital_read_byte2
digital_write_byte digital_write_byte2
ADC (analog to digital)
ads1115_setup analog_read analog_write
BMP180 barometric pressure sensor
bmp180_setup bmp180_pressure bmp180_temp
Board
gpio_layout phys_to_gpio phys_to_wpi
pi_board40_pin pi_board_id pi_rp1_model
wpi_to_gpio
Developer
wiringpi_global_memory_access wiringpi_user_level_access
I2C
i2c_setup i2c_interface
i2c_read i2c_read_byte i2c_read_word
i2c_read_block i2c_raw_read
i2c_write i2c_write_byte i2c_write_word
i2c_write_block i2c_raw_write
Interrupt
set_interrupt background_interrupt background_interrupts
auto_dispatch_interrupts dispatch_interrupts
wait_interrupts run_interrupt_loop stop_interrupt
stop_interrupts stop_interrupt_loop interrupt_fd
interrupt_buffer interrupt_dropped last_interrupt
LCD
lcd_init lcd_char_def lcd_clear
lcd_cursor lcd_cursor_blink lcd_display
lcd_home lcd_position lcd_put_char
lcd_puts lcd_send_cmd
Pad drive / tone / clock
gpio_clock_set pwm_tone_write set_pad_drive
set_pad_drive_pin
PWM
pwm_set_clock pwm_set_mode pwm_set_range
pwm_write
Serial
serial_open serial_close serial_data_avail
serial_flush serial_get_char serial_gets
serial_put_char serial_puts
Shift register
shift_reg_setup
Soft PWM
soft_pwm_create soft_pwm_stop soft_pwm_write
Soft tone
soft_tone_create soft_tone_stop soft_tone_write
SPI
spi_setup spi_setup_mode spi_data
spi_get_fd spi_close
Thread / lock
pi_lock pi_unlock
Timing
delay_microseconds pi_hi_pri pi_micros64
Worker
workerEXPORT_TAGS
See "EXPORT_OK"
:all
Exports all available exportable functions.
:perl
Export only Perlish snake_case named version of the functions.
:wiringPi
Export only the C based camelCase version of the function names.
:constants
Export only the constants. These (including WPI_PIN_BCM / WPI_PIN_WPI and the INT_EDGE_* edge triggers) are defined in and re-exported from RPi::Const, the single source of truth for constants across the RPi:: suite.
FUNCTION TABLE OF CONTENTS
CORE
See "CORE FUNCTIONS".
BOARD
See "BOARD FUNCTIONS".
LCD
See "LCD FUNCTIONS".
INTERRUPT
CONCURRENCY / BACKGROUND WORKERS
See "CONCURRENCY / BACKGROUND WORKERS".
ANALOG TO DIGITAL CONVERTER
See "ADC FUNCTIONS".
SHIFT REGISTER
See "SHIFT REGISTER FUNCTIONS"
SERIAL
I2C
See "I2C FUNCTIONS"
SPI
See "SPI FUNCTIONS"
BAROMETRIC SENSOR
See "BMP180 PRESSURE SENSOR FUNCTIONS".
CORE FUNCTIONS
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.
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 should be called per program run.
setup_gpio()
Maps to int wiringPiSetupGpio()
Sets the pin numbering scheme to GPIO.
Personally, this is the setup routine that I always use, due to the GPIO numbers physically printed right on the Pi board.
wiringpi_setup_pin_type($pin_type)
Maps to int wiringPiSetupPinType(enum WPIPinType pinType)
A unified setup routine that takes the pin-numbering scheme as a parameter, rather than having a separate function per scheme. $pin_type must be one of the exported constants WPI_PIN_BCM (equivalent to setup_gpio()) or WPI_PIN_WPI (equivalent to setup()).
Physical-pin setup (WPI_PIN_PHYS) is not supported - that constant is not exported, and passing it (or any other value) causes a croak.
wiringpi_setup_gpio_device($pin_type)
Maps to int wiringPiSetupGpioDevice(enum WPIPinType pinType)
As wiringpi_setup_pin_type(), but initialises wiringPi over the GPIO character-device (libgpiod) interface instead of the legacy /dev/gpiomem memory-mapped path. $pin_type takes the same WPI_PIN_BCM / WPI_PIN_WPI constants and is validated the same way.
This is offered as an opt-in alternative; the default setup() / setup_gpio() routines are unchanged.
wiringpi_gpio_device_get_fd()
Maps to int wiringPiGpioDeviceGetFd()
Returns the open file descriptor of the GPIO character device, when wiringPi was initialised via wiringpi_setup_gpio_device().
The pin-type constants WPI_PIN_BCM and WPI_PIN_WPI are available individually or via the :constants / :all export tags.
wiringpi_version()
Maps to void wiringPiVersion(int *major, int *minor).
Returns the version of the installed wiringPi C library (eg. 3.18). This is the underlying library version, not the $VERSION of this Perl distribution.
In scalar context, returns the version as a string (eg. "3.18"). In list context, returns the ($major, $minor) integer pair (eg. (3, 18)).
The exported C-level wiringPiVersion() always returns the version string.
pin_mode($pin, $mode)
Maps to void pinMode(int pin, int mode)
Puts the pin in either INPUT, OUTPUT, PWM or GPIO_CLOCK mode.
Parameters:
$pinMandatory: The pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
$modeMandatory: 0 for INPUT, 1 OUTPUT, 2 PWM_OUTPUT and 3 GPIO_CLOCK.
pin_mode_alt($pin, $alt)
Maps to the undocumented void pinModeAlt(int pin, int mode)
Allows you to set any pin to any mode. ALT modes allowed:
value mode
------------
0 INPUT
1 OUTPUT
4 ALT0
5 ALT1
6 ALT2
7 ALT3
3 ALT4
2 ALT5Parameters:
$pinMandatory: The pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
$altMandatory, Integer: The mode you want to put the pin into. See the list above for the relevant values for this parameter.
Raspberry Pi 5 (RP1) differences
On the Pi 5 the GPIO is driven by the RP1 chip rather than the Broadcom SoC, and its alternate-function map is completely different from earlier Pis. The $alt values above are unchanged - wiringPi remaps them internally - but what each mode selects is not: ALT0..ALT5 route entirely different peripherals on the Pi 5 than they do on a Pi 0-4. Consult the RP1 datasheet (or the pinctrl tool) for your Pi 5, not the BCM2835 ALT tables, to know which function a given value actually enables.
Two further specifics on the Pi 5:
INPUT(0) andOUTPUT(1) both select the RP1 GPIO (SYS_RIO) function; the in/out direction itself is set separately (eg. viapin_mode()), not by the alt value.RP1 adds three more alternate functions -
ALT6,ALT7andALT8(values8,9and10). These are accepted only on a Pi 5; on a Pi 0-4 the valid range stays0-7and passing8-10croaks. The Pi 5 is detected viapi_rp1_model(), so asetup*()routine must have run first.
read_pin($pin);
Maps to int digitalRead(int pin)
Returns the current state (HIGH/on, LOW/off) of a given pin.
Parameters:
$pinMandatory: 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, int state)
Sets the state (HIGH/on, LOW/off) of a given pin.
Parameters:
$pinMandatory: The pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
$stateMandatory: 1 to turn the pin on (HIGH), and 0 to turn it LOW (off).
analog_read($pin);
Maps to int analogRead(int pin)
Returns the data for an analog pin. Note that the Raspberry Pi doesn't have analog pins, so this is used when connected through an ADC or to pseudo analog pins.
Parameters:
$pinMandatory: The pseudo pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
analog_write($pin, $value)
Maps to void analogWrite(int pin, int value)
Writes the value to the corresponding analog pseudo pin.
Parameters:
$pinMandatory: The pseudo pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
$valueMandatory: The data which you want to write to the pseudo pin.
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:
$pinMandatory: The pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
$directionMandatory: 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:
$pinMandatory: The pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
$valueMandatory: 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_OUT 2 and CLOCK 3.
Parameters:
$pinMandatory: The pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
digital_read_byte()
Maps to unsigned int digitalReadByte()
Reads all eight bits of the first 8-bit GPIO bank at once and returns the value as a single integer (0-255).
Note: the byte-bank operations (digital_read_byte(), digital_read_byte2(), digital_write_byte(), digital_write_byte2()) are not supported on the Raspberry Pi 5. On a Pi 5, the underlying wiringPi call prints a diagnostic and terminates the process.
digital_read_byte2()
Maps to unsigned int digitalReadByte2()
As digital_read_byte(), but reads the second 8-bit GPIO bank.
digital_write_byte($value)
Maps to void digitalWriteByte(int value)
Writes the 8-bit $value (0-255) to the first 8-bit GPIO bank in a single operation.
Parameters:
$valueMandatory: An integer 0-255; each bit is written to the corresponding pin of the bank.
digital_write_byte2($value)
Maps to void digitalWriteByte2(int value)
As digital_write_byte(), but writes to the second 8-bit GPIO bank.
BOARD FUNCTIONS
gpio_layout()
Maps to int piGpioLayout()
Returns the Raspberry Pi board's GPIO layout (ie. the board revision).
wpi_to_gpio($pin_num)
Maps to int wpiPinToGpio(int pin)
Converts a wiringPi pin number to the Broadcom (GPIO) representation, and returns it.
Parameters:
$pin_numMandatory: 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_numMandatory: 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_numMandatory: The pin number on the physical Raspberry Pi board.
Returns: The wiringPi pin number, or -1 if the physical pin has no wiringPi equivalent or $pin_num is out of range (less than 0 or greater than 63).
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:
$rangeMandatory: An integer between 0 and 1023.
pwm_set_clock($divisor)
Maps to void pwmSetClock(int divisor).
The PWM clock can be set to control the PWM pulse widths. The PWM clock is derived from a 19.2MHz clock. You can set any divider.
For example, say you wanted to drive a DC motor with PWM at about 1kHz, and control the speed in 1/1024 increments from 0/1024 (stopped) through to 1024/1024 (full on). In that case you might set the clock divider to be 16, and the RANGE to 1024. The pulse repetition frequency will be 1.2MHz/1024 = 1171.875Hz.
Parameters:
$divisorMandatory, Integer: An unsigned integer to set the pulse width to.
pwm_set_mode($mode)
Each PWM channel can run in either Balanced or Mark-Space mode. In Balanced mode, the hardware sends a combination of clock pulses that results in an overall DATA pulses per RANGE pulses. In Mark-Space mode, the hardware sets the output HIGH for DATA clock pulses wide, followed by LOW for RANGE-DATA clock pulses.
Parameters:
$modeMandatory, Integer: 0 for Mark-Space mode, or 1 for Balanced mode.
Note: If using RPi::WiringPi::Constant, you can use PWM_MODE_MS or PWM_MODE_BAL.
SOFT PWM FUNCTIONS
Software-driven PWM on any GPIO pin. See wiringPi softPwm page.
soft_pwm_create($pin, $value, $range)
Maps to int softPwmCreate(int pin, int value, int range)
Creates a software-controlled PWM pin. Returns 0 on success.
Parameters:
$pinMandatory: The pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
$valueMandatory: The initial duty-cycle value, between 0 and $range.
$rangeMandatory: The PWM range (a typical value is 100).
soft_pwm_write($pin, $value)
Maps to void softPwmWrite(int pin, int value)
Updates the PWM duty-cycle value on a pin previously set up with soft_pwm_create().
Parameters:
$pinMandatory: The pin number.
$valueMandatory: The new duty-cycle value, between 0 and the range the pin was created with.
soft_pwm_stop($pin)
Maps to void softPwmStop(int pin)
Stops software PWM on the given pin.
Parameters:
$pinMandatory: The pin number.
SOFT TONE FUNCTIONS
Software-generated tone (square-wave frequency) output on any GPIO pin. See wiringPi softTone page.
(Note: wiringPi's softServo library is not built into the wiringPi 3.18 shared library and is therefore not wrapped.)
soft_tone_create($pin)
Maps to int softToneCreate(int pin)
Sets up a pin for software tone output. Returns 0 on success.
Parameters:
$pinMandatory: The pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
soft_tone_write($pin, $freq)
Maps to void softToneWrite(int pin, int freq)
Sets the frequency (in Hz) of the tone on a pin previously set up with soft_tone_create(). A frequency of 0 stops the tone.
Parameters:
$pinMandatory: The pin number.
$freqMandatory: The frequency in Hz.
soft_tone_stop($pin)
Maps to void softToneStop(int pin)
Stops the software tone on the given pin.
Parameters:
$pinMandatory: The pin number.
THREAD/LOCK FUNCTIONS
Mutex locks provided by wiringPi for synchronising access between threads. They are typically used to serialise shared state in a mechanism => 'thread' worker - see "CONCURRENCY / BACKGROUND WORKERS".
pi_lock($key)
Maps to void piLock(int key)
Acquires the lock identified by $key, waiting until it is available.
Parameters:
$keyMandatory: The lock number, 0 to 3.
pi_unlock($key)
Maps to void piUnlock(int key)
Releases the lock identified by $key.
Parameters:
$keyMandatory: The lock number, 0 to 3.
TIMING FUNCTIONS
wiringPi timing and scheduling helpers. See wiringPi timing page.
delay(), millis() and micros() are exported under the :wiringPi tag as their native wiringPi names.
delay($ms)
Maps to void delay(unsigned int ms)
Pauses execution for at least $ms milliseconds.
delay_microseconds($us)
Maps to void delayMicroseconds(unsigned int us)
Pauses execution for at least $us microseconds.
millis()
Maps to unsigned int millis()
Returns the number of milliseconds elapsed since the program called one of the setup*() routines, as an integer.
micros()
Maps to unsigned int micros()
Returns the number of microseconds elapsed since the program called one of the setup*() routines, as an integer.
pi_micros64()
Maps to unsigned long long piMicros64()
As micros(), but returns a 64-bit microsecond count (does not wrap as quickly). Requires a 64-bit Perl (use64bitint).
pi_hi_pri($priority)
Maps to int piHiPri(const int pri)
Attempts to set a high (real-time) scheduling priority for the running program. Returns 0 on success, -1 on failure (e.g. insufficient privileges).
Parameters:
$priorityMandatory: The priority, 0 (lowest) to 99 (highest).
PAD DRIVE / TONE / CLOCK FUNCTIONS
set_pad_drive($group, $value)
Maps to void setPadDrive(int group, int value)
Sets the drive strength for a group of GPIO pins.
Parameters:
$groupMandatory: The pad group (0, 1 or 2).
$valueMandatory: The drive strength, 0 to 7.
set_pad_drive_pin($pin, $value)
Maps to void setPadDrivePin(int pin, int value)
Sets the drive strength for a single GPIO pin.
Parameters:
$pinMandatory: The pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
$valueMandatory: The drive strength, 0 to 7.
pwm_tone_write($pin, $freq)
Maps to void pwmToneWrite(int pin, int freq)
Writes a tone of the given frequency (in Hz) to a PWM-capable pin.
Parameters:
$pinMandatory: The pin number.
$freqMandatory: The frequency in Hz. A frequency of 0 stops the tone.
gpio_clock_set($pin, $freq)
Maps to void gpioClockSet(int pin, int freq)
Sets the output frequency (in Hz) on a GPIO clock pin.
Parameters:
$pinMandatory: The pin number.
$freqMandatory: The clock frequency in Hz.
BOARD IDENTITY FUNCTIONS
pi_board_id()
Maps to void piBoardId(int *model, int *rev, int *mem, int *maker, int *overVolted)
Returns identifying information about the board. In list context, returns ($model, $rev, $mem, $maker, $over_volted). In scalar context, returns a hash reference with keys model, rev, mem, maker and over_volted. The values are the integer codes used by wiringPi.
pi_board40_pin()
Maps to int piBoard40Pin()
Returns true if the board has the standard 40-pin GPIO header.
pi_rp1_model()
Maps to int piRP1Model()
Returns the RP1 model code on boards that use the RP1 I/O controller (e.g. the Raspberry Pi 5), or a falsey value on boards without one.
get_pin_mode_alt($pin)
Maps to enum WPIPinAlt getPinModeAlt(int pin)
Like get_alt(), but returns the pin's current mode as a WPIPinAlt enum value: -1 (unknown), 0 (input), 1 (output), then the ALT modes.
Parameters:
$pinMandatory: The pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
wiringpi_global_memory_access()
Maps to int wiringPiGlobalMemoryAccess()
Returns a value indicating the level of direct GPIO memory access available to the current process (0 if none).
wiringpi_user_level_access()
Maps to int wiringPiUserLevelAccess()
Returns true if user-level (non-root) GPIO access is available (e.g. via /dev/gpiomem).
LCD FUNCTIONS
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 (file descriptor) of the device.
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.
NOTE: There is an upper limit of the number of LCDs that can be initialized simultaneously. This number is 8 (0-7). Always check the return of this function to ensure you're under the maximum file descriptors. If you receive a `-1`, you're out of bounds, and any functions called on the LCD will cause a segmentation fault.
lcd_home($fd)
Maps to void lcdHome(int fd)
Moves the LCD cursor to the home position (top row, leftmost column).
Parameters:
$fdMandatory: The file descriptor integer returned by lcd_init().
lcd_clear($fd)
Maps to void lcdClear(int fd)
Clears the LCD display.
Parameters:
$fdMandatory: 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:
$fdMandatory: The file descriptor integer returned by lcd_init().
$stateMandatory: 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:
$fdMandatory: The file descriptor integer returned by lcd_init().
$stateMandatory: 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:
$fdMandatory: The file descriptor integer returned by lcd_init().
$stateMandatory: 0 to turn the cursor blink off, 1 for on. Default is off (0).
lcd_send_cmd($fd, $command)
Maps to void lcdSendCommand(int fd, char command)
Sends any arbitrary command to the LCD.
Parameters:
$fdMandatory: The file descriptor integer returned by lcd_init().
$commandMandatory: 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:
$fdMandatory: The file descriptor integer returned by lcd_init().
$xMandatory: Column position. 0 is the left-most edge.
$yMandatory: Row position. 0 is the top row.
lcd_char_def($fd, $index, $data)
Maps to void lcdCharDef(int fd, unsigned char data [8]). This function is
This allows you to re-define one of the 8 user-definable characters in the display.
Parameters:
$fdMandatory: The file descriptor integer returned by lcd_init().
$indexMandatory: Index of the display character. Values are 0-7. Once the char is stored at this index, it can be used at any time with the lcd_put_char() function.
$dataMandatory: Array reference of exactly 8 elements. Each element is a single unsigned char byte. These bytes represent the character from the top-line to the bottom line.
Note that the characters are actually 5 x 8, so only the lower 5 bits are of each element are used (ie. `0b11111` or 0b00011111`). The index is from 0 to 7 and you can subsequently print the character defined using the lcdPutchar() call using the same index sent in to this function.
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:
$fdMandatory: The file descriptor integer returned by lcd_init().
$charMandatory: The character byte to print to the LCD. Note that 0-7 are reserved for custom characters, as defined with lcd_char_def(). To print one of your custom chars, $char should be the same integer of the $index you used to store it in that function.
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:
$fdMandatory: The file descriptor integer returned by lcd_init().
$stringMandatory: A string to display.
INTERRUPT FUNCTIONS
set_interrupt($pin, $edge, $callback, $debounce_us)
Arms an interrupt handler on $pin. Maps to wiringPi's wiringPiISR2().
The wiringPi interrupt thread never calls into Perl: when an edge fires it writes a small event record to an internal pipe (the "self-pipe"). Your $callback runs later, in your interpreter, when you service that pipe with wait_interrupts() or dispatch_interrupts(). Because Perl is only ever entered by the interpreter that owns it, this works on any Perl - threaded or not - and the old "interrupts need a threaded Perl or they segfault" caveat no longer applies.
Arm in the same process that will dispatch. For background handling while your main program does other work, fork a child that arms and dispatches (see the examples below).
Parameters:
$pinMandatory: The pin number, in the pin numbering scheme dictated by whichever setup*() routine you used.
$edgeMandatory: one of INT_EDGE_FALLING (1), INT_EDGE_RISING (2) or INT_EDGE_BOTH (3). INT_EDGE_SETUP (0) is not a valid trigger and is rejected. These constants are importable via the :constants or :all tags.
$callbackMandatory: A code reference that runs when the interrupt is dispatched. It receives two arguments: the edge that fired and the event timestamp in microseconds.
$debounce_usOptional: debounce period in microseconds, passed through to wiringPiISR2() (default 0 = no debounce).
\%optsOptional: a trailing options hash reference. The only option is auto_dispatch: a true value turns on auto-dispatch (see auto_dispatch_interrupts()) as part of arming, so the callback fires on its own without a dispatch loop. This enables the process-wide switch (it is not selective per pin); a string value picks the delivery signal, eg { auto_dispatch => 'USR1' }.
Re-arming the same pin is safe - the previous listener is stopped first, so a second wiringPi thread is never stacked on the pin.
dispatch_interrupts()
Non-blocking. Reads every event currently waiting in the self-pipe, runs the registered callback for each, and returns the number dispatched (0 if none were waiting). Never blocks waiting for an edge.
wait_interrupts($timeout_ms)
Blocks until at least one interrupt event is available (or $timeout_ms milliseconds elapse), dispatches all pending events via dispatch_interrupts(), and returns the number dispatched (0 on timeout). An undefined $timeout_ms blocks indefinitely. The usual single-threaded pattern is:
wait_interrupts(1000) while 1;interrupt_fd()
Returns the readable file descriptor of the self-pipe (an integer), or -1 before any interrupt has been armed. Use this to drive your own select/poll loop instead of wait_interrupts(); call dispatch_interrupts() when it becomes readable.
interrupt_dropped()
Returns the number of interrupt events dropped because the self-pipe was full when an edge fired (bursts beyond the pipe buffer). Normally 0; reset by stop_interrupts().
Overflow policy. Edges are FIFO-queued in the kernel pipe (capacity is the kernel default - typically 64 KiB to 256 KiB - holding thousands of the fixed-size event records). The wiringPi ISR thread writes each edge with a non-blocking write(), so it never stalls. If the pipe is full (your code isn't draining fast enough - e.g. stuck in a long, non-yielding C/XS call), the overflowing edges are dropped, not merged and not blocked, and each one increments interrupt_dropped() - so loss is never silent. Order is preserved; no two edges are ever coalesced into one (debounce, via set_interrupt's $debounce_us, is the only mechanism that intentionally collapses edges). If you see drops, drain faster (wait_interrupts/auto_dispatch_interrupts), move handling to its own process (background_interrupt), raise the queue size with interrupt_buffer(), or debounce to cut the edge rate.
interrupt_buffer($bytes)
Gets or sets the capacity of the interrupt self-pipe (the queue that absorbs edge bursts before interrupt_dropped() starts counting).
With no argument, returns the current capacity in bytes (or the pending request if no interrupt has been armed yet). With $bytes, requests that capacity (F_SETPIPE_SZ) and returns the size the kernel actually granted - it rounds up to a page and caps at /proc/sys/fs/pipe-max-size:
interrupt_buffer(1 << 20); # ask for ~1 MiB of queue
my $size = interrupt_buffer; # what we actually gotThe request is remembered, so you may set it before arming (it is applied when the pipe is created) and it persists across stop_interrupts() - the new pipe from a later set_interrupt() is sized the same way.
run_interrupt_loop($timeout_ms, $max)
A blocking dispatch loop, so you don't have to write wait_interrupts(...) while 1 yourself. It repeatedly calls wait_interrupts($timeout_ms) (poll interval, default 1000 ms) and returns the total number of events dispatched.
It runs until one of:
stop_interrupt_loop()is called - from inside a callback, or from a signal handler (it only flips a flag, so it is signal-safe);$maxevents have been dispatched, if you pass a positive$max.
The $timeout_ms is just the poll granularity - how often the loop checks the stop flag - not a run time limit. Arm your interrupts first; if nothing is armed the loop sleeps the interval rather than spinning.
set_interrupt(0, INT_EDGE_RISING, sub {
my ($edge, $ts) = @_;
stop_interrupt_loop() if done_enough(); # break out from the callback
});
my $count = run_interrupt_loop(1000); # blocks, dispatching, until stoppedstop_interrupt_loop()
Breaks out of run_interrupt_loop() at the next iteration. Safe to call from a callback or a signal handler, and a no-op if no loop is running.
last_interrupt()
Returns a hash reference describing the most recently dispatched interrupt event, or undef if none has been dispatched yet (or since the last stop_interrupts()). The keys are:
pin the pin you armed (your numbering scheme - the dispatch key)
pin_bcm the BCM gpio that fired
edge INT_EDGE_FALLING (1) or INT_EDGE_RISING (2)
status wiringPi's statusOK (1 for a real edge on this path)
ts_us edge timestamp, in microsecondsThe event is published before the callback runs, so a callback - which only receives ($edge, $ts_us) - can call last_interrupt() to obtain the BCM pin or status as well. Handy when one shared callback is armed on several pins:
set_interrupt($pin, INT_EDGE_BOTH, sub {
my $i = last_interrupt();
printf "BCM %d went %s\n", $i->{pin_bcm},
$i->{edge} == INT_EDGE_RISING ? "high" : "low";
});Returns a fresh copy each call, so mutating it won't affect later reads.
stop_interrupt($pin)
Stops the interrupt on $pin (wiringPiISRStop()) and forgets its callback.
stop_interrupts()
Stops every armed interrupt, closes the self-pipe and resets interrupt state. There is no dispatcher thread to join. A later set_interrupt() re-creates the pipe automatically.
auto_dispatch_interrupts($bool, $signal)
Enables (1) or disables (0) async auto-dispatch. When enabled, the interrupt read fd is put into async mode and a signal handler drains and dispatches pending events, so set_interrupt() callbacks fire automatically in this process with no wait_interrupts()/dispatch_interrupts() loop to write. Callbacks run at Perl safe points (between ops, and on interrupted sleep/select), so they may read and modify your program's variables with no locking.
The optional $signal chooses the delivery signal (default 'IO', i.e. SIGIO). Pass a signal name - eg 'USR1' ('SIGUSR1' is also accepted) - to deliver via that signal instead (wired with F_SETSIG), which avoids clashing with other SIGIO/O_ASYNC users in your program. The name must be one Perl knows (it croaks otherwise).
You can call it before or after set_interrupt(); arming creates the pipe and wires it for you. Disabling restores the previous handler for the chosen signal.
Caveats: a long, non-yielding C/XS call defers the callback until it returns (use background_interrupt() if you need it to fire even then); and it claims a process-global signal - don't enable it on a signal your program already drives. See the example below.
background_interrupt($pin, $edge, $callback, $debounce_us)
Handles an interrupt in a background process with one call: it forks, arms the interrupt in the child, and runs $callback there on each edge while your main program does whatever it likes - true fire-while-busy, even during long blocking work. $callback receives ($edge, $timestamp_us). Arguments are validated (and croak) before forking; $debounce_us is optional.
Because the callback runs in a separate process it cannot see or change your main program's variables (use it for independent handlers - drive a pin, log, notify). Returns a handle:
my $h = background_interrupt(0, INT_EDGE_RISING, sub { ... });
$h->stop; # signal the child, run its ISR teardown, reap it
$h->pid; # the child PID
$h->running; # true while the child is alivestop is idempotent (safe to call repeatedly, and after the child has already exited). A handle going out of scope stops its child, and an END block reaps any still-running background children at exit, so a forgotten stop can't leak a zombie. Needs no threaded Perl. See the example below.
A trailing options hash reference may follow the arguments. The only option is results: when true, a defined value returned by $callback is shipped back to the parent, which drains it from the handle:
my $h = background_interrupt(0, INT_EDGE_RISING, sub {
my ($edge, $ts_us) = @_;
return "$edge\@$ts_us"; # reported to the parent
}, { results => 1 });
while (defined(my $msg = $h->read)) { # non-blocking drain
print "handler said: $msg\n";
}
# $h->fh gives the read filehandle, for select / IO::SelectWithout results (the default) the handler is fire-and-forget and the common case stays a one-liner.
background_interrupts([$pin, $edge, $callback, $debounce_us], ...)
Like background_interrupt(), but a single background child services many pins (instead of one child per pin). Pass one array-ref spec per pin; all are validated before forking, and the child arms them all and dispatches every edge from one loop. Returns a handle with the same stop/pid/ running, plus arm($pin) and disarm($pin):
my $h = background_interrupts(
[17, INT_EDGE_RISING, \&on_button],
[27, INT_EDGE_BOTH, \&on_sensor, 5000], # with debounce
);
$h->disarm(27); # stop servicing pin 27 (without killing the child)
$h->arm(27); # resume it
$h->stop; # tear down + reap the one childThe callbacks are fixed when the child forks - fork cannot carry new code across - so arm/disarm only toggle pins that were registered in the initial call (arming an unregistered pin croaks). Each callback runs in the child and cannot touch your main program's variables.
The shared-child handle has no results channel: calling $h->read or $h->fh on it croaks. Routing per-pin return values back through one multiplexed child is out of scope here - use a per-pin "background_interrupt($pin, $edge, $callback, $debounce_us)" with { results => 1 } when you need values back from the handler.
Example - single-threaded event loop (any Perl)
use WiringPi::API qw(setup pin_mode set_interrupt wait_interrupts
INT_EDGE_RISING);
setup();
pin_mode(0, 0);
set_interrupt(0, INT_EDGE_RISING, sub {
my ($edge, $ts_us) = @_;
print "edge $edge at $ts_us us\n";
});
wait_interrupts(1000) while 1; # dispatches in THIS processExample - background handling via fork
use WiringPi::API qw(setup pin_mode set_interrupt wait_interrupts
INT_EDGE_RISING);
setup(); # once, in the parent, before forking
pin_mode(0, 0);
my $pid = fork // die "fork: $!";
if ($pid == 0) { # child owns + dispatches the interrupt
set_interrupt(0, INT_EDGE_RISING, sub {
my ($edge, $ts_us) = @_;
# ... handle the edge ...
});
wait_interrupts(1000) while 1;
exit 0;
}
# parent is free to do other work; reap $pid at exitExample - hands-off in-process handling (auto_dispatch_interrupts)
Fire callbacks automatically in your own process, with no dispatch loop. The callback updates your program's own state (no locking needed):
use WiringPi::API qw(setup pin_mode set_interrupt auto_dispatch_interrupts
INT_EDGE_RISING);
setup();
pin_mode(0, 0);
auto_dispatch_interrupts(1); # callbacks now fire on their own
my $count = 0;
set_interrupt(0, INT_EDGE_RISING, sub { $count++ });
while (1) {
do_main_work(); # the callback fires between ops & in sleep
print "edges so far: $count\n";
sleep 1;
}Example - background process (background_interrupt)
Run an independent handler in its own process - it fires even while main is blocked in long work. The library owns the fork, the loop and the cleanup:
use WiringPi::API qw(setup pin_mode background_interrupt INT_EDGE_RISING);
setup();
pin_mode(0, 0);
my $h = background_interrupt(0, INT_EDGE_RISING, sub {
my ($edge, $ts_us) = @_;
# runs in the background on each rising edge - independent work only
});
for (1 .. 10) {
do_other_work(); # the handler fires on its own meanwhile
sleep 1;
}
$h->stop; # stops + reaps the background handlerCONCURRENCY / BACKGROUND WORKERS
worker() runs a piece of code in the background with the least possible user code: it owns the spawn mechanism, the loop and the lifecycle, so your body carries no fork, no use threads, no detach, no while (1) and no manual cleanup. It is the general-purpose sibling of "background_interrupt($pin, $edge, $callback, $debounce_us)".
This module needs neither threads nor a threaded Perl: worker() is fork-based by default and works on any Perl. An ithread mechanism is available as a documented opt-in (see mechanism below) for users who specifically want shared-memory ergonomics on a threaded Perl.
The setup-once-in-main contract: call setup() (or setup_gpio()) and do your pin_mode() calls once, in the parent, before starting a worker. A fork-based worker inherits that state; you drive the pins from inside the body.
The hands-off heartbeat LED - the helper owns the loop and the lifecycle:
use WiringPi::API qw(setup pin_mode write_pin worker);
setup();
pin_mode(2, 1); # OUTPUT, once in main
my $w = worker(sub { write_pin(2, 1); sleep 1;
write_pin(2, 0); sleep 1 });
# ... main does its own work ...
$w->stop; # idempotent; END reaps if forgottenworker(\&body, \%opts)
Spawns a background child that runs \&body repeatedly by default, and returns a handle (see "The worker handle" below). All arguments are validated before spawning, so a bad call croaks immediately rather than failing in the background.
\&body is mandatory and must be a CODE reference. \%opts, if given, must be a hash reference. The options are:
once => 1-
Run
\&bodya single time, then the child exits on its own ($w->runningbecomes false). Without this, the body loops until the worker is stopped. interval => $secs-
Pace the loop: sleep
$secs(a positive number, fractional allowed) between passes, so a periodic sampler/blinker needs nosleepof its own. The sleep wakes early when the worker is stopped, so$w->stopstays responsive even with a long cadence. results => 1-
Stream every defined value the body returns back to the parent, length-framed over an inherited pipe. Drain it with
$w->read(non-blocking) or select on$w->fh- identical tobackground_interrupt's results channel. -
Publish the body's return value as a lossy latest value: the parent reads the most recent value with
$w->value. The child never blocks on a slow or absent reader (a full pipe simply drops the update), so this suits a sampler whose intermediate readings don't matter. mechanism => 'fork' | 'thread'-
The spawn mechanism. Defaults to
'fork'(no threaded Perl required).'thread'runs the body in an ithread for shared-memory ergonomics; it requiresthreadsto be loaded (use threads;before callingworker()) and croaks with a clear message otherwise. Under'thread'theresultsandsharedpipe channels are rejected - share a variable and serialise it with "pi_lock($key)" / "pi_unlock($key)" instead.
The worker handle
worker() returns a handle - WiringPi::API::Worker for a fork worker, or WiringPi::API::WorkerThread for a thread worker - with the same shape as the "background_interrupt($pin, $edge, $callback, $debounce_us)" handle:
$w->stop-
Stop the worker and reap it. Idempotent - safe to call more than once, and a
DESTROYplus anENDblock reap the worker if you forget, so a missedstopcan't leak a zombie or an orphaned thread. $w->running-
True while the worker is still alive; false once it has stopped or (for
once => 1) finished its single pass. $w->pid-
The child's process id for a fork worker, or the thread id (tid) for a thread worker.
$w->read/$w->fh-
Drain the next streamed value / get the readable filehandle, when the worker was started with
results => 1(otherwiseundef). $w->value-
The latest published value, when the worker was started with
shared => 1(otherwiseundef).
Periodic sampler handing data back to main
use WiringPi::API qw(setup pin_mode analog_read worker);
setup();
pin_mode(0, 0); # INPUT, once in main
# Sample once a second; main only ever wants the latest reading.
my $w = worker(sub { analog_read(0) }, { interval => 1, shared => 1 });
while (1) {
my $latest = $w->value; # most recent sample, or undef yet
# ... act on $latest ...
sleep 5;
}
$w->stop;Shared-memory mechanism (opt-in ithread)
On a threaded Perl you can run the body in an ithread instead of a fork, and share state directly. Serialise access to shared state with the wiringPi mutex locks (see "THREAD/LOCK FUNCTIONS"):
use threads; # required for mechanism => 'thread'
use threads::shared;
use WiringPi::API qw(setup worker pi_lock pi_unlock);
setup();
my $count :shared = 0;
my $w = worker(sub {
pi_lock(0);
$count++;
pi_unlock(0);
select(undef, undef, undef, 0.1);
}, { mechanism => 'thread' });
# ... main reads $count under the same lock ...
$w->stop; # sets the stop flag and joins the threadADC FUNCTIONS
Analog to digital converters (ADC) allow you to read analog data on the Raspberry Pi, as the Pi doesn't have any analog input pins.
This section is broken down by type/model.
ADS1115 MODEL
ads1115_setup($pin_base, $addr)
Maps to `ads1115Setup(int pinBase, int addr)`.
The ADS1115 is a four channel, 16-bit wide ADC.
Parameters:
$pin_baseMandatory: Signed integer, higher than that of all GPIO pins. This is the base number we'll use to access the pseudo pins on the ADC. Example: If 400 is sent in, ADC pin A0 (or 0) will be pin 400, and AD3 (the fourth analog pin) will be 403.
Parameters:
$addrMandatory: Signed integer. This parameter depends on how you have the ADDR pin on the ADC connected to the Pi. Below is a chart showing if the ADDR pin is connected to the Pi Pin, you'll get the address. You can also use i2cdetect -y 1 to find out your ADC address.
Pin Address
---------------
Gnd 0x48
VDD 0x49
SDA 0x4A
SCL 0x4BSHIFT 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_baseMandatory: 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_pinsMandatory: 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_pinMandatory: Integer, the GPIO pin number connected to the register's DS pin (14). Can be any GPIO pin capable of output.
$clock_pinMandatory: Integer, the GPIO pin number connected to the register's SHCP pin (11). Can be any GPIO pin capable of output.
$latch_pinMandatory: Integer, the GPIO pin number connected to the register's STCP pin (12). Can be any GPIO pin capable of output.
SERIAL FUNCTIONS
These functions provide basic access to read and write to a serial device.
serial_open($device, $baud)
Maps to int serialOpen(const char *device, const int baud)
Opens a serial device for read/write access.
Parameters:
$deviceMandatory, String: The name of the serial device, eg: /dev/ttyACM0.
$baudMandatory, Integer: The speed of the serial device. (eg: 9600).
Return, Integer: The file descriptor of the device.
serial_close($fd)
Maps to void serialClose(const int fd)
Closes an already open serial device.
Parameters:
$fdMandatory, Integer: The file descriptor returned by your call to serial_open().
serial_flush($fd)
Maps to serialFlush(const int fd)
Flushes the serial device's buffer.
Parameters:
$fdMandatory, Integer: The file descriptor returned by your call to serial_open().
serial_data_avail($fd)
Maps to serialDataAvail(const int fd)
Check if there is any data available on the serial interface.
Parameters:
$fdMandatory, Integer: The file descriptor returned by your call to serial_open().
serial_get_char($fd)
Maps to serialGetchar(const int fd)
Read a single byte from the serial interface.
Parameters:
$fdMandatory, Integer: The file descriptor returned by your call to serial_open().
serial_put_char($fd, $char)
Maps to serialPutchar(const int fd, const unsigned char c)
Write a single byte to the interface.
Parameters:
$fdMandatory, Integer: The file descriptor returned by your call to serial_open().
$charMandatory, Byte: A single byte to write to the serial interface.
serial_puts($fd, $string)
Maps to serialPuts(const int fd, const char* string)
Write an arbitrary length string to the serial interface.
Parameters:
$fdMandatory, Integer: The file descriptor returned by your call to serial_open().
$stringMandatory, String: The content to write to the device.
serial_gets($fd, $nbytes)
Reads up to $nbytes bytes from the serial interface and returns them as a single string.
The read blocks only until the port's configured read timeout (the VTIME value set by serial_open()) elapses, so the returned string may be shorter than $nbytes if fewer bytes arrived in time (or the device closed). The result is binary-safe: embedded NUL bytes and trailing whitespace are preserved exactly as received.
Parameters:
$fdMandatory, Integer: The file descriptor returned by your call to serial_open().
$nbytesMandatory, Integer: The maximum number of bytes to read. Must be a non-negative integer.
Returns: A string of the bytes actually read (length 0 to $nbytes). Croaks on a read error.
I2C FUNCTIONS
These functions allow you to read and write devices on the Inter-Integrated Circuit (I2C) bus.
i2c_setup($addr)
Maps to int wiringPiI2CSetup(int devId)
Configures the I2C bus in preparation for communicating with a device.
Parameters:
$addrMandatory: Integer, the address of your device as seen by running for example: i2cdetect -y 1.
i2c_interface($device, $addr)
Maps to int wiringPiI2CSetupInterface(const char* device, int devId)
Like i2c_setup(), but lets you name the I2C device file explicitly (e.g. /dev/i2c-1) instead of relying on the default.
Parameters:
$deviceMandatory: String, the path to the I2C device file (e.g. /dev/i2c-1).
$addrMandatory: Integer, the I2C address of the device.
Returns: Integer, the file descriptor for the device (as i2c_setup()).
i2c_read($fd)
Performs a quick one-off, one-byte read without needing to specify the register value. Some very simple devices operate without register values needed.
Parameters:
$fdMandatory: Integer, the file descriptor that was returned from i2c_setup().
Returns: A single byte of data from the device on the I2C bus.
i2c_read_byte($fd, $reg)
Reads a single byte from the specified register.
Parameters:
$fdMandatory: Integer, the file descriptor that was returned from i2c_setup().
$regMandatory: Integer, the register to read data from.
Returns: A single byte of data from the device on the I2C bus from the selected register.
i2c_read_word($fd, $reg)
Reads two bytes from the specified register.
Parameters:
$fdMandatory: Integer, the file descriptor that was returned from i2c_setup().
$regMandatory: Integer, the register to read data from.
Returns: Integer, two bytes of data from the device on the I2C bus from the selected register.
i2c_write($fd, $data)
Performs a quick one-off, one-byte write without needing to specify the register value. Some very simple devices operate without register values needed.
Parameters:
$fdMandatory: Integer, the file descriptor that was returned from i2c_setup().
$dataMandatory: Integer, the value to write to the device.
Returns: The value of the ioctl() call, 0 on success.
i2c_write_byte($fd, $reg, $data)
Writes a single byte to the register specified.
Parameters:
$fdMandatory: Integer, the file descriptor that was returned from i2c_setup().
$regMandatory: Integer, the register to write the data to.
$dataMandatory: Integer, the value to write to the device.
Returns: The value of the ioctl() call, 0 on success.
i2c_write_word($fd, $reg, $data)
Writes two bytes to the register specified.
Parameters:
$fdMandatory: Integer, the file descriptor that was returned from i2c_setup().
$regMandatory: Integer, the register to write the data to.
$dataMandatory: Integer, the value to write to the device.
Returns: The value of the ioctl() call, 0 on success.
i2c_read_block($fd, $reg, $size)
Maps to int wiringPiI2CReadBlockData(int fd, int reg, uint8_t *values, uint8_t size)
Reads up to $size bytes (max 255) in a single block transaction starting at register $reg.
Parameters:
$fdMandatory: Integer, the file descriptor returned from i2c_setup().
$regMandatory: Integer, the register to read from.
$sizeMandatory: Integer 0-255, the number of bytes to read.
Returns: A list of the bytes read (its length is the actual count returned by the device). Croaks on a read error.
i2c_raw_read($fd, $size)
Maps to int wiringPiI2CRawRead(int fd, uint8_t *values, uint8_t size)
As i2c_read_block(), but reads directly from the device without a register address.
Parameters:
$fdMandatory: Integer, the file descriptor returned from i2c_setup().
$sizeMandatory: Integer 0-255, the number of bytes to read.
Returns: A list of the bytes read. Croaks on a read error.
i2c_write_block($fd, $reg, \@bytes)
Maps to int wiringPiI2CWriteBlockData(int fd, int reg, const uint8_t *values, uint8_t size)
Writes a block of up to 255 bytes in a single transaction starting at register $reg.
Parameters:
$fdMandatory: Integer, the file descriptor returned from i2c_setup().
$regMandatory: Integer, the register to write to.
\@bytesMandatory: An array reference of byte values (0-255), at most 255 elements.
Returns: The value of the underlying call, 0 on success.
i2c_raw_write($fd, \@bytes)
Maps to int wiringPiI2CRawWrite(int fd, const uint8_t *values, uint8_t size)
As i2c_write_block(), but writes directly to the device without a register address.
Parameters:
$fdMandatory: Integer, the file descriptor returned from i2c_setup().
\@bytesMandatory: An array reference of byte values (0-255), at most 255 elements.
Returns: The value of the underlying call, 0 on success.
SPI FUNCTIONS
These functions allow you to set up and read/write to devices on the serial peripheral interface (SPI) bus.
spi_setup
Maps to int wiringPiSPISetup(int channel, int speed)
Configure the SPI bus for use to communicate with its connected devices.
Parameters:
$channelMandatory: Integer, the SPI channel the device is connected to. 0 for channel /dev/spidev0.0 and 1 for channel /dev/spidev0.1.
$speedOptional: Integer, the speed for SPI communication. Defaults to 1000000 (1MHz).
Note that it's wise to do some error checking when attempting to open the SPI bus. We return the return value of an ioctl() call, so this does the trick:
if ((spi_setup(0, 1000000) < 0){
croak "failed to open the SPI bus...\n";
}spi_data
Maps to: int spiDataRW(int channel, AV* data, int len), which calls int wiringPiSPIDataRW(int channel, unsigned char* data, int len).
Writes, and then reads a block of data over the SPI bus. The read following the write is read into the transmit buffer, so it'll be overwritten and sent back as a Perl array.
Parameters:
$channelMandatory: Integer, the SPI channel the device is connected to. 0 for channel /dev/spidev0.0 and 1 for channel /dev/spidev0.1.
$dataMandatory: An array reference, with each element containing a single unsigned 8-bit byte that you want to write to the device. If you want to read-only, send in an aref with all the elements set to 0. These will be overwritten with the read data, and sent back as a Perl array.
$lenMandatory: Integer, the number of bytes contained in the $data parameter array reference that will be sent to the device. I could just count the number of elements, but this keeps things consistent, and ensures the user is fully aware of the data they are sending on the bus.
Returns a Perl array containing the same number of elements you sent in.
# read-only... three bytes
my $buf = [0x00, 0x00, 0x00];
my @ret = spiDataRW($chan, $buf, 3);spi_get_fd($channel)
Maps to int wiringPiSPIGetFd(int channel)
Returns the open file descriptor for an SPI channel that was previously set up.
Parameters:
$channelMandatory: Integer, 0 or 1.
spi_setup_mode($channel, $speed, $mode)
Maps to int wiringPiSPISetupMode(int channel, int speed, int mode)
As spi_setup(), but also selects the SPI mode (clock polarity/phase).
Parameters:
$channelMandatory: Integer, 0 or 1.
$speedMandatory: Integer, the bus speed in Hz (e.g. 1000000).
$modeMandatory: Integer 0-3, the SPI mode.
Returns: Integer, the file descriptor on success or -1 on error.
spi_close($channel)
Maps to int wiringPiSPIClose(const int channel)
Closes the given SPI channel, releasing its file descriptor.
Parameters:
$channelMandatory: Integer, 0 or 1.
BMP180 PRESSURE SENSOR FUNCTIONS
These functions configure and fetch data from the BMP180 barometric pressure sensor.
bmp180_setup($pin_base)
Configures the system to read from a BMP180 pressure sensor.
These functions can not return the raw values from the sensor. See each function documentation to learn how to do so.
Parameters:
$pin_baseMandatory: Integer, the number at which to place the pseudo analog pins in the GPIO stack. For example, if you use 200, pin 200 represents the temperature feature of the sensor, and 201 represents the pressure feature.
Return: undef.
bmp180_temp($pin, $want)
Returns the temperature from the sensor.
Parameters:
$pinMandatory: Integer, represents the $pin_base used in the setup function + 0.
$wantOptional: 'c' for Celcius, and 'f' for Farenheit. Defaults to 'f'.
Return: A floating point number in the requested conversion.
NOTE: To get the raw sensor temperature, call the C function bmp180Temp($pin) directly.
bmp180_pressure($pin)
Returns the current air pressure in kPa.
Parameters:
$pinMandatory: Integer, represents the $pin_base used in the setup function + 1.
Return: A floating point number that represents the air pressure in kPa.
NOTE: To get the raw sensor pressure, call the C function bmp180Pressure($pin) directly.
DEVELOPER FUNCTIONS
These functions are under testing, or don't potentially have a use to the end user. They may be risky to use, so use at your own risk.
The functions in this section do not have a Perl wrapper equivalent.
pseudoPinsSetup(int pinBase)
This function allocates shared memory for the pseudo pins used to communicate with devices that are beyond the reach of the Pi's GPIO (eg: shift registers, ADCs etc).
Parameters:
pinBaseMandatory: Integer, larger than the highest GPIO pin number. Eg: 500 will be the base for the analog pins on an ADS1115 ADC. Pin A0 would be 500, and ADC pin A3 would be 503.
pinModeAlt(int pin, int mode)
Undocumented function that allows any pin to be set to any mode.
The alternate-function map differs between the Broadcom SoC (Pi 0-4) and the RP1 chip on the Pi 5; see "pin_mode_alt($pin, $alt)" for the mode values and the per-SoC differences in what each one selects.
Parameters:
pinMandatory: Signed integer, any valid GPIO pin number.
modeMandatory: Signed integer, any valid wiringPi pin mode.
digitalWriteByte(const int value)
Writes an 8-bit byte to the first eight GPIO pins.
Parameters:
valueMandatory: Unsigned int, the byte value you want to send in.
Return: void
digitalWriteByte2(const int value)
Same as "digitalWriteByte(const int value)", but writes to the second group of eight GPIO pins.
digitalReadByte()
Reads an 8-bit byte from the first eight GPIO pins on the Pi.
Takes no parameters, returns the byte value as an unsigned int.
digitalReadByte2()
Same as "digitalReadByte()", but reads from the second group of eight GPIO pins.
AUTHOR
Steve Bertrand, <steveb@cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2017-2026 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.