<metaname="description"content="Raspberry Pi Reg. C GPIO library and Python GPIO module and shell command utilities to control the GPIO, including SPI, I2C, and serial links."/>
The socket and pipe interfaces allow control of the Pi's GPIO by
passing messages to the running pigpio library.
<br><br>The normal way to start the pigpio library would be as a daemon during boot.
<br><br><code>sudo pigpiod<br></code><h3>Features</h3>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 reading/writing all of the GPIO in a bank as one operation
<br><br>o individually setting GPIO modes, reading and writing
<br><br>o notifications when any of GPIO 0-31 change state
<br><br>o the construction of output waveforms with microsecond timing
<br><br>o I2C, SPI, and serial link wrappers
<br><br>o creating and running scripts on the pigpio daemon
<h3>GPIO</h3>ALL GPIO are identified by their Broadcom number.
<h3>Usage</h3>pigs is a program and internally uses the socket interface to pigpio
whereas /dev/pigpio uses the pipe interface.
<br><br>pigs and the pipe interface share the same commands and are invoked in
a similar fashion from the command line.
<br><br>The pigpio library must be running, either by running a program linked
with the library or starting the pigpio daemon (sudo pigpiod).
<br><br>pigs {command}+
<br><br>echo "{command}+" >/dev/pigpio
<br><br>pigs will show the result of the command on screen.
<br><br>The pigs process returns an exit status (which can be displayed with
the command echo $?).
<br><br><code>PIGS_OK 0<br>PIGS_CONNECT_ERR 255<br>PIGS_OPTION_ERR 254<br>PIGS_SCRIPT_ERR 253<br><br></code><br><br>The results of /dev/pigpio commands need to be read from /dev/pigout,
e.g. cat /dev/pigout (try cat /dev/pigout& so that all subsequent
results are shown on screen).
<br><br>In both cases if an error was detected a message will have been written
to /dev/pigerr (try cat /dev/pigerr&). This is likely to be more
informative than the message returned by pigs or the error code
returned by the pipe interface.
<br><br>Several commands may be entered on a line. If present PROC and PARSE must
be the last command on a line.
<br><br>E.g.
<br><br><code>pigs w 22 1 mils 1000 w 22 0<br></code><br><br>is equivalent to
<br><br><code>echo "m 4 w w 4 0 mils 250 m 4 r r 4" >/dev/pigpio<br></code><br><br>is equivalent to
<br><br><code>echo "m 4 w" >/dev/pigpio<br>echo "w 4 0" >/dev/pigpio<br>echo "mils 250" >/dev/pigpio<br>echo "m 4 r" >/dev/pigpio<br>echo "r 4" >/dev/pigpio<br></code><h3>Notes</h3>The examples from now on will show the pigs interface but the same
commands will also work on the pipe interface.
<br><br>pigs does not show the status of successful commands unless the
command itself returns data. The status (0) will be returned to
pigs but will be discarded.
<br><br>The status/data of each command sent to the pipe interface should
be read from /dev/pigout.
<br><br>When a command takes a number as a parameter it may be entered as hex
(precede by 0x), octal (precede by 0), or decimal.
<br><br>E.g. 23 is 23 decimal, 0x100 is 256 decimal, 070 is 56 decimal.
<br><br>Some commands can return a variable number of data bytes. By
default this data is displayed as decimal. The pigs -a option
can be used to force the display as ASCII and the pigs -x
option can be used to force the display as hex.
<br><br>E.g. assuming the transmitted serial data is the letters ABCDEONM
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#P/PWM">P/PWM</a><ahref="#u">u</a><ahref="#v">v</a></td><td>Set GPIO PWM value </td><td><small><ahref="cif.html#gpioPWM">gpioPWM</a></small></td></tr><tr><td><ahref="#PFS">PFS</a><ahref="#u">u</a><ahref="#v">v</a></td><td>Set GPIO PWM frequency </td><td><small><ahref="cif.html#gpioSetPWMfrequency">gpioSetPWMfrequency</a></small></td></tr><tr><td><ahref="#PRS">PRS</a><ahref="#u">u</a><ahref="#v">v</a></td><td>Set GPIO PWM range </td><td><small><ahref="cif.html#gpioSetPWMrange">gpioSetPWMrange</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#GDC">GDC</a><ahref="#u">u</a></td><td>Get GPIO PWM dutycycle </td><td><small><ahref="cif.html#gpioGetPWMdutycycle">gpioGetPWMdutycycle</a></small></td></tr><tr><td><ahref="#PFG">PFG</a><ahref="#u">u</a></td><td>Get GPIO PWM frequency </td><td><small><ahref="cif.html#gpioGetPWMfrequency">gpioGetPWMfrequency</a></small></td></tr><tr><td><ahref="#PRG">PRG</a><ahref="#u">u</a></td><td>Get GPIO PWM range </td><td><small><ahref="cif.html#gpioGetPWMrange">gpioGetPWMrange</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#PRRG">PRRG</a><ahref="#u">u</a></td><td>Get GPIO PWM real range </td><td><small><ahref="cif.html#gpioGetPWMrealRange">gpioGetPWMrealRange</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>Servo (overrides PWM commands on same GPIO)
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#TRIG">TRIG</a><ahref="#u">u</a><ahref="#pl">pl</a><ahref="#L">L</a></td><td>Send a trigger pulse </td><td><small><ahref="cif.html#gpioTrigger">gpioTrigger</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#WDOG">WDOG</a><ahref="#u">u</a><ahref="#v">v</a></td><td>Set GPIO watchdog </td><td><small><ahref="cif.html#gpioSetWatchdog">gpioSetWatchdog</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#BR1">BR1</a></td><td>Read bank 1 GPIO </td><td><small><ahref="cif.html#gpioRead_Bits_0_31">gpioRead_Bits_0_31</a></small></td></tr><tr><td><ahref="#BR2">BR2</a></td><td>Read bank 2 GPIO </td><td><small><ahref="cif.html#gpioRead_Bits_32_53">gpioRead_Bits_32_53</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#BC1">BC1</a><ahref="#bits">bits</a></td><td>Clear specified GPIO in bank 1 </td><td><small><ahref="cif.html#gpioWrite_Bits_0_31_Clear">gpioWrite_Bits_0_31_Clear</a></small></td></tr><tr><td><ahref="#BC2">BC2</a><ahref="#bits">bits</a></td><td>Clear specified GPIO in bank 2 </td><td><small><ahref="cif.html#gpioWrite_Bits_32_53_Clear">gpioWrite_Bits_32_53_Clear</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#BS1">BS1</a><ahref="#bits">bits</a></td><td>Set specified GPIO in bank 1 </td><td><small><ahref="cif.html#gpioWrite_Bits_0_31_Set">gpioWrite_Bits_0_31_Set</a></small></td></tr><tr><td><ahref="#BS2">BS2</a><ahref="#bits">bits</a></td><td>Set specified GPIO in bank 2 </td><td><small><ahref="cif.html#gpioWrite_Bits_32_53_Set">gpioWrite_Bits_32_53_Set</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>ADVANCED
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#NO">NO</a></td><td>Request a notification </td><td><small><ahref="cif.html#gpioNotifyOpen">gpioNotifyOpen</a></small></td></tr><tr><td><ahref="#NC">NC</a><ahref="#h">h</a></td><td>Close notification </td><td><small><ahref="cif.html#gpioNotifyClose">gpioNotifyClose</a></small></td></tr><tr><td><ahref="#NB">NB</a><ahref="#h">h</a><ahref="#bits">bits</a></td><td>Start notification </td><td><small><ahref="cif.html#gpioNotifyBegin">gpioNotifyBegin</a></small></td></tr><tr><td><ahref="#NP">NP</a><ahref="#h">h</a></td><td>Pause notification </td><td><small><ahref="cif.html#gpioNotifyPause">gpioNotifyPause</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#HC">HC</a><ahref="#g">g</a><ahref="#cf">cf</a></td><td>Set hardware clock frequency </td><td><small><ahref="cif.html#gpioHardwareClock">gpioHardwareClock</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#HP">HP</a><ahref="#g">g</a><ahref="#pf">pf</a><ahref="#pdc">pdc</a></td><td>Set hardware PWM frequency and dutycycle </td><td><small><ahref="cif.html#gpioHardwarePWM">gpioHardwarePWM</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#FG">FG</a><ahref="#u">u</a><ahref="#stdy">stdy</a></td><td>Set a glitch filter on a GPIO </td><td><small><ahref="cif.html#gpioGlitchFilter">gpioGlitchFilter</a></small></td></tr><tr><td><ahref="#FN">FN</a><ahref="#u">u</a><ahref="#stdy">stdy</a><ahref="#actv">actv</a></td><td>Set a noise filter on a GPIO </td><td><small><ahref="cif.html#gpioNoiseFilter">gpioNoiseFilter</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#PADS">PADS</a><ahref="#pad">pad</a><ahref="#padma">padma</a></td><td>Set pad drive strength </td><td><small><ahref="cif.html#gpioSetPad">gpioSetPad</a></small></td></tr><tr><td><ahref="#PADG">PADG</a><ahref="#pad">pad</a></td><td>Get pad drive strength </td><td><small><ahref="cif.html#gpioGetPad">gpioGetPad</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#SHELL">SHELL</a><ahref="#name">name</a><ahref="#str">str</a></td><td>Execute a shell command </td><td><small><ahref="cif.html#shell">shell</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>Custom
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#CF1">CF1</a><ahref="#uvs">uvs</a></td><td>Custom function 1 </td><td><small><ahref="cif.html#gpioCustom1">gpioCustom1</a></small></td></tr><tr><td><ahref="#CF2">CF2</a><ahref="#uvs">uvs</a></td><td>Custom function 2 </td><td><small><ahref="cif.html#gpioCustom1">gpioCustom1</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>Events
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#EVM">EVM</a><ahref="#h">h</a><ahref="#bits">bits</a></td><td>Set events to monitor </td><td><small><ahref="cif.html#eventMonitor">eventMonitor</a></small></td></tr><tr><td><ahref="#EVT">EVT</a><ahref="#event">event</a></td><td>Trigger event </td><td><small><ahref="cif.html#eventTrigger">eventTrigger</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>Scripts
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#PROC">PROC</a><ahref="#t">t</a></td><td>Store script </td><td><small><ahref="cif.html#gpioStoreScript">gpioStoreScript</a></small></td></tr><tr><td><ahref="#PROCR">PROCR</a><ahref="#sid">sid</a><ahref="#pars">pars</a></td><td>Run script </td><td><small><ahref="cif.html#gpioRunScript">gpioRunScript</a></small></td></tr><tr><td><ahref="#PROCU">PROCU</a><ahref="#sid">sid</a><ahref="#pars">pars</a></td><td>Set script parameters </td><td><small><ahref="cif.html#gpioUpdateScript">gpioUpdateScript</a></small></td></tr><tr><td><ahref="#PROCP">PROCP</a><ahref="#sid">sid</a></td><td>Get script status and parameters </td><td><small><ahref="cif.html#gpioScriptStatus">gpioScriptStatus</a></small></td></tr><tr><td><ahref="#PROCS">PROCS</a><ahref="#sid">sid</a></td><td>Stop script </td><td><small><ahref="cif.html#gpioStopScript">gpioStopScript</a></small></td></tr><tr><td><ahref="#PROCD">PROCD</a><ahref="#sid">sid</a></td><td>Delete script </td><td><small><ahref="cif.html#gpioDeleteScript">gpioDeleteScript</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#PARSE">PARSE</a><ahref="#t">t</a></td><td>Validate script </td><td><small><ahref="cif.html#gpioParseScript">gpioParseScript</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>I2C
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#I2CO">I2CO</a><ahref="#ib">ib</a><ahref="#id">id</a><ahref="#if">if</a></td><td>Open I2C bus and device with flags </td><td><small><ahref="cif.html#i2cOpen">i2cOpen</a></small></td></tr><tr><td><ahref="#I2CC">I2CC</a><ahref="#h">h</a></td><td>Close I2C handle </td><td><small><ahref="cif.html#i2cClose">i2cClose</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#I2CWQ">I2CWQ</a><ahref="#h">h</a><ahref="#bit">bit</a></td><td>smb Write Quick: write bit </td><td><small><ahref="cif.html#i2cWriteQuick">i2cWriteQuick</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#I2CRS">I2CRS</a><ahref="#h">h</a></td><td>smb Read Byte: read byte </td><td><small><ahref="cif.html#i2cReadByte">i2cReadByte</a></small></td></tr><tr><td><ahref="#I2CWS">I2CWS</a><ahref="#h">h</a><ahref="#bv">bv</a></td><td>smb Write Byte: write byte </td><td><small><ahref="cif.html#i2cWriteByte">i2cWriteByte</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#I2CRB">I2CRB</a><ahref="#h">h</a><ahref="#r">r</a></td><td>smb Read Byte Data: read byte from register </td><td><small><ahref="cif.html#i2cReadByteData">i2cReadByteData</a></small></td></tr><tr><td><ahref="#I2CWB">I2CWB</a><ahref="#h">h</a><ahref="#r">r</a><ahref="#bv">bv</a></td><td>smb Write Byte Data: write byte to register </td><td><small><ahref="cif.html#i2cWriteByteData">i2cWriteByteData</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#I2CRW">I2CRW</a><ahref="#h">h</a><ahref="#r">r</a></td><td>smb Read Word Data: read word from register </td><td><small><ahref="cif.html#i2cReadWordData">i2cReadWordData</a></small></td></tr><tr><td><ahref="#I2CWW">I2CWW</a><ahref="#h">h</a><ahref="#r">r</a><ahref="#wv">wv</a></td><td>smb Write Word Data: write word to register </td><td><small><ahref="cif.html#i2cWriteWordData">i2cWriteWordData</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#I2CRK">I2CRK</a><ahref="#h">h</a><ahref="#r">r</a></td><td>smb Read Block Data: read data from register </td><td><small><ahref="cif.html#i2cReadBlockData">i2cReadBlockData</a></small></td></tr><tr><td><ahref="#I2CWK">I2CWK</a><ahref="#h">h</a><ahref="#r">r</a><ahref="#bvs">bvs</a></td><td>smb Write Block Data: write data to register </td><td><small><ahref="cif.html#i2cWriteBlockData">i2cWriteBlockData</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#I2CWI">I2CWI</a><ahref="#h">h</a><ahref="#r">r</a><ahref="#bvs">bvs</a></td><td>smb Write I2C Block Data </td><td><small><ahref="cif.html#i2cWriteI2CBlockData">i2cWriteI2CBlockData</a></small></td></tr><tr><td><ahref="#I2CRI">I2CRI</a><ahref="#h">h</a><ahref="#r">r</a><ahref="#num">num</a></td><td>smb Read I2C Block Data: read bytes from register </td><td><small><ahref="cif.html#i2cReadI2CBlockData">i2cReadI2CBlockData</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#I2CRD">I2CRD</a><ahref="#h">h</a><ahref="#num">num</a></td><td>i2c Read device </td><td><small><ahref="cif.html#i2cReadDevice">i2cReadDevice</a></small></td></tr><tr><td><ahref="#I2CWD">I2CWD</a><ahref="#h">h</a><ahref="#bvs">bvs</a></td><td>i2c Write device </td><td><small><ahref="cif.html#i2cWriteDevice">i2cWriteDevice</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#I2CPC">I2CPC</a><ahref="#h">h</a><ahref="#r">r</a><ahref="#wv">wv</a></td><td>smb Process Call: exchange register with word </td><td><small><ahref="cif.html#i2cProcessCall">i2cProcessCall</a></small></td></tr><tr><td><ahref="#I2CPK">I2CPK</a><ahref="#h">h</a><ahref="#r">r</a><ahref="#bvs">bvs</a></td><td>smb Block Process Call: exchange data bytes with register </td><td><small><ahref="cif.html#i2cBlockProcessCall">i2cBlockProcessCall</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#I2CZ">I2CZ</a><a
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#BI2CO">BI2CO</a><ahref="#sda">sda</a><ahref="#scl">scl</a><ahref="#b">b</a></td><td>Open bit bang I2C </td><td><small><ahref="cif.html#bbI2COpen">bbI2COpen</a></small></td></tr><tr><td><ahref="#BI2CC">BI2CC</a><ahref="#sda">sda</a></td><td>Close bit bang I2C </td><td><small><ahref="cif.html#bbI2CClose">bbI2CClose</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#BI2CZ">BI2CZ</a><ahref="#sda">sda</a><ahref="#bvs">bvs</a></td><td>I2C bit bang multiple transactions </td><td><small><ahref="cif.html#bbI2CZip">bbI2CZip</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>I2C/SPI SLAVE
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#BSCX">BSCX</a><ahref="#bctl">bctl</a><ahref="#bvs">bvs</a></td><td>BSC I2C/SPI transfer </td><td><small><ahref="cif.html#bscXfer">bscXfer</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>SERIAL
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#SERO">SERO</a><ahref="#dev">dev</a><ahref="#b">b</a><ahref="#sef">sef</a></td><td>Open serial device dev at baud b with flags </td><td><small><ahref="cif.html#serOpen">serOpen</a></small></td></tr><tr><td><ahref="#SERC">SERC</a><ahref="#h">h</a></td><td>Close serial handle </td><td><small><ahref="cif.html#serClose">serClose</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#SERRB">SERRB</a></td><td>Read byte from serial handle </td><td><small><ahref="cif.html#serReadByte">serReadByte</a></small></td></tr><tr><td><ahref="#SERWB">SERWB</a><ahref="#h">h</a><ahref="#bv">bv</a></td><td>Write byte to serial handle </td><td><small><ahref="cif.html#serWriteByte">serWriteByte</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#SERR">SERR</a><ahref="#h">h</a><ahref="#num">num</a></td><td>Read bytes from serial handle </td><td><small><ahref="cif.html#serRead">serRead</a></small></td></tr><tr><td><ahref="#SERW">SERW</a><ahref="#h">h</a><ahref="#bvs">bvs</a></td><td>Write bytes to serial handle </td><td><small><ahref="cif.html#serWrite">serWrite</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#SERDA">SERDA</a><ahref="#h">h</a></td><td>Check for serial data ready to read </td><td><small><ahref="cif.html#serDataAvailable">serDataAvailable</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>SERIAL BIT BANG (read only)
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#SLRO">SLRO</a><ahref="#u">u</a><ahref="#b">b</a><ahref="#db">db</a></td><td>Open GPIO for bit bang serial data </td><td><small><ahref="cif.html#gpioSerialReadOpen">gpioSerialReadOpen</a></small></td></tr><tr><td><ahref="#SLRC">SLRC</a><ahref="#u">u</a></td><td>Close GPIO for bit bang serial data </td><td><small><ahref="cif.html#gpioSerialReadClose">gpioSerialReadClose</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#SLRI">SLRI</a><ahref="#u">u</a><ahref="#v">v</a></td><td>Sets bit bang serial data logic levels </td><td><small><ahref="cif.html#gpioSerialReadInvert">gpioSerialReadInvert</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#SLR">SLR</a><ahref="#u">u</a><ahref="#num">num</a></td><td>Read bit bang serial data from GPIO </td><td><small><ahref="cif.html#gpioSerialRead">gpioSerialRead</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>SPI
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#SPIO">SPIO</a><ahref="#c">c</a><ahref="#b">b</a><ahref="#spf">spf</a></td><td>SPI open channel at baud b with flags </td><td><small><ahref="cif.html#spiOpen">spiOpen</a></small></td></tr><tr><td><ahref="#SPIC">SPIC</a><ahref="#h">h</a></td><td>SPI close handle </td><td><small><ahref="cif.html#spiClose">spiClose</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#SPIR">SPIR</a><ahref="#h">h</a><ahref="#num">num</a></td><td>SPI read bytes from handle </td><td><small><ahref="cif.html#spiRead">spiRead</a></small></td></tr><tr><td><ahref="#SPIW">SPIW</a><ahref="#h">h</a><ahref="#bvs">bvs</a></td><td>SPI write bytes to handle </td><td><small><ahref="cif.html#spiWrite">spiWrite</a></small></td></tr><tr><td><ahref="#SPIX">SPIX</a><ahref="#h">h</a><ahref="#bvs">bvs</a></td><td>SPI transfer bytes to handle </td><td><small><ahref="cif.html#spiXfer">spiXfer</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>SPI BIT BANG
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#BSPIO">BSPIO</a><ahref="#cs">cs</a><ahref="#miso">miso</a><ahref="#mosi">mosi</a><ahref="#sclk">sclk</a><ahref="#b">b</a><ahref="#spf">spf</a></td><td>Open bit bang SPI </td><td><small><ahref="cif.html#bbSPIOpen">bbSPIOpen</a></small></td></tr><tr><td><ahref="#BSPIC">BSPIC</a><ahref="#cs">cs</a></td><td>Close bit bang SPI </td><td><small><ahref="cif.html#bbSPIClose">bbSPIClose</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#BSPIX">BSPIX</a><ahref="#cs">cs</a><ahref="#bvs">bvs</a></td><td>SPI bit bang transfer </td><td><small><ahref="cif.html#bbSPIXfer">bbSPIXfer</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>FILES
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#FO">FO</a><ahref="#file">file</a><ahref="#mode">mode</a></td><td>Open a file in mode </td><td><small><ahref="cif.html#fileOpen">fileOpen</a></small></td></tr><tr><td><ahref="#FC">FC</a><ahref="#h">h</a></td><td>Close file handle </td><td><small><ahref="cif.html#fileClose">fileClose</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#FR">FR</a><ahref="#h">h</a><ahref="#num">num</a></td><td>Read bytes from file handle </td><td><small><ahref="cif.html#fileRead">fileRead</a></small></td></tr><tr><td><ahref="#FW">FW</a><ahref="#h">h</a><ahref="#bvs">bvs</a></td><td>Write bytes to file handle </td><td><small><ahref="cif.html#fileWrite">fileWrite</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#FS">FS</a><ahref="#h">h</a><ahref="#num">num</a><ahref="#from">from</a></td><td>Seek to file handle position </td><td><small><ahref="cif.html#fileSeek">fileSeek</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#FL">FL</a><ahref="#pat">pat</a><ahref="#num">num</a></td><td>List files which match pattern </td><td><small><ahref="cif.html#fileList">fileList</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>WAVES
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#WVCLR">WVCLR</a></td><td>Clear all waveforms </td><td><small><ahref="cif.html#gpioWaveClear">gpioWaveClear</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#WVNEW">WVNEW</a></td><td>Initialise a new waveform </td><td><small><ahref="cif.html#gpioWaveAddNew">gpioWaveAddNew</a></small></td></tr><tr><td><ahref="#WVAG">WVAG</a><ahref="#trips">trips</a></td><td>Add generic pulses to waveform </td><td><small><ahref="cif.html#gpioWaveAddGeneric">gpioWaveAddGeneric</a></small></td></tr><tr><td><ahref="#WVAS">WVAS</a><ahref="#u">u</a><ahref="#b">b</a><ahref="#db">db</a><ahref="#sb">sb</a><ahref="#o">o</a><ahref="#bvs">bvs</a></td><td>Add serial data to waveform </td><td><small><ahref="cif.html#gpioWaveAddSerial">gpioWaveAddSerial</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#WVCRE">WVCRE</a></td><td>Create a waveform </td><td><small><ahref="cif.html#gpioWaveCreate">gpioWaveCreate</a></small></td></tr><tr><td><ahref="#WVCAP">WVCAP</a></td><td>Create a waveform of fixed size </td><td><small><ahref="cif.html#gpioWaveCreatePad">gpioWaveCreatePad</a></small></td></tr><tr><td><ahref="#WVDEL">WVDEL</a><ahref="#wid">wid</a></td><td>Delete selected waveform </td><td><small><ahref="cif.html#gpioWaveDelete">gpioWaveDelete</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#WVTX">WVTX</a><ahref="#wid">wid</a></td><td>Transmits waveform once </td><td><small><ahref="cif.html#gpioWaveTxSend">gpioWaveTxSend</a></small></td></tr><tr><td><ahref="#WVTXM">WVTXM</a><ahref="#wid">wid</a><ahref="#wmde">wmde</a></td><td>Transmits waveform using mode </td><td><small><ahref="cif.html#gpioWaveTxSend">gpioWaveTxSend</a></small></td></tr><tr><td><ahref="#WVTXR">WVTXR</a><ahref="#wid">wid</a></td><td>Transmits waveform repeatedly </td><td><small><ahref="cif.html#gpioWaveTxSend">gpioWaveTxSend</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#WVCHA">WVCHA</a><ahref="#bvs">bvs</a></td><td>Transmits a chain of waveforms </td><td><small><ahref="cif.html#gpioWaveChain">gpioWaveChain</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#WVTAT">WVTAT</a></td><td>Returns the current transmitting waveform </td><td><small><ahref="cif.html#gpioWaveTxAt">gpioWaveTxAt</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#WVBSY">WVBSY</a></td><td>Check if waveform is being transmitted </td><td><small><ahref="cif.html#gpioWaveTxBusy">gpioWaveTxBusy</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#WVHLT">WVHLT</a></td><td>Stop waveform </td><td><small><ahref="cif.html#gpioWaveTxStop">gpioWaveTxStop</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#WVSC">WVSC</a><ahref="#ws">ws</a></td><td>Get waveform DMA CB stats </td><td><small><ahref="cif.html#gpioWaveGetCbs">gpioWaveGetCbs</a></small></td></tr><tr><td><ahref="#WVSM">WVSM</a><ahref="#ws">ws</a></td><td>Get waveform time stats </td><td><small><ahref="cif.html#gpioWaveGetMicros">gpioWaveGetMicros</a></small></td></tr><tr><td><ahref="#WVSP">WVSP</a><ahref="#ws">ws</a></td><td>Get waveform pulse stats </td><td><small><ahref="cif.html#gpioWaveGetPulses">gpioWaveGetPulses</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>UTILITIES
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#H/HELP">H/HELP</a></td><td>Display command help </td><td><small><ahref="cif.html#"></a></small></td></tr><tr><td><ahref="#HWVER">HWVER</a></td><td>Get hardware version </td><td><small><ahref="cif.html#gpioHardwareRevision">gpioHardwareRevision</a></small></td></tr><tr><td><ahref="#MICS">MICS</a><ahref="#v">v</a></td><td>Microseconds delay </td><td><small><ahref="cif.html#gpioDelay">gpioDelay</a></small></td></tr><tr><td><ahref="#MILS">MILS</a><ahref="#v">v</a></td><td>Milliseconds delay </td><td><small><ahref="cif.html#gpioDelay">gpioDelay</a></small></td></tr><tr><td><ahref="#PIGPV">PIGPV</a></td><td>Get pigpio library version </td><td><small><ahref="cif.html#gpioVersion">gpioVersion</a></small></td></tr><tr><td><ahref="#T/TICK">T/TICK</a></td><td>Get current tick </td><td><small><ahref="cif.html#gpioTick">gpioTick</a></small></td></tr><tr><td></td><td></td><td></td></tr><tr><td>CONFIGURATION
</td><td></td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td><ahref="#CGI">CGI</a></td><td>Configuration get internals </td><td><small><ahref="cif.html#gpioCfgGetInternals">gpioCfgGetInternals</a></small></td></tr><tr><td><ahref="#CSI">CSI</a><ahref="#v">v</a></td><td>Configuration set internals </td><td><small><ahref="cif.html#gpioCfgSetInternals">gpioCfgSetInternals</a></small></td></tr><tr><td></td><td></td><td></td></tr></tbody></table><h2><aname="Commands">Commands</a></h2>
<h3><aname="BC1">BC1</a>
<ahref="#bits">bits</a> - Clear specified GPIO in bank 1</h3>This command clears (sets low) the GPIO specified by <ahref="#bits">bits</a> in bank 1.
Bank 1 consists of GPIO 0-31.
<br><br>Upon success nothing is returned. On error a negative status code
<ahref="#sda">sda</a><ahref="#scl">scl</a><ahref="#b">b</a> - Open bit bang I2C</h3>This command signals that GPIO <ahref="#sda">sda</a> and <ahref="#scl">scl</a> are to be used
for bit banging I2C at <ahref="#b">b</a> baud.
<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<br>
o repeated starts<br>
o clock stretching<br>
o I2C on any pair of spare GPIO
<br><br>The baud rate may be between 50 and 500000 bits per second.
<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.
<h3><aname="BI2CZ">BI2CZ</a>
<ahref="#sda">sda</a><ahref="#bvs">bvs</a> - I2C bit bang multiple transactions</h3>This function executes a sequence of bit banged I2C operations. The
operations to be performed are specified by the contents of <ahref="#bvs">bvs</a>
which contains the concatenated command codes and associated data.
<br><br>The following command codes are supported:
<br><br><tableborder="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
<ahref="#bctl">bctl</a><ahref="#bvs">bvs</a> - BSC I2C/SPI transfer</h3>This command performs a BSC I2C/SPI slave transfer as defined by
<ahref="#bctl">bctl</a> with data <ahref="#bvs">bvs</a>.
<br><br>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 command sets the BSC mode and writes any data <ahref="#bvs">bvs</a>
to the BSC transmit FIFO. It returns the data count (at least 1
for the status word), the status word, followed by any data bytes
read from the BSC receive FIFO.
<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>For I2C use a control word of (I2C address << 16) + 0x305.
<br><br>E.g. to talk as I2C slave with address 0x13 use 0x130305.
<br><br>GPIO used for models other than those based on the BCM2711.
<br><br><tableborder="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><tableborder="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>The control word 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><tableborder="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 returned 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><tableborder="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>This example assumes that GPIO 2/3 are connected to GPIO 18/19
<ahref="#cs">cs</a><ahref="#miso">miso</a><ahref="#mosi">mosi</a><ahref="#sclk">sclk</a><ahref="#b">b</a><ahref="#spf">spf</a> - Open bit bang SPI</h3>This command starts bit banging SPI on a group of GPIO with slave
select <ahref="#cs">cs</a>, MISO <ahref="#miso">miso</a>, MOSI <ahref="#mosi">mosi</a>, and clock <ahref="#sclk">sclk</a>.
<br><br>Data will be transferred at baud <ahref="#b">b</a> bits per second (which may
be set in the range 50-250000).
<br><br>The flags <ahref="#spf">spf</a> may be used to modify the default behaviour of
mode 0, active low chip select.
<br><br>The 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> 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.
<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>p is 0 if CS is active low (default) and 1 for active high.
<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.
<br><br>R is 1 if the least significant bit is received on MISO first, the
default (0) receives the most significant bit first.
<br><br>The other bits in flags should be set to zero.
<br><br>Upon success 0 is returned. On error a negative status code
will be returned.
<br><br>If more than one device is connected to the SPI bus (defined by
<ahref="#u">u</a><ahref="#stdy">stdy</a> - Set a glitch filter on a GPIO</h3>Level changes on the GPIO <ahref="#u">u</a> are not reported unless the level
has been stable for at least <ahref="#stdy">stdy</a> microseconds. The
level is then reported. Level changes of less than <ahref="#stdy">stdy</a>
microseconds are ignored.
<br><br>The filter only affects callbacks (including pipe notifications).
<br><br>The <ahref="#R/READ">R/READ</a>, <ahref="#BR1">BR1</a>, and <ahref="#BR2">BR2</a> commands are not affected.
<br><br>Note, each (stable) edge will be timestamped <ahref="#stdy">stdy</a> microseconds
<ahref="#pat">pat</a><ahref="#num">num</a> - List files which match pattern</h3>This command returns a list of the files matching <ahref="#pat">pat</a>. Up
to <ahref="#num">num</a> bytes may be returned.
<br><br>Upon success the count of returned bytes followed by the matching
files is returned. On error a negative status code will be returned.
<br><br>A newline (0x0a) character separates each file name.
<br><br>Only files which have a matching entry in /opt/pigpio/access may
<ahref="#u">u</a><ahref="#stdy">stdy</a><ahref="#actv">actv</a> - Set a noise filter on a GPIO</h3>Level changes on the GPIO <ahref="#u">u</a> are ignored until a level which has
been stable for <ahref="#stdy">stdy</a> microseconds is detected. Level
changes on the GPIO are then reported for <ahref="#actv">actv</a> microseconds
after which the process repeats.
<br><br>The filter only affects callbacks (including pipe notifications).
<br><br>The <ahref="#R/READ">R/READ</a>, <ahref="#BR1">BR1</a>, and <ahref="#BR2">BR2</a> commands are not affected.
<br><br>Note, level changes before and after the active period may
be reported. Your software must be designed to cope with
<ahref="#file">file</a><ahref="#mode">mode</a> - Open a file in mode</h3>This function returns a handle to a file <ahref="#file">file</a> opened
in a specified mode <ahref="#mode">mode</a>.
<br><br>Upon success a handle (>=0) is returned. On error a negative status code
will be returned.
<br><br>File
<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><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td></td><td>Value</td><td>Meaning</td></tr><tr><td>READ</td><td>1</td><td>open file for reading</td></tr><tr><td>WRITE</td><td>2</td><td>open file for writing</td></tr><tr><td>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><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td></td><td>Value</td><td>Meaning</td></tr><tr><td>APPEND</td><td>4</td><td>All writes append data to the end of the file</td></tr><tr><td>CREATE</td><td>8</td><td>The file is created if it doesn't exist</td></tr><tr><td>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 read and write.
<ahref="#h">h</a><ahref="#num">num</a><ahref="#from">from</a> - Seek to file handle position</h3>This command seeks to a position within the file associated
with handle <ahref="#h">h</a>.
<br><br>The number of bytes to move is <ahref="#num">num</a>. Positive offsets
move forward, negative offsets backwards. The move start
position is determined by <ahref="#from">from</a> as follows.
<br><br><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td></td><td>From</td></tr><tr><td>0</td><td>start</td></tr><tr><td>1</td><td>current position</td></tr><tr><td>2</td><td>end</td></tr></tbody></table><br><br>Upon success the new byte position within the file (>=0) is
returned. On error a negative status code will be returned.
<ahref="#g">g</a><ahref="#cf">cf</a> - Set hardware clock frequency</h3>This command sets the hardware clock associated with GPIO <ahref="#g">g</a> to
frequency <ahref="#cf">cf</a>. Frequencies above 30MHz are unlikely to work.
<br><br>Upon success nothing is returned. On error a negative status code
will be returned.
<br><br><b><small>Example</small></b><br><br><code>$ pigs hc 4 5000 # start a 5 KHz clock on GPIO 4 (clock 0)<br><br>$ pigs hc 5 5000000 # start a 5 MHz clcok on GPIO 5 (clock 1)<br>-99<br>ERROR: need password to use hardware clock 1<br></code><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><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td>4</td><td>clock 0</td><td>All models</td></tr><tr><td>5</td><td>clock 1</td><td>All models but A and B (reserved for system use)</td></tr><tr><td>6</td><td>clock 2</td><td>All models but A and B</td></tr><tr><td>20</td><td>clock 0</td><td>All models but A and B</td></tr><tr><td>21</td><td>clock 1</td><td>All models but A and B Rev.2 (reserved for system use)</td></tr></tbody></table><br><br><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td>32</td><td>clock 0</td><td>Compute module only</td></tr><tr><td>34</td><td>clock 0</td><td>Compute module only</td></tr><tr><td>42</td><td>clock 1</td><td>Compute module only (reserved for system use)</td></tr><tr><td>43</td><td>clock 2</td><td>Compute module only</td></tr><tr><td>44</td><td>clock 1</td><td>Compute module only (reserved for system use)</td></tr></tbody></table><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
with the GPIO number.
<h3><aname="HP">HP</a>
<ahref="#g">g</a><ahref="#pf">pf</a><ahref="#pdc">pdc</a> - Set hardware PWM frequency and dutycycle</h3>This command sets the hardware PWM associated with GPIO <ahref="#g">g</a> to
frequency <ahref="#pf">pf</a> with dutycycle <ahref="#pdc">pdc</a>. Frequencies above 30MHz
are unlikely to work.
<br><br>NOTE: Any waveform started by <ahref="#WVTX">WVTX</a>, <ahref="#WVTXR">WVTXR</a>, or <ahref="#WVCHA">WVCHA</a>
will be cancelled.
<br><br>This function is only valid if the pigpio main clock is PCM. The
main clock defaults to PCM but may be overridden when the pigpio
daemon is started (option -t).
<br><br>Upon success nothing is returned. On error a negative status code
will be returned.
<br><br><code>$ pigs hp 18 100 800000 # 80% dutycycle<br><br>$ pigs hp 19 100 200000 # 20% dutycycle<br><br>$ pigs hp 19 400000000 100000<br>-96<br>ERROR: invalid hardware PWM frequency<br></code><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><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td>12</td><td>PWM channel 0</td><td>All models but A and B</td></tr><tr><td>13</td><td>PWM channel 1</td><td>All models but A and B</td></tr><tr><td>18</td><td>PWM channel 0</td><td>All models</td></tr><tr><td>19</td><td>PWM channel 1</td><td>All models but A and B</td></tr></tbody></table><br><br><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td>40</td><td>PWM channel 0</td><td>Compute module only</td></tr><tr><td>41</td><td>PWM channel 1</td><td>Compute module only</td></tr><tr><td>45</td><td>PWM channel 1</td><td>Compute module only</td></tr><tr><td>52</td><td>PWM channel 0</td><td>Compute module only</td></tr><tr><td>53</td><td>PWM channel 1</td><td>Compute module only</td></tr></tbody></table><br><br>The actual number of steps beween off and fully on is the
integral part of 250M/<ahref="#pf">pf</a> (375M/<ahref="#pf">pf</a> 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 <ahref="#pf">pf</a> of 250 (375 for
the BCM2711). Lower frequencies will have more steps and higher
frequencies will have fewer steps. <ahref="#pdc">pdc</a> is
automatically scaled to take this into account.
<h3><aname="HWVER">HWVER</a>
- Get hardware version</h3>This command returns the hardware revision of the Pi.
<br><br>The hardware revision is found in the last 4 characters on the revision
line of /proc/cpuinfo.
<br><br>If the hardware revision can not be found or is not a valid hexadecimal
number the command returns 0.
<br><br>The revision number can be used to determine the assignment of GPIO
to pins (see <ahref="#g">g</a>).
<br><br>There are currently three types of board.
<br><br>Type 1 boards have hardware revision numbers of 2 and 3.
<br><br>Type 2 boards have hardware revision numbers of 4, 5, 6, and 15.
<br><br>Type 3 boards have hardware revision numbers of 16 or greater.
<br><br>for "Revision : 0002" the command returns 2.
<br><br>for "Revision : 000f" the command returns 15.
<br><br>for "Revision : 000g" the command returns 0.
<ahref="#ib">ib</a><ahref="#id">id</a><ahref="#if">if</a> - Open I2C bus and device with flags</h3>This command returns a handle to access device <ahref="#id">id</a> on I2C bus <ahref="#ib">ib</a>.
The device is opened with flags <ahref="#if">if</a>.
<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><tableborder="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>No flags are currently defined. The parameter <ahref="#if">if</a> should be 0.
<br><br>Upon success the next free handle (>=0) is returned. On error a
<ahref="#h">h</a><ahref="#r">r</a><ahref="#wv">wv</a> - smb Process Call: exchange register with word</h3>This command writes <ahref="#wv">wv</a> to register <ahref="#r">r</a> of the I2C device
associated with handle <ahref="#h">h</a> and returns a 16-bit word read from the
device.
<br><br>Upon success a value between 0 and 65535 will be returned. On error
<ahref="#h">h</a><ahref="#r">r</a><ahref="#bvs">bvs</a> - smb Block Process Call: exchange data bytes with register</h3>This command writes the data bytes <ahref="#bvs">bvs</a> to register <ahref="#r">r</a> of the I2C device
associated with handle <ahref="#h">h</a> and returns a device specific number of bytes.
<br><br>Upon success the count of returned bytes followed by the bytes themselves
is returned. On error a negative status code will be returned.
<ahref="#h">h</a><ahref="#r">r</a> - smb Read Byte Data: read byte from register</h3>This command returns a single byte read from register <ahref="#r">r</a> of the I2C device
associated with handle <ahref="#h">h</a>.
<br><br>Upon success a value between 0 and 255 will be returned. On error
<ahref="#h">h</a><ahref="#r">r</a> - smb Read Block Data: read data from register</h3>This command returns between 1 and 32 bytes read from register <ahref="#r">r</a> of
the I2C device associated with handle <ahref="#h">h</a>.
<br><br>Upon success the count of returned bytes followed by the bytes themselves
is returned. On error a negative status code will be returned.
<br><br>The number of bytes of returned data is specific to the device and
<ahref="#h">h</a><ahref="#r">r</a> - smb Read Word Data: read word from register</h3>This command returns a single 16 bit word read from register <ahref="#r">r</a> of
the I2C device associated with handle <ahref="#h">h</a>.
<br><br>Upon success a value between 0 and 65535 will be returned. On error
<ahref="#h">h</a><ahref="#r">r</a><ahref="#bv">bv</a> - smb Write Byte Data: write byte to register</h3>This command writes a single byte <ahref="#bv">bv</a> to register <ahref="#r">r</a> of the
I2C device associated with handle <ahref="#h">h</a>.
<br><br>Upon success nothing is returned. On error a negative status code
<ahref="#h">h</a><ahref="#r">r</a><ahref="#bvs">bvs</a> - smb Write I2C Block Data</h3>This command writes between 1 and 32 bytes <ahref="#bvs">bvs</a> to register <ahref="#r">r</a> of
the I2C device associated with handle <ahref="#h">h</a>.
<br><br>Upon success nothing is returned. On error a negative status code
<ahref="#h">h</a><ahref="#r">r</a><ahref="#bvs">bvs</a> - smb Write Block Data: write data to register</h3>This command writes between 1 and 32 bytes <ahref="#bvs">bvs</a> to register <ahref="#r">r</a> of
the I2C device associated with handle <ahref="#h">h</a>.
<br><br>Upon success nothing is returned. On error a negative status code
<ahref="#h">h</a><ahref="#bit">bit</a> - smb Write Quick: write bit</h3>This command writes a single <ahref="#bit">bit</a> to the I2C device associated
with handle <ahref="#h">h</a>.
<br><br>Upon success nothing is returned. On error a negative status code
<ahref="#h">h</a><ahref="#bv">bv</a> - smb Write Byte: write byte</h3>This command writes a single byte <ahref="#bv">bv</a> to the I2C device associated
with handle <ahref="#h">h</a>.
<br><br>Upon success nothing is returned. On error a negative status code
<ahref="#h">h</a><ahref="#r">r</a><ahref="#wv">wv</a> - smb Write Word Data: write word to register</h3>This command writes a single 16 bit word <ahref="#wv">wv</a> to register <ahref="#r">r</a> of
the I2C device associated with handle <ahref="#h">h</a>.
<br><br>Upon success nothing is returned. On error a negative status code
<ahref="#h">h</a><ahref="#bvs">bvs</a> - Performs multiple I2C transactions</h3>This command executes a sequence of I2C operations. The
operations to be performed are specified by the contents of <ahref="#bvs">bvs</a>
which contains the concatenated command codes and associated data.
<br><br>The following command codes are supported:
<br><br><tableborder="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 <ahref="#h">h</a>.
The flags default to 0. The address and flags maintain their
<ahref="#u">u</a><ahref="#v">v</a> - Set GPIO PWM value</h3>This command starts PWM on GPIO <ahref="#u">u</a> with dutycycle <ahref="#v">v</a>. The dutycycle
varies from 0 (off) to range (fully on). The range defaults to 255.
<br><br>Upon success nothing is returned. On error a negative status code
will be returned.
<br><br>This and the servo functionality use the DMA and PWM or PCM peripherals
to control and schedule the pulsewidths and dutycycles.
<br><br>The <ahref="#PRS">PRS</a> command may be used to change the default range of 255.
<ahref="#pad">pad</a><ahref="#padma">padma</a> - Set pad drive strength</h3>This command sets the <ahref="#pad">pad</a> drive strength <ahref="#padma">padma</a> in mA.
<br><br>Upon success nothing is returned. On error a negative status code
<ahref="#u">u</a><ahref="#v">v</a> - Set GPIO PWM frequency</h3>This command sets the PWM frequency <ahref="#v">v</a> to be used for GPIO <ahref="#u">u</a>.
<br><br>The numerically closest frequency to <ahref="#v">v</a> will be selected.
<br><br>Upon success the new frequency is returned. On error a negative status code
will be returned.
<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.
<ahref="#sid">sid</a><ahref="#pars">pars</a> - Set script parameters</h3>This command sets the parameters of a stored script <ahref="#sid">sid</a> passing
it up to 10 parameters.
<br><br>Upon success nothing is returned. On error a negative status code
<ahref="#u">u</a><ahref="#v">v</a> - Set GPIO PWM range</h3>This command sets the dutycycle range <ahref="#v">v</a> to be used for GPIO <ahref="#u">u</a>.
Subsequent uses of command <ahref="#P/PWM">P/PWM</a> will use a dutycycle between 0 (off)
and <ahref="#v">v</a> (fully on).
<br><br>Upon success the real underlying range used by the GPIO is returned.
On error a negative status code will be returned.
<br><br>If PWM is currently active on the GPIO its dutycycle will be scaled to
reflect the new range.
<br><br>The real range, the number of steps between fully off and fully on
for each frequency, is given in the following table.
<br><br><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td>#1</td><td>#2</td><td>#3</td><td>#4</td><td>#5</td><td>#6</td><td>#7</td><td>#8</td><td>#9</td></tr><tr><td>25</td><td>50</td><td>100</td><td>125</td><td>200</td><td>250</td><td>400</td><td>500</td><td>625</td></tr><tr><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>#10</td><td>#11</td><td>#12</td><td>#13</td><td>#14</td><td>#15</td><td>#16</td><td>#17</td><td>#18</td></tr><tr><td>800</td><td>1000</td><td>1250</td><td>2000</td><td>2500</td><td>4000</td><td>5000</td><td>10000</td><td>20000</td></tr></tbody></table><br><br>The real value set by <ahref="#PRS">PRS</a> is (dutycycle * real range) / range.
<ahref="#g">g</a><ahref="#p">p</a> - Set GPIO pull up/down</h3>This command sets the internal pull/up down for GPIO <ahref="#g">g</a> to mode <ahref="#p">p</a>.
<br><br>Upon success nothing is returned. On error a negative status code
will be returned.
<br><br>The mode may be pull-down (D), pull-up (U), or off (O).
<ahref="#u">u</a><ahref="#v">v</a> - Set GPIO servo pulsewidth</h3>This command starts servo pulses of <ahref="#v">v</a> microseconds on GPIO <ahref="#u">u</a>.
<br><br>Upon success nothing is returned. On error a negative status code
will be returned.
<br><br>The servo pulsewidth may be 0 (off), 500 (most anti-clockwise)
to 2500 (most clockwise).
<br><br>The range supported by servos varies and should probably be determined
by experiment. Generally values between 1000-2000 should be safe.
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 limits.
<br><br><b><small>Example</small></b><br><br><code>$ pigs SERVO 17 1500<br></code><br><br>This example causes an on pulse of 1500 microseconds duration to be
transmitted on GPIO 17 at a rate of 50 times per second.
<br><br>This will command a servo connected to GPIO 17 to rotate to its mid-point.
<ahref="#dev">dev</a><ahref="#b">b</a><ahref="#sef">sef</a> - Open serial device dev at baud b with flags</h3>This command opens the serial <ahref="#dev">dev</a> at <ahref="#b">b</a> bits per second.
<br><br>No flags are currently defined. <ahref="#sef">sef</a> should be set to zero.
<br><br>Upon success a handle (>=0) is returned. On error a negative status code
will be returned.
<br><br>The device name must start with /dev/tty or /dev/serial.
<br><br>The baud rate must be one of 50, 75, 110, 134, 150,
<ahref="#h">h</a><ahref="#num">num</a> - Read bytes from serial handle</h3>This command returns up to <ahref="#num">num</a> bytes of data read from the
serial device associated with handle <ahref="#h">h</a>.
<br><br>Upon success the count of returned bytes followed by the bytes themselves
is returned. On error a negative status code will be returned.
<ahref="#name">name</a><ahref="#str">str</a> - Execute a shell command</h3>This command uses the system call to execute a shell script <ahref="#name">name</a>
with the given string <ahref="#str">str</a> as its parameter.
<br><br>The exit status of the system call is returned if OK, otherwise
PI_BAD_SHELL_STATUS.
<br><br><ahref="#name">name</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><tableborder="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>$ pigs shell scr1 hello world<br>256<br><br># pass three parameters, hello, string with spaces, and world<br>$ pigs shell scr1 "hello 'string with spaces' world"<br>256<br><br># pass one parameter, hello string with spaces world<br>$ pigs shell scr1 "\"hello string with spaces world\""<br>256<br><br># non-existent script<br>$ pigs shell scr78 par1<br>32512<br></code><h3><aname="SLR">SLR</a>
<ahref="#u">u</a><ahref="#num">num</a> - Read bit bang serial data from GPIO</h3>This command returns up to <ahref="#num">num</a> bytes of bit bang serial data
read from GPIO <ahref="#u">u</a>.
<br><br>Upon success the count of returned bytes followed by the bytes themselves
is returned. On error a negative status code will be returned.
<br><br>The GPIO <ahref="#u">u</a> should have been initialised with the <ahref="#SLRO">SLRO</a> command.
<br><br>The bytes returned for each character depend upon the number of
data bits <ahref="#db">db</a> specified in the <ahref="#SLRO">SLRO</a> command.
<br><br>For <ahref="#db">db</a> 1-8 there will be one byte per character.<br>
For <ahref="#db">db</a> 9-16 there will be two bytes per character.<br>
For <ahref="#db">db</a> 17-32 there will be four bytes per character.
<ahref="#u">u</a><ahref="#b">b</a><ahref="#db">db</a> - Open GPIO for bit bang serial data</h3>This command opens GPIO <ahref="#u">u</a> for reading bit bang serial data
at <ahref="#b">b</a> baud and <ahref="#db">db</a> data bits.
<br><br>Upon success nothing is returned. On error a negative status code
will be returned.
<br><br>The baud rate may be between 50 and 250000 bits per second.
<br><br>The received data is held in a cyclic buffer.
<br><br>It is the user's responsibility to read the data (with <ahref="#SLR">SLR</a>)
<ahref="#c">c</a><ahref="#b">b</a><ahref="#spf">spf</a> - SPI open channel at baud b with flags</h3>This command returns a handle to a SPI device on channel <ahref="#c">c</a>.
<br><br>Data will be transferred at <ahref="#b">b</a> bits per second. The flags <ahref="#spf">spf</a>
may be used to modify the default behaviour of 4-wire operation,
mode 0, active low chip select.
<br><br>Speeds between 32kbps and 125Mbps are allowed. Speeds above 30Mbps
are unlikely to work.
<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><tableborder="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>The 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 <ahref="#SPIR">SPIR</a>, <ahref="#SPIW">SPIW</a>, and <ahref="#SPIX">SPIX</a> commands 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.<br>
For bits 9-16 there will be two bytes per character.<br>
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 64 bytes need to be sent.
<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.
<br><br>Upon success a handle (>=0) is returned. On error a negative status code
<ahref="#u">u</a><ahref="#pl">pl</a><ahref="#L">L</a> - Send a trigger pulse</h3>This command sends a trigger pulse of <ahref="#pl">pl</a> microseconds at level <ahref="#L">L</a>
to GPIO <ahref="#u">u</a>.
<br><br>Upon success nothing is returned. On error a negative status code
will be returned.
<br><br>The GPIO is set to not level at the end of the pulse.
<ahref="#u">u</a><ahref="#v">v</a> - Set GPIO watchdog</h3>This command sets a watchdog of <ahref="#v">v</a> milliseconds on GPIO <ahref="#u">u</a>.
<br><br>Upon success nothing is returned. On error a negative status code
will be returned.
<br><br>The watchdog is nominally in milliseconds.
<br><br>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 monitors of the GPIO
will be triggered every timeout interval after the last
GPIO activity. The watchdog expiry will be indicated by
a special TIMEOUT value.
<br><br><b><small>Example</small></b><br><br><code>$ pigs wdog 23 90000<br>-15<br>ERROR: timeout not 0-60000<br><br>$ pigs wdog 23 9000<br></code><br><br>This example causes a report to be written to any notification pipes
listening on GPIO 23 whenever GPIO 23 changes state or approximately
every 9000 ms.
<h3><aname="WVAG">WVAG</a>
<ahref="#trips">trips</a> - Add generic pulses to waveform</h3>This command adds 1 one or more triplets <ahref="#trips">trips</a> of GPIO on, GPIO off,
delay to the existing waveform (if any).
<br><br>Upon success the total number of pulses in the waveform so far is
returned. On error a negative status code will be returned.
<br><br>The triplets will be added at the start of the existing waveform. If
they are to start offset from the start then the first triplet should
<ahref="#u">u</a><ahref="#b">b</a><ahref="#db">db</a><ahref="#sb">sb</a><ahref="#o">o</a><ahref="#bvs">bvs</a> - Add serial data to waveform</h3>This command adds a waveform representing serial data <ahref="#bvs">bvs</a> to
GPIO <ahref="#u">u</a> at <ahref="#b">b</a> baud to the existing waveform (if any).
The serial data starts <ahref="#o">o</a> microseconds from the start of the
waveform.
<br><br>Upon success the total number of pulses in the waveform so far is
returned. On error a negative status code will be returned.
<br><br>The serial data is formatted as one start bit, <ahref="#db">db</a> data bits, and
<ahref="#sb">sb</a>/2 stop bits.
<br><br>The baud rate may be between 50 and 1000000 bits per second.
<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 <ahref="#db">db</a>.
<br><br>For <ahref="#db">db</a> 1-8 there will be one byte per character.<br>
For <ahref="#db">db</a> 9-16 there will be two bytes per character.<br>
For <ahref="#db">db</a> 17-32 there will be four bytes per character.
<ahref="#bvs">bvs</a> - Transmits a chain of waveforms</h3>This command transmits a chain of waveforms.
<br><br>NOTE: Any hardware PWM started by <ahref="#HP">HP</a> will
be cancelled.
<br><br>The waves to be transmitted are specified by the contents of
<ahref="#bvs">bvs</a> which contains an ordered list of wave_ids and optional
command codes and related data.
<br><br>Upon success 0 is returned. On error a negative status code
will be returned.
<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><tableborder="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 roughly
<ahref="#wid">wid</a><ahref="#wmde">wmde</a> - Transmits waveform using mode</h3>This command transmits the waveform with id <ahref="#wid">wid</a> using mode <ahref="#wmde">wmde</a>.
<br><br>The mode may be send once (0), send repeatedly (1), send once but
first sync with previous wave (2), or send repeatedly but first
sync with previous wave (3).
<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 <ahref="#HP">HP</a> will be cancelled.
<br><br>Upon success the number of DMA control blocks in the waveform is returned.
<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>See <ahref="#HWVER">HWVER</a>.
<br><br>The user GPIO are marked with an X in the following table.
<br><br><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td></td><td>0</td><td>1</td><td>2</td><td>3</td><td>4</td><td>5</td><td>6</td><td>7</td><td>8</td><td>9</td><td>10</td><td>11</td><td>12</td><td>13</td><td>14</td><td>15</td></tr><tr><td>Type 1</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>X</td></tr><tr><td>Type 2</td><td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>X</td></tr><tr><td>Type 3</td><td></td><td></td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr><tr><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td></td><td>16</td><td>17</td><td>18</td><td>19</td><td>20</td><td>21</td><td>22</td><td>23</td><td>24</td><td>25</td><td>26</td><td>27</td><td>28</td><td>29</td><td>30</td><td>31</td></tr><tr><td>Type 1</td><td>-</td><td>X</td><td>X</td><td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td><td>-</td></tr><tr><td>Type 2</td><td>-</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>X</td><td>X</td><td>X</td><td>X</td><td>-</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td></tr><tr><td>Type 3</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>X</td><td>-</td><td>-</td><td>-</td><td>-</td></tr></tbody></table><br><br>You are not prevented from writing to unsafe GPIO. The consequences
of doing so range from no effect, to a crash, or corrupted data.
<h3><aname="h">h</a> - handle (>=0)</h3>
The command expects a handle.
<br><br>A handle is a number referencing an object opened by one of <ahref="#FO">FO</a>,
The GPIO used for the MISO signal when bit banging SPI.
<h3><aname="mode">mode</a> - file open mode</h3>
One of the following values.
<br><br><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td></td><td>Value</td><td>Meaning</td></tr><tr><td>READ</td><td>1</td><td>open file for reading</td></tr><tr><td>WRITE</td><td>2</td><td>open file for writing</td></tr><tr><td>RW</td><td>3</td><td>open file for reading and writing</td></tr></tbody></table><br><br>The following values can be or'd into the mode.
<br><br><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td></td><td>Value</td><td>Meaning</td></tr><tr><td>APPEND</td><td>4</td><td>All writes append data to the end of the file</td></tr><tr><td>CREATE</td><td>8</td><td>The file is created if it doesn't exist</td></tr><tr><td>TRUNC</td><td>16</td><td>The file is truncated</td></tr></tbody></table><h3><aname="mosi">mosi</a> - GPIO (0-31)</h3>
The GPIO used for the MOSI signal when bit banging SPI.
<h3><aname="name">name</a> - the name of a script</h3>
Only alphanumeric characters, '-' and '_' are allowed in the name.
<h3><aname="num">num</a> - maximum number of bytes to return (1-)</h3>
The command expects the maximum number of bytes to return.
<br><br>For the I2C and SPI commands the requested number of bytes will always
be returned.
<br><br>For the serial and file commands the smaller of the number of
bytes available to be read (which may be zero) and <ahref="#num">num</a> bytes
will be returned.
<h3><aname="o">o</a> - offset (>=0)</h3>
Serial data is stored offset microseconds from the start of the waveform.
<h3><aname="p">p</a> - PUD (ODU)</h3>
The command expects a PUD character.
<br><br>Each GPIO can be configured to use or not use an internal pull up or
pull down resistor. This is useful to provide a default state for inputs.
<br><br>A pull up will default the input to 1 (high).
<br><br>A pull down will default the input to 0 (low).
<br><br>To set the pull up down state use the command character for the state.
<br><br><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td>Pull Up Down</td><td>Off</td><td>Pull Down</td><td>Pull Up</td></tr><tr><td>Command Character</td><td>O</td><td>D</td><td>U</td></tr></tbody></table><br><br>There is no mechanism to read the pull up down state.
<h3><aname="wv">wv</a> - word value (0-65535)</h3>
The command expects a word value.
<h2><aname="Scripts">Scripts</a></h2>
Scripts are programs to be stored and executed by the pigpio daemon.
They are intended to mitigate any performance problems associated with
the pigpio daemon server/client model.
<h3>Example</h3>A trivial example might be useful. Suppose you want to toggle a GPIO
on and off as fast as possible.
<br><br>From the command line you could write
<br><br><code>for ((i=0; i<1000;i++)); do pigs w 22 1 w 22 0; done<br></code><br><br>Timing that you will see it takes about 14 seconds, or roughly
70 toggles per second.
<br><br>Using the pigpio Python module you could use code such as
<br><br><code>#!/usr/bin/env python<br><br>import time<br><br>import pigpio<br><br>PIN=4<br><br>TOGGLE=10000<br><br>pi = pigpio.pi() # Connect to local Pi.<br><br>s = time.time()<br><br>for i in range(TOGGLE):<br> pi.write(PIN, 1)<br> pi.write(PIN, 0)<br><br>e = time.time()<br><br>print("pigpio did {} toggles per second".format(int(TOGGLE/(e-s))))<br><br>pi.stop()<br></code><br><br>Timing that shows a speed improvement to roughly 800 toggles per second.
<br><br>Now let's use a script.
<br><br><code>pigs proc tag 999 w 22 1 w 22 0 dcr p0 jp 999<br></code><br><br>Ignore the details for now.
<br><br>Let's time the script running.
<br><br>Again, ignore the details for now.
<br><br><code>time (pigs procr 0 10000000; while a=$(pigs procp 0); [[ ${a::1} -eq 2 ]];\<br> do sleep 0.2; done)<br></code><br><br>The script takes roughly 12 seconds to complete, or 800,000 toggles per second.
<br><br>That is the advantage of a stored script.
<br><br>Some details.
<br><br><code>pigs proc tag 999 w 22 1 w 22 0 dcr p0 jp 999<br></code><br><br>proc introduces a script. Everything after proc is part of the script.<br>
tag 999 names the current position in the script.<br>
w 22 1 writes 1 to GPIO 22.<br>
w 22 0 writes 0 to GPIO 22.<br>
dcr p0 decrements parameter 0.<br>
jp 999 jumps to tag 999 if the result is positive.
<br><br><code>time (pigs procr 0 10000000; while a=$(pigs procp 0); [[ ${a::1} -eq 2 ]];\<br> do sleep 0.2; done)<br></code><br><br>pigs procr 0 10000000 starts script 0 with parameter 0 of 10 million.
<br><br>The rest is bash apart from
<br><br>pigs procp 0 asks for the status and parameters of script 0.
The status will be 2 while the script is running and 1 when it is complete.
<h3>Virtual machine</h3>A script runs within a virtual machine with
<br><br>a 32 bit accumulator A.<br>
a flags register F.<br>
a program counter PC.
<br><br>Each script has
<br><br>10 parameters named 0 through 9.<br>
150 variables named 0 through 149.<br>
50 labels which are named by any unique number.
<h3>Commands</h3>Many pigpio commands may be used within a script. However
some commands do not work within the script model as designed and
are not permitted.
<br><br>The following commands are not permitted within a script:
<br><br>Script control - PARSE PROC PROCD PROCP PROCR PROCS PROCU
<br><br>Serial - SERO SERR SERW SLR
<br><br>SPI - BSPIO BSPIX SPIR SPIW SPIX
<br><br>Waves - WVAG WVAS WVCHA WVGO WVGOR
<br><br>The following commands are only permitted within a script:
<br><br><tableborder="1"cellpadding="2"cellspacing="2"><tbody><tr><td>Command</td><td>Description</td><td>Definition</td></tr><tr><td>ADD x</td><td>Add x to accumulator</td><td>A+=x; F=A</td></tr><tr><td>AND x</td><td>And x with accumulator</td><td>A&=x; F=A</td></tr><tr><td>CALL L</td><td>Call subroutine at tag L</td><td>push(PC+1); PC=L</td></tr><tr><td>CMP x</td><td>Compare x with accumulator</td><td>F=A-x</td></tr><tr><td>DCR y</td><td>Decrement register</td><td>--*y; F=*y</td></tr><tr><td>DCRA</td><td>Decrement accumulator</td><td>--A; F=A</td></tr><tr><td>DIV x</td><td>Divide x into accumulator</td><td>A/=x; F=A</td></tr><tr><td>EVTWT</td><td>Wait for an event to occur</td><td>A=wait(x); F=A</td></tr><tr><td>HALT</td><td>Halt</td><td>Halt</td></tr><tr><td>INR y</td><td>Increment register</td><td>++*y; F=*y</td></tr><tr><td>INRA</td><td>Increment accumulator</td><td>++A; F=A</td></tr><tr><td>JM L</td><td>Jump if minus to tag L</td><td>if (F<0) PC=L</td></tr><tr><td>JMP L</td><td>Jump to tag L</td><td>PC=L</td></tr><tr><td>JNZ L</td><td>Jump if non-zero to tag L</td><td>if (F) PC=L</td></tr><tr><td>JP L</td><td>Jump if positive to tag L</td><td>if (F>=0) PC=L</td></tr><tr><td>JZ L</td><td>Jump if zero to tag L</td><td>if (!F) PC=L</td></tr><tr><td>LD y x</td><td>Load register with x</td><td>*y=x</td></tr><tr><td>LDA x</td><td>Load accumulator with x</td><td>A=x</td></tr><tr><td>MLT x</td><td>Multiply x with accumulator</td><td>A*=x; F=A</td></tr><tr><td>MOD x</td><td>Modulus x with accumulator</td><td>A%=x; F=A</td></tr><tr><td>OR x</td><td>Or x with accumulator</td><td>A|=x; F=A</td></tr><tr><td>POP y</td><td>Pop register</td><td>y=pop()</td></tr><tr><td>POPA</td><td>Pop accumulator</td><td>A=pop()</td></tr><tr><td>PUSH y</td><td>Push register</td><td>push(y)</td></tr><tr><td>PUSHA</td><td>Push accumulator</td><td>push(A)</td></tr><tr><td>RET</td><td>Return from subroutine</td><td>PC=pop()</td></tr><tr><td>RL y x</td><td>Rotate left register x bits</td><td>*y<<=x; F=*y</td></tr><tr><td>RLA x</td><td>Rotate left accumulator x bits</td><td>A<<=x; F=A</td></tr><tr><td>RR y x</td><td>Rotate right register x bits</td><td>*y>>=x; F=*y</td></tr><tr><td>RRA x</td><td>Rotate right accumulator x bits</td><td>A>>=x; F=A</td></tr><tr><td>STA y</td><td>Store accumulator in register</td><td>y=A</td></tr><tr><td>SUB x</td><td>Subtract x from accumulator</td><td>A-=x; F=A</td></tr><tr><td>SYS str</td><td>Run external script (/opt/pigpio/cgi/str)</td><td>system(str); F=A</td></tr><tr><td>TAG L</td><td>Label the current script position</td><td>N/A</td></tr><tr><td>WAIT x</td><td>Wait for a GPIO in x to change state</td><td>A=wait(x); F=A</td></tr><tr><td>X y1 y2</td><td>Exchange contents of registers y1 and y2</td><td>t=*y1;*y1=*y2;*y2=t</td></tr><tr><td>XA y</td><td>Exchange contents of accumulator and register</td><td>t=A;A=*y;*y=t</td></tr><tr><td>XOR x</td><td>Xor x with accumulator</td><td>A^=x; F=A</td></tr></tbody></table><br><br>x may be a constant, a parameter (p0-p9), or a variable (v0-v149).
<br><br>y may be a parameter (p0-p9), or a variable (v0-v149). If p or v isn't
specified y is assumed to be a variable.
<br><br>The EVTWT command parameter is a bit-mask with 1 set for events of interest.
<br><br>The WAIT command parameter is a bit-mask with 1 set for GPIO of interest.
<br><br>The SYS script receives two unsigned parameters: the accumulator A and
