/ 
RPi-WiringPi-3.1802
⭐ Starred 7 / README.md

NAME

RPi::WiringPi - Perl interface to Raspberry Pi's board, GPIO, LCDs and other various items

Table of Contents

SYNOPSIS

Please see the FAQ for full usage details.

   use RPi::WiringPi;
   use RPi::Const qw(:all);

   my $pi = RPi::WiringPi->new;

   # For the below handful of system methods, see RPi::SysInfo

   my $mem_percent = $pi->mem_percent;
   my $cpu_percent = $pi->cpu_percent;
   my $cpu_temp    = $pi->core_temp;
   my $gpio_info   = $pi->gpio_info;
   my $raspi_conf  = $pi->raspi_config;
   my $net_info    = $pi->network_info;
   my $file_system = $pi->file_system;
   my $hw_details  = $pi->pi_details;
   my $pi_model    = $pi->pi_model;

   # Pin

   my $pin = $pi->pin(5);
   $pin->mode(OUTPUT);
   $pin->write(ON);

   my $num     = $pin->num;
   my $mode    = $pin->mode;
   my $state   = $pin->read;

   # Cleanup all pins and reset them to default before exiting your program

   $pi->cleanup;

DESCRIPTION

This is the root module for the RPi::WiringPi system. It interfaces to a Raspberry Pi board, its accessories and its GPIO pins via the wiringPi library through the Perl wrapper WiringPi::API module, and various other custom device specific modules.

wiringPi must be installed prior to installing/using this module (v3.18).

We always and only use the GPIO pin numbering scheme.

This module is essentially a 'manager' for the sub-modules (ie. components). You can use the component modules directly, but retrieving components through this module instead has many benefits. We maintain a registry of pins and other data, and reset the Pi back to default settings when your program ends (on normal exit, on an uncaught die(), and on SIGINT/SIGTERM), so components are not left in an inconsistent state. Component modules do none of these things.

There are a basic set of constants that can be imported. See RPi::Const.

It's handy to have access to a pin mapping conversion chart. There's an excellent pin scheme map for reference at pinout.xyz. You can also run the pinmap command that was installed by this module, or wiringPi's gpio readall command.

BASE METHODS

new([%args])

Returns a new RPi::WiringPi object. We exclusively use the GPIO (Broadcom (BCM) GPIO) pin numbering scheme.

Parameters:

setup => $string

Optional, String: Which wiringPi setup routine (and therefore pin numbering scheme) to initialize the board with. Matching is case-insensitive on the first letter:

'gpio'      - GPIO (BCM) numbering; the default if not sent in
'wiringpi'  - wiringPi's own (WPI) numbering
'none'      - skip board setup entirely (the pin scheme remains
              uninitialized; primarily for testing)

Any other value will croak. Note that if another application in the process has already run a setup routine (signalled via the RPI_PIN_MODE environment variable), that existing scheme is honoured and this parameter is ignored.

shm_key => $string

By default, we use the key rpiw as the shared memory segment key. You can change this if desired. Useful for separating "groups" of Pi objects from one another (for example, production scripts can operate at the same time as test scripts, and both use their own shared memory pool).

fatal_exit => $bool

Optional: Controls what happens when we trap a SIGINT (Ctrl-C) or SIGTERM. In both cases we first reset the Pi hardware to a safe state. By default (fatal_exit true), we then re-raise the signal so the program terminates as it normally would. Set fatal_exit to false (0) to perform the cleanup and then continue running your script (eg. for unit-test work, or to allow your own signal handling to take over).

With multiple Pi objects in a single process, the signal is re-raised only if every live object has fatal_exit true; any object created with fatal_exit => 0 keeps the process running.

Note that this only affects trapped signals. Hardware cleanup on a normal exit or on an uncaught die() always happens automatically (via the object's END/ DESTROY handling); we do not trap $SIG{__DIE__}, so a die() you catch yourself with eval will not disturb your pins. Any $SIG{INT}/$SIG{TERM} handler you installed before creating the object is chained to, not replaced.

rpi_register => $bool

Optional: Set this value to false (0) to bypass the Pi object registration in the meta data. This will also prevent pins from being registered as well. If set to false, no object or pin cleanup will take place at the end of a program run.

rpi_register_pins => $bool

Optional: Similar to rpi_register, but only bypasses the pin registration. Object registration will still occur, and the object will be cleaned up after but the pins will not. Should only be used for testing.

adc

There are two different ADCs that you can select from. The default is the ADS1x15 series:

ADS1115

Returns a RPi::ADC::ADS object, which allows you to read the four analog input channels on an Adafruit ADS1xxx analog to digital converter.

Parameters:

The default (no parameters) is almost always enough, but please do review the documentation in the link above for further information, and have a look at the ADC tutorial section in this distribution.

MCP3008

You can also use an RPi::ADC::MCP3008 ADC.

Parameters:

   model => 'MCP3008'

Mandatory, String. The exact quoted string above.

   channel => $channel

Mandatory, Integer. 0 or 1 for the Pi's onboard hardware CS/SS CE0 and CE1 pins, or any GPIO number above 1 in order to use an arbitrary GPIO pin for the CS pin, and we'll do the bit-banging of the SPI bus automatically.

bmp

Returns a RPi::BMP180 object, which allows you to return the current temperature in farenheit or celcius, along with the ability to retrieve the barometric pressure in kPa.

dac

Returns a RPi::DAC::MCP4922 object (supports all 49x2 series DACs). These chips provide analog output signals from the Pi's digital output. Please see the documentation of that module for further information on both the configuration and use of the DAC object.

Parameters:

   model => 'MCP4922'

Optional, String. The model of the DAC you're using. Defaults to MCP4922.

   channel => 0|1

Mandatory, Bool. The SPI channel to use.

   cs => $pin

Mandatory, Integer. A valid GPIO pin that the DAC's Chip Select is connected to.

There are a handful of other parameters that aren't required. For those, please refer to the RPi::DAC::MCP4922 documentation.

dpot($cs, $channel)

Returns a RPi::DigiPot::MCP4XXXX object, which allows you to manage a digital potentiometer (only the MCP4XXXX versions are currently supported).

See the linked documentation for full documentation on usage, or the RPi::WiringPi::FAQ for usage examples.

gps

Returns a GPSD::Parse object, allowing you to track your location.

The GPS distribution requires gpsd to be installed and running. All parameters for the GPS can be sent in here and we'll pass them along. Please see the link above for the full documentation on that module.

hcsr04($trig, $echo)

Returns a RPi::HCSR04 ultrasonic distance measurement sensor object, allowing you to retrieve the distance from the sensor in inches, centimetres or raw data.

Parameters:

   $trig

Mandatory, Integer: The trigger pin number, in GPIO numbering scheme.

   $echo

Mandatory, Integer: The echo pin number, in GPIO numbering scheme.

hygrometer($pin)

Returns a RPi::DHT11 temperature/humidity sensor object, allows you to fetch the temperature (celcius or farenheit) as well as the current humidity level.

Parameters:

   $pin

Mandatory, Integer: The GPIO pin the sensor is connected to.

i2c($addr, [$device])

Creates a new RPi::I2C device object which allows you to communicate with the devices on an I2C bus.

See the linked documentation for full documentation on usage, or the RPi::WiringPi::FAQ for usage examples.

Aruino note: If using I2C with an Arduino, the Pi may speak faster than the Arduino can. If this is the case, try lowering the I2C bus speed on the Pi:

   dtparam=i2c_arm_baudrate=10000

lcd(...)

Returns a RPi::LCD object, which allows you to fully manipulate LCD displays connected to your Raspberry Pi.

Please see the linked documentation for information regarding the parameters required.

oled([$model], [$i2c_addr], [$display_splash_page])

Returns a specific RPi::OLED::SSD1306 OLED display object, allowing you to display text, characters and shapes to the screen.

Currently, only the 128x64 size model is offered, see the RPi::OLED::SSD1306::128_64 documentation for full usage details.

Parameters:

$model

Optional, String: The screen size of the OLED you've got. Valid options are 128x64, 128x32 and 96x16. Currently, only the 128x64 option is valid, and it's the default if not sent in.

$i2c_addr

Optional, Integer: The I2C address of your display. Defaults to 0x3C if not sent in.

$display_splash_page

Optional, Bool: Whether to display the splash page when the display is initialized. Defaults to true (1); send in 0 to skip it.

pin($pin_num, $comment)

Returns a RPi::Pin object, mapped to a specified GPIO pin, which you can then perform operations on. See that documentation for full usage details.

Parameters:

$pin_num

Mandatory, Integer: The pin number to attach to.

$comment

Optional, String: A label stored alongside the pin's registration (visible in the metadata store and used by the test suite). Defaults to none.

rtc

Creates a new RPi::RTC::DS3231 object which provides access to the DS3231 or DS1307 real-time clock modules.

See the linked documentation for full documentation on usage, or the RPi::WiringPi::FAQ for some usage examples.

Parameters:

   $i2c_addr

Optional, Integer: The I2C address of the RTC module. Defaults to 0x68 for the DS3231 unit.

eeprom

Creates and returns a new RPi::EEPROM::AT24C32 object for reading and writing to.

See the linked documentation for full documentation on usage, parameters or the RPi::WiringPi::FAQ for some usage examples.

expander

Creates a new RPi::GPIOExpander::MCP23017 GPIO expander chip object. This adds an additional 16 pins across two banks (8 pins per bank).

See the linked documentation for full documentation on usage, or the RPi::WiringPi::FAQ for some usage examples.

Parameters:

   $i2c_addr

Optional, Integer: The I2C address of the device. Defaults to 0x20.

   $expander

Optional, String: The GPIO expander device type. Defaults to MCP23017, and currently, this is the only option available.

serial($device, $baud)

Creates a new RPi::Serial object which allows basic read/write access to a serial bus.

See the linked documentation for full documentation on usage, or the RPi::WiringPi::FAQ for usage examples.

NOTE: On the Pi 3 and Pi 4, Bluetooth occupies the primary UART, leaving the header pins (14, 15) on the mini-UART (/dev/ttyS0). To put the full PL011 UART back on the header you must disable Bluetooth in the /boot/firmware/config.txt file (/boot/config.txt on releases before Bookworm):

dtoverlay=pi3-disable-bt-overlay

On the Pi 5, Bluetooth has its own dedicated UART, so no disable-bt overlay is needed; simply enable the header UART (/dev/ttyAMA0) with enable_uart=1.

servo($pin_num)

This method configures PWM clock and divisor to operate a typical 50Hz servo, and returns a special RPi::Pin object. These servos have a left pulse of 50, a centre pulse of 150 and a right pulse of 250. On exit of the program (or a crash), we automatically clean everything up properly.

Parameters:

   $pin_num

Mandatory, Integer: The pin number (technically, this *must* be 18 on the Raspberry Pi 3, as that's the only hardware PWM pin.

   %pwm_config

Optional, Hash. This parameter should only be used if you know what you're doing and are having very specific issues.

Keys are clock with a value that coincides with the PWM clock speed. It defaults to 192. The other key is range, the value being an integer that sets the range of the PWM. Defaults to 2000.

Example:

   my $servo = $pi->servo(18);

   $servo->pwm(50);  # all the way left
   $servo->pwm(250); # all the way right

shift_register($base, $num_pins, $data, $clk, $latch)

Allows you to access the output pins of up to four 74HC595 shift registers in series, for a total of eight new output pins per register. Numerous chains of four registers are permitted, each chain uses three GPIO pins.

Parameters:

   $base

Mandatory: Integer, represents the number at which you want to start referencing the new output pins attached to the register(s). For example, if you use 100 here, output pin 0 of the register will be 100, output 1 will be 101 etc.

   $num_pins

Mandatory: Integer, the number of output pins on the registers you want to use. Each register has eight outputs, so if you have a single register in use, the maximum number of additional pins would be eight.

   $data

Mandatory: Integer, the GPIO pin number attached to the DS pin (14) on the shift register.

   $clk

Mandatory: Integer, the GPIO pin number attached to the SHCP pin (11) on the shift register.

   $latch

Mandatory: Integer, the GPIO pin number attached to the STCP pin (12) on the shift register.

spi($channel, $speed)

Creates a new RPi::SPI object which allows you to communicate on the Serial Peripheral Interface (SPI) bus with attached devices.

See the linked documentation for full documentation on usage, or the RPi::WiringPi::FAQ for usage examples.

stepper_motor($pins)

Creates a new RPi::StepperMotor object which allows you to drive a 28BYJ-48 stepper motor with a ULN2003 driver chip.

See the linked documentation for full usage instructions and the optional parameters.

Parameters:

   pins => $aref

Mandatory, Array Reference: The ULN2003 has four data pins, IN1, IN2, IN3 and IN4. Send in the GPIO pin numbers in the array reference which correlate to the driver pins in the listed order.

   speed => 'half'|'full'

Optional, String: By default we run in "half speed" mode. Essentially, in this mode we run through all eight steps. Send in 'full' to double the speed of the motor. We do this by skipping every other step.

   delay => Float|Int

Optional, Float or Int: By default, between each step, we delay by 0.01 seconds. Send in a float or integer for the number of seconds to delay each step by. The smaller this number, the faster the motor will turn.

CORE PI SYSTEM METHODS

Core methods are inherited in and documented in RPi::WiringPi::Core. See that documentation for full details of each one. I've included a basic description of them here.

gpio_layout

Returns the GPIO layout, which in essence is the Pi board revision number.

io_led

Turn the disk IO (green) LED on or off.

pwr_led

Turn the power (red) LED on or off.

identify

Toggles the power led off and disk IO led on which allows external physical identification of the Pi you're running on.

label

Sets an internal label/name to your RPi::WiringPi Pi object.

pin_scheme

Returns the current pin mapping scheme in use within the object.

pin_map

Returns a hash reference mapping of the physical pin numbers to a pin scheme's pin numbers.

pin_to_gpio

Converts a pin number from any non-GPIO (BCM) scheme to GPIO (BCM) scheme.

wpi_to_gpio

Converts a wiringPi pin number to GPIO pin number.

phys_to_gpio

Converts a physical pin number to the GPIO pin number.

pwm_range

Set/get the PWM range.

pwm_mode

Set/get the PWM mode.

pwm_clock

Set/get the PWM clock.

registered_pins

Returns an array reference of all pin numbers currently registered in the system. Used primarily for cleanup functionality.

register_pin

Registers a pin with the system for error checking, and proper resetting in the cleanup routines.

unregister_pin

Removes an already registered pin.

cleanup

Cleans up the entire system, resetting all pins and devices back to the state we found them in when we initialized the system. It also releases any armed interrupts (via WiringPi::API::stop_interrupts()) - stopping the wiringPi ISR threads and closing the event pipe - so you don't have to do that yourself at teardown.

Only the process that created the object performs the cleanup: in a forked child the call is a no-op, so a child can't reset pins or mutate the shared metadata on the parent's behalf when it exits.

ADDITIONAL PI SYSTEM METHODS

We also include in the Pi object several hardware-type methods brought in from RPi::SysInfo. They are loaded through RPi::WiringPi::Core via inheritance. See the RPi::SysInfo documentation for full method details.

   my $mem_percent = $pi->mem_percent;
   my $cpu_percent = $pi->cpu_percent;
   my $cpu_temp    = $pi->core_temp;
   my $gpio_info   = $pi->gpio_info;
   my $raspi_conf  = $pi->raspi_config;
   my $net_info    = $pi->network_info;
   my $file_system = $pi->file_system;
   my $hw_details  = $pi->pi_details;

cpu_percent

Returns the current CPU usage.

mem_percent

Returns the current memory usage.

core_temp

Returns the current temperature of the CPU core.

gpio_info

Returns the current status and configuration of one, many or all of the GPIO pins.

raspi_config

Returns the live vcgencmd get_config values plus the non-comment directives from the active config.txt (/boot/firmware/config.txt on Bookworm and later, falling back to /boot/config.txt on older releases).

network_info

Returns the network configuration of the Pi, via ifconfig where the net-tools package is installed, falling back to ip addr where it is not (as on current Raspberry Pi OS Lite).

file_system

Returns current disk and mount information.

pi_details

Returns various information on both the hardware and OS aspects of the Pi.

pi_model

Returns the normalized Raspberry Pi board name (eg. Raspberry Pi 5 Model B Rev 1.1), read from the devicetree model with a /proc/cpuinfo revision-code decode fallback. Works across the Pi 0 through 5.

INTERRUPT METHODS

Arm an interrupt on a pin with $pin->set_interrupt($edge, $callback) (see RPi::Pin). As of WiringPi::API 3.18 the callback must be a code reference, and it runs in your own interpreter when you service the interrupt rather than in the wiringPi ISR thread. The following methods drive that dispatch. See Interrupt usage in the FAQ for a complete example.

wait_interrupts($timeout_ms)

Blocks until an edge arrives or $timeout_ms milliseconds elapse, then runs all pending interrupt callbacks. Returns the number of callbacks dispatched. Call it in a loop to handle interrupts:

$pi->wait_interrupts(1000) while 1;

run_interrupt_loop($timeout_ms, $max)

A blocking dispatch loop, so you don't have to write the wait_interrupts ... while 1 yourself. Repeatedly dispatches and returns the total number of events handled. It runs until $pi->stop_interrupt_loop is called (from a callback or a signal handler) or, if you pass $max, until that many events have been dispatched.

$pi->run_interrupt_loop;        # block, dispatching, until stop_interrupt_loop

Parameters:

$timeout_ms

Optional, Integer: The per-iteration poll granularity in milliseconds (how long each underlying wait_interrupts blocks waiting for an edge). Defaults to 1000.

$max

Optional, Integer: The maximum number of events to dispatch before returning. If omitted, the loop only ends when $pi->stop_interrupt_loop is called.

stop_interrupt_loop

Breaks out of run_interrupt_loop at the next iteration. Safe to call from a callback or a signal handler.

dispatch_interrupts

Runs all pending interrupt callbacks without blocking, and returns the number dispatched. Use this instead of wait_interrupts when you already block elsewhere (eg. in your own event loop).

stop_interrupts

Releases every armed interrupt: stops the wiringPi ISR threads and closes the event pipe. The object's cleanup calls this for you automatically, so you only need it to disarm interrupts while the program keeps running.

last_interrupt

Returns a hash reference describing the most recently dispatched interrupt event - { pin, pin_bcm, edge, status, ts_us } - or undef if none has fired yet. Because the callback only receives ($edge, $timestamp_us), this lets it (or your main loop) recover the BCM pin and status; useful when one handler is armed on several pins. Like auto_dispatch_interrupts, it reports a process-wide value (the last event on any pin), so it lives on the Pi object.

auto_dispatch_interrupts($bool, $signal)

Enables (1) or disables (0) async auto-dispatch for the whole process. When enabled, $pin->set_interrupt callbacks fire automatically at Perl safe points (via SIGIO) with no wait_interrupts/dispatch_interrupts loop, and may touch your program's variables with no locking. The optional $signal picks the delivery signal (default SIGIO; pass eg 'USR1' to avoid clashing with other SIGIO users). This is a process-global switch (it affects every armed pin), which is why it lives on the Pi object rather than on an individual pin. A long, non-yielding C/XS call defers the callback until it returns - use $pin->background_interrupt (see RPi::Pin) if you need it to fire even then.

interrupt_buffer($bytes)

Gets (no argument) or sets the capacity of the interrupt queue - the kernel pipe that absorbs edge bursts. On overflow the newest edges are dropped (never merged or blocked) and counted, so raise this if a fast source outpaces your dispatch. May be set before arming and persists across teardown. Process-wide, so it lives on the Pi object. See interrupt_buffer in WiringPi::API for details.

interrupt_dropped

Returns the running total of interrupt events dropped because the queue (see interrupt_buffer) overflowed. A non-zero count means a source is outpacing your dispatch - raise interrupt_buffer or dispatch more often. Process-wide, so it lives on the Pi object. See interrupt_dropped in WiringPi::API for details.

background_interrupts([$pin, $edge, $callback, $debounce], ...)

Handles many pins in a single background child (rather than one child per pin via $pin->background_interrupt). Pass one array-ref spec per pin; the returned handle adds $h->arm($pin) / $h->disarm($pin) (toggling pins registered at creation) to the usual stop/pid/running. Because it spans several pins it lives on the Pi object, not on a single pin. See background_interrupts in WiringPi::API for details.

Dependency note: the per-pin $pin->background_interrupt form referenced above requires RPi::Pin 2.3609 or greater (the version this distribution already requires). To drive multiple pins from a single background child rather than one child per pin, use this $pi->background_interrupts method.

worker(\&body, \%opts)

Runs \&body as a hands-off background task, hiding the spawn mechanism, the loop, and the lifecycle - the GPIO sibling of background_interrupts. By default it forks a child (no use threads required) that runs body repeatedly, and returns a WiringPi::API::Worker handle:

pin_mode(2, 1);                                   # OUTPUT, once in main

my $w = $pi->worker(sub {
    digital_write(2, 1); sleep 1;
    digital_write(2, 0); sleep 1;
});

# ... main does its own work ...

$w->stop;                                         # idempotent

The handle carries $w->stop (idempotent), $w->pid, and $w->running, matching the interrupt handle. You normally need not call stop at all: $pi->cleanup (and therefore DESTROY) automatically stops every worker started through this method, and a forked child never reaps the parent's workers.

\%opts mirrors WiringPi::API::worker() exactly:

All argument validation happens in the low-level layer, so an invalid body, interval, or mechanism croaks before anything is spawned. See worker in WiringPi::API and RPi::WiringPi::WORKERS for full details.

RUNNING TESTS

Please see RUNNING TESTS in the FAQ.

TROUBLESHOOTING

Please read through the SETUP section in the FAQ.

AUTHOR

Steve Bertrand, steveb@cpan.org

COPYRIGHT AND LICENSE

Copyright (C) 2016-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.