pigpio is a Python module for the Raspberry which talks to
the pigpio daemon to allow control of the general purpose
input outputs (GPIO).
<h3>Features</h3>o the pigpio Python module can run on Windows, Macs, or Linux
<br><br>o controls one or more Pi's
<br><br>o hardware timed PWM on any of GPIO 0-31
<br><br>o hardware timed servo pulses on any of GPIO 0-31
<br><br>o callbacks when any of GPIO 0-31 change state
<br><br>o creating and transmitting precisely timed waveforms
<br><br>o reading/writing GPIO and setting their modes
<br><br>o wrappers for I2C, SPI, and serial links
<br><br>o creating and running scripts on the pigpio daemon
<h3>GPIO</h3>ALL GPIO are identified by their Broadcom number.
<h3>Notes</h3>Transmitted waveforms are accurate to a microsecond.
<br><br>Callback level changes are time-stamped and will be
accurate to within a few microseconds.
<h3>Settings</h3>A number of settings are determined when the pigpio daemon is started.
<br><br>o the sample rate (1, 2, 4, 5, 8, or 10 us, default 5 us).
<br><br>o the set of GPIO which may be updated (generally written to). The
default set is those available on the Pi board revision.
<br><br>o the available PWM frequencies (see <a href="#set_PWM_frequency">set_PWM_frequency</a>).
<h3>Exceptions</h3>By default a fatal exception is raised if you pass an invalid
argument to a pigpio function.
<br><br>If you wish to handle the returned status yourself you should set
pigpio.exceptions to False.
<br><br>You may prefer to check the returned status in only a few parts
of your code. In that case do the following:
<br><br><b><small>Example</small></b><br><br><code>pigpio.exceptions = False<br><br># Code where you want to test the error status.<br><br>pigpio.exceptions = True<br></code><h3>Usage</h3>This module uses the services of the C pigpio library. pigpio
must be running on the Pi(s) whose GPIO are to be manipulated.
<br><br>The normal way to start pigpio is as a daemon (during system
start).
<br><br>sudo pigpiod
<br><br>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.
<br><br><b><small>Example</small></b><br><br><code>pi1 = pigpio.pi() # pi1 accesses the local Pi's GPIO<br>pi2 = pigpio.pi('tom') # pi2 accesses tom's GPIO<br>pi3 = pigpio.pi('dick') # pi3 accesses dick's GPIO<br><br>pi1.write(4, 0) # set local Pi's GPIO 4 low<br>pi2.write(4, 1) # set tom's GPIO 4 to high<br>pi3.read(4) # get level of dick's GPIO 4<br></code><br><br>The later example code snippets assume that pi is an instance of
</td></tr><tr><td></td><td></td></tr><tr><td><a href="#read">read</a></td><td> Read a GPIO
</td></tr><tr><td><a href="#write">write</a></td><td> Write a GPIO
</td></tr><tr><td></td><td></td></tr><tr><td><b>PWM (overrides servo commands on same GPIO)
</b></td><td></td></tr><tr><td></td><td></td></tr><tr><td><a href="#set_PWM_dutycycle">set_PWM_dutycycle</a></td><td> Start/stop PWM pulses on a GPIO
</td></tr><tr><td><a href="#set_PWM_frequency">set_PWM_frequency</a></td><td> Set PWM frequency of a GPIO
</td></tr><tr><td><a href="#set_PWM_range">set_PWM_range</a></td><td> Configure PWM range of a GPIO
</td></tr><tr><td></td><td></td></tr><tr><td><a href="#get_PWM_dutycycle">get_PWM_dutycycle</a></td><td> Get PWM dutycycle set on a GPIO
</td></tr><tr><td><a href="#get_PWM_frequency">get_PWM_frequency</a></td><td> Get PWM frequency of a GPIO
</td></tr><tr><td><a href="#get_PWM_range">get_PWM_range</a></td><td> Get configured PWM range of a GPIO
</td></tr><tr><td></td><td></td></tr><tr><td><a href="#get_PWM_real_range">get_PWM_real_range</a></td><td> Get underlying PWM range for a GPIO
</td></tr><tr><td></td><td></td></tr><tr><td><b>Servo (overrides PWM commands on same GPIO)
</b></td><td></td></tr><tr><td></td><td></td></tr><tr><td><a href="#set_servo_pulsewidth">set_servo_pulsewidth</a></td><td> Start/Stop servo pulses on a GPIO
</td></tr><tr><td></td><td></td></tr><tr><td><a href="#get_servo_pulsewidth">get_servo_pulsewidth</a></td><td> Get servo pulsewidth set on a GPIO
</b></td><td></td></tr><tr><td></td><td></td></tr><tr><td><a href="#serial_open">serial_open</a></td><td> Opens a serial device
</td></tr><tr><td><a href="#serial_close">serial_close</a></td><td> Closes a serial device
</td></tr><tr><td></td><td></td></tr><tr><td><a href="#serial_read_byte">serial_read_byte</a></td><td> Reads a byte from a serial device
</td></tr><tr><td><a href="#serial_write_byte">serial_write_byte</a></td><td> Writes a byte to a serial device
</td></tr><tr><td></td><td></td></tr><tr><td><a href="#serial_read">serial_read</a></td><td> Reads bytes from a serial device
</td></tr><tr><td><a href="#serial_write">serial_write</a></td><td> Writes bytes to a serial device
</td></tr><tr><td></td><td></td></tr><tr><td><a href="#serial_data_available">serial_data_available</a></td><td> Returns number of bytes ready to be read
</td></tr><tr><td></td><td></td></tr><tr><td><b>SERIAL BIT BANG (read only)
</b></td><td></td></tr><tr><td></td><td></td></tr><tr><td><a href="#bb_serial_read_open">bb_serial_read_open</a></td><td> Open a GPIO for bit bang serial reads
</td></tr><tr><td><a href="#bb_serial_read_close">bb_serial_read_close</a></td><td> Close a GPIO for bit bang serial reads
</td></tr><tr><td></td><td></td></tr><tr><td><a href="#bb_serial_invert">bb_serial_invert</a></td><td> Invert serial logic (1 invert, 0 normal)
</td></tr><tr><td></td><td></td></tr><tr><td><a href="#bb_serial_read">bb_serial_read</a></td><td> Read bit bang serial data from a GPIO
<br><br><b><small>Parameters</small></b><br><br><samp>host:= the host name of the Pi on which the pigpio daemon is<br> running. The default is localhost unless overridden by<br> the PIGPIO_ADDR environment variable.<br></samp><br><br><b><small>Parameters</small></b><br><br><samp>port:= the port number on which the pigpio daemon is listening.<br> The default is 8888 unless overridden by the PIGPIO_PORT<br> environment variable. The pigpio daemon must have been<br> started with the same port number.<br></samp><br><br>This connects to the pigpio daemon and reserves resources
to be used for sending commands and receiving notifications.
<br><br>An instance attribute <a href="#connected">connected</a> may be used to check the
success of the connection. If the connection is established
successfully <a href="#connected">connected</a> will be True, otherwise False.
This function stops bit banging I2C on a pair of GPIO
previously opened with <a href="#bb_i2c_open">bb_i2c_open</a>.
<br><br><b><small>Parameters</small></b><br><br><samp>SDA:= 0-31, the SDA GPIO used in a prior call to <a href="#bb_i2c_open">bb_i2c_open</a><br></samp><br><br>Returns 0 if OK, otherwise PI_BAD_USER_GPIO, or PI_NOT_I2C_GPIO.
This function selects a pair of GPIO for bit banging I2C at a
specified baud rate.
<br><br>Bit banging I2C allows for certain operations which are not possible
with the standard I2C driver.
<br><br>o baud rates as low as 50
o repeated starts
o clock stretching
o I2C on any pair of spare GPIO
<br><br><b><small>Parameters</small></b><br><br><samp> SDA:= 0-31<br> SCL:= 0-31<br>baud:= 50-500000<br></samp><br><br>Returns 0 if OK, otherwise PI_BAD_USER_GPIO, PI_BAD_I2C_BAUD, or
PI_GPIO_IN_USE.
<br><br>NOTE:
<br><br>The GPIO used for SDA and SCL must have pull-ups to 3V3 connected.
As a guide the hardware pull-ups on pins 3 and 5 are 1k8 in value.
This function executes a sequence of bit banged I2C operations.
The operations to be performed are specified by the contents
of data which contains the concatenated command codes and
associated data.
<br><br><b><small>Parameters</small></b><br><br><samp> SDA:= 0-31 (as used in a prior call to <a href="#bb_i2c_open">bb_i2c_open</a>)<br>data:= the concatenated I2C commands, see below<br></samp><br><br>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).
<br><br><b><small>Example</small></b><br><br><code>(count, data) = pi.bb_i2c_zip(<br> SDA, [4, 0x53, 2, 7, 1, 0x32, 2, 6, 6, 3, 0])<br></code><br><br>The following command codes are supported:
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td>Name</td><td>Cmd & Data</td><td>Meaning</td></tr><tr><td>End</td><td>0</td><td>No more commands</td></tr><tr><td>Escape</td><td>1</td><td>Next P is two bytes</td></tr><tr><td>Start</td><td>2</td><td>Start condition</td></tr><tr><td>Stop</td><td>3</td><td>Stop condition</td></tr><tr><td>Address</td><td>4 P</td><td>Set I2C address to P</td></tr><tr><td>Flags</td><td>5 lsb msb</td><td>Set I2C flags to lsb + (msb << 8)</td></tr><tr><td>Read</td><td>6 P</td><td>Read P bytes of data</td></tr><tr><td>Write</td><td>7 P ...</td><td>Write P bytes of data</td></tr></tbody></table><br><br>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).
<br><br>The address and flags default to 0. The address and flags maintain
their previous value until updated.
<br><br>No flags are currently defined.
<br><br>Any read I2C data is concatenated in the returned bytearray.
Returns data from the bit bang serial cyclic buffer.
<br><br><b><small>Parameters</small></b><br><br><samp>user_gpio:= 0-31 (opened in a prior call to <a href="#bb_serial_read_open">bb_serial_read_open</a>)<br></samp><br><br>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).
<br><br>The bytes returned for each character depend upon the number of
data bits <a href="#bb_bits">bb_bits</a> specified in the <a href="#bb_serial_read_open">bb_serial_read_open</a>
command.
<br><br>For <a href="#bb_bits">bb_bits</a> 1-8 there will be one byte per character.
For <a href="#bb_bits">bb_bits</a> 9-16 there will be two bytes per character.
For <a href="#bb_bits">bb_bits</a> 17-32 there will be four bytes per character.
<br><br><b><small>Parameters</small></b><br><br><samp>user_gpio:= 0-31, the GPIO to use.<br> baud:= 50-250000, the baud rate.<br> bb_bits:= 1-32, the number of bits per word, default 8.<br></samp><br><br>The serial data is held in a cyclic buffer and is read using
<a href="#bb_serial_read">bb_serial_read</a>.
<br><br>It is the caller's responsibility to read data from the cyclic
This function stops bit banging SPI on a set of GPIO
opened with <a href="#bb_spi_open">bb_spi_open</a>.
<br><br><b><small>Parameters</small></b><br><br><samp>CS:= 0-31, the CS GPIO used in a prior call to <a href="#bb_spi_open">bb_spi_open</a><br></samp><br><br>Returns 0 if OK, otherwise PI_BAD_USER_GPIO, or PI_NOT_SPI_GPIO.
This function selects a set of GPIO for bit banging SPI at a
specified baud rate.
<br><br><b><small>Parameters</small></b><br><br><samp> CS := 0-31<br> MISO := 0-31<br> MOSI := 0-31<br> SCLK := 0-31<br> baud := 50-250000<br>spiFlags := see below<br></samp><br><br>spiFlags consists of the least significant 22 bits.
<br><br><code>21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0<br> 0 0 0 0 0 0 R T 0 0 0 0 0 0 0 0 0 0 0 p m m<br></code><br><br>mm defines the SPI mode, defaults to 0
<br><br><code>Mode CPOL CPHA<br> 0 0 0<br> 1 0 1<br> 2 1 0<br> 3 1 1<br></code><br><br>The following constants may be used to set the mode:
<br><br><b><small>Parameters</small></b><br><br><samp> CS:= 0-31 (as used in a prior call to <a href="#bb_spi_open">bb_spi_open</a>)<br>data:= data to be sent<br></samp><br><br>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
This function allows the Pi to act as a slave I2C device.
<br><br>This function is not available on the BCM2711 (e.g. as
used in the Pi4B).
<br><br>The data bytes (if any) are written to the BSC transmit
FIFO and the bytes in the BSC receive FIFO are returned.
<br><br><b><small>Parameters</small></b><br><br><samp>i2c_address:= the I2C slave address.<br> data:= the data bytes to transmit.<br></samp><br><br>The returned value is a tuple of the status, the number
of bytes read, and a bytearray containing the read bytes.
<br><br>See <a href="#bsc_xfer">bsc_xfer</a> for details of the status value.
<br><br>If there was an error the status will be less than zero
(and will contain the error code).
<br><br>Note that an i2c_address of 0 may be used to close
the BSC device and reassign the used GPIO as inputs.
<br><br>This example assumes GPIO 2/3 are connected to GPIO 18/19
(GPIO 10/11 on the BCM2711).
<br><br><b><small>Example</small></b><br><br><code>#!/usr/bin/env python<br>import time<br>import pigpio<br><br>I2C_ADDR=0x13<br><br>def i2c(id, tick):<br> global pi<br><br> s, b, d = pi.bsc_i2c(I2C_ADDR)<br> if b:<br> if d[0] == ord('t'): # 116 send 'HH:MM:SS*'<br><br> print("sent={} FR={} received={} [{}]".<br> format(s>>16, s&0xfff,b,d))<br><br> s, b, d = pi.bsc_i2c(I2C_ADDR,<br> "{}*".format(time.asctime()[11:19]))<br><br> elif d[0] == ord('d'): # 100 send 'Sun Oct 30*'<br><br> print("sent={} FR={} received={} [{}]".<br> format(s>>16, s&0xfff,b,d))<br><br> s, b, d = pi.bsc_i2c(I2C_ADDR,<br> "{}*".format(time.asctime()[:10]))<br><br>pi = pigpio.pi()<br><br>if not pi.connected:<br> exit()<br><br># Respond to BSC slave activity<br><br>e = pi.event_callback(pigpio.EVENT_BSC, i2c)<br><br>pi.bsc_i2c(I2C_ADDR) # Configure BSC as I2C slave<br><br>time.sleep(600)<br><br>e.cancel()<br><br>pi.bsc_i2c(0) # Disable BSC peripheral<br><br>pi.stop()<br></code><br><br>While running the above.
This function provides a low-level interface to the SPI/I2C Slave
peripheral on the BCM chip.
<br><br>This peripheral allows the Pi to act as a hardware slave device
on an I2C or SPI bus.
<br><br>This is not a bit bang version and as such is OS timing
independent. The bus timing is handled directly by the chip.
<br><br>The output process is simple. You simply append data to the FIFO
buffer on the chip. This works like a queue, you add data to the
queue and the master removes it.
<br><br>I can't get SPI to work properly. I tried with a
control word of 0x303 and swapped MISO and MOSI.
<br><br>The function sets the BSC mode, writes any data in
the transmit buffer to the BSC transmit FIFO, and
copies any data in the BSC receive FIFO to the
receive buffer.
<br><br><b><small>Parameters</small></b><br><br><samp>bsc_control:= see below<br> data:= the data bytes to place in the transmit FIFO.<br></samp><br><br>The returned value is a tuple of the status (see below),
the number of bytes read, and a bytearray containing the
read bytes. If there was an error the status will be less
than zero (and will contain the error code).
<br><br>Note that the control word sets the BSC mode. The BSC will
stay in that mode until a different control word is sent.
<br><br>GPIO used for models other than those based on the BCM2711.
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td></td><td>SDA</td><td>SCL</td><td>MOSI</td><td>SCLK</td><td>MISO</td><td>CE</td></tr><tr><td>I2C</td><td>18</td><td>19</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td>SPI</td><td>-</td><td>-</td><td>18</td><td>19</td><td>20</td><td>21</td></tr></tbody></table><br><br>GPIO used for models based on the BCM2711 (e.g. the Pi4B).
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td></td><td>SDA</td><td>SCL</td><td>MOSI</td><td>SCLK</td><td>MISO</td><td>CE</td></tr><tr><td>I2C</td><td>10</td><td>11</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td>SPI</td><td>-</td><td>-</td><td>10</td><td>11</td><td>9</td><td>8</td></tr></tbody></table><br><br>When a zero control word is received the used GPIO will be reset
to INPUT mode.
<br><br>bsc_control consists of the following bits:
<br><br><code>22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0<br> a a a a a a a - - IT HC TF IR RE TE BK EC ES PL PH I2 SP EN<br></code><br><br>Bits 0-13 are copied unchanged to the BSC CR register. See
pages 163-165 of the Broadcom peripherals document for full
details.
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td>aaaaaaa</td><td>defines the I2C slave address (only relevant in I2C mode)</td></tr><tr><td>IT</td><td>invert transmit status flags</td></tr><tr><td>HC</td><td>enable host control</td></tr><tr><td>TF</td><td>enable test FIFO</td></tr><tr><td>IR</td><td>invert receive status flags</td></tr><tr><td>RE</td><td>enable receive</td></tr><tr><td>TE</td><td>enable transmit</td></tr><tr><td>BK</td><td>abort operation and clear FIFOs</td></tr><tr><td>EC</td><td>send control register as first I2C byte</td></tr><tr><td>ES</td><td>send status register as first I2C byte</td></tr><tr><td>PL</td><td>set SPI polarity high</td></tr><tr><td>PH</td><td>set SPI phase high</td></tr><tr><td>I2</td><td>enable I2C mode</td></tr><tr><td>SP</td><td>enable SPI mode</td></tr><tr><td>EN</td><td>enable BSC peripheral</td></tr></tbody></table><br><br>The status has the following format:
<br><br><code>20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0<br> S S S S S R R R R R T T T T T RB TE RF TF RE TB<br></code><br><br>Bits 0-15 are copied unchanged from the BSC FR register. See
pages 165-166 of the Broadcom peripherals document for full
details.
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td>SSSSS</td><td>number of bytes successfully copied to transmit FIFO</td></tr><tr><td>RRRRR</td><td>number of bytes in receieve FIFO</td></tr><tr><td>TTTTT</td><td>number of bytes in transmit FIFO</td></tr><tr><td>RB</td><td>receive busy</td></tr><tr><td>TE</td><td>transmit FIFO empty</td></tr><tr><td>RF</td><td>receive FIFO full</td></tr><tr><td>TF</td><td>transmit FIFO full</td></tr><tr><td>RE</td><td>receive FIFO empty</td></tr><tr><td>TB</td><td>transmit busy</td></tr></tbody></table><br><br><b><small>Example</small></b><br><br><code>(status, count, data) = pi.bsc_xfer(0x330305, "Hello!")<br></code><h3><a name="callback">callback<small>(<a href="#user_gpio">user_gpio</a>, <a href="#edge">edge</a>, <a href="#func">func</a>)</small></h3>
Calls a user supplied function (a callback) whenever the
specified GPIO edge is detected.
<br><br><b><small>Parameters</small></b><br><br><samp>user_gpio:= 0-31.<br> edge:= EITHER_EDGE, RISING_EDGE (default), or FALLING_EDGE.<br> func:= user supplied callback function.<br></samp><br><br>The user supplied callback receives three parameters, the GPIO,
the level, and the tick.
<br><br><code>Parameter Value Meaning<br><br>GPIO 0-31 The GPIO which has changed state<br><br>level 0-2 0 = change to low (a falling edge)<br> 1 = change to high (a rising edge)<br> 2 = no level change (a watchdog timeout)<br><br>tick 32 bit The number of microseconds since boot<br> WARNING: this wraps around from<br> 4294967295 to 0 roughly every 72 minutes<br></code><br><br>If a user callback is not specified a default tally callback is
provided which simply counts edges. The count may be retrieved
by calling the tally function. The count may be reset to zero
by calling the reset_tally function.
<br><br>The callback may be cancelled by calling the cancel function.
<br><br>A GPIO may have multiple callbacks (although I can't think of
a reason to do so).
<br><br>The GPIO are sampled at a rate set when the pigpio daemon
is started (default 5 us).
<br><br>The number of samples per second is given in the following table.
<br><br><code> samples<br> per sec<br><br> 1 1,000,000<br> 2 500,000<br>sample 4 250,000<br>rate 5 200,000<br>(us) 8 125,000<br> 10 100,000<br></code><br><br>GPIO level changes shorter than the sample rate may be missed.
<br><br>The daemon software which generates the callbacks is triggered
1000 times per second. The callbacks will be called once per
level change since the last time they were called.
i.e. The callbacks will get all level changes but there will
be a latency.
<br><br>If you want to track the level of more than one GPIO do so by
maintaining the state in the callback. Do not use <a href="#read">read</a>.
Remember the event that triggered the callback may have
happened several milliseconds before and the GPIO may have
Clears GPIO 0-31 if the corresponding bit in bits is set.
<br><br><b><small>Parameters</small></b><br><br><samp>bits:= a 32 bit mask with 1 set if the corresponding GPIO is<br> to be cleared.<br></samp><br><br>A returned status of PI_SOME_PERMITTED indicates that the user
is not allowed to write to one or more of the GPIO.
Clears GPIO 32-53 if the corresponding bit (0-21) in bits is set.
<br><br><b><small>Parameters</small></b><br><br><samp>bits:= a 32 bit mask with 1 set if the corresponding GPIO is<br> to be cleared.<br></samp><br><br>A returned status of PI_SOME_PERMITTED indicates that the user
is not allowed to write to one or more of the GPIO.
<br><br><b><small>Parameters</small></b><br><br><samp>arg1:= >=0, default 0.<br>arg2:= >=0, default 0.<br>argx:= extra arguments (each 0-255), default empty.<br></samp><br><br>The returned value is an integer which by convention
<br><br><b><small>Parameters</small></b><br><br><samp> arg1:= >=0, default 0.<br> argx:= extra arguments (each 0-255), default empty.<br>retMax:= >=0, maximum number of bytes to return, default 8192.<br></samp><br><br>The returned value is a tuple of the number of bytes
returned and a bytearray containing the bytes. If
there was an error the number of bytes read will be
Calls a user supplied function (a callback) whenever the
specified event is signalled.
<br><br><b><small>Parameters</small></b><br><br><samp>event:= 0-31.<br> func:= user supplied callback function.<br></samp><br><br>The user supplied callback receives two parameters, the event id,
and the tick.
<br><br>If a user callback is not specified a default tally callback is
provided which simply counts events. The count may be retrieved
by calling the tally function. The count may be reset to zero
by calling the reset_tally function.
<br><br>The callback may be cancelled by calling the event_cancel function.
<br><br>An event may have multiple callbacks (although I can't think of
<br><br><b><small>Parameters</small></b><br><br><samp>fpattern:= file pattern to match.<br></samp><br><br>Returns the number of returned bytes if OK, otherwise
PI_NO_FILE_ACCESS, or PI_NO_FILE_MATCH.
<br><br>The pattern must match an entry in /opt/pigpio/access. The
pattern may contain wildcards. See <a href="#file_open">file_open</a>.
<br><br>NOTE
<br><br>The returned value is not the number of files, it is the number
of bytes in the buffer. The file names are separated by newline
This function returns a handle to a file opened in a specified mode.
<br><br><b><small>Parameters</small></b><br><br><samp>file_name:= the file to open.<br>file_mode:= the file open mode.<br></samp><br><br>Returns a handle (>=0) if OK, otherwise PI_NO_HANDLE,
<br><br>A file may only be opened if permission is granted by an entry
in /opt/pigpio/access. This is intended to allow remote access
to files in a more or less controlled manner.
<br><br>Each entry in /opt/pigpio/access takes the form of a file path
which may contain wildcards followed by a single letter permission.
The permission may be R for read, W for write, U for read/write,
and N for no access.
<br><br>Where more than one entry matches a file the most specific rule
applies. If no entry matches a file then access is denied.
<br><br>Suppose /opt/pigpio/access contains the following entries:
<br><br><code>/home/* n<br>/home/pi/shared/dir_1/* w<br>/home/pi/shared/dir_2/* r<br>/home/pi/shared/dir_3/* u<br>/home/pi/shared/dir_1/file.txt n<br></code><br><br>Files may be written in directory dir_1 with the exception
of file.txt.
<br><br>Files may be read in directory dir_2.
<br><br>Files may be read and written in directory dir_3.
<br><br>If a directory allows read, write, or read/write access then files
may be created in that directory.
<br><br>In an attempt to prevent risky permissions the following paths are
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td>Constant</td><td>Value</td><td>Meaning</td></tr><tr><td>FILE_READ</td><td>1</td><td>open file for reading</td></tr><tr><td>FILE_WRITE</td><td>2</td><td>open file for writing</td></tr><tr><td>FILE_RW</td><td>3</td><td>open file for reading and writing</td></tr></tbody></table><br><br>The following values may be or'd into the mode:
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td>Name</td><td>Value</td><td>Meaning</td></tr><tr><td>FILE_APPEND</td><td>4</td><td>All writes append data to the end of the file</td></tr><tr><td>FILE_CREATE</td><td>8</td><td>The file is created if it doesn't exist</td></tr><tr><td>FILE_TRUNC</td><td>16</td><td>The file is truncated</td></tr></tbody></table><br><br>Newly created files are owned by root with permissions owner
Reads up to count bytes from the file associated with handle.
<br><br><b><small>Parameters</small></b><br><br><samp>handle:= >=0 (as returned by a prior call to <a href="#file_open">file_open</a>).<br> count:= >0, the number of bytes to read.<br></samp><br><br>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
Returns the range of PWM values being used on the GPIO.
<br><br><b><small>Parameters</small></b><br><br><samp>user_gpio:= 0-31.<br></samp><br><br>If a hardware clock or hardware PWM is active on the GPIO
This function returns the pad drive strength in mA.
<br><br><b><small>Parameters</small></b><br><br><samp>pad:= 0-2, the pad to get.<br></samp><br><br>Returns the pad drive strength if OK, otherwise PI_BAD_PAD.
<br><br>The same PWM channel is available on multiple GPIO.
The latest frequency and dutycycle setting will be used
by all GPIO which share a PWM channel.
<br><br>The GPIO must be one of the following:
<br><br><code>12 PWM channel 0 All models but A and B<br>13 PWM channel 1 All models but A and B<br>18 PWM channel 0 All models<br>19 PWM channel 1 All models but A and B<br><br>40 PWM channel 0 Compute module only<br>41 PWM channel 1 Compute module only<br>45 PWM channel 1 Compute module only<br>52 PWM channel 0 Compute module only<br>53 PWM channel 1 Compute module only<br></code><br><br>The actual number of steps beween off and fully on is the
integral part of 250M/PWMfreq (375M/PWMfreq for the BCM2711).
<br><br>The actual frequency set is 250M/steps (375M/steps
for the BCM2711).
<br><br>There will only be a million steps for a PWMfreq of 250
(375 for the BCM2711). Lower frequencies will have more
steps and higher frequencies will have fewer steps.
PWMduty is automatically scaled to take this into account.
<br><br>The same clock is available on multiple GPIO. The latest
frequency setting will be used by all GPIO which share a clock.
<br><br>The GPIO must be one of the following:
<br><br><code>4 clock 0 All models<br>5 clock 1 All models but A and B (reserved for system use)<br>6 clock 2 All models but A and B<br>20 clock 0 All models but A and B<br>21 clock 1 All models but A and Rev.2 B (reserved for system use)<br><br>32 clock 0 Compute module only<br>34 clock 0 Compute module only<br>42 clock 1 Compute module only (reserved for system use)<br>43 clock 2 Compute module only<br>44 clock 1 Compute module only (reserved for system use)<br></code><br><br>Access to clock 1 is protected by a password as its use will
likely crash the Pi. The password is given by or'ing 0x5A000000
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.
<br><br><b><small>Parameters</small></b><br><br><samp>handle:= >=0 (as returned by a prior call to <a href="#i2c_open">i2c_open</a>).<br> reg:= >=0, the device register.<br> data:= the bytes to write.<br></samp><br><br>The SMBus 2.0 documentation states that a minimum of 1 byte may
be sent and a minimum of 1 byte may be received. The total
number of bytes sent/received must be 32 or less.
<br><br>SMBus 2.0 5.5.8 - Block write-block read.
<code>S Addr Wr [A] reg [A] len(data) [A] data0 [A] ... datan [A]<br> S Addr Rd [A] [Count] A [Data] ... A P<br></code><br><br>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
Returns a handle (>=0) for the device at the I2C bus address.
<br><br><b><small>Parameters</small></b><br><br><samp> i2c_bus:= >=0.<br>i2c_address:= 0-0x7F.<br> i2c_flags:= 0, no flags are currently defined.<br></samp><br><br>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.
<br><br>The GPIO used are given in the following table.
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td></td><td>SDA</td><td>SCL</td></tr><tr><td>I2C 0</td><td>0</td><td>1</td></tr><tr><td>I2C 1</td><td>2</td><td>3</td></tr></tbody></table><br><br>For the SMBus commands the low level transactions are shown
at the end of the function description. The following
<code>S Addr Wr [A] reg [A]<br> S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P<br></code><br><br>The amount of returned data is set by the device.
<br><br>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
Returns count bytes read from the raw device associated
with handle.
<br><br><b><small>Parameters</small></b><br><br><samp>handle:= >=0 (as returned by a prior call to <a href="#i2c_open">i2c_open</a>).<br> count:= >0, the number of bytes to read.<br></samp><br><br><code>S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P<br></code><br><br>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
Reads count bytes from the specified register of the device
associated with handle . The count may be 1-32.
<br><br><b><small>Parameters</small></b><br><br><samp>handle:= >=0 (as returned by a prior call to <a href="#i2c_open">i2c_open</a>).<br> reg:= >=0, the device register.<br> count:= >0, the number of bytes to read.<br></samp><br><br><code>S Addr Wr [A] reg [A]<br> S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P<br></code><br><br>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
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.
<br><br><b><small>Parameters</small></b><br><br><samp>handle:= >=0 (as returned by a prior call to <a href="#i2c_open">i2c_open</a>).<br> data:= the concatenated I2C commands, see below<br></samp><br><br>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).
<br><br><b><small>Example</small></b><br><br><code>(count, data) = pi.i2c_zip(h, [4, 0x53, 7, 1, 0x32, 6, 6, 0])<br></code><br><br>The following command codes are supported:
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td>Name</td><td>Cmd & Data</td><td>Meaning</td></tr><tr><td>End</td><td>0</td><td>No more commands</td></tr><tr><td>Escape</td><td>1</td><td>Next P is two bytes</td></tr><tr><td>On</td><td>2</td><td>Switch combined flag on</td></tr><tr><td>Off</td><td>3</td><td>Switch combined flag off</td></tr><tr><td>Address</td><td>4 P</td><td>Set I2C address to P</td></tr><tr><td>Flags</td><td>5 lsb msb</td><td>Set I2C flags to lsb + (msb << 8)</td></tr><tr><td>Read</td><td>6 P</td><td>Read P bytes of data</td></tr><tr><td>Write</td><td>7 P ...</td><td>Write P bytes of data</td></tr></tbody></table><br><br>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).
<br><br>The address defaults to that associated with the handle.
The flags default to 0. The address and flags maintain their
previous value until updated.
<br><br>Any read I2C data is concatenated in the returned bytearray.
<br><br><b><small>Parameters</small></b><br><br><samp>handle:= >=0 (as returned by a prior call to <a href="#notify_open">notify_open</a>)<br> bits:= a 32 bit mask indicating the GPIO to be notified.<br></samp><br><br>The notification sends state changes for each GPIO whose
corresponding bit in bits is set.
<br><br>The following code starts notifications for GPIO 1, 4,
6, 7, and 10 (1234 = 0x04D2 = 0b0000010011010010).
<br><br><b><small>Parameters</small></b><br><br><samp>handle:= >=0 (as returned by a prior call to <a href="#notify_open">notify_open</a>)<br></samp><br><br>Notifications for the handle are suspended until
<a href="#notify_begin">notify_begin</a> is called again.
Returns the run status of a stored script as well as the
current values of parameters 0 to 9.
<br><br><b><small>Parameters</small></b><br><br><samp>script_id:= id of stored script.<br></samp><br><br>The run status may be
<br><br><code>PI_SCRIPT_INITING<br>PI_SCRIPT_HALTED<br>PI_SCRIPT_RUNNING<br>PI_SCRIPT_WAITING<br>PI_SCRIPT_FAILED<br></code><br><br>The return value is a tuple of run status and a list of
the 10 parameters. On error the run status will be negative
at baud bits per second. The device name must start
with /dev/tty or /dev/serial.
<br><br><b><small>Parameters</small></b><br><br><samp> tty:= the serial device to open.<br> baud:= baud rate in bits per second, see below.<br>ser_flags:= 0, no flags are currently defined.<br></samp><br><br>Normally you would only use the <a href="#serial_*">serial_*</a> functions if
you are or will be connecting to the Pi over a network. If
you will always run on the local Pi use the standard serial
module instead.
<br><br>The baud rate must be one of 50, 75, 110, 134, 150,
Reads up to count bytes from the device associated with handle.
<br><br><b><small>Parameters</small></b><br><br><samp>handle:= >=0 (as returned by a prior call to <a href="#serial_open">serial_open</a>).<br> count:= >0, the number of bytes to read (defaults to 1000).<br></samp><br><br>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).
<br><br>If no data is ready a bytes read of zero is returned.
Returns a single byte from the device associated with handle.
<br><br><b><small>Parameters</small></b><br><br><samp>handle:= >=0 (as returned by a prior call to <a href="#serial_open">serial_open</a>).<br></samp><br><br>If no data is ready a negative error code will be returned.
Starts (non-zero dutycycle) or stops (0) PWM pulses on the GPIO.
<br><br><b><small>Parameters</small></b><br><br><samp>user_gpio:= 0-31.<br>dutycycle:= 0-range (range defaults to 255).<br></samp><br><br>The <a href="#set_PWM_range">set_PWM_range</a> function can change the default range of 255.
Sets the frequency (in Hz) of the PWM to be used on the GPIO.
<br><br><b><small>Parameters</small></b><br><br><samp>user_gpio:= 0-31.<br>frequency:= >=0 Hz<br></samp><br><br>Returns the numerically closest frequency if OK, otherwise
PI_BAD_USER_GPIO or PI_NOT_PERMITTED.
<br><br>If PWM is currently active on the GPIO it will be switched
off and then back on at the new frequency.
<br><br>Each GPIO can be independently set to one of 18 different
PWM frequencies.
<br><br>The selectable frequencies depend upon the sample rate which
may be 1, 2, 4, 5, 8, or 10 microseconds (default 5). The
sample rate is set when the pigpio daemon is started.
Sets GPIO 0-31 if the corresponding bit in bits is set.
<br><br><b><small>Parameters</small></b><br><br><samp>bits:= a 32 bit mask with 1 set if the corresponding GPIO is<br> to be set.<br></samp><br><br>A returned status of PI_SOME_PERMITTED indicates that the user
is not allowed to write to one or more of the GPIO.
Sets GPIO 32-53 if the corresponding bit (0-21) in bits is set.
<br><br><b><small>Parameters</small></b><br><br><samp>bits:= a 32 bit mask with 1 set if the corresponding GPIO is<br> to be set.<br></samp><br><br>A returned status of PI_SOME_PERMITTED indicates that the user
is not allowed to write to one or more of the GPIO.
<br><br>Level changes on the GPIO are not reported unless the level
has been stable for at least <a href="#steady">steady</a> microseconds. The
level is then reported. Level changes of less than <a href="#steady">steady</a>
microseconds are ignored.
<br><br><b><small>Parameters</small></b><br><br><samp>user_gpio:= 0-31<br> steady:= 0-300000<br></samp><br><br>Returns 0 if OK, otherwise PI_BAD_USER_GPIO, or PI_BAD_FILTER.
<br><br>This filter affects the GPIO samples returned to callbacks set up
with <a href="#callback">callback</a> and <a href="#wait_for_edge">wait_for_edge</a>.
<br><br>It does not affect levels read by <a href="#read">read</a>,
<a href="#read_bank_1">read_bank_1</a>, or <a href="#read_bank_2">read_bank_2</a>.
<br><br>Each (stable) edge will be timestamped <a href="#steady">steady</a>
<br><br>Level changes on the GPIO are ignored until a level which has
been stable for <a href="#steady">steady</a> microseconds is detected. Level
changes on the GPIO are then reported for <a href="#active">active</a>
microseconds after which the process repeats.
<br><br><b><small>Parameters</small></b><br><br><samp>user_gpio:= 0-31<br> steady:= 0-300000<br> active:= 0-1000000<br></samp><br><br>Returns 0 if OK, otherwise PI_BAD_USER_GPIO, or PI_BAD_FILTER.
<br><br>This filter affects the GPIO samples returned to callbacks set up
with <a href="#callback">callback</a> and <a href="#wait_for_edge">wait_for_edge</a>.
<br><br>It does not affect levels read by <a href="#read">read</a>,
<a href="#read_bank_1">read_bank_1</a>, or <a href="#read_bank_2">read_bank_2</a>.
<br><br>Level changes before and after the active period may
be reported. Your software must be designed to cope with
<br><br><b><small>Parameters</small></b><br><br><samp> pad:= 0-2, the pad to set.<br>pad_strength:= 1-16 mA.<br></samp><br><br>Returns 0 if OK, otherwise PI_BAD_PAD, or PI_BAD_STRENGTH.
Starts (500-2500) or stops (0) servo pulses on the GPIO.
<br><br><b><small>Parameters</small></b><br><br><samp> user_gpio:= 0-31.<br>pulsewidth:= 0 (off),<br> 500 (most anti-clockwise) - 2500 (most clockwise).<br></samp><br><br>The selected pulsewidth will continue to be transmitted until
changed by a subsequent call to set_servo_pulsewidth.
<br><br>The pulsewidths supported by servos varies and should probably
be determined by experiment. A value of 1500 should always be
safe and represents the mid-point of rotation.
<br><br>You can DAMAGE a servo if you command it to move beyond its
<br><br><b><small>Parameters</small></b><br><br><samp> user_gpio:= 0-31.<br>wdog_timeout:= 0-60000.<br></samp><br><br>The watchdog is nominally in milliseconds.
<br><br>Only one watchdog may be registered per GPIO.
<br><br>The watchdog may be cancelled by setting timeout to 0.
<br><br>Once a watchdog has been started callbacks for the GPIO
will be triggered every timeout interval after the last
GPIO activity.
<br><br>The callback will receive the special level TIMEOUT.
This function uses the system call to execute a shell script
with the given string as its parameter.
<br><br><b><small>Parameters</small></b><br><br><samp>shellscr:= the name of the script, only alphanumerics,<br> '-' and '_' are allowed in the name<br>pstring := the parameter string to pass to the script<br></samp><br><br>The exit status of the system call is returned if OK,
otherwise PI_BAD_SHELL_STATUS.
<br><br><a href="#shellscr">shellscr</a> must exist in /opt/pigpio/cgi and must be executable.
<br><br>The returned exit status is normally 256 times that set by
the shell script exit function. If the script can't be
found 32512 will be returned.
<br><br>The following table gives some example returned statuses:
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td>Script exit status</td><td>Returned system call status</td></tr><tr><td>1</td><td>256</td></tr><tr><td>5</td><td>1280</td></tr><tr><td>10</td><td>2560</td></tr><tr><td>200</td><td>51200</td></tr><tr><td>script not found</td><td>32512</td></tr></tbody></table><br><br><b><small>Example</small></b><br><br><code>// pass two parameters, hello and world<br>status = pi.shell("scr1", "hello world");<br><br>// pass three parameters, hello, string with spaces, and world<br>status = pi.shell("scr1", "hello 'string with spaces' world");<br><br>// pass one parameter, hello string with spaces world<br>status = pi.shell("scr1", "\"hello string with spaces world\"");<br></code><h3><a name="spi_close">spi_close<small>(<a href="#handle">handle</a>)</small></h3>
Returns a handle for the SPI device on the 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.
<br><br>The Pi has two SPI peripherals: main and auxiliary.
<br><br>The main SPI has two chip selects (channels), the auxiliary
has three.
<br><br>The auxiliary SPI is available on all models but the A and B.
<br><br>The GPIO used are given in the following table.
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td></td><td>MISO</td><td>MOSI</td><td>SCLK</td><td>CE0</td><td>CE1</td><td>CE2</td></tr><tr><td>Main SPI</td><td>9</td><td>10</td><td>11</td><td>8</td><td>7</td><td>-</td></tr><tr><td>Aux SPI</td><td>19</td><td>20</td><td>21</td><td>18</td><td>17</td><td>16</td></tr></tbody></table><br><br><b><small>Parameters</small></b><br><br><samp>spi_channel:= 0-1 (0-2 for the auxiliary SPI).<br> baud:= 32K-125M (values above 30M are unlikely to work).<br> spi_flags:= see below.<br></samp><br><br>spi_flags consists of the least significant 22 bits.
<br><br><code>21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0<br> b b b b b b R T n n n n W A u2 u1 u0 p2 p1 p0 m m<br></code><br><br>mm defines the SPI mode.
<br><br>WARNING: modes 1 and 3 do not appear to work on
the auxiliary SPI.
<br><br><code>Mode POL PHA<br> 0 0 0<br> 1 0 1<br> 2 1 0<br> 3 1 1<br></code><br><br>px is 0 if CEx is active low (default) and 1 for active high.
<br><br>ux is 0 if the CEx GPIO is reserved for SPI (default)
and 1 otherwise.
<br><br>A is 0 for the main SPI, 1 for the auxiliary SPI.
<br><br>W is 0 if the device is not 3-wire, 1 if the device is 3-wire.
Main SPI only.
<br><br>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. Main SPI only.
<br><br>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 only.
<br><br>R is 1 if the least significant bit is received on MISO
first, the default (0) receives the most significant bit
first. Auxiliary SPI only.
<br><br>bbbbbb defines the word size in bits (0-32). The default (0)
sets 8 bits per word. Auxiliary SPI only.
<br><br>The <a href="#spi_read">spi_read</a>, <a href="#spi_write">spi_write</a>, and <a href="#spi_xfer">spi_xfer</a> functions
transfer data packed into 1, 2, or 4 bytes according to
the word size in bits.
<br><br>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.
<br><br>Multi-byte transfers are made in least significant byte
first order.
<br><br>E.g. to transfer 32 11-bit words data should
contain 64 bytes.
<br><br>E.g. to transfer the 14 bit value 0x1ABC send the
bytes 0xBC followed by 0x1A.
<br><br>The other bits in flags should be set to zero.
Reads count bytes from the SPI device associated with handle.
<br><br><b><small>Parameters</small></b><br><br><samp>handle:= >=0 (as returned by a prior call to <a href="#spi_open">spi_open</a>).<br> count:= >0, the number of bytes to read.<br></samp><br><br>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
Writes the data bytes to the SPI device associated with handle,
returning the data bytes read from the device.
<br><br><b><small>Parameters</small></b><br><br><samp>handle:= >=0 (as returned by a prior call to <a href="#spi_open">spi_open</a>).<br> data:= the bytes to write.<br></samp><br><br>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
<br><br>See <a href="http://abyz.me.uk/rpi/pigpio/pigs.html#Scripts">http://abyz.me.uk/rpi/pigpio/pigs.html#Scripts</a> for
details.
<br><br><b><small>Parameters</small></b><br><br><samp>script:= the script text as a series of bytes.<br></samp><br><br>Returns a >=0 script id if OK.
<br><br><b><small>Parameters</small></b><br><br><samp> user_gpio:= 0-31.<br> edge:= EITHER_EDGE, RISING_EDGE (default), or<br> FALLING_EDGE.<br>wait_timeout:= >=0.0 (default 60.0).<br></samp><br><br>The function returns when the edge is detected or after
the number of seconds specified by timeout has expired.
<br><br>Do not use this function for precise timing purposes,
the edge is only checked 20 times a second. Whenever
you need to know the accurate time of GPIO events use
a <a href="#callback">callback</a> function.
<br><br>The function returns True if the edge is detected,
<br><br><b><small>Parameters</small></b><br><br><samp> event:= 0-31.<br>wait_timeout:= >=0.0 (default 60.0).<br></samp><br><br>The function returns when the event is signalled or after
the number of seconds specified by timeout has expired.
<br><br>The function returns True if the event is detected,
<br><br><b><small>Parameters</small></b><br><br><samp>pulses:= list of pulses to add to the waveform.<br></samp><br><br>Returns the new total number of pulses in the current waveform.
<br><br>The pulses are interleaved in time order within the existing
waveform (if any).
<br><br>Merging allows the waveform to be built in parts, that is the
settings for GPIO#1 can be added, and then GPIO#2 etc.
<br><br>If the added waveform is intended to start after or within
the existing waveform then the first pulse should consist
Adds a waveform representing serial data to the existing
waveform (if any). The serial data starts <a href="#offset">offset</a>
microseconds from the start of the waveform.
<br><br><b><small>Parameters</small></b><br><br><samp>user_gpio:= GPIO to transmit data. You must set the GPIO mode<br> to output.<br> baud:= 50-1000000 bits per second.<br> data:= the bytes to write.<br> offset:= number of microseconds from the start of the<br> waveform, default 0.<br> bb_bits:= number of data bits, default 8.<br> bb_stop:= number of stop half bits, default 2.<br></samp><br><br>Returns the new total number of pulses in the current waveform.
<br><br>The serial data is formatted as one start bit, <a href="#bb_bits">bb_bits</a>
data bits, and <a href="#bb_stop">bb_stop</a>/2 stop bits.
<br><br>It is legal to add serial data streams with different baud
rates to the same waveform.
<br><br>The bytes required for each character depend upon <a href="#bb_bits">bb_bits</a>.
<br><br>For <a href="#bb_bits">bb_bits</a> 1-8 there will be one byte per character.
For <a href="#bb_bits">bb_bits</a> 9-16 there will be two bytes per character.
For <a href="#bb_bits">bb_bits</a> 17-32 there will be four bytes per character.
<br><br>Each wave is transmitted in the order specified. A wave
may occur multiple times per chain.
<br><br>A blocks of waves may be transmitted multiple times by
using the loop commands. The block is bracketed by loop
start and end commands. Loops may be nested.
<br><br>Delays between waves may be added with the delay command.
<br><br>The following command codes are supported:
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td>Name</td><td>Cmd & Data</td><td>Meaning</td></tr><tr><td>Loop Start</td><td>255 0</td><td>Identify start of a wave block</td></tr><tr><td>Loop Repeat</td><td>255 1 x y</td><td>loop x + y*256 times</td></tr><tr><td>Delay</td><td>255 2 x y</td><td>delay x + y*256 microseconds</td></tr><tr><td>Loop Forever</td><td>255 3</td><td>loop forever</td></tr></tbody></table><br><br>If present Loop Forever must be the last entry in the chain.
<br><br>The code is currently dimensioned to support a chain with
<br><br><code>percent: 0-100, size of waveform as percentage of maximum available.<br></code><br><br>The data provided by the <a href="#wave_add_*">wave_add_*</a> functions are consumed by this
This function deletes the waveform with id wave_id.
<br><br><b><small>Parameters</small></b><br><br><samp>wave_id:= >=0 (as returned by a prior call to <a href="#wave_create">wave_create</a>).<br></samp><br><br>Wave ids are allocated in order, 0, 1, 2, etc.
<br><br>The wave is flagged for deletion. The resources used by the wave
will only be reused when either of the following apply.
<br><br>- all waves with higher numbered wave ids have been deleted or have
been flagged for deletion.
<br><br>- a new wave is created which uses exactly the same resources as
the current wave (see the C source for gpioWaveCreate for details).
Transmits the waveform with id wave_id. The waveform is sent
once.
<br><br>NOTE: Any hardware PWM started by <a href="#hardware_PWM">hardware_PWM</a> will
be cancelled.
<br><br><b><small>Parameters</small></b><br><br><samp>wave_id:= >=0 (as returned by a prior call to <a href="#wave_create">wave_create</a>).<br></samp><br><br>Returns the number of DMA control blocks used in the waveform.
Transmits the waveform with id wave_id. The waveform repeats
until wave_tx_stop is called or another call to <a href="#wave_send_*">wave_send_*</a>
is made.
<br><br>NOTE: Any hardware PWM started by <a href="#hardware_PWM">hardware_PWM</a> will
be cancelled.
<br><br><b><small>Parameters</small></b><br><br><samp>wave_id:= >=0 (as returned by a prior call to <a href="#wave_create">wave_create</a>).<br></samp><br><br>Returns the number of DMA control blocks used in the waveform.
Transmits the waveform with id wave_id using mode mode.
<br><br><b><small>Parameters</small></b><br><br><samp>wave_id:= >=0 (as returned by a prior call to <a href="#wave_create">wave_create</a>).<br> mode:= WAVE_MODE_ONE_SHOT, WAVE_MODE_REPEAT,<br> WAVE_MODE_ONE_SHOT_SYNC, or WAVE_MODE_REPEAT_SYNC.<br></samp><br><br>WAVE_MODE_ONE_SHOT: same as <a href="#wave_send_once">wave_send_once</a>.
<br><br>WAVE_MODE_REPEAT same as <a href="#wave_send_repeat">wave_send_repeat</a>.
<br><br>WAVE_MODE_ONE_SHOT_SYNC same as <a href="#wave_send_once">wave_send_once</a> but tries
to sync with the previous waveform.
<br><br>WAVE_MODE_REPEAT_SYNC same as <a href="#wave_send_repeat">wave_send_repeat</a> but tries
to sync with the previous waveform.
<br><br>WARNING: bad things may happen if you delete the previous
waveform before it has been synced to the new waveform.
<br><br>NOTE: Any hardware PWM started by <a href="#hardware_PWM">hardware_PWM</a> will
be cancelled.
<br><br><b><small>Parameters</small></b><br><br><samp>wave_id:= >=0 (as returned by a prior call to <a href="#wave_create">wave_create</a>).<br></samp><br><br>Returns the number of DMA control blocks used in the waveform.
<br><br><b><small>Parameters</small></b><br><br><samp> GPIO:= 0-53.<br>level:= 0, 1.<br></samp><br><br>If PWM or servo pulses are active on the GPIO they are
switched off.
<br><br><b><small>Example</small></b><br><br><code>pi.set_mode(17, pigpio.OUTPUT)<br><br>pi.write(17,0)<br>print(pi.read(17))<br>0<br><br>pi.write(17,1)<br>print(pi.read(17))<br>1<br></code><h2> class pulse
<br><br><b><small>Parameters</small></b><br><br><samp>uint32:= an unsigned 32 bit number<br></samp><br><br><b><small>Example</small></b><br><br><code>print(u2i(4294967272))<br>-24<br>print(u2i(37))<br>37<br></code><h2>PARAMETERS</h2><h3><a name="active"></a>active: 0-1000000</h3>The number of microseconds level changes are reported for once
a noise filter has been triggered (by <a href="#steady">steady</a> microseconds of
a stable level).
<h3><a name="arg1"></a>arg1: </h3>An unsigned argument passed to a user customised function. Its
meaning is defined by the customiser.
<h3><a name="arg2"></a>arg2: </h3>An unsigned argument passed to a user customised function. Its
meaning is defined by the customiser.
<h3><a name="argx"></a>argx: </h3>An array of bytes passed to a user customised function.
Its meaning and content is defined by the customiser.
<h3><a name="baud"></a>baud: </h3>The speed of serial communication (I2C, SPI, serial link, waves)
in bits per second.
<h3><a name="bb_bits"></a>bb_bits: 1-32</h3>The number of data bits to be used when adding serial data to a
waveform.
<h3><a name="bb_stop"></a>bb_stop: 2-8</h3>The number of (half) stop bits to be used when adding serial data
to a waveform.
<h3><a name="bit"></a>bit: 0-1</h3>A value of 0 or 1.
<h3><a name="bits"></a>bits: 32 bit number</h3>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
<h3><a name="file_mode"></a>file_mode: </h3>The mode may have the following values
<br><br><code>FILE_READ 1<br>FILE_WRITE 2<br>FILE_RW 3<br></code><br><br>The following values can be or'd into the file open mode
<br><br><code>FILE_APPEND 4<br>FILE_CREATE 8<br>FILE_TRUNC 16<br></code><h3><a name="file_name"></a>file_name: </h3>A full file path. To be accessible the path must match
an entry in /opt/pigpio/access.
<h3><a name="fpattern"></a>fpattern: </h3>A file path which may contain wildcards. To be accessible the path
must match an entry in /opt/pigpio/access.
<h3><a name="frequency"></a>frequency: 0-40000</h3>Defines the frequency to be used for PWM on a GPIO.
The closest permitted frequency will be used.
<h3><a name="func"></a>func: </h3>A user supplied callback function.
<h3><a name="gpio"></a>gpio: 0-53</h3>A Broadcom numbered GPIO. All the user GPIO are in the range 0-31.
<br><br>There are 54 General Purpose Input Outputs (GPIO) named GPIO0
through GPIO53.
<br><br>They are split into two banks. Bank 1 consists of GPIO0
through GPIO31. Bank 2 consists of GPIO32 through GPIO53.
<br><br>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.
<br><br>The user GPIO are marked with an X in the following table
<br><br><code> 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15<br>Type 1 X X - - X - - X X X X X - - X X<br>Type 2 - - X X X - - X X X X X - - X X<br>Type 3 X X X X X X X X X X X X X X<br><br> 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31<br>Type 1 - X X - - X X X X X - - - - - -<br>Type 2 - X X - - - X X X X - X X X X X<br>Type 3 X X X X X X X X X X X X - - - -<br></code><h3><a name="gpio_off"></a>gpio_off: </h3>A mask used to select GPIO to be operated on. See <a href="#bits">bits</a>.
<br><br>This mask selects the GPIO to be switched off at the start
of a pulse.
<h3><a name="gpio_on"></a>gpio_on: </h3>A mask used to select GPIO to be operated on. See <a href="#bits">bits</a>.
<br><br>This mask selects the GPIO to be switched on at the start
of a pulse.
<h3><a name="handle"></a>handle: >=0</h3>A number referencing an object opened by one of the following
<br><br><a href="#file_open">file_open</a>
<a href="#i2c_open">i2c_open</a>
<a href="#notify_open">notify_open</a>
<a href="#serial_open">serial_open</a>
<a href="#spi_open">spi_open</a>
<h3><a name="host"></a>host: </h3>The name or IP address of the Pi running the pigpio daemon.
<h3><a name="i2c_address"></a>i2c_address: 0-0x7F</h3>The address of a device on the I2C bus.
<h3><a name="i2c_bus"></a>i2c_bus: >=0</h3>An I2C bus number.
<h3><a name="i2c_flags"></a>i2c_flags: 0</h3>No I2C flags are currently defined.
<h3><a name="invert"></a>invert: 0-1</h3>A flag used to set normal or inverted bit bang serial data
level logic.
<h3><a name="level"></a>level: 0-1 (2)</h3><code>CLEAR = 0<br>HIGH = 1<br>LOW = 0<br>OFF = 0<br>ON = 1<br>SET = 1<br>TIMEOUT = 2 # only returned for a watchdog timeout<br></code><h3><a name="MISO"></a>MISO: </h3>The GPIO used for the MISO signal when bit banging SPI.
<h3><a name="mode"></a>mode: </h3>1.The operational mode of a GPIO, normally INPUT or OUTPUT.
<br><br><code>ALT0 = 4<br>ALT1 = 5<br>ALT2 = 6<br>ALT3 = 7<br>ALT4 = 3<br>ALT5 = 2<br>INPUT = 0<br>OUTPUT = 1<br></code><br><br>2. The mode of waveform transmission.
<br><br><code>WAVE_MODE_ONE_SHOT = 0<br>WAVE_MODE_REPEAT = 1<br>WAVE_MODE_ONE_SHOT_SYNC = 2<br>WAVE_MODE_REPEAT_SYNC = 3<br></code><h3><a name="MOSI"></a>MOSI: </h3>The GPIO used for the MOSI signal when bit banging SPI.
<h3><a name="offset"></a>offset: >=0</h3>The offset wave data starts from the beginning of the waveform
being currently defined.
<h3><a name="pad"></a>pad: 0-2</h3>A set of GPIO which share common drivers.
<br><br><table border="1" cellpadding="2" cellspacing="2"><tbody><tr><td>Pad</td><td>GPIO</td></tr><tr><td>0</td><td>0-27</td></tr><tr><td>1</td><td>28-45</td></tr><tr><td>2</td><td>46-53</td></tr></tbody></table><h3><a name="pad_strength"></a>pad_strength: 1-16</h3>The mA which may be drawn from each GPIO whilst still guaranteeing the
high and low levels.
<h3><a name="params"></a>params: 32 bit number</h3>When scripts are started they can receive up to 10 parameters
<h3><a name="port"></a>port: </h3>The port used by the pigpio daemon, defaults to 8888.
<h3><a name="pstring"></a>pstring: </h3>The string to be passed to a <a href="#shell">shell</a> script to be executed.
<h3><a name="pud"></a>pud: 0-2</h3><code>PUD_DOWN = 1<br>PUD_OFF = 0<br>PUD_UP = 2<br></code><h3><a name="pulse_len"></a>pulse_len: 1-100</h3>The length of the trigger pulse in microseconds.
<h3><a name="pulses"></a>pulses: </h3>A list of class pulse objects defining the characteristics of a
<h3><a name="PWMfreq"></a>PWMfreq: 1-125M (1-187.5M for the BCM2711)</h3>The hardware PWM frequency.
<h3><a name="range_"></a>range_: 25-40000</h3>Defines the limits for the <a href="#dutycycle">dutycycle</a> parameter.
<br><br>range_ defaults to 255.
<h3><a name="reg"></a>reg: 0-255</h3>An I2C device register. The usable registers depend on the
actual device.
<h3><a name="retMax"></a>retMax: >=0</h3>The maximum number of bytes a user customised function
should return, default 8192.
<h3><a name="SCL"></a>SCL: </h3>The user GPIO to use for the clock when bit banging I2C.
<h3><a name="SCLK"></a>SCLK: :</h3>The GPIO used for the SCLK signal when bit banging SPI.
<h3><a name="script"></a>script: </h3>The text of a script to store on the pigpio daemon.
<h3><a name="script_id"></a>script_id: >=0</h3>A number referencing a script created by <a href="#store_script">store_script</a>.
<h3><a name="SDA"></a>SDA: </h3>The user GPIO to use for data when bit banging I2C.
<h3><a name="seek_from"></a>seek_from: 0-2</h3>Direction to seek for <a href="#file_seek">file_seek</a>.
<br><br><code>FROM_START=0<br>FROM_CURRENT=1<br>FROM_END=2<br></code><h3><a name="seek_offset"></a>seek_offset: </h3>The number of bytes to move forward (positive) or backwards
(negative) from the seek position (start, current, or end of file).
<h3><a name="ser_flags"></a>ser_flags: 32 bit</h3>No serial flags are currently defined.
<h3><a name="serial_*"></a>serial_*: </h3>One of the serial_ functions.
<h3><a name="shellscr"></a>shellscr: </h3>The name of a shell script. The script must exist
in /opt/pigpio/cgi and must be executable.
<h3><a name="show_errors"></a>show_errors: </h3>Controls the display of pigpio daemon connection failures.
The default of True prints the probable failure reasons to
