Are my GPIO broken?
Audio is broken
Can´t initialise pigpio library
Can´t lock var/run/pigpio.pid
Hello World!
Clock skew, make fails
Have I fried my GPIO?
How do I debounce inputs?
How fast is SPI?
Library update didn't work
make fails with clock skew
Porting pigpio to another CPU/SoC
Sound isn't working
Symbol not found
What is I2C?
What is Serial?
What is SPI?
Which library should I use?

### Are my GPIO broken?

See Have I fried my GPIO?

### Audio is broken

See Sound isn't working

### Can´t lock /var/run/pigpio.pid

See Can´t_initialise_pigpio_library

### Can´t initialise pigpio library

This message means the pigpio daemon is already running.

The default daemon is called pigpiod and may be removed as follows.

Check that it is running with the command

`ps aux | grep pigpiod`

Kill the daemon with

`sudo killall pigpiod`

If your own program is acting as the daemon it may be removed as follows.

Find its process id (pid).

`cat /var/run/pigpio.pid`

Kill the program with

`sudo kill -9 pid`

If the above doesn't work do the following and try starting the daemon again

`sudo rm /var/run/pigpio.pid
`

To start the daemon do

`sudo pigpiod`

### Have I fried my GPIO?

If you think you have damaged one or more GPIO you can carry out a diagnostic test.

The test is a command line script called gpiotest

For the duration of the test nothing must be connected to the GPIO (no LEDs, wires, ribbon cables etc.).

The test checks that each GPIO may be read and written and that the internal resistor pull-ups and pull-downs are functional.

A video showing what happens to the GPIO during a test.

A test with all GPIO okay.

    This program checks the Pi's (user) gpios.

    The program reads and writes all the gpios.  Make sure NOTHING
    is connected to the gpios during this test.

    The program uses the pigpio daemon which must be running.

    To start the daemon use the command sudo pigpiod.

    Press the ENTER key to continue or ctrl-C to abort...

    Testing...
    Skipped non-user gpios: 0 1 28 29 30 31
    Tested user gpios: 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
     19 20 21 22 23 24 25 26 27
    Failed user gpios: None

A test showing failed GPIO.

    This program checks the Pi's (user) gpios.

    The program reads and writes all the gpios. Make sure NOTHING
    is connected to the gpios during this test.

    The program uses the pigpio daemon which must be running.

    To start the daemon use the command sudo pigpiod.

    Press the ENTER key to continue or ctrl-C to abort...

    Testing...
    Write 1 to gpio 17 failed.
    Pull up on gpio 17 failed.
    Write 1 to gpio 18 failed.
    Pull up on gpio 18 failed.
    Write 0 to gpio 23 failed.
    Pull down on gpio 23 failed.
    Write 0 to gpio 24 failed.
    Pull down on gpio 24 failed.
    Write 1 to gpio 27 failed.
    Pull up on gpio 27 failed.
    Skipped non-user gpios: 0 1 28 29 30 31
    Tested user gpios: 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
     19 20 21 22 23 24 25 26 27
    Failed user gpios: 17 18 23 24 27

### How do I debounce inputs?

Some devices like mechanical switches can generate multiple interrupts as they bounce between on and off. It is possible to debounce the inputs in hardware by the correct use of resistors and capacitors.

In software use the glitch filter which ignores all events shorter than a set number of microseconds. C gpioGlitchFilter, Python set_glitch_filter.

### How fast is SPI?

The SPI throughput in samples per second depends on a number of factors.

- The SPI bit rate (transfer rate in bits per second)

- The number of bytes transferred per sample (a 12 bit ADC sample may require 3 bytes to transfer)

- The driver used

Two of those factors are fixed, the variable is the driver used.

The pigpio driver is considerably faster than the Linux SPI driver as is demonstrated by the following graphs.

Each graph shows the SPI bit rate in bits per second along the horizontal axis. The samples per second achieved is shown on the vertical axis. Each graph contains plots assuming 1 to 5 bytes per transfer.

The source code used for the tests is spi-driver-speed.c and spi-pigpio-speed.c

### Library update didn't work

pigpio places files in the following locations

/usr/local/include (pigpio.h, pigpiod_if.h, pigpiod_if2.h)
/usr/local/lib (libpigpio.so, libpigpiod_if.so, libpigpiod_if2.so)
/usr/local/bin (pig2vcd, pigpiod, pigs)
/usr/local/man (man pages)

The raspberrypi.org image containing pigpio uses different locations.

/usr/include (pigpio.h, pigpiod_if.h, pigpiod_if2.h)
/usr/lib (libpigpio.so, libpigpiod_if.so, libpigpiod_if2.so)
/usr/bin (pig2vcd, pigpiod, pigs)
/usr/man (man pages)

Mostly this doesn't matter as the /usr/local directories will generally be earlier in the search path. The pigpio built includes, binaries, and manuals are normally found first.

However the wrong libraries may be linked during the compilation. If this is the case remove the /usr/lib entries for libpigpio.so , libpigpiod_if.so, and libpigpiod_if2.so

### Hello World!

The following examples show how to use the various components of the pigpio library.

Each example shows how to read the level of a GPIO.

#### C

read_cif.c

    #include <stdio.h>
    #include <pigpio.h>

    int main(int argc, char *argv[])
    {
       int GPIO=4;
       int level;

       if (gpioInitialise() < 0) return 1;

       level = gpioRead(GPIO);

       printf("GPIO %d is %d\n", GPIO, level);

       gpioTerminate();
    }

Build

`gcc -pthread -o read_cif read_cif.c -lpigpio`

Run

`sudo ./read_cif`

#### C via pigpio daemon

read_pdif.c

    #include <stdio.h>
    #include <pigpiod_if2.h>

    int main(int argc, char *argv[])
    {
       int pi;
       int GPIO=4;
       int level;

       pi = pigpio_start(0, 0); /* Connect to local Pi. */

       if (pi < 0)
       {
          printf("Can't connect to pigpio daemon\n");
          return 1;
       }

       level = gpio_read(pi, GPIO);

       printf("GPIO %d is %d\n", GPIO, level);

       pigpio_stop(pi); /* Disconnect from local Pi. */

       return 0;
    }

Build

`gcc -pthread -o read_pdif read_pdif.c -lpigpiod_if2`

Run

`./read_pdif`

#### Python

read_gpio.py

    #!/usr/bin/env python

    import pigpio

    GPIO=4

    pi = pigpio.pi()
    if not pi.connected:
       exit()

    level = pi.read(GPIO)

    print("GPIO {} is {}".format(GPIO, level))

    pi.stop()

Run

`python read_gpio.py`

#### pigs

    pigs r 4

#### pipe I/F

    echo "r 4" >/dev/pigpio
    cat /dev/pigout

### make fails with clock skew

If make fails with one of the following messages it is probably because the Pi's clock is wrong.

`make: Warning: File 'xxx' has modification time x s in the future
make: warning: Clock skew detected. Your build may be incomplete.`

make uses the current time to work out which files need to be rebuilt (a file is rebuilt if it depends on other files which have a later time-stamp).

The solution is to make sure the system clock is correct. If the Pi is networked this will not normally be a problem.

To set the date and time use the date command as in the following example.

`sudo date -d "2017-03-01 18:47:00"`

### Porting pigpio to another CPU/SoC

### Sound isn't working

The Pi contains two pieces of hardware, a PWM peripheral and a PCM peripheral, to generate sound. The PWM peripheral is normally used and generates medium quality audio out of the headphone jack. The PCM peripheral may be used by add-ons such as HATs and generates high quality audio.

pigpio uses at least one of these peripherals during normal operation (for timing DMA transfers). pigpio will use both peripherals if waves or the hardware PWM function is used.

By default pigpio uses the PCM peripheral leaving the PWM peripheral free for medium quality audio.

You can change the default with a configuration option. For C use gpioCfgClock, for the pigpio daemon use the -t option.

### What is I2C?

I2C is a data link between the Pi (master) and one or more slaves.

Data may be sent and received but the Pi initiates all transfers.

I2C is a medium speed link. On the Pi the default speed is 100 kbps, but 400 kbps also works.

I2C is implemented as a bus with two lines called

- SDA - for data
- SCL - for a clock

On the Pi bus 1 is used which uses GPIO 2 (pin 3) for SDA and GPIO 3 (pin 5) for SCL.
Only one slave device may be communicated with at a time. Each message from the Pi includes the slave to be addressed and whether a read or write is to be performed.
When the Pi (master) wishes to talk to a slave it begins by issuing a start sequence on the I2C bus. A start sequence is one of two special sequences defined for the I2C bus, the other being the stop sequence. The start sequence and stop sequence are special in that these are the only places where the SDA (data line) is allowed to change while the SCL (clock line) is high. When data is being transferred, SDA must remain stable and not change whilst SCL is high. The start and stop sequences mark the beginning and end of a transaction with the slave device.
Data is transferred in 8-bit bytes. The bytes are placed on the SDA line starting with the most significant bit. The SCL line is then pulsed high, then low. For every byte transferred, the device receiving the data sends back an acknowledge bit, so there are actually 9 SCL clock pulses to transfer each 8-bit byte of data. If the receiving device sends back a low ACK bit, then it has received the data and is ready to accept another byte. If it sends back a high then it is indicating it cannot accept any further data and the master should terminate the transfer by sending a stop sequence.

### What is Serial?

Serial is a data link between the Pi and one other device.

Data may be sent and received. Either the Pi or the device can initiate a transfer.

Serial is a low to medium speed link. On the Pi speeds of 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, 115200, and 230400 bps may be used.

Serial is implemented with one line for transmit called TXD and one line for receive called RXD.

If only receive or transmit are required the other line need not be connected.

The Pi uses GPIO 14 (pin 8) for TXD and GPIO 15 (pin 10) for RXD.

Data is normally transmitted in 8-bit bytes with a start bit, eight data bits, no parity, and one stop bit. This is represented as 8N1. The number of transmitted bits per second (bps) is called the baud rate. The time for each bit, 1 / baud rate seconds, is referred to as the bit period.

The lines are in the high state when no data is being transmitted. The start of a byte is signalled by the line going low for one bit period (the start bit). The data bits are then sent least significant bit firsts (low if the bit is 0, high if the bit is 1). The data bits are followed by the optional parity bit. Finally the line is set high for at least the number of stop bit periods. The line will stay high if there are no more bytes to be transmitted.

### What is SPI?

SPI is a data link between the Pi (master) and one or more slaves.

Data may be sent and received but the Pi initiates all transfers.

SPI is a medium to high speed link. On the Pi speeds of 32 kbps to 8 Mbps may be used.

SPI is implemented as a bus with three lines called

- MOSI - for data from the Pi to the slave
- MISO - for data from the slave to the Pi
- SCLK - for a clock

Only one slave device may be communicated with at a time. An additional line per slave called slave select is used to identify the slave to be addressed.

The Pi has two SPI buses

1. the main SPI bus
   - MOSI GPIO 10 (pin 19)
   - MISO GPIO 9 (pin 21)
   - SCLK GPIO 11 (pin 23)
   - Slave selects
   - - CE0 GPIO 8 (pin 24)
     - CE1 GPIO 7 (pin 26)
2. the auxiliary SPI bus
   - MOSI GPIO 20 (pin 38)
   - MISO GPIO 19 (pin 35)
   - SCLK GPIO 21 (pin 40)
   - Slave selects
   - - CE0 GPIO 18 (pin 12)
     - CE1 GPIO 17 (pin 11)
     - CE2 GPIO 16 (pin 36)

### Which library should I use?