The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
RPi-PIGPIO-0.011
River stage zero No dependents
4 ++
/ 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";

SUPPORTED 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

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_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_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);

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