RPi-WiringPi
view release on metacpan or search on metacpan
lib/RPi/WiringPi/FAQ.pod view on Meta::CPAN
=head2 I2C configuration
You need to have some core software installed before using the I2C bus. The
Raspberry Pi 3 already has everything pre-loaded. On a typical Unix computer,
you'd do something along these lines:
sudo apt-get install libi2c-dev i2c-tools build-essential
To test your I2C bus:
i2cdetect -y 1
...or on some machines:
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<ram=i2c_arm> directive is set to C<on> in the
C</boot/config.txt> file:
dtparam=i2c_arm=on
NOTE: If you get permission errors accessing the I2C bus, you may need to add
the C<pi> user to the C<i2c> group:
sudo adduser pi i2c
=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/config.txt> file:
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/config.txt> file:
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
In order to use GPIO pins 14 and 15 as a serial interface on the Raspberry Pi,
you need to disable the built-in Bluetooth adaptor. This distribution's serial
functionality will not operate correctly without this being done.
First, in C<raspi-config>, in the C<Serial> section in C<Interfacing Options>,
disable "login shell" on the serial interface, then disable Bluetooth by editing
the C</boot/config.txt>, and add the following line:
dtoverlay=pi3-disable-bt-overlay
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
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:
$pi->io_led(1);
Return it to default state of acting as disk I/O indicator:
$pi->io_led(0); # or just $pi->io_led;
=head3 Power LED toggling
Turn the power LED off permanently:
lib/RPi/WiringPi/FAQ.pod view on Meta::CPAN
my $mem_percent = $pi->mem_percent;
say "RAM utilization: $mem_percent%";
Example output:
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
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
=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 simply returns the information from the C<ifconfig> system call.
=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="Raspbian GNU/Linux 9 (stretch)"
NAME="Raspbian GNU/Linux"
VERSION_ID="9"
VERSION="9 (stretch)"
Linux pi-test 4.14.98-v7+ #1200 SMP Tue Feb 12 20:27:48 GMT 2019 armv7l GNU/Linux
Hardware : BCM2835
Revision : a22082
Serial : 000000005d916dc3
Throttled flag : throttled=0x50000
Camera : supported=0 detected=0
=head1 PIN
=head2 Creating and using a GPIO pin object
The L<RPi::Pin> class provides you with objects that directly map to the
Raspberry Pi's onboard GPIO pins. You generate a pin object through the main
C<$pi> object we created above. See that documentation for full usage
information.
my $pin = $pi->pin(27);
# set the mode to output, presumably to power an external device
$pin->mode(OUTPUT);
lib/RPi/WiringPi/FAQ.pod view on Meta::CPAN
$pin->interrupt_set(EDGE_BOTH, 'handler');
sub handler {
print "in handler\n";
# do other stuff, perhaps turning on/off other pins
}
NOTE: If you receive errors about the handler callback not being found, simply
specify the callback with the full package (eg. C<'main::handler'>).
=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
Bluetooth on the Pi overlays the serial pins (14, 15) on the Pi. To use
serial, you must disable bluetooth in the C</boot/config.txt> file:
dtoverlay=pi3-disable-bt-overlay
=head2 Usage
my $dev = "/dev/ttyS0";
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
First off, please review the C<t/README> file for the GPIO pins we use for the
test physical configuration, and set up the Pi according to the
L<unit test diagram|https://stevieb9.github.io/rpi-wiringpi/breadboard/brewbuild_test_platform_bb.jpg>.
=head3 Base information
Before running the tests, you need to set a special environment variable so that
we know we're on a Pi board. This ensures CPAN testers won't run the tests
across all of its platforms:
export PI_BOARD=1
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:
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 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/config.txt> file, 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>, disable "terminal over
serial", and then reboot after adding the following line in the
C</boot/config.txt> file (this disabled Bluetooth on the Serial interface):
dtoverlay=pi3-disable-bt-overlay
=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
In order to run tests for PWM and SPI, the following environment variable is
required to be set:
( run in 2.263 seconds using v1.01-cache-2.11-cpan-75ffa21a3d4 )