pigpio is a Python module for the Raspberry which talks to
the pigpio daemon to allow control of the general purpose
input outputs (GPIO).
[http://abyz.me.uk/rpi/pigpio/python.html]
*Features*
o the pigpio Python module can run on Windows, Macs, or Linux
o controls one or more Pi's
o hardware timed PWM on any of GPIO 0-31
o hardware timed servo pulses on any of GPIO 0-31
o callbacks when any of GPIO 0-31 change state
o creating and transmitting precisely timed waveforms
o reading/writing GPIO and setting their modes
o wrappers for I2C, SPI, and serial links
o creating and running scripts on the pigpio daemon
*GPIO*
ALL GPIO are identified by their Broadcom number.
*Notes*
Transmitted waveforms are accurate to a microsecond.
Callback level changes are time-stamped and will be
accurate to within a few microseconds.
*Settings*
A number of settings are determined when the pigpio daemon is started.
o the sample rate (1, 2, 4, 5, 8, or 10 us, default 5 us).
o the set of GPIO which may be updated (generally written to). The
default set is those available on the Pi board revision.
o the available PWM frequencies (see [*set_PWM_frequency*]).
*Exceptions*
By default a fatal exception is raised if you pass an invalid
argument to a pigpio function.
If you wish to handle the returned status yourself you should set
pigpio.exceptions to False.
You may prefer to check the returned status in only a few parts
of your code. In that case do the following:
...
pigpio.exceptions = False
# Code where you want to test the error status.
pigpio.exceptions = True
...
*Usage*
This module uses the services of the C pigpio library. pigpio
must be running on the Pi(s) whose GPIO are to be manipulated.
The normal way to start pigpio is as a daemon (during system
start).
sudo pigpiod
Your Python program must import pigpio and create one or more
instances of the pigpio.pi class. This class gives access to
a specified Pi's GPIO.
...
pi1 = pigpio.pi() # pi1 accesses the local Pi's GPIO
pi2 = pigpio.pi('tom') # pi2 accesses tom's GPIO
pi3 = pigpio.pi('dick') # pi3 accesses dick's GPIO
pi1.write(4, 0) # set local Pi's GPIO 4 low
pi2.write(4, 1) # set tom's GPIO 4 to high
pi3.read(4) # get level of dick's GPIO 4
...
The later example code snippets assume that pi is an instance of
the pigpio.pi class.
OVERVIEW
Essential
pigpio.pi Initialise Pi connection
stop Stop a Pi connection
Beginner
set_mode Set a GPIO mode
get_mode Get a GPIO mode
set_pull_up_down Set/clear GPIO pull up/down resistor
read Read a GPIO
write Write a GPIO
set_PWM_dutycycle Start/stop PWM pulses on a GPIO
get_PWM_dutycycle Get PWM dutycycle set on a GPIO
set_servo_pulsewidth Start/Stop servo pulses on a GPIO
get_servo_pulsewidth Get servo pulsewidth set on a GPIO
callback Create GPIO level change callback
wait_for_edge Wait for GPIO level change
Intermediate
gpio_trigger Send a trigger pulse to a GPIO
set_watchdog Set a watchdog on a GPIO
set_PWM_range Configure PWM range of a GPIO
get_PWM_range Get configured PWM range of a GPIO
set_PWM_frequency Set PWM frequency of a GPIO
get_PWM_frequency Get PWM frequency of a GPIO
read_bank_1 Read all bank 1 GPIO
read_bank_2 Read all bank 2 GPIO
clear_bank_1 Clear selected GPIO in bank 1
clear_bank_2 Clear selected GPIO in bank 2
set_bank_1 Set selected GPIO in bank 1
set_bank_2 Set selected GPIO in bank 2
Advanced
get_PWM_real_range Get underlying PWM range for a GPIO
notify_open Request a notification handle
notify_begin Start notifications for selected GPIO
notify_pause Pause notifications
notify_close Close a notification
bb_serial_read_open Open a GPIO for bit bang serial reads
bb_serial_read Read bit bang serial data from a GPIO
bb_serial_read_close Close a GPIO for bit bang serial reads
bb_serial_invert Invert serial logic (1 invert, 0 normal)
hardware_clock Start hardware clock on supported GPIO
hardware_PWM Start hardware PWM on supported GPIO
set_glitch_filter Set a glitch filter on a GPIO
set_noise_filter Set a noise filter on a GPIO
get_pad_strength Gets a pads drive strength
set_pad_strength Sets a pads drive strength
shell Executes a shell command
Scripts
store_script Store a script
run_script Run a stored script
update_script Set a scripts parameters
script_status Get script status and parameters
stop_script Stop a running script
delete_script Delete a stored script
Waves
wave_clear Deletes all waveforms
wave_add_new Starts a new waveform
wave_add_generic Adds a series of pulses to the waveform
wave_add_serial Adds serial data to the waveform
wave_create Creates a waveform from added data
wave_delete Deletes a waveform
wave_send_once Transmits a waveform once
wave_send_repeat Transmits a waveform repeatedly
wave_send_using_mode Transmits a waveform in the chosen mode
wave_chain Transmits a chain of waveforms
wave_tx_at Returns the current transmitting waveform
wave_tx_busy Checks to see if a waveform has ended
wave_tx_stop Aborts the current waveform
wave_get_micros Length in microseconds of the current waveform
wave_get_max_micros Absolute maximum allowed micros
wave_get_pulses Length in pulses of the current waveform
wave_get_max_pulses Absolute maximum allowed pulses
wave_get_cbs Length in cbs of the current waveform
wave_get_max_cbs Absolute maximum allowed cbs
I2C
i2c_open Opens an I2C device
i2c_close Closes an I2C device
i2c_write_quick SMBus write quick
i2c_write_byte SMBus write byte
i2c_read_byte SMBus read byte
i2c_write_byte_data SMBus write byte data
i2c_write_word_data SMBus write word data
i2c_read_byte_data SMBus read byte data
i2c_read_word_data SMBus read word data
i2c_process_call SMBus process call
i2c_write_block_data SMBus write block data
i2c_read_block_data SMBus read block data
i2c_block_process_call SMBus block process call
i2c_read_i2c_block_data SMBus read I2C block data
i2c_write_i2c_block_data SMBus write I2C block data
i2c_read_device Reads the raw I2C device
i2c_write_device Writes the raw I2C device
i2c_zip Performs multiple I2C transactions
bb_i2c_open Opens GPIO for bit banging I2C
bb_i2c_close Closes GPIO for bit banging I2C
bb_i2c_zip Performs multiple bit banged I2C transactions
SPI
spi_open Opens a SPI device
spi_close Closes a SPI device
spi_read Reads bytes from a SPI device
spi_write Writes bytes to a SPI device
spi_xfer Transfers bytes with a SPI device
bb_spi_open Opens GPIO for bit banging SPI
bb_spi_close Closes GPIO for bit banging SPI
bb_spi_xfer Transfers bytes with bit banging SPI
I2C/SPI_Slave
bsc_xfer I2C/SPI as slave transfer
bsc_i2c I2C as slave transfer
Serial
serial_open Opens a serial device
serial_close Closes a serial device
serial_read Reads bytes from a serial device
serial_read_byte Reads a byte from a serial device
serial_write Writes bytes to a serial device
serial_write_byte Writes a byte to a serial device
serial_data_available Returns number of bytes ready to be read
Files
file_open Opens a file
file_close Closes a file
file_read Reads bytes from a file
file_write Writes bytes to a file
file_seek Seeks to a position within a file
file_list List files which match a pattern
Events
event_callback Sets a callback for an event
event_trigger Triggers an event
wait_for_event Wait for an event
Custom
custom_1 User custom function 1
custom_2 User custom function 2
Utility
get_current_tick Get current tick (microseconds)
get_hardware_revision Get hardware revision
get_pigpio_version Get the pigpio version
pigpio.error_text Gets error text from error number
pigpio.tickDiff Returns difference between two ticks
active: 0-1000000
The number of microseconds level changes are reported for once
a noise filter has been triggered (by [*steady*] microseconds of
a stable level).
arg1:
An unsigned argument passed to a user customised function. Its
meaning is defined by the customiser.
arg2:
An unsigned argument passed to a user customised function. Its
meaning is defined by the customiser.
argx:
An array of bytes passed to a user customised function.
Its meaning and content is defined by the customiser.
baud:
The speed of serial communication (I2C, SPI, serial link, waves)
in bits per second.
bb_bits: 1-32
The number of data bits to be used when adding serial data to a
waveform.
bb_stop: 2-8
The number of (half) stop bits to be used when adding serial data
to a waveform.
bit: 0-1
A value of 0 or 1.
bits: 32 bit number
A mask used to select GPIO to be operated on. If bit n is set
then GPIO n is selected. A convenient way of setting bit n is to
bit or in the value (1<<n).
To select GPIO 1, 7, 23
bits = (1<<1) | (1<<7) | (1<<23)
bsc_control:
. .
22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
a a a a a a a - - IT HC TF IR RE TE BK EC ES PL PH I2 SP EN
. .
aaaaaaa defines the I2C slave address (only relevant in I2C mode)
Bits 0-13 are copied unchanged to the BSC CR register. See
pages 163-165 of the Broadcom peripherals document.
byte_val: 0-255
A whole number.
clkfreq: 4689-250M
The hardware clock frequency.
connected:
True if a connection was established, False otherwise.
count:
The number of bytes of data to be transferred.
CS:
The GPIO used for the slave select signal when bit banging SPI.
data:
Data to be transmitted, a series of bytes.
delay: >=1
The length of a pulse in microseconds.
dutycycle: 0-range_
A number between 0 and range_.
The dutycycle sets the proportion of time on versus time off during each
PWM cycle.
Dutycycle @ On time
0 @ Off
range_ * 0.25 @ 25% On
range_ * 0.50 @ 50% On
range_ * 0.75 @ 75% On
range_ @ Fully On
edge: 0-2
. .
EITHER_EDGE = 2
FALLING_EDGE = 1
RISING_EDGE = 0
. .
errnum: <0
. .
PI_BAD_USER_GPIO = -2
PI_BAD_GPIO = -3
PI_BAD_MODE = -4
PI_BAD_LEVEL = -5
PI_BAD_PUD = -6
PI_BAD_PULSEWIDTH = -7
PI_BAD_DUTYCYCLE = -8
PI_BAD_WDOG_TIMEOUT = -15
PI_BAD_DUTYRANGE = -21
PI_NO_HANDLE = -24
PI_BAD_HANDLE = -25
PI_BAD_WAVE_BAUD = -35
PI_TOO_MANY_PULSES = -36
PI_TOO_MANY_CHARS = -37
PI_NOT_SERIAL_GPIO = -38
PI_NOT_PERMITTED = -41
PI_SOME_PERMITTED = -42
PI_BAD_WVSC_COMMND = -43
PI_BAD_WVSM_COMMND = -44
PI_BAD_WVSP_COMMND = -45
PI_BAD_PULSELEN = -46
PI_BAD_SCRIPT = -47
PI_BAD_SCRIPT_ID = -48
PI_BAD_SER_OFFSET = -49
PI_GPIO_IN_USE = -50
PI_BAD_SERIAL_COUNT = -51
PI_BAD_PARAM_NUM = -52
PI_DUP_TAG = -53
PI_TOO_MANY_TAGS = -54
PI_BAD_SCRIPT_CMD = -55
PI_BAD_VAR_NUM = -56
PI_NO_SCRIPT_ROOM = -57
PI_NO_MEMORY = -58
PI_SOCK_READ_FAILED = -59
PI_SOCK_WRIT_FAILED = -60
PI_TOO_MANY_PARAM = -61
PI_SCRIPT_NOT_READY = -62
PI_BAD_TAG = -63
PI_BAD_MICS_DELAY = -64
PI_BAD_MILS_DELAY = -65
PI_BAD_WAVE_ID = -66
PI_TOO_MANY_CBS = -67
PI_TOO_MANY_OOL = -68
PI_EMPTY_WAVEFORM = -69
PI_NO_WAVEFORM_ID = -70
PI_I2C_OPEN_FAILED = -71
PI_SER_OPEN_FAILED = -72
PI_SPI_OPEN_FAILED = -73
PI_BAD_I2C_BUS = -74
PI_BAD_I2C_ADDR = -75
PI_BAD_SPI_CHANNEL = -76
PI_BAD_FLAGS = -77
PI_BAD_SPI_SPEED = -78
PI_BAD_SER_DEVICE = -79
PI_BAD_SER_SPEED = -80
PI_BAD_PARAM = -81
PI_I2C_WRITE_FAILED = -82
PI_I2C_READ_FAILED = -83
PI_BAD_SPI_COUNT = -84
PI_SER_WRITE_FAILED = -85
PI_SER_READ_FAILED = -86
PI_SER_READ_NO_DATA = -87
PI_UNKNOWN_COMMAND = -88
PI_SPI_XFER_FAILED = -89
PI_NO_AUX_SPI = -91
PI_NOT_PWM_GPIO = -92
PI_NOT_SERVO_GPIO = -93
PI_NOT_HCLK_GPIO = -94
PI_NOT_HPWM_GPIO = -95
PI_BAD_HPWM_FREQ = -96
PI_BAD_HPWM_DUTY = -97
PI_BAD_HCLK_FREQ = -98
PI_BAD_HCLK_PASS = -99
PI_HPWM_ILLEGAL = -100
PI_BAD_DATABITS = -101
PI_BAD_STOPBITS = -102
PI_MSG_TOOBIG = -103
PI_BAD_MALLOC_MODE = -104
PI_BAD_SMBUS_CMD = -107
PI_NOT_I2C_GPIO = -108
PI_BAD_I2C_WLEN = -109
PI_BAD_I2C_RLEN = -110
PI_BAD_I2C_CMD = -111
PI_BAD_I2C_BAUD = -112
PI_CHAIN_LOOP_CNT = -113
PI_BAD_CHAIN_LOOP = -114
PI_CHAIN_COUNTER = -115
PI_BAD_CHAIN_CMD = -116
PI_BAD_CHAIN_DELAY = -117
PI_CHAIN_NESTING = -118
PI_CHAIN_TOO_BIG = -119
PI_DEPRECATED = -120
PI_BAD_SER_INVERT = -121
PI_BAD_FOREVER = -124
PI_BAD_FILTER = -125
PI_BAD_PAD = -126
PI_BAD_STRENGTH = -127
PI_FIL_OPEN_FAILED = -128
PI_BAD_FILE_MODE = -129
PI_BAD_FILE_FLAG = -130
PI_BAD_FILE_READ = -131
PI_BAD_FILE_WRITE = -132
PI_FILE_NOT_ROPEN = -133
PI_FILE_NOT_WOPEN = -134
PI_BAD_FILE_SEEK = -135
PI_NO_FILE_MATCH = -136
PI_NO_FILE_ACCESS = -137
PI_FILE_IS_A_DIR = -138
PI_BAD_SHELL_STATUS = -139
PI_BAD_SCRIPT_NAME = -140
PI_BAD_SPI_BAUD = -141
PI_NOT_SPI_GPIO = -142
PI_BAD_EVENT_ID = -143
PI_CMD_INTERRUPTED = -144
. .
event:0-31
An event is a signal used to inform one or more consumers
to start an action.
file_mode:
The mode may have the following values
. .
FILE_READ 1
FILE_WRITE 2
FILE_RW 3
. .
The following values can be or'd into the file open mode
. .
FILE_APPEND 4
FILE_CREATE 8
FILE_TRUNC 16
. .
file_name:
A full file path. To be accessible the path must match
an entry in /opt/pigpio/access.
fpattern:
A file path which may contain wildcards. To be accessible the path
must match an entry in /opt/pigpio/access.
frequency: 0-40000
Defines the frequency to be used for PWM on a GPIO.
The closest permitted frequency will be used.
func:
A user supplied callback function.
gpio: 0-53
A Broadcom numbered GPIO. All the user GPIO are in the range 0-31.
There are 54 General Purpose Input Outputs (GPIO) named GPIO0
through GPIO53.
They are split into two banks. Bank 1 consists of GPIO0
through GPIO31. Bank 2 consists of GPIO32 through GPIO53.
All the GPIO which are safe for the user to read and write are in
bank 1. Not all GPIO in bank 1 are safe though. Type 1 boards
have 17 safe GPIO. Type 2 boards have 21. Type 3 boards have 26.
See [*get_hardware_revision*].
The user GPIO are marked with an X in the following table
. .
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
Type 1 X X - - X - - X X X X X - - X X
Type 2 - - X X X - - X X X X X - - X X
Type 3 X X X X X X X X X X X X X X
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
Type 1 - X X - - X X X X X - - - - - -
Type 2 - X X - - - X X X X - X X X X X
Type 3 X X X X X X X X X X X X - - - -
. .
gpio_off:
A mask used to select GPIO to be operated on. See [*bits*].
This mask selects the GPIO to be switched off at the start
of a pulse.
gpio_on:
A mask used to select GPIO to be operated on. See [*bits*].
This mask selects the GPIO to be switched on at the start
of a pulse.
handle: >=0
A number referencing an object opened by one of the following
[*file_open*]
[*i2c_open*]
[*notify_open*]
[*serial_open*]
[*spi_open*]
host:
The name or IP address of the Pi running the pigpio daemon.
i2c_*:
One of the i2c_ functions.
i2c_address: 0-0x7F
The address of a device on the I2C bus.
i2c_bus: >=0
An I2C bus number.
i2c_flags: 0
No I2C flags are currently defined.
invert: 0-1
A flag used to set normal or inverted bit bang serial data
level logic.
level: 0-1 (2)
. .
CLEAR = 0
HIGH = 1
LOW = 0
OFF = 0
ON = 1
SET = 1
TIMEOUT = 2 # only returned for a watchdog timeout
. .
MISO:
The GPIO used for the MISO signal when bit banging SPI.
mode:
1.The operational mode of a GPIO, normally INPUT or OUTPUT.
. .
ALT0 = 4
ALT1 = 5
ALT2 = 6
ALT3 = 7
ALT4 = 3
ALT5 = 2
INPUT = 0
OUTPUT = 1
. .
2. The mode of waveform transmission.
. .
WAVE_MODE_ONE_SHOT = 0
WAVE_MODE_REPEAT = 1
WAVE_MODE_ONE_SHOT_SYNC = 2
WAVE_MODE_REPEAT_SYNC = 3
. .
MOSI:
The GPIO used for the MOSI signal when bit banging SPI.
offset: >=0
The offset wave data starts from the beginning of the waveform
being currently defined.
pad: 0-2
A set of GPIO which share common drivers.
Pad @ GPIO
0 @ 0-27
1 @ 28-45
2 @ 46-53
pad_strength: 1-16
The mA which may be drawn from each GPIO whilst still guaranteeing the
high and low levels.
params: 32 bit number
When scripts are started they can receive up to 10 parameters
to define their operation.
port:
The port used by the pigpio daemon, defaults to 8888.
pstring:
The string to be passed to a [*shell*] script to be executed.
pud: 0-2
. .
PUD_DOWN = 1
PUD_OFF = 0
PUD_UP = 2
. .
pulse_len: 1-100
The length of the trigger pulse in microseconds.
pulses:
A list of class pulse objects defining the characteristics of a
waveform.
pulsewidth:
The servo pulsewidth in microseconds. 0 switches pulses off.
PWMduty: 0-1000000 (1M)
The hardware PWM dutycycle.
PWMfreq: 1-125000000 (125M)
The hardware PWM frequency.
range_: 25-40000
Defines the limits for the [*dutycycle*] parameter.
range_ defaults to 255.
reg: 0-255
An I2C device register. The usable registers depend on the
actual device.
retMax: >=0
The maximum number of bytes a user customised function
should return, default 8192.
SCL:
The user GPIO to use for the clock when bit banging I2C.
SCLK::
The GPIO used for the SCLK signal when bit banging SPI.
script:
The text of a script to store on the pigpio daemon.
script_id: >=0
A number referencing a script created by [*store_script*].
SDA:
The user GPIO to use for data when bit banging I2C.
seek_from: 0-2
Direction to seek for [*file_seek*].
. .
FROM_START=0
FROM_CURRENT=1
FROM_END=2
. .
seek_offset:
The number of bytes to move forward (positive) or backwards
(negative) from the seek position (start, current, or end of file).
ser_flags: 32 bit
No serial flags are currently defined.
serial_*:
One of the serial_ functions.
shellscr:
The name of a shell script. The script must exist
in /opt/pigpio/cgi and must be executable.
show_errors:
Controls the display of pigpio daemon connection failures.
The default of True prints the probable failure reasons to
standard output.
spi_*:
One of the spi_ functions.
spi_channel: 0-2
A SPI channel.
spi_flags: 32 bit
See [*spi_open*].
steady: 0-300000
The number of microseconds level changes must be stable for
before reporting the level changed ([*set_glitch_filter*])
or triggering the active part of a noise filter
([*set_noise_filter*]).
t1:
A tick (earlier).
t2:
A tick (later).
tty:
A Pi serial tty device, e.g. /dev/ttyAMA0, /dev/ttyUSB0
uint32:
An unsigned 32 bit number.
user_gpio: 0-31
A Broadcom numbered GPIO.
All the user GPIO are in the range 0-31.
Not all the GPIO within this range are usable, some are reserved
for system use.
See [*gpio*].
wait_timeout: 0.0 -
The number of seconds to wait in [*wait_for_edge*] before timing out.
wave_add_*:
One of the following
[*wave_add_new*]
[*wave_add_generic*]
[*wave_add_serial*]
wave_id: >=0
A number referencing a wave created by [*wave_create*].
wave_send_*:
One of the following
[*wave_send_once*]
[*wave_send_repeat*]
wdog_timeout: 0-60000
Defines a GPIO watchdog timeout in milliseconds. If no level
change is detected on the GPIO for timeout millisecond a watchdog
timeout report is issued (with level TIMEOUT).
word_val: 0-65535
A whole number.
Definition at line 5111 of file pigpio.py.