The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


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


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;

    # pin

    my $pin = $pi->pin(5);

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

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



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 (v2.36+).

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. We also trap $SIG{__DIE__} and $SIG{INT}, so that in the event of a crash, we can reset the Pi back to default settings, 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 You can also run the pinmap command that was installed by this module, or wiringPi's gpio readall command.



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


    fatal_exit => $bool

Optional: We trap all die() calls and clean up for safety reasons. If a call to die() is trapped, by default, we clean up, and then exit(). Set fatal_exit to false (0) to perform the cleanup, and then continue running your script.

We recommend only disabling this feature if you're doing unit test work, want to allow other exit traps to catch, allow the Pi to continue on working after a fatal error etc. If disabled, you will be responsible for doing your own cleanup of the Pi hardware configuration on exit.


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


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


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.


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


    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.


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.


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.


    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.


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.



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


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


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



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:



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])

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.



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.


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


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.



Mandatory, Integer: The pin number to attach to.


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.



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


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.



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


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: Bluetooth on the Pi overlays the serial pins (14, 15) on the Pi. To use serial, you must disable bluetooth in the /boot/config.txt file:



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.



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


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.


    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.



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.


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.


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


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


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.


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.


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


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


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


Turn the power (red) LED on or off.


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


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


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


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


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


Converts a wiringPi pin number to GPIO pin number.


Converts a physical pin number to the GPIO pin number.


Set/get the PWM range.


Set/get the PWM mode.


Set/get the PWM clock.


Exports a pin if running under the setup_sys() initialization scheme.


Un-exports a pin if running under the setup_sys() initialization scheme.


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


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


Removes an already registered pin.


Cleans up the entire system, resetting all pins and devices back to the state we found them in when we initialized the system.


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;


Returns the current CPU usage.


Returns the current memory usage.


Returns the current temperature of the CPU core.


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


Returns a list of all configured parameters in the /boot/config.txt file.


Returns the network configuration of the Pi.


Returns current disk and mount information.


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


Please see RUNNING TESTS in the FAQ.


Please read through the SETUP section in the FAQ.


Steve Bertrand, <>


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