/ 
RPi-PIGPIO-0.017
River stage zero No dependents
/ RPi::PIGPIO

NAME

RPi::PIGPIO - remotely control the GPIO on a RaspberryPi using the pigpiod daemon

DESCRIPTION

This module impements a client for the pigpiod daemon, and can be used to control the GPIO on a local or remote RaspberryPi

On every RapberryPi that you want to use you must have pigpiod daemon running!

You can download pigpiod from here http://abyz.co.uk/rpi/pigpio/download.html

SYNOPSYS

Blink a led connecyed to GPIO17 on the RasPi connected to the network with ip address 192.168.1.10

use RPi::PIGPIO ':all';

my $pi = RPi::PIGPIO->connect('192.168.1.10');

$pi->set_mode(17, PI_OUTPUT);

$pi->write(17, HI);

sleep 3;

$pi->write(17, LOW);

Easier mode to controll leds / switches :

use RPi::PIGPIO;
use RPi::PIGPIO::Device::LED;

my $pi = RPi::PIGPIO->connect('192.168.1.10');

my $led = RPi::PIGPIO::Device::LED->new($pi,17);

$led->on;

sleep 3;

$led->off;

Same with a switch (relay):

use RPi::PIGPIO;
use RPi::PIGPIO::Device::Switch;

my $pi = RPi::PIGPIO->connect('192.168.1.10');

my $switch = RPi::PIGPIO::Device::Switch->new($pi,4);

$switch->on;

sleep 3;

$switch->off;

Read the temperature and humidity from a DHT22 sensor connected to GPIO4

use RPi::PIGPIO;
use RPi::PIGPIO::Device::DHT22;

my $dht22 = RPi::PIGPIO::Device::DHT22->new($pi,4);

$dht22->trigger(); #trigger a read

print "Temperature : ".$dht22->temperature."\n";
print "Humidity : ".$dht22->humidity."\n";

ALREADY IMPLEMENTED DEVICES

Note: you can write your own code using methods implemeted here to controll your own device

This is just a list of devices for which we already implemented some functionalities to make your life easier

Generic LED

See complete documentations here: RPi::PIGPIO::Device::LED

Usage:

use RPi::PIGPIO;
use RPi::PIGPIO::Device::LED;

my $pi = RPi::PIGPIO->connect('192.168.1.10');

my $led = RPi::PIGPIO::Device::LED->new($pi,17);

$led->on;

sleep 3;

$led->off;

Seneric switch / relay

See complete documentations here: RPi::PIGPIO::Device::Switch

Usage:

use RPi::PIGPIO;
use RPi::PIGPIO::Device::Switch;

my $pi = RPi::PIGPIO->connect('192.168.1.10');

my $switch = RPi::PIGPIO::Device::Switch->new($pi,4);

$switch->on;

sleep 3;

$switch->off;

DHT22 temperature/humidity sensor

See complete documentations here : RPi::PIGPIO::Device::DHT22

Usage:

use RPi::PIGPIO;
use RPi::PIGPIO::Device::DHT22;

my $pi = RPi::PIGPIO->connect('192.168.1.10');

my $dht22 = RPi::PIGPIO::Device::DHT22->new($pi,4);

$dht22->trigger(); #trigger a read

print "Temperature : ".$dht22->temperature."\n";
print "Humidity : ".$dht22->humidity."\n";

BMP180 atmospheric presure/temperature sensor

See complete documentations here : RPi::PIGPIO::Device::BMP180

Usage:

use RPi::PIGPIO;
use RPi::PIGPIO::Device::BMP180;

my $pi = RPi::PIGPIO->connect('192.168.1.10');

my $bmp180 = RPi::PIGPIO::Device::BMP180->new($pi,1);

$bmp180->read_sensor(); #trigger a read

print "Temperature : ".$bmp180->temperature." C\n";
print "Presure : ".$bmp180->presure." mbar\n";

DSM501A dust particle concentraction sensor

See complete documentations here : RPi::PIGPIO::Device::DSM501A

Usage: use RPi::PIGPIO; use RPi::PIGPIO::Device::DSM501A;

my $pi = RPi::PIGPIO->connect('192.168.1.10');

my $dust_sensor = RPi::PIGPIO::Device::DSM501A->new($pi,4);

# Sample the air for 30 seconds and report
my ($ratio, $mg_per_m3, $pcs_per_m3, $pcs_per_ft3) = $dust_sensor->sample();

MH-Z14 CO2 module

See complete documentations here: RPi::PIGPIO::Device::MH_Z14

Usage: use RPi::PIGPIO; use RPi::PIGPIO::Device::MH_Z14;

my $pi = RPi::PIGPIO->connect('192.168.1.10');

my $co2_sensor = RPi::PIGPIO::Device::MH_Z14->new($pi,mode => 'serial', tty => '/dev/ttyAMA0');

$ppm = $co2_sensor->read();

MCP3008/MCP3004 analog-to-digital convertor

See complete documentations here: RPi::PIGPIO::Device::ADC::MCP300x

Usage: use feature 'say'; use RPi::PIGPIO; use RPi::PIGPIO::Device::ADC::MCP300x;

my $pi = RPi::PIGPIO->connect('192.168.1.10');

my $mcp = RPi::PIGPIO::Device::ADC::MCP300x->new(0);

say "Sensor 1: " .$mcp->read(0);
say "Sensor 2: " .$mcp->read(1);

METHODS

connect

Connects to the pigpiod running on the given IP address/port and returns an object that will allow us to manipulate the GPIO on that Raspberry Pi

Usage:

my $pi = RPi::PIGPIO->connect('127.0.0.1');

Arguments:

  • arg1: ip_address - The IP address of the pigpiod daemon

  • arg2: port - optional, defaults to 8888

Note: The pigiod daemon must be running on the raspi that you want to use

connected

Returns true is we have an established connection with the remote pigpiod daemon

disconnect

Disconnect from the gpiod daemon.

The current object is no longer usable once we disconnect.

get_mode

Returns the mode of a given GPIO pin

Usage :

my $mode = $pi->get_mode(4);

Arguments:

  • arg1: gpio - GPIO for which you want to change the mode

Return values (constant exported by this module):

0 = PI_INPUT
1 = PI_OUTPUT
4 = PI_ALT0
5 = PI_ALT1
6 = PI_ALT2
7 = PI_ALT3
3 = PI_ALT4
2 = PI_ALT5

set_mode

Sets the GPIO mode

Usage:

$pi->set_mode(17, PI_OUTPUT);

Arguments :

  • arg1: gpio - GPIO for which you want to change the mode

  • arg2: mode - the mode that you want to set. Valid values for mode are exported as constants and are : PI_INPUT, PI_OUTPUT, PI_ALT0, PI_ALT1, PI_ALT2, PI_ALT3, PI_ALT4, PI_ALT5

Returns 0 if OK, otherwise PI_BAD_GPIO, PI_BAD_MODE, or PI_NOT_PERMITTED.

write

Sets the voltage level on a GPIO pin to HI or LOW

Note: You first must set the pin mode to PI_OUTPUT

Usage :

$pi->write(17, HI);
or 
$pi->write(17, LOW);

Arguments:

  • arg1: gpio - GPIO to witch you want to write

  • arg2: level - The voltage level that you want to write (one of HI or LOW)

Note: This method will set the GPIO mode to "OUTPUT" and leave it like this

read

Gets the voltage level on a GPIO

Note: You first must set the pin mode to PI_INPUT

Usage :

$pi->read(17);

Arguments:

  • arg1: gpio - gpio that you want to read

Note: This method will set the GPIO mode to "INPUT" and leave it like this

set_watchdog

If no level change has been detected for the GPIO for timeout milliseconds any notification for the GPIO has a report written to the fifo with the flags set to indicate a watchdog timeout.

Arguments:

  • arg1: gpio - GPIO for which to set the watchdog

  • arg2. timeout - time to wait for a level change in milliseconds.

Only one watchdog may be registered per GPIO.

The watchdog may be cancelled by setting timeout to 0.

NOTE: This method requires another connection to be created and subcribed to notifications for this GPIO (see DHT22 implementation)

set_pull_up_down

Set or clear the GPIO pull-up/down resistor.

  • arg1: gpio - GPIO for which we want to modify the pull-up/down resistor

  • arg2: level - PI_PUD_UP, PI_PUD_DOWN, PI_PUD_OFF.

Usage:

$pi->set_pull_up_down(18, PI_PUD_DOWN);

gpio_trigger

This function sends a trigger pulse to a GPIO. The GPIO is set to level for pulseLen microseconds and then reset to not level.

Arguments (in this order):

  • arg1: gpio - number of the GPIO pin we want to monitor

  • arg2: length - pulse length in microseconds

  • arg3: level - level to use for the trigger (HI or LOW)

Usage:

$pi->gpio_trigger(4,17,LOW);

Note: After running you call this method the GPIO is left in "INPUT" mode

SPI interface

spi_open

Comunication is done via harware SPI so MAKE SURE YOU ENABLED SPI on your RPi (use raspi-config command and go to "Advanced")

Returns a handle for the SPI device on channel. Data will be transferred at baud bits per second. The flags may be used to modify the default behaviour of 4-wire operation, mode 0, active low chip select.

An auxiliary SPI device is available on all models but the A and B and may be selected by setting the A bit in the flags. The auxiliary device has 3 chip selects and a selectable word size in bits.

Arguments:

  • arg1: spi_channel:= 0-1 (0-2 for the auxiliary SPI device).

  • arg2: baud:= 32K-125M (values above 30M are unlikely to work).

  • arg3: spi_flags:= see below.

spi_flags consists of the least significant 22 bits.

21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
b  b  b  b  b  b  R  T  n  n  n  n   W  A u2 u1 u0 p2 p1 p0  m  m

mm defines the SPI mode.

WARNING: modes 1 and 3 do not appear to work on the auxiliary device.

Mode POL PHA
0    0   0
1    0   1
2    1   0
3    1   1

px is 0 if CEx is active low (default) and 1 for active high.

ux is 0 if the CEx GPIO is reserved for SPI (default) and 1 otherwise.

A is 0 for the standard SPI device, 1 for the auxiliary SPI.

W is 0 if the device is not 3-wire, 1 if the device is 3-wire. Standard SPI device only.

nnnn defines the number of bytes (0-15) to write before switching the MOSI line to MISO to read data. This field is ignored if W is not set. Standard SPI device only.

T is 1 if the least significant bit is transmitted on MOSI first, the default (0) shifts the most significant bit out first. Auxiliary SPI device only.

R is 1 if the least significant bit is received on MISO first, the default (0) receives the most significant bit first. Auxiliary SPI device only.

bbbbbb defines the word size in bits (0-32). The default (0) sets 8 bits per word. Auxiliary SPI device only.

The spi_read, spi_write, and spi_xfer functions transfer data packed into 1, 2, or 4 bytes according to the word size in bits.

For bits 1-8 there will be one byte per character. For bits 9-16 there will be two bytes per character. For bits 17-32 there will be four bytes per character.

E.g. 32 12-bit words will be transferred in 64 bytes.

The other bits in flags should be set to zero.

Example: open SPI device on channel 1 in mode 3 at 50k bits per second

my $spi_handle = $pi->spi_open(1, 50_000, 3);

spi_close

Closes an SPI channel

Usage :

my $spi = $pi->spi_open(0,32_000);
... 
$pi->spi_close($spi);

spi_read

Arguments (in this order):

  • arg1: handle= >=0 (as returned by a prior call to spi_open).

  • arg2: count= >0, the number of bytes to read.

The returned value is a bytearray containing the bytes.

Usage:

my $spi_handle = $pi->spi_open(1, 50_000, 3);

my $data = $pi->spi_read($spi_handle, 12);

$pi->spi_close($spi_handle);

spi_write

Writes the data bytes to the SPI device associated with handle.

Arguments (in this order):

  • arg1: handle:= >=0 (as returned by a prior call to spi_open).

  • arg2: data:= the bytes to write.

Examples :

my $spi_handle = $pi->spi_open(1, 50_000, 3);

$pi->spi_write($spi_handle, [2, 192, 128]);      # write 3 bytes to device 1

spi_xfer

Writes the data bytes to the SPI device associated with handle, returning the data bytes read from the device.

Arguments (in this order):

  • arg1: handle= >=0 (as returned by a prior call to spi_open).

  • arg2: data= the bytes to write.

The returned value is a bytearray containing the bytes.

Examples :

my $spi_handle = $pi->spi_open(1, 50_000, 3);

my $rx_data = $pi->spi_xfer($spi_handle, [1, 128, 0]);

Serial interface

serial_open

Returns a handle for the serial tty device opened at baud bits per second. The device name must start with /dev/tty or /dev/serial.

Arguments :

  • arg1 : tty => the serial device to open.

  • arg2 : baud => baud rate in bits per second, see below.

Returns: a handle for the serial connection which will be used in calls to serial_* methods

The baud rate must be one of 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, 115200, or 230400.

Notes: On the raspi on which you want to use the serial device you have to :

1 enable UART -> run sudo nano /boot/config.txt and add the bottom enable_uart=1
2 run sudo raspi-config and disable the login via the Serial port

More info (usefull for Raspi 3) here : http://spellfoundry.com/2016/05/29/configuring-gpio-serial-port-raspbian-jessie-including-pi-3/

Usage:

$h1 = $pi->serial_open("/dev/ttyAMA0", 300)

$h2 = $pi->serial_open("/dev/ttyUSB1", 19200, 0)

$h3 = $pi->serial_open("/dev/serial0", 9600)

serial_close

Closes the serial device associated with handle.

Arguments:

  • arg1: handle => the connection as returned by a prior call to serial_open

Usage:

$pi->serial_close($handle);

serial_write

Write a string to the serial handle opened with serial_open

Arguments:

  • arg1: handle => connection handle obtained from calling serial_open

  • arg2: data => data to write (string)

Usage :

my $h = $pi->serial_open('/dev/ttyAMA0',9600);

my $data = 'foo bar';

$pi->serial_write($h, $data);

$pi->serial_close($h);

serial_read

Read a string from the serial handle opened with serial_open

Arguments:

  • arg1: handle => connection handle obtained from calling serial_open

  • arg2: count => number of bytes to read

Usage :

my $h = $pi->serial_open('/dev/ttyAMA0',9600);

my $data = $pi->serial_read($h, 10); #read 10 bytes

$pi->serial_close($h);

Note: Between a read and a write you might want to sleep for half a second

serial_data_available

Checks if we have any data waiting to be read from the serial handle

Usage :

my $h = $pi->serial_open('/dev/ttyAMA0',9600);

my $count = $pi->serial_data_available($h);

my $data = $pi->serial_read($h, $count);

$pi->serial_close($h);

I2C interface

i2c_open

Returns a handle (>=0) for the device at the I2C bus address.

Arguments:

  • i2c_bus: >=0 the i2c bus number

  • i2c_address: 0-0x7F => the address of the device on the bus

  • i2c_flags: defaults to 0, no flags are currently defined (optional).

Physically buses 0 and 1 are available on the Pi. Higher numbered buses will be available if a kernel supported bus multiplexor is being used.

Usage :

my $handle = $pi->i2c_open(1, 0x53) # open device at address 0x53 on bus 1

i2c_close

Closes the I2C device associated with handle.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

i2c_write_quick

Sends a single bit to the device associated with handle.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • bit: 0 or 1, the value to write.

Usage:

$pi->i2c_write_quick(0, 1) # send 1 to device 0
$pi->i2c_write_quick(3, 0) # send 0 to device 3

i2c_write_byte

Sends a single byte to the device associated with handle.

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • byte_val: 0-255, the value to write.

Usage:

$pi->i2c_write_byte(1, 17)   # send byte   17 to device 1
$pi->i2c_write_byte(2, 0x23) # send byte 0x23 to device 2

i2c_read_byte

Reads a single byte from the device associated with handle.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

Usage:

my $val = $pi->i2c_read_byte(2) # read a byte from device 2

i2c_write_byte_data

Writes a single byte to the specified register of the device associated with handle.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • reg: >=0, the device register.

  • byte_val: 0-255, the value to write.

Usage:

# send byte 0xC5 to reg 2 of device 1
$pi->i2c_write_byte_data(1, 2, 0xC5);

# send byte 9 to reg 4 of device 2
$pi->i2c_write_byte_data(2, 4, 9);

i2c_write_word_data

Writes a single 16 bit word to the specified register of the device associated with handle.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • reg: >=0, the device register.

  • word_val: 0-65535, the value to write.

Usage:

# send word 0xA0C5 to reg 5 of device 4
$pi->i2c_write_word_data(4, 5, 0xA0C5);

# send word 2 to reg 2 of device 5
$pi->i2c_write_word_data(5, 2, 23);

i2c_read_byte_data

Reads a single byte from the specified register of the device associated with handle.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • reg: >=0, the device register.

Usage: # read byte from reg 17 of device 2 my $b = $pi->i2c_read_byte_data(2, 17);

# read byte from reg  1 of device 0
my $b = pi->i2c_read_byte_data(0, 1);

i2c_read_word_data

Reads a single 16 bit word from the specified register of the device associated with handle.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • reg: >=0, the device register.

Usage: # read byte from reg 17 of device 2 my $w = $pi->i2c_read_word_data(2, 17);

# read byte from reg  1 of device 0
my $w = pi->i2c_read_word_data(0, 1);

i2c_process_call

Writes 16 bits of data to the specified register of the device associated with handle and reads 16 bits of data in return.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • reg: >=0, the device register.

  • word_val: 0-65535, the value to write.

Usage:

my $r = $pi->i2c_process_call(1, 4, 0x1231);

my $r = $pi->i2c_process_call(2, 6, 0);

i2c_write_block_data

Writes up to 32 bytes to the specified register of the device associated with handle.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • reg: >=0, the device register.

  • data: arrayref of bytes to write

Usage:

$pi->i2c_write_block_data(6, 2, [0, 1, 0x22]);

i2c_read_block_data

Reads a block of up to 32 bytes from the specified register of the device associated with handle.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • reg: >=0, the device register.

The amount of returned data is set by the device.

The returned value is a tuple of the number of bytes read and a bytearray containing the bytes. If there was an error the number of bytes read will be less than zero (and will contain the error code).

Usage:

my ($bytes,$data) = $pi->i2c_read_block_data($handle, 10);

i2c_block_process_call

Writes data bytes to the specified register of the device associated with handle and reads a device specified number of bytes of data in return.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • reg: >=0, the device register.

  • data: arrayref of bytes to write

Usage:

my ($bytes,$data) = $pi->i2c_block_process_call($handle, 10, [2, 5, 16]);

The returned value is a tuple of the number of bytes read and a bytearray containing the bytes.

If there was an error the number of bytes read will be less than zero (and will contain the error code).

i2c_write_i2c_block_data

Writes data bytes to the specified register of the device associated with handle. 1-32 bytes may be written.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • reg: >=0, the device register.

  • data: arrayref of bytes to write

Usage:

$pi->i2c_write_i2c_block_data(6, 2, [0, 1, 0x22]);

i2c_read_i2c_block_data

Reads count bytes from the specified register of the device associated with handle. The count may be 1-32.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • reg: >=0, the device register.

  • count: >0, the number of bytes to read (1-32).

Usage:

my ($bytes, $data) = $pi->i2c_read_i2c_block_data($handle, 4, 32);

The returned value is a tuple of the number of bytes read and a bytearray containing the bytes. If there was an error the number of bytes read will be less than zero (and will contain the error code).

i2c_read_device

Returns count bytes read from the raw device associated with handle.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • count: >0, the number of bytes to read (1-32).

Usage:

my ($count, $data) = $pi->i2c_read_device($handle, 12);

i2c_write_device

Writes the data bytes to the raw device associated with handle.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • data: arrayref of bytes to write

Usage:

$pi->i2c_write_device($handle, [23, 56, 231]);

i2c_zip

This function executes a sequence of I2C operations. The operations to be performed are specified by the contents of data which contains the concatenated command codes and associated data.

Arguments:

  • handle: >=0 ( as returned by a prior call to i2c_open() )

  • data: arrayref of the concatenated I2C commands, see below

The returned value is a tuple of the number of bytes read and a bytearray containing the bytes. If there was an error the number of bytes read will be less than zero (and will contain the error code).

Usage:

my ($count, $data) = $pi->i2c_zip($handle, [4, 0x53, 7, 1, 0x32, 6, 6, 0])

The following command codes are supported:

Name    @ Cmd & Data @ Meaning
End     @ 0          @ No more commands
Escape  @ 1          @ Next P is two bytes
On      @ 2          @ Switch combined flag on
Off     @ 3          @ Switch combined flag off
Address @ 4 P        @ Set I2C address to P
Flags   @ 5 lsb msb  @ Set I2C flags to lsb + (msb << 8)
Read    @ 6 P        @ Read P bytes of data
Write   @ 7 P ...    @ Write P bytes of data

The address, read, and write commands take a parameter P. Normally P is one byte (0-255). If the command is preceded by the Escape command then P is two bytes (0-65535, least significant byte first).

The address defaults to that associated with the handle. The flags default to 0. The address and flags maintain their previous value until updated.

Any read I2C data is concatenated in the returned bytearray.

Set address 0x53, write 0x32, read 6 bytes
Set address 0x1E, write 0x03, read 6 bytes
Set address 0x68, write 0x1B, read 8 bytes
End

0x04 0x53   0x07 0x01 0x32   0x06 0x06
0x04 0x1E   0x07 0x01 0x03   0x06 0x06
0x04 0x68   0x07 0x01 0x1B   0x06 0x08
0x00

PWM

write_pwm

Sets the voltage level on a GPIO pin to a value from 0-255 (PWM) approximating a lower voltage. Useful for dimming LEDs for example.

Note: You first must set the pin mode to PI_OUTPUT

Usage :

$pi->write_pwm(17, 255);
or
$pi->write_pwm(17, 120);
or
$pi->write_pwm(17, 0);

Arguments:

  • arg1: gpio - GPIO to which you want to write

  • arg2: level - The voltage level that you want to write (one of 0-255)

Note: This method will set the GPIO mode to "OUTPUT" and leave it like this

PRIVATE METHODS

send_command

Sends a command to the pigiod daemon and waits for a response

  • arg1: command - code of the command you want to send (see package constants)

  • arg2: param1 - first parameter (usualy the GPIO)

  • arg3: param2 - second parameter - optional - usualy the level to which to set the GPIO (HI/LOW)

send_command_on_socket

Same as send_command but allows you to specify the socket you want to use

The pourpose of this is to allow you to use the send_command functionality on secondary connections used to monitor changes on GPIO

Arguments:

  • arg1: socket - Instance of IO::Socket::INET

  • arg2: command - code of the command you want to send (see package constants)

  • arg3: param1 - first parameter (usualy the GPIO)

  • arg3: param2 - second parameter - optional - usualy the level to which to set the GPIO (HI/LOW)

send_command_ext

Sends an extended command to the pigpiod daemon

send_i2c_command

Method used for sending and reading back i2c data

1 POD Error

The following errors were encountered while parsing the POD:

Around line 202:

=back without =over