RPi-WiringPi
view release on metacpan or search on metacpan
lib/RPi/WiringPi/FAQ.pod view on Meta::CPAN
i2cdetect -y 0
First thing you need to do is enable the I2C bus. You can do so in
C<raspi-config>, or ensure the C<dtparam=i2c_arm> directive is set to C<on> in the
C</boot/firmware/config.txt> file (C</boot/config.txt> on releases before
Bookworm):
dtparam=i2c_arm=on
B<Note>: If you get permission errors accessing the I2C bus, you may need to add
your user (eg. C<pi>) to the C<i2c> group:
sudo adduser pi i2c
B<Note>: The test suite gates tests that require a live I2C bus behind the
C<RPI_I2C> environment variable. If the I2C bus is disabled (or you simply
don't want to exercise it), leave C<RPI_I2C> unset and those tests will be
skipped rather than failing. To run them, enable the bus as above and set the
variable before running the suite:
RPI_I2C=1
=head2 Arduino I2C configuration
Often, the default speed of the I2C bus master is too fast for an Arduino. If
you do not get any results, try changing the speed. On a Raspberry Pi, you do
that by setting the C<dtparam=i2c_arm_baudrate> directive in the
C</boot/firmware/config.txt> file (C</boot/config.txt> on releases before
Bookworm):
dtparam=i2c_arm_baudrate=10000
=head2 SPI configuration
First thing you need to do is enable the SPI bus. You can do so in
C<raspi-config>, or ensure the C<dtparam=spi> directive is set to C<on> in the
C</boot/firmware/config.txt> file (C</boot/config.txt> on releases before
Bookworm):
dtparam=spi=on
NOTE: If you get permission errors accessing the SPI bus, you may need to add
the C<pi> user to the C<spi> group:
sudo adduser pi spi
=head2 Serial configuration
To use GPIO pins 14 (TXD) and 15 (RXD) as a serial interface, the procedure
differs by board. On B<all> boards, first free the port from the kernel console:
in C<raspi-config>, under C<Interface Options -E<gt> Serial Port>, answer B<no>
to the login shell and B<yes> to the serial hardware.
B<Raspberry Pi 3 / 4 (and Zero W):> the on-board Bluetooth modem is wired to the
primary PL011 UART, leaving GPIO 14/15 on the inferior, baud-unstable mini-UART
(C</dev/ttyS0>). To move the good UART onto the header pins you must disable
Bluetooth. Edit C</boot/firmware/config.txt> (C</boot/config.txt> on releases
before Bookworm) and add:
enable_uart=1
dtoverlay=disable-bt
With that overlay the header serial port becomes C</dev/ttyAMA0>.
B<Raspberry Pi 5:> Bluetooth has its B<own dedicated UART> and is B<not> shared
with the GPIO 14/15 pins, so there is nothing to disable. Just enable the header
UART in C</boot/firmware/config.txt>:
enable_uart=1
The header serial port is C</dev/ttyAMA0>. (Note that on the Pi 5 C</dev/serial0>
maps to the separate 3-pin debug-UART connector, B<not> the header pins.)
Save the file, then reboot the Pi.
=head1 PI
=head2 Create a Raspberry Pi object
First thing that needs doing is some back-end Pi configuration. We take care of
that automatically during the Raspberry Pi object creation. Upon instantiation,
we set the system to use the GPIO pin numbering scheme.
my $pi = RPi::WiringPi->new;
=head2 Board revision
The board revision is the same as the GPIO pin layout on the board:
my $revision = $pi->gpio_layout;
=head2 Identifying which Raspberry Pi hardware you're working on
B<Warning>: This methods call system command line commands using C<sudo>
internally!
In addition to the following methods, we also install a pre-written command-line
script C<pidentify> that can be used.
pidentify [20]
The C<20> is optional. By default, we stay in "identify" state for 5 seconds.
The argument specifies that we'll stay in "identify" state for 20 seconds.
While in "identify" state, the green disk I/O LED will stay on completely, and
the red power LED will remain off completely.
Turn the green activity LED on full-time, and turn off the red power LED for
the default 5 seconds:
$pi->identify;
Send in an integer as the number of seconds to hold the leds in identify mode:
$pi->identify(10);
The above C<identify()> method sleeps the duration. If you wish to enable or
disable the above LEDs indefinitely without sleeping in the meantime:
=head3 Disk I/O LED toggling
Turn the disk I/O LED on permanently:
lib/RPi/WiringPi/FAQ.pod view on Meta::CPAN
RAM utilization: 71.01%
=head3 CPU core temperature
my $tC = $pi->core_temp;
my $tF = $pi->core_temp('f');
say "Core CPU temperature: $tC C : $tF F";
Example output:
Core CPU temperature: 46.7 C : 116.06 F
=head3 GPIO information
B<Note>: if you do not supply an array reference with pin numbers, by default,
we'll return the information for *all* GPIO pins.
my $pin_21_info = $pi->gpio_info([21]);
my $multi_pin_info = $pi->gpio_info([2, 4, 6]);
say "Pin 21 info:";
say "$pin_21_info\n";
say "Multi-pin info:";
say $multi_pin_info;
Example output:
Pin 21 info:
GPIO 21: level=0 fsel=0 func=INPUT
Multi-pin info:
GPIO 2: level=1 fsel=4 alt=0 func=SDA1
GPIO 4: level=0 fsel=1 func=OUTPUT
GPIO 6: level=0 fsel=1 func=OUTPUT
The example above shows the legacy C<raspi-gpio> output. On current Raspberry Pi
OS (and on the Pi 5, where C<raspi-gpio> never existed) the data is collected
with C<pinctrl>, whose lines instead read like C<< 2: ip pu | hi // GPIO2 = input >>.
=head3 Boot configuration settings
say $pi->raspi_config;
Example output (significantly snipped for brevity):
arm_freq=1200
audio_pwm_mode=514
config_hdmi_boost=5
core_freq=250
desired_osc_freq=0x36ee80
...
dtparam=i2c_arm=on
dtparam=spi=on
dtparam=audio=on
enable_uart=1
dtparam=i2c_arm_baudrate=10000
dtoverlay=pi3-disable-bt-overlay
dtoverlay=spi-bcm2835
=head3 Network configuration information
say $pi->network_info;
This method returns the output of C<ifconfig> where the C<net-tools> package is
installed, falling back to C<ip addr> where it is not (as on current Raspberry
Pi OS Lite). Both forms carry the interface C<inet>/C<inet6> addresses.
=head3 File system information
say $pi->file_system;
Example output:
Filesystem 1K-blocks Used Available Use% Mounted on
/dev/root 61289372 3375520 55373576 6% /
devtmpfs 470116 0 470116 0% /dev
tmpfs 474724 0 474724 0% /dev/shm
tmpfs 474724 24140 450584 6% /run
tmpfs 5120 4 5116 1% /run/lock
tmpfs 474724 0 474724 0% /sys/fs/cgroup
/dev/mmcblk0p1 43234 22035 21199 51% /boot
tmpfs 94944 0 94944 0% /run/user/1000
Filename Type Size Used Priority
/var/swap file 102396 0 -2
=head3 Pi board and OS details
say $pi->pi_details;
Raspberry Pi 3 Model B Rev 1.2
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
Linux pi-test 6.6.31+rpt-rpi-v8 #1 SMP PREEMPT Debian 1:6.6.31-1+rpt1 (2024-05-29) aarch64 GNU/Linux
Revision : a22082
Serial : 000000005d916dc3
Model : Raspberry Pi 3 Model B Rev 1.2
Board : Raspberry Pi 3 Model B Rev 1.2
SoC / RAM : BCM2837, 1GB, Embest
Throttled flag : throttled=0x0
Camera : none detected (libcamera)
=head3 Pi model name
say $pi->pi_model;
Example output:
Raspberry Pi 3 Model B Rev 1.2
This is the normalized board name, read from the devicetree model with a
C</proc/cpuinfo> revision-code decode fallback. It works across the Pi 0 through
5 (the Pi 5's RP1-based board included).
lib/RPi/WiringPi/FAQ.pod view on Meta::CPAN
Edges are queued in a kernel pipe until you dispatch them. If a fast source
outruns your dispatching, the queue fills and the newest edges are B<dropped>
(never merged into one, never blocked) - and each is counted, so loss is never
silent. Read the count with C<< $pi->interrupt_dropped >>, and if you
need a deeper queue, enlarge it with C<< $pi->interrupt_buffer($bytes) >>.
=head1 I2C BUS
Allows you to read and write to devices on the I2C bus using the external
L<RPi::I2C> distribution. Please refer to that documentation for full usage
instructions.
Aruino note: The Arduino may not be able to keep up with the I2C bus speed of
the Pi. If this is the case, lower the I2C bus speed on the Pi:
dtparam=i2c_arm_baudrate=10000
=head2 Instantiation and communication
my $device_addr = 0x04;
my $device = $pi->i2c($device_addr);
# Read a single byte at the default register address
print $device->read;
# Read a single byte at a specified register
print $device->read_byte(0x15);
# Read a block of five bytes (register param optional, not shown)
my @bytes = $device->read_block(5);
# Write a byte
$device->write(255);
# Write a byte to a register location
$device->write_byte(255, 0x0A);
# Write a block of bytes (register param left out again)
$device->write_block([1, 2, 3, 4]);
=head1 SERIAL BUS
Allows you to perform basic read and write operations on a standard serial
interface using the L<RPi::Serial> library. See that documentation for full
usage information.
=head2 Note
On the Raspberry Pi 3 and 4, Bluetooth shares the primary UART with GPIO pins
14/15, so you must disable it. Add to C</boot/firmware/config.txt>
(C</boot/config.txt> on releases before Bookworm) and reboot:
enable_uart=1
dtoverlay=disable-bt
On the Raspberry Pi 5, Bluetooth has its own dedicated UART and does B<not>
share the header pins, so no overlay is needed - C<enable_uart=1> alone
suffices. See L</Serial configuration> for the full procedure.
=head2 Usage
my $dev = "/dev/ttyAMA0"; # Pi 5, and Pi 3/4 once Bluetooth is disabled
my $baud = 115200;
my $ser = $pi->serial($dev, $baud);
$ser->putc(5);
my $char = $ser->getc;
$ser->puts("hello, world!");
my $num_bytes = 12;
my $str = $ser->gets($num_bytes);
$ser->flush;
my $bytes_available = $ser->avail;
=head1 SERIAL PERIPHERAL INTERFACE (SPI) BUS
=head2 Set up and communication
Allows you to write to and read from devices attached to the SPI bus, using the
external L<RPi::SPI> distribution. Please refer to that documentation for full
usage instructions.
# Generate a new SPI object
my $channel = 0; # /dev/spidev0.0
my $spi = $pi->spi($channel);
my $buf = [0x01, 0x02];
my $len = 2;
# Write the two bytes in the buffer to channel /dev/spidev0.0
$spi->rw($buf, $len);
# Do a read-only call. Send in the number of bytes you want back as dummy
# bytes (eg. 0)
my $dummy = [0x00, 0x00, 0x00];
my @read_buf = $spi->rw($dummy, 3);
=head1 ANALOG TO DIGITAL CONVERTERS (ADC)
=head2 Initialization and reading input
We provide access to both the ADS1x15 and MCP3008 ADCs.
The default is to return an ADS1115 object from L<RPi::ADC::ADS>. Please review
that documentation for full usage instructions.
# Fetch a new ADC object
lib/RPi/WiringPi/FAQ.pod view on Meta::CPAN
Personally, I set all the environment variables in my C</etc/environment> file.
There are a couple of test files that require root privileges, but we handle
this internally by re-running the file with C<sudo> enabled. This allows all
tests but these couple to be run as a standard user.
=head3 Author Testing
To run the author tests (manifest, POD etc), set:
export RPI_RELEASE_TESTING=1
We use this instead of C<RELEASE_TESTING>, because that typically caused
all sorts of grief when installing prerequisites from the CPAN. Other
people's distribution's author tests often fail due to having it set.
=head3 Multi Object Testing
We've switched over to having shared data between objects and processes.
Although it's the default, you still have to enable these tests explicitly by
setting the following environment variable:
export RPI_MULTI=1
=head3 Arduino/I2C
For testing the L<RPi::I2C> module, we have a dedicated Arduino sketch in the
C<docs/sketch> directory that we test against. Install the sketch, hook up the
I2C between the Pi and the Arduino, and connect a ground pin on the Arduino to
the ground bus on the Pi.
The Arudino has a slower I2C bus than the Pi, so we must lower our bus speed.
Add the following line to the C</boot/firmware/config.txt> file (C</boot/config.txt> on releases before
Bookworm), then reboot:
dtparam=i2c_arm_baudrate=10000
You then set the following environment variable:
export RPI_ARDUINO=1
These tests skip by default.
=head3 Serial Port Testing
To test the serial port L<RPi::Serial> library, you must have a loopback
between the Tx and Rx pins, and:
export RPI_SERIAL=1
These tests will skip by default otherwise.
Note that you must enable serial in C<raspi-config> and disable "terminal over
serial", then reboot. On the Pi 3/4 you must also free the header UART from
Bluetooth; on the Pi 5 that is unnecessary (Bluetooth has its own UART). Add the
appropriate lines to C</boot/firmware/config.txt> (C</boot/config.txt> on
releases before Bookworm):
enable_uart=1
dtoverlay=disable-bt # Pi 3 / 4 only; neither needed nor used on the Pi 5
The loopback test talks to C</dev/ttyAMA0> (the header UART on the Pi 5, and on
the Pi 3/4 once Bluetooth is disabled).
=head3 BMP Barometric Pressure Sensor Testing
To test the temperature and barometric pressure from the BMPx80 sensors:
export RPI_BMP=1
These tests skip by default.
=head3 HCSR04 Ultrasonic Testing
For this test, please see the documentation for L<RPi::HCSR04>, and check the
test files for the pins that are needed. After confirmed and connected, set
export RPI_HCSR04=1
These tests only occur in automated mode when building on a Perl that doesn't
have prerequisites installed.
=head3 OLED Display Testing
These tests use the L<RPi::OLED::SSD1306::128_64> distribution with a 128x64
pixel I2C OLED display. To have these tests execute, set:
export RPI_OLED=1
There's a functional script that will display aspects of the system (time, date,
temperature and barometric pressure sensor) on an available OLED. While the OLED
tests are running, the script automatically disables itself. To operate this
functionality:
perl examples/oled_display_date_time_temp.pl &
=head3 LCD Testing
In order to perform the L<RPi::LCD> test, a 2 row by 16 column or 4 row by 20
column LCD must be connected and operable. Then, set the following environment
variable to a true value:
export RPI_LCD=1
=head3 RTC Testing
To test the L<RPi::RTC::DS3231> distribution, you must set the following
environment variable:
export RPI_RTC=1
=head3 MCP23017 GPIO Expander Testing
To test the L<RPi::GPIOExpander::MCP23017> distribution, set the following
environment variable:
export RPI_MCP23017=1
=head3 PWM/SPI Testing
( run in 0.901 second using v1.01-cache-2.11-cpan-7fcb06a456a )