V17

1 files changed, 3486 insertions, 0 deletions

diff --git a/pigs.1 b/pigs.1
new file mode 100644
index 0000000..4154690
--- /dev/null
+++ b/pigs.1
@@ -0,0 +1,3486 @@
+
+." Process this file with
+." groff -man -Tascii foo.1
+."
+.TH pigs 1 2012-2014 Linux "pigpio archive"
+.SH NAME
+pigs - command line socket access to the pigpio daemon.
+
+/dev/pigpio - command line pipe access to the pigpio daemon.
+
+.SH SYNOPSIS
+
+.B sudo pigpiod
+
+then
+
+.B pigs {command}+
+
+or
+
+.B "echo {command}+ >/dev/pigpio"
+
+.SH DESCRIPTION
+
+
+.br
+The socket and pipe interfaces allow control of the gpios by passing
+messages to the running pigpio library.
+
+.br
+The normal way to start the pigpio library would be as a daemon during boot.
+
+.br
+
+.EX
+sudo pigpiod
+.br
+
+.EE
+
+.br
+pigs is a program and internally uses the socket interface to pigpio
+whereas /dev/pigpio uses the pipe interface.
+
+.br
+.SS Features
+.br
+o PWM on any of gpios 0-31
+
+.br
+o servo pulses on any of gpios 0-31
+
+.br
+o reading/writing all of the gpios in a bank as one operation
+
+.br
+o individually setting gpio modes, reading and writing
+
+.br
+o notifications when any of gpios 0-31 change state
+
+.br
+o the construction of output waveforms with microsecond timing
+
+.br
+o I2C, SPI, and serial link wrappers
+
+.br
+o creating and running scripts on the pigpio daemon
+
+.br
+.SS gpios
+.br
+ALL gpios are identified by their Broadcom number.
+
+.br
+.SS Usage
+.br
+pigs and the socket interface share the same commands and are invoked in
+a similar fashion from the command line.
+
+.br
+The pigpio library must be running, either by running a program linked
+with the library or starting the pigpio daemon (sudo pigpiod).
+
+.br
+pigs {command}+
+
+.br
+echo "{command}+" >/dev/pigpio
+
+.br
+pigs will show the result of the command on screen.
+
+.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
+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
+Several commands may be entered on a line.  If present PROC and PARSE must
+be the last command on a line.
+
+.br
+E.g.
+
+.br
+
+.EX
+pigs w 22 1 mils 1000 w 22 0
+.br
+
+.EE
+
+.br
+is equivalent to
+
+.br
+
+.EX
+pigs w 22 1
+.br
+pigs mils 1000
+.br
+pigs w 22 0
+.br
+
+.EE
+
+.br
+and
+
+.br
+
+.EX
+echo "m 4 w w 4 0 mils 250 m 4 r r 4" >/dev/pigpio
+.br
+
+.EE
+
+.br
+is equivalent to
+
+.br
+
+.EX
+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
+
+.EE
+
+.br
+.SS Notes
+.br
+The examples from now on will show the pigs interface but the same
+commands will also work on the pipe interface.
+
+.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
+The status/data of each command sent to the pipe interface should
+be read from /dev/pigout.
+
+.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
+E.g. 23 is 23 decimal, 0x100 is 256 decimal, 070 is 56 decimal.
+
+.br
+
+.SH COMMANDS
+
+.br
+
+.IP "\fBBC1 bits\fP - Clear specified gpios in bank 1"
+.IP "" 4
+This command clears (sets low) the gpios specified by \fBbits\fP in bank 1.
+Bank 1 consists of gpios 0-31.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs bc1 0x400010 # clear gpios 4 (1<<4) and 22 (1<<22)
+.br
+
+.br
+$ pigs bc1 32 # clear gpio 5 (1<<5)
+.br
+-42
+.br
+ERROR: no permission to update one or more gpios
+.br
+
+.EE
+
+.br
+
+.IP "\fBBC2 bits\fP - Clear specified gpios in bank 2"
+.IP "" 4
+This command clears (sets low) the gpios specified by \fBbits\fP in bank 2.
+Bank 2 consists of gpios 32-53.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs bc2 0x8000 # clear gpio 47 (activity LED on B+)
+.br
+
+.br
+$ pigs bc2 1 # clear gpio 32 (first in bank 2)
+.br
+-42
+.br
+ERROR: no permission to update one or more gpios
+.br
+
+.EE
+
+.br
+
+.IP "\fBBR1 \fP - Read bank 1 gpios"
+.IP "" 4
+This command read gpios 0-31 (bank 1) and returns the levels as a
+32-bit hexadecimal value.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs br1
+.br
+1001C1CF
+.br
+
+.EE
+
+.br
+
+.IP "\fBBR2 \fP - Read bank 2 gpios"
+.IP "" 4
+This command read gpios 32-53 (bank 2) and returns the levels as a
+32-bit hexadecimal value.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs br2
+.br
+003F0000
+.br
+
+.EE
+
+.br
+
+.IP "\fBBS1 bits\fP - Set specified gpios in bank 1"
+.IP "" 4
+This command sets (sets high) the gpios specified by \fBbits\fP in bank 1.
+Bank 1 consists of gpios 0-31.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs bs1 16 # set gpio 4 (1<<4)
+.br
+
+.br
+$ pigs bs1 1 # set gpio 1 (1<<0)
+.br
+-42
+.br
+ERROR: no permission to update one or more gpios
+.br
+
+.EE
+
+.br
+
+.IP "\fBBS2 bits\fP - Set specified gpios in bank 2"
+.IP "" 4
+This command sets (sets high) the gpios specified by \fBbits\fP in bank 2.
+Bank 2 consists of gpios 32-53.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs bs2 0x40 # set gpio 38 (enable high current mode B+)
+.br
+
+.br
+$ pigs bs2 1 # set gpio 32 (first in bank 2)
+.br
+-42
+.br
+ERROR: no permission to update one or more gpios
+.br
+
+.EE
+
+.br
+
+.IP "\fBH/HELP \fP - Display command help"
+.IP "" 4
+This command displays a brief list of the commands and their parameters.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs h
+.br
+
+.br
+$ pigs help
+.br
+
+.EE
+
+.br
+
+.IP "\fBHWVER \fP - Get hardware version"
+.IP "" 4
+This command returns the hardware revision of the Pi.
+
+.br
+The hardware revision is found in the last 4 characters on the Revision
+line of /proc/cpuinfo.
+
+.br
+If the hardware revision can not be found or is not a valid hexadecimal
+number the command returns 0.
+
+.br
+The revision number can be used to determine the assignment of gpios to pins.
+
+.br
+There are currently three types of board.
+
+.br
+Type 1 has gpio 0 on P1-3, gpio 1 on P1-5, and gpio 21 on P1-13.
+
+.br
+Type 2 has gpio 2 on P1-3, gpio 3 on P1-5, gpio 27 on P1-13, and
+gpios 28-31 on P5.
+
+.br
+Type 3 has a 40 pin connector rather than the 26 pin connector of
+the earlier boards.  Gpios 0 to 27 are brought out to the connector
+(although gpios 0 and 1 are reserved).
+
+.br
+Type 1 boards have hardware revision numbers of 2 and 3.
+
+.br
+Type 2 boards have hardware revision numbers of 4, 5, 6, and 15.
+
+.br
+Type 3 boards have hardware revision number 16.
+
+.br
+for "Revision : 0002" the command returns 2.
+
+.br
+for "Revision : 000f" the command returns 15.
+
+.br
+for "Revision : 000g" the command returns 0.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs hwver # On a B+
+.br
+16
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CC h\fP - Close I2C handle"
+.IP "" 4
+This command closes an I2C handle \fBh\fP previously opened with \fBI2CO\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2cc 0 # First close okay.
+.br
+
+.br
+$ pigs i2cc 0 # Second fails.
+.br
+-25
+.br
+ERROR: unknown handle
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CO ib id if\fP - Open I2C bus and device with flags"
+.IP "" 4
+This command returns a handle to access device \fBid\fP on I2C bus \fBib\fP.
+The device is opened with flags \fBif\fP.
+
+.br
+No flags are currently defined.  The parameter \fBif\fP should be 0.
+
+.br
+Upon success the next free handle (>=0) is returned.  On error a
+negative status code will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2co 1 0x70 0 # Bus 1, device 0x70, flags 0.
+.br
+0
+.br
+
+.br
+$ pigs i2co 1 0x53 0 # Bus 1, device 0x53, flags 0.
+.br
+1
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CPC h r wv\fP - smb Process Call: exchange register with word"
+.IP "" 4
+This command writes \fBwv\fP to register \fBr\fP of the I2C device
+associated with handle \fBh\fP and returns a 16-bit word read from the
+device.
+
+.br
+Upon success a value between 0 and 65535 will be returned.  On error
+a negative status code will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2cpc 0 37 43210
+.br
+39933
+.br
+
+.br
+$ pigs i2cpc 0 256 43210
+.br
+ERROR: bad i2c/spi/ser parameter
+.br
+-81
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CPK h r bvs\fP - smb Block Process Call: exchange data bytes with register"
+.IP "" 4
+
+.br
+This command writes the data bytes \fBbvs\fP to register \fBr\fP of the I2C device
+associated with handle \fBh\fP and returns a device specific number of bytes.
+
+.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
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2cpk 0 0 0x11 0x12
+.br
+6 0 0 0 0 0 0
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CRB h r\fP - smb Read Byte Data: read byte from register"
+.IP "" 4
+
+.br
+This command returns a single byte read from register \fBr\fP of the I2C device
+associated with handle \fBh\fP.
+
+.br
+Upon success a value between 0 and 255 will be returned.  On error
+a negative status code will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2crb 0 0
+.br
+6
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CRD h num\fP - i2c Read bytes"
+.IP "" 4
+
+.br
+This command returns \fBnum\fP bytes read from the I2C device associated with
+handle \fBh\fP.
+
+.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
+This command operates on the raw I2C device.  The maximum value of the
+parameter \fBnum\fP is dependent on the I2C drivers and the device
+itself. pigs imposes a limit of about 8000 bytes.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2crd 0 16
+.br
+16 6 24 0 0 0 0 0 0 0 0 0 0 0 0 32 78
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CRI h r num\fP - smb Read I2C Block Data: read bytes from register"
+.IP "" 4
+
+.br
+This command returns \fBnum\fP bytes from register \fBr\fP of the I2C device
+associated with handle \fBh\fP.
+
+.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
+The parameter \fBnum\fP may be 1-32.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2cri 0 0 16
+.br
+16 237 155 155 155 155 155 155 155 155 155 155 155 155 155 155 155
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CRK h r\fP - smb Read Block Data: read data from register"
+.IP "" 4
+
+.br
+This command returns between 1 and 32 bytes read from register \fBr\fP of
+the I2C device associated with handle \fBh\fP.
+
+.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
+The number of bytes of returned data is specific to the device and
+register.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2crk 0 0
+.br
+6 0 0 0 0 0 0
+.br
+
+.br
+$ pigs i2crk 0 1
+.br
+24 0 0 0 0 0 0 0 0 0 0 0 0 120 222 105 215 128 87 195 217 0 0 0 0
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CRS h\fP - smb Read Byte: read byte"
+.IP "" 4
+
+.br
+This command returns a single byte read from the I2C device
+associated with handle \fBh\fP.
+
+.br
+Upon success a value between 0 and 255 will be returned.  On error
+a negative status code will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2crs 0
+.br
+0
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CRW h r\fP - smb Read Word Data: read word from register"
+.IP "" 4
+
+.br
+This command returns a single 16 bit word read from register \fBr\fP of
+the I2C device associated with handle \fBh\fP.
+
+.br
+Upon success a value between 0 and 65535 will be returned.  On error
+a negative status code will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2crw 0 0
+.br
+6150
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CWB h r bv\fP - smb Write Byte Data: write byte to register"
+.IP "" 4
+
+.br
+This command writes a single byte \fBbv\fP to register \fBr\fP of the
+I2C device associated with handle \fBh\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2cwb 0 10 0x54
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CWD h bvs\fP - i2c Write data"
+.IP "" 4
+
+.br
+This command writes a block of bytes \fBbvs\fP to the I2C device
+associated with handle \fBh\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+The number of bytes which may be written in one transaction is
+dependent on the I2C drivers and the device itself.  pigs imposes
+a limit of about 500 bytes.
+
+.br
+This command operates on the raw I2C device.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2cwd 0 0x01 0x02 0x03 0x04
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CWI h r bvs\fP - smb Write I2C Block Data"
+.IP "" 4
+
+.br
+This command writes between 1 and 32 bytes \fBbvs\fP to register \fBr\fP of
+the I2C device associated with handle \fBh\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2cwi 0 4 0x01 0x04 0xc0
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CWK h r bvs\fP - smb Write Block Data: write data to register"
+.IP "" 4
+
+.br
+This command writes between 1 and 32 bytes \fBbvs\fP to register \fBr\fP of
+the I2C device associated with handle \fBh\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+pigs i2cwk 0 4 0x01 0x04 0xc0
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CWQ h bit\fP - smb Write Quick: write bit"
+.IP "" 4
+
+.br
+This command writes a single \fBbit\fP to the I2C device associated
+with handle \fBh\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2cwq 0 1
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CWS h bv\fP - smb Write Byte: write byte"
+.IP "" 4
+
+.br
+This command writes a single byte \fBbv\fP to the I2C device associated
+with handle \fBh\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2cws 0 0x12
+.br
+
+.br
+$ pigs i2cws 0 0xff
+.br
+-82
+.br
+ERROR: I2C write failed
+.br
+
+.EE
+
+.br
+
+.IP "\fBI2CWW h r wv\fP - smb Write Word Data: write word to register"
+.IP "" 4
+
+.br
+This command writes a single 16 bit word \fBwv\fP to register \fBr\fP of
+the I2C device associated with handle \fBh\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs i2cww 0 0 0xffff
+.br
+
+.EE
+
+.br
+
+.IP "\fBM/MODES g m\fP - Set gpio mode"
+.IP "" 4
+
+.br
+This command sets gpio \fBg\fP to mode \fBm\fP, typically input (read)
+or output (write).
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+Each gpio can be configured to be in one of 8 different modes. The modes
+are named Input, Output, ALT0, ALT1, ALT2, ALT3, ALT4, and ALT5.
+
+.br
+To set the mode use the code for the mode.
+
+.br
+
+.EX
+Mode  Input Output ALT0 ALT1 ALT2 ALT3 ALT4 ALT5
+Code      R      W    0    1    2    3    4    5
+
+.EE
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs m 4 r # Input (read)
+.br
+$ pigs m 4 w # Output (write)
+.br
+$ pigs m 4 0 # ALT 0
+.br
+$ pigs m 4 5 # ALT 5
+.br
+
+.EE
+
+.br
+
+.IP "\fBMG/MODEG g\fP - Get gpio mode"
+.IP "" 4
+
+.br
+This command returns the current mode of gpio \fBg\fP.
+
+.br
+Upon success the value of the gpio mode is returned.
+On error a negative status code will be returned.
+
+.br
+
+.EX
+Value      0      1    2    3    4    5    6    7
+Mode   Input Output ALT5 ALT4 ALT0 ALT1 ALT2 ALT3
+
+.EE
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs mg 4
+.br
+1
+.br
+
+.EE
+
+.br
+
+.IP "\fBMICS v\fP - Microseconds delay"
+.IP "" 4
+This command delays execution for \fBv\fP microseconds.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+The main use of this command is expected to be within \fBScripts\fP.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs mics 20 # Delay 20 microseconds.
+.br
+$ pigs mics 1000000 # Delay 1 second.
+.br
+
+.br
+$ pigs mics 2000000
+.br
+-64
+.br
+ERROR: bad MICS delay (too large)
+.br
+
+.EE
+
+.br
+
+.IP "\fBMILS v\fP - Milliseconds delay"
+.IP "" 4
+
+.br
+This command delays execution for \fBv\fP milliseconds.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs mils 2000 # Delay 2 seconds.
+.br
+
+.br
+$ pigs mils 61000
+.br
+-65
+.br
+ERROR: bad MILS delay (too large)
+.br
+
+.EE
+
+.br
+
+.IP "\fBNB h bits\fP - Start notification"
+.IP "" 4
+
+.br
+This command starts notifications on handle \fBh\fP returned by
+a prior call to \fBNO\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+The notification gets state changes for each gpio specified by \fBbits\fP.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs nb 0 -1 # Shorthand for gpios 0-31.
+.br
+$ pigs nb 0 0xf0 # Get notifications for gpios 4-7.
+.br
+
+.br
+$ pigs nb 1 0xf
+.br
+-25
+.br
+ERROR: unknown handle
+.br
+
+.EE
+
+.br
+
+.IP "\fBNC h\fP - Close notification"
+.IP "" 4
+
+.br
+This command stops notifications on handle \fBh\fP returned by
+a prior call to \fBNO\fP and releases the handle for reuse.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs nc 0 # First call succeeds.
+.br
+
+.br
+$ pigs nc 1 # Second call fails.
+.br
+-25
+.br
+ERROR: unknown handle
+.br
+
+.EE
+
+.br
+
+.IP "\fBNO \fP - Request a notification"
+.IP "" 4
+
+.br
+This command requests a free notification handle.
+
+.br
+A notification is a method for being notified of gpio state changes via a pipe.
+
+.br
+Upon success the command returns a handle greater than or equal to zero.
+On error a negative status code will be returned.
+
+.br
+Notifications for handle x will be available at the pipe named /dev/pigpiox
+(where x is the handle number).
+
+.br
+E.g. if the command returns 15 then the notifications must be read
+from /dev/pigpio15.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs no
+.br
+0
+.br
+
+.EE
+
+.br
+
+.IP "\fBNP h\fP - Pause notification"
+.IP "" 4
+
+.br
+This command pauses notifications on handle \fBh\fP returned by
+a prior call to \fBNO\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+Notifications for the handle are suspended until a new \fBNB\fP command
+is given for the handle.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs np 0
+.br
+
+.EE
+
+.br
+
+.IP "\fBP/PWM u v\fP - Set gpio PWM value"
+.IP "" 4
+
+.br
+This command starts PWM on gpio \fBu\fP with duty cycle \fBv\fP.  The duty cycle
+varies from 0 (off) to range (fully on).  The range defaults to 255.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+This and the servo functionality use the DMA and PWM or PCM peripherals
+to control and schedule the pulse lengths and duty cycles.
+
+.br
+The \fBPRS\fP command may be used to change the default range of 255.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs p 4 64  # Start PWM on gpio 4 with 25% dutycycle
+.br
+$ pigs p 4 128 # 50%
+.br
+$ pigs p 4 192 # 75%
+.br
+$ pigs p 4 255 # 100%
+.br
+
+.EE
+
+.br
+
+.IP "\fBPARSE t\fP - Validate script"
+.IP "" 4
+
+.br
+Validates the text \fBt\fP of a script without storing the script.
+
+.br
+Upon success nothing is returned.  On error a list of detected
+script errors will be given.
+
+.br
+See \fBScripts\fP.
+
+.br
+This command may be used to find script syntax faults.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs parse tag 100 w 22 1 mils 200 w 22 0 mils 800 jmp 100
+.br
+
+.br
+$ pigs parse tag 0 w 22 1 mills 50 w 22 0 dcr p10 jp 99
+.br
+Unknown command: mills
+.br
+Unknown command: 50
+.br
+Bad parameter to dcr
+.br
+Can't resolve tag 99
+.br
+
+.EE
+
+.br
+
+.IP "\fBPFG u\fP - Get gpio PWM frequency"
+.IP "" 4
+
+.br
+This command returns the PWM frequency in Hz used for gpio \fBu\fP.
+
+.br
+Upon success the PWM frequency is returned.  On error a negative
+status code will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs pfg 4
+.br
+800
+.br
+
+.br
+pigs pfg 34
+.br
+ERROR: gpio not 0-31
+.br
+-2
+.br
+
+.EE
+
+.br
+
+.IP "\fBPFS u v\fP - Set gpio PWM frequency"
+.IP "" 4
+This command sets the PWM frequency \fBv\fP to be used for gpio \fBu\fP.
+
+.br
+The numerically closest frequency to \fBv\fP will be selected.
+
+.br
+Upon success the new frequency is returned.  On error a negative status code
+will be returned.
+
+.br
+The selectable frequencies depend upon the sample rate with which the
+pigpiod daemon was started.  The sample rate is one of 1, 2, 4, 5, 8,
+or 10 microseconds (default 5).
+
+.br
+Each gpio can be independently set to one of 18 different PWM frequencies.
+
+.br
+If PWM is currently active on the gpio it will be switched off and then
+back on at the new frequency.
+
+.br
+The frequencies for each sample rate are:
+
+.br
+
+.EX
+        #1    #2    #3   #4   #5   #6   #7   #8   #9
+ 1us 40000 20000 10000 8000 5000 4000 2500 2000 1600
+ 2us 20000 10000  5000 4000 2500 2000 1250 1000  800
+ 4us 10000  5000  2500 2000 1250 1000  625  500  400
+ 5us  8000  4000  2000 1600 1000  800  500  400  320
+ 8us  5000  2500  1250 1000  625  500  313  250  200
+10us  4000  2000  1000  800  500  400  250  200  160
+                                                   
+.br
+       #10   #11   #12  #13  #14  #15  #16  #17  #18
+ 1us  1250  1000   800  500  400  250  200  100   50
+ 2us   625   500   400  250  200  125  100   50   25
+ 4us   313   250   200  125  100   63   50   25   13
+ 5us   250   200   160  100   80   50   40   20   10
+ 8us   156   125   100   63   50   31   25   13    6
+10us   125   100    80   50   40   25   20   10    5
+
+.EE
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+pigs pfs 4 0 # 0 selects the lowest frequency.
+.br
+10
+.br
+
+.br
+$ pigs pfs 4 1000 # Set 1000Hz PWM.
+.br
+1000
+.br
+
+.br
+$ pigs pfs 4 100000 # Very big number selects the highest frequency.
+.br
+8000
+.br
+
+.EE
+
+.br
+
+.IP "\fBPIGPV \fP - Get pigpio library version"
+.IP "" 4
+
+.br
+This command returns the pigpio library version.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs pigpv
+.br
+17
+.br
+
+.EE
+
+.br
+
+.IP "\fBPRG u\fP - Get gpio PWM range"
+.IP "" 4
+
+.br
+This command returns the dutycycle range for gpio \fBu\fP.
+
+.br
+Upon success the range is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs prg 4
+.br
+255
+.br
+
+.EE
+
+.br
+
+.IP "\fBPROC t\fP - Store script"
+.IP "" 4
+
+.br
+This command stores a script \fBt\fP for later execution.
+
+.br
+If the script is valid a script id (>=0) is returned which is passed
+to the other script commands. On error a negative status code
+will be returned.
+
+.br
+See \fBScripts\fP.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs proc tag 123 w 4 0 mils 200 w 4 1 mils 300 dcr p0 jp 123
+.br
+0
+.br
+
+.br
+$ pigs proc tag 123 w 4 0 mils 5 w 4 1 mils 5 jmp 12
+.br
+ERROR: script has unresolved tag
+.br
+-63
+.br
+
+.EE
+
+.br
+
+.IP "\fBPROCD sid\fP - Delete script"
+.IP "" 4
+
+.br
+This command deletes script \fBsid\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+See \fBScripts\fP.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs procd 1
+.br
+
+.br
+$ pigs procd 1
+.br
+ERROR: unknown script id
+.br
+-48
+.br
+
+.EE
+
+.br
+
+.IP "\fBPROCP sid\fP - Get script status and parameters"
+.IP "" 4
+
+.br
+This command returns the status of script \fBsid\fP as well as the
+current value of its 10 parameters.
+
+.br
+Upon success the script status and parameters are  returned.
+On error a negative status code will be returned.
+
+.br
+The script status may be one of
+
+.br
+
+.EX
+0   being initialised
+1   halted
+2   running
+3   waiting
+4   failed
+
+.EE
+
+.br
+See \fBScripts\fP.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs procp 0
+.br
+1 0 0 0 0 0 0 0 0 0 0
+.br
+
+.EE
+
+.br
+
+.IP "\fBPROCR sid pars\fP - Run script"
+.IP "" 4
+
+.br
+This command runs stored script \fBsid\fP passing it up to 10 optional
+parameters.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+See \fBScripts\fP.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs proc tag 123 w 4 0 mils 200 w 4 1 mils 300 dcr p0 jp 123
+.br
+0
+.br
+
+.br
+$ pigs procr 0 50 # Run script 0 with parameter 0 of 50.
+.br
+
+.br
+$ pigs procp 0
+.br
+2 44 0 0 0 0 0 0 0 0 0
+.br
+$ pigs procp 0
+.br
+2 37 0 0 0 0 0 0 0 0 0
+.br
+$ pigs procp 0
+.br
+2 10 0 0 0 0 0 0 0 0 0
+.br
+$ pigs procp 0
+.br
+2 5 0 0 0 0 0 0 0 0 0
+.br
+$ pigs procp 0
+.br
+2 2 0 0 0 0 0 0 0 0 0
+.br
+$ pigs procp 0
+.br
+1 -1 0 0 0 0 0 0 0 0 0
+.br
+
+.EE
+
+.br
+
+.IP "\fBPROCS sid\fP - Stop script"
+.IP "" 4
+
+.br
+This command stops a running script \fBsid\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+See \fBScripts\fP.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs procs 0
+.br
+
+.br
+$ pigs procs 1
+.br
+-48
+.br
+ERROR: unknown script id
+.br
+
+.EE
+
+.br
+
+.IP "\fBPRRG u\fP - Get gpio PWM real range"
+.IP "" 4
+
+.br
+This command returns the real underlying range used by gpio \fBu\fP.
+
+.br
+Upon success the real range is returned.  On error a negative status code
+will be returned.
+
+.br
+See \fBPRS\fP.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs prrg 17
+.br
+250
+.br
+
+.br
+$ pigs pfs 17 0
+.br
+10
+.br
+$ pigs prrg 17
+.br
+20000
+.br
+
+.br
+$ pigs pfs 17 100000
+.br
+8000
+.br
+$ pigs prrg 17
+.br
+25
+.br
+
+.EE
+
+.br
+
+.IP "\fBPRS u v\fP - Set gpio PWM range"
+.IP "" 4
+
+.br
+This command sets the dutycycle range \fBv\fP to be used for gpio \fBu\fP.
+Subsequent uses of command \fBP/PWM\fP will use a dutycycle between 0 (off)
+and \fBv\fP (fully on).
+
+.br
+Upon success the real underlying range used by the gpio is returned.
+On error a negative status code will be returned.
+
+.br
+If PWM is currently active on the gpio its dutycycle will be scaled to
+reflect the new range.
+
+.br
+The real range, the number of steps between fully off and fully on
+for each frequency, is given in the following table.
+
+.br
+
+.EX
+ #1   #2   #3   #4   #5   #6   #7    #8    #9
+ 25   50  100  125  200  250  400   500   625
+                                        
+#10  #11  #12  #13  #14  #15  #16   #17   #18
+800 1000 1250 2000 2500 4000 5000 10000 20000
+
+.EE
+
+.br
+The real value set by \fBPRS\fP is (dutycycle * real range) / range.
+
+.br
+See \fBPRRG\fP
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs prs 18 1000
+.br
+250
+.br
+
+.EE
+
+.br
+
+.IP "\fBPUD g p\fP - Set gpio pull up/down"
+.IP "" 4
+
+.br
+This command sets the internal pull/up down for gpio \fBg\fP to mode \fBp\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+The mode may be pull-down (D), pull-up (U), or off (O).
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs pud 4 d # Set pull-down on gpio 4.
+.br
+$ pigs pud 4 u # Set pull-up on gpio 4.
+.br
+$ pigs pud 4 o # No pull-up/down on gpio 4.
+.br
+
+.EE
+
+.br
+
+.IP "\fBR/READ g\fP - Read gpio level"
+.IP "" 4
+
+.br
+This reads the current level of gpio \fBg\fP.
+
+.br
+Upon success the current level is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs r 17 # Get level of gpio 17.
+.br
+0
+.br
+
+.br
+$ pigs r 4 # Get level of gpio 4.
+.br
+1
+.br
+
+.EE
+
+.br
+
+.IP "\fBS/SERVO u v\fP - Set gpio servo pulsewidth"
+.IP "" 4
+
+.br
+This command starts servo pulses of \fBv\fP microseconds on gpio \fBu\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+The servo pulse width may be 0 (off), 500 (most anti-clockwise)
+to 2500 (most clockwise).
+
+.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
+You can DAMAGE a servo if you command it to move beyond its limits.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs SERVO 17 1500
+.br
+
+.EE
+
+.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
+This will command a servo connected to gpio 17 to rotate to its mid-point.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+pigs s 17 0 # Switch servo pulses off.
+.br
+
+.EE
+
+.br
+
+.IP "\fBSERC h\fP - Close serial handle"
+.IP "" 4
+
+.br
+This command closes a serial handle \fBh\fP previously opened with \fBSERO\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs serc 0 # First close okay.
+.br
+
+.br
+$ pigs serc 0 # Second close gives error.
+.br
+-25
+.br
+ERROR: unknown handle
+.br
+
+.EE
+
+.br
+
+.IP "\fBSERDA h\fP - Check for serial data ready to read"
+.IP "" 4
+
+.br
+This command returns the number of bytes of data available
+to be read from the serial device associated with handle \fBh\fP.
+
+.br
+Upon success the count of bytes available to be read is
+returned (which may be 0).  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs serda 0
+.br
+0
+.br
+
+.EE
+
+.br
+
+.IP "\fBSERO dev b sef\fP - Open serial device dev at baud with flags"
+.IP "" 4
+
+.br
+This command opens the serial \fBdev\fP at \fBb\fP bits per second.
+
+.br
+No flags are currently defined.  \fBsef\fP should be set to zero.
+
+.br
+Upon success a handle (>=0) is returned.  On error a negative status code
+will be returned.
+
+.br
+The UART is /dev/ttyAMA0.  The consoles are /dev/ttyx.  The USB
+devices are /dev/ttyUSBx.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs sero /dev/ttyAMA0 9600 0
+.br
+0
+.br
+
+.br
+$ pigs sero /dev/tty1 38400 0
+.br
+1
+.br
+
+.EE
+
+.br
+
+.IP "\fBSERR h num\fP - Read bytes from serial handle"
+.IP "" 4
+
+.br
+This command returns up to \fBnum\fP bytes of data read from the
+serial device associated with handle \fBh\fP.
+
+.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
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs serr 0 10
+.br
+5 48 49 128 144 255
+.br
+
+.br
+$ pigs serr 0 10
+.br
+0
+.br
+
+.EE
+
+.br
+
+.IP "\fBSERRB \fP - Read byte from serial handle"
+.IP "" 4
+
+.br
+This command returns a byte of data read from the serial
+device associated with handle \fBh\fP.
+
+.br
+Upon success a number between 0 and 255 is returned.
+On error a negative status code will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs serrb 0
+.br
+23
+.br
+$ pigs serrb 0
+.br
+45
+.br
+
+.EE
+
+.br
+
+.IP "\fBSERW h bvs\fP - Write bytes to serial handle"
+.IP "" 4
+
+.br
+This command writes bytes \fBbvs\fP to the serial device
+associated with handle \fBh\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs serw 0 23 45 67 89
+.br
+
+.EE
+
+.br
+
+.IP "\fBSERWB h bv\fP - Write byte to serial handle"
+.IP "" 4
+
+.br
+This command writes a single byte \fBbv\fP to the serial device
+associated with handle \fBh\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs serwb 0 23
+.br
+$ pigs serwb 0 0xf0
+.br
+
+.EE
+
+.br
+
+.IP "\fBSLR u num\fP - Read bit bang serial data from gpio"
+.IP "" 4
+
+.br
+This command returns up to \fBnum\fP bytes of bit bang serial data
+read from gpio \fBu\fP.
+
+.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
+The gpio \fBu\fP should have been initialised with the \fBSLRO\fP command.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs slr 15 20
+.br
+6 1 0 23 45 89 0
+.br
+
+.EE
+
+.br
+
+.IP "\fBSLRC u\fP - Close gpio for bit bang serial data"
+.IP "" 4
+
+.br
+This command closes gpio \fBu\fP for reading bit bang serial data.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs slrc 23
+.br
+
+.br
+$ pigs slrc 23
+.br
+-38
+.br
+ERROR: no serial read in progress on gpio
+.br
+
+.EE
+
+.br
+
+.IP "\fBSLRO u b\fP - Open gpio for bit bang serial data"
+.IP "" 4
+
+.br
+This command opens gpio \fBu\fP for reading bit bang serial data
+at \fBb\fP baud.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+The received data is held in a cyclic buffer.
+
+.br
+It is the user's responsibility to read the data (with \fBSLR\fP)
+in a timely fashion.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs slro 23 19200
+.br
+
+.br
+$ pigs slro 23 19200
+.br
+-50
+.br
+ERROR: gpio already in use
+.br
+
+.EE
+
+.br
+
+.IP "\fBSPIC h\fP - SPI close handle"
+.IP "" 4
+
+.br
+This command closes the SPI handle \fBh\fP returned by a prior
+call to \fBSPIO\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+.IP "\fBSPIO c b spf\fP - SPI open channel at baud with flags"
+.IP "" 4
+
+.br
+This command returns a handle to a SPI device on channel \fBc\fP. 
+.br
+
+.br
+Data will be transferred at \fBb\fP bits per second.  The least
+significant two bits of the flags \fBspf\fP determine the SPI mode.  All
+other bits in \fBspf\fP should be set to zero.
+
+.br
+
+.EX
+Flags   Mode
+0       0
+1       1
+2       2
+3       3
+
+.EE
+
+.br
+Upon success a handle (>=0) is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs spio 0 100000 3 # Open channel 0 at 100kbps in mode 3.
+.br
+0
+.br
+
+.EE
+
+.br
+
+.IP "\fBSPIR h num\fP - SPI read bytes from handle"
+.IP "" 4
+
+.br
+This command returns \fBnum\fP bytes read from the SPI device
+associated with handle \fBh\fP.
+
+.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
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs spir 0 10 # Read 10 bytes from the SPI device.
+.br
+10 0 0 0 0 0 0 0 0 0 0
+.br
+
+.EE
+
+.br
+
+.IP "\fBSPIW h bvs\fP - SPI write bytes to handle"
+.IP "" 4
+
+.br
+This command writes bytes \fBbvs\fP to the SPI device
+associated with handle \fBh\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs spiw 0 0x22 0x33 0xcc 0xff
+.br
+
+.EE
+
+.br
+
+.IP "\fBSPIX h bvs\fP - SPI transfer bytes to handle"
+.IP "" 4
+
+.br
+This command writes bytes \fBbvs\fP to the SPI device
+associated with handle \fBh\fP.  It returns the same
+number of bytes read from the device.
+
+.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
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs spix 0 0x22 0x33 0xcc 0xff
+.br
+4 0 0 0 0
+.br
+
+.EE
+
+.br
+
+.IP "\fBT/TICK \fP - Get current tick"
+.IP "" 4
+
+.br
+This command returns the current system tick.
+
+.br
+Tick is the number of microseconds since system boot.
+
+.br
+As tick is an unsigned 32 bit quantity it wraps around after 2^32 microseconds,
+which is approximately 1 hour 12 minutes.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs t mils 1000 t
+.br
+3691823946
+.br
+3692833987
+.br
+
+.EE
+
+.br
+
+.IP "\fBTRIG u pl L\fP - Send a trigger pulse"
+.IP "" 4
+
+.br
+This command sends a trigger pulse of \fBpl\fP microseconds at level \fBL\fP
+to gpio \fBu\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+The gpio is set to not level at the end of the pulse.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs trig 4 10 1
+.br
+
+.br
+$ pigs trig 4 51 1
+.br
+-46
+.br
+ERROR: trigger pulse > 50 microseconds
+.br
+
+.EE
+
+.br
+
+.IP "\fBW/WRITE g L\fP - Write gpio level"
+.IP "" 4
+
+.br
+This command sets gpio \fBg\fP to level \fBL\fP.  The level may be 0
+(low, off, clear) or 1 (high, on, set).
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs w 23 0
+.br
+$ pigs w 23 1
+.br
+
+.br
+$ pigs w 23 2
+.br
+-5
+.br
+ERROR: level not 0-1
+.br
+
+.EE
+
+.br
+
+.IP "\fBWDOG u v\fP - Set gpio watchdog"
+.IP "" 4
+
+.br
+This command sets a watchdog of \fBv\fP milliseconds on gpio \fBu\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+The watchdog is nominally in milliseconds.
+
+.br
+One watchdog may be registered per gpio.
+
+.br
+The watchdog may be cancelled by setting timeout to 0.
+
+.br
+If no level change has been detected for the gpio for timeout milliseconds:-
+
+.br
+any notification for the gpio has a report written to the fifo with
+the flags set to indicate a watchdog timeout.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wdog 23 90000
+.br
+-15
+.br
+ERROR: timeout not 0-60000
+.br
+
+.br
+$ pigs wdog 23 9000
+.br
+
+.EE
+
+.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.
+
+.br
+
+.IP "\fBWVAG trips\fP - Add generic pulses to waveform"
+.IP "" 4
+
+.br
+This command adds 1 one or more triplets \fBtrips\fP of gpios on, gpios off,
+delay to the existing waveform (if any).
+
+.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
+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
+consist solely of a delay i.e. 0 0 offset.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvag 0x10 0x80 1000 0x80 0x10 9000
+.br
+2
+.br
+
+.br
+$ pigs wvag 0 0 10000 0x10 0x80 1000 0x80 0x10 9000
+.br
+4
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVAS u b o bvs\fP - Add serial data to waveform"
+.IP "" 4
+
+.br
+This command adds a waveform representing serial data \fBbvs\fP to
+gpio \fBu\fP at \fBb\fP baud to the existing waveform (if any).
+The serial data starts \fBo\fP microseconds from the start of the waveform.
+
+.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
+Data with different baud rates may be added to the same wavefrom.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvas 4 9600 0 0x30 0x31 0x32 0x33
+.br
+23
+.br
+
+.br
+$ pigs wvas 7 38400 0 0x41 0x42
+.br
+35
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVBSY \fP - Check if waveform is being transmitted"
+.IP "" 4
+
+.br
+This command checks to see if a waveform is currently being transmitted.
+
+.br
+Returns 1 if a waveform is currently being transmitted, otherwise 0.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvbsy
+.br
+0
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVCLR \fP - Clear all waveforms"
+.IP "" 4
+
+.br
+This command clears all waveforms.
+
+.br
+Nothing is returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvclr
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVCRE \fP - Create a waveform"
+.IP "" 4
+
+.br
+This command creates a waveform from the data provided by the prior
+calls to the \fBWVAG\fP and \fBWVAS\fP commands.
+
+.br
+Upon success a wave id (>=0) is returned.  On error a negative status
+code will be returned.
+
+.br
+The data provided by the \fBWVAG\fP and \fBWVAS\fP commands is
+consumed by this command.
+
+.br
+As many waveforms may be created as there is space available.
+The wave id is passed to \fBWVTX\fP or \fBWVTXR\fP to specify the
+waveform to transmit.
+
+.br
+Normal usage would be
+
+.br
+Step 1. \fBWVCLR\fP to clear all waveforms and added data.
+
+.br
+Step 2. \fBWVAG\fP/\fBWVAS\fP calls to supply the waveform data.
+
+.br
+Step 3. \fBWVCRE\fP to create the waveform and get a unique id.
+
+.br
+Repeat steps 2 and 3 as needed.
+
+.br
+Step 4. \fBWVTX\fP or \fBWVTXR\fP with the id of the waveform to transmit.
+
+.br
+A waveform comprises of one or more pulses.
+
+.br
+A pulse specifies
+
+.br
+1) the gpios to be switched on at the start of the pulse.
+.br
+2) the gpios to be switched off at the start of the pulse.
+.br
+3) the delay in microseconds before the next pulse.
+
+.br
+Any or all the fields can be zero.  It doesn't make any sense to
+set all the fields to zero (the pulse will be ignored).
+
+.br
+When a waveform is started each pulse is executed in order with
+the specified delay between the pulse and the next.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvas 4 9600 0 23 45 67 89 90
+.br
+37
+.br
+$ pigs wvcre
+.br
+0
+.br
+
+.br
+$ pigs wvcre
+.br
+-69
+.br
+ERROR: attempt to create an empty waveform
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVDEL wid\fP - Delete selected waveforms"
+.IP "" 4
+
+.br
+This command deletes all waveforms with ids greater than or equal to \fBwid\fP.
+
+.br
+Upon success nothing is returned.  On error a negative status code
+will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvdel 0
+.br
+
+.br
+$ pigs wvdel 0
+.br
+-66
+.br
+ERROR: non existent wave id
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVGO \fP - Transmit waveform once (DEPRECATED)"
+.IP "" 4
+
+.br
+This command transmits the current waveform.  The waveform is sent once.
+
+.br
+Upon success the number of DMA control blocks in the waveform is returned.
+On error a negative status code will be returned.
+
+.br
+
+.IP "\fBWVGOR \fP - Transmit waveform repeatedly (DEPRECATED)"
+.IP "" 4
+
+.br
+This command transmits the current waveform.  The waveform is sent repeatedly.
+
+.br
+Upon success the number of DMA control blocks in the waveform is returned.
+On error a negative status code will be returned.
+
+.br
+
+.IP "\fBWVHLT \fP - Stop waveform"
+.IP "" 4
+
+.br
+This command aborts the transmission of the current waveform.
+
+.br
+Nothing is returned.
+
+.br
+This command is intended to stop a waveform started in the repeat mode.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvhlt
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVNEW \fP - Initialise a new waveform"
+.IP "" 4
+
+.br
+This clears any existing waveform data ready for the creation of a new
+waveform.
+
+.br
+Nothing is returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvnew
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVSC ws\fP - Get waveform DMA CB stats"
+.IP "" 4
+
+.br
+The statistic requested by \fBws\fP is returned.
+
+.br
+\fBws\fP identifies the subcommand as follows.
+
+.br
+0 Get Cbs
+.br
+1 Get High Cbs
+.br
+2 Get Max Cbs
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvas 4 9600 0 23 45 67 89 90
+.br
+37
+.br
+
+.br
+$ pigs wvsc 0
+.br
+74
+.br
+$ pigs wvsc 1
+.br
+74
+.br
+$ pigs wvsc 2
+.br
+25016
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVSM ws\fP - Get waveform time stats"
+.IP "" 4
+
+.br
+The statistic requested by \fBws\fP is returned.
+
+.br
+\fBws\fP identifies the subcommand as follows.
+
+.br
+0 Get Micros
+.br
+1 Get High Micros
+.br
+2 Get Max Micros
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvsm 0
+.br
+5314
+.br
+$ pigs wvsm 1
+.br
+5314
+.br
+$ pigs wvsm 2
+.br
+1800000000
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVSP ws\fP - Get waveform pulse stats"
+.IP "" 4
+
+.br
+The statistic requested by \fBws\fP is returned.
+
+.br
+\fBws\fP identifies the subcommand as follows.
+
+.br
+0 Get Pulses
+.br
+1 Get High Pulses
+.br
+2 Get Max Pulses
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvsp 0
+.br
+37
+.br
+$ pigs wvsp 1
+.br
+37
+.br
+$ pigs wvsp 2
+.br
+12000
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVTX wid\fP - Transmit waveform once"
+.IP "" 4
+
+.br
+This command transmits the waveform with id \fBwid\fP once.
+
+.br
+Upon success the number of DMA control blocks in the waveform is returned.
+On error a negative status code will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvtx 1
+.br
+75
+.br
+
+.br
+$ pigs wvtx 2
+.br
+-66
+.br
+ERROR: non existent wave id
+.br
+
+.EE
+
+.br
+
+.IP "\fBWVTXR wid\fP - Transmit waveform repeatedly"
+.IP "" 4
+
+.br
+This command transmits the waveform with id \fBwid\fP repeatedly.
+
+.br
+Upon success the number of DMA control blocks in the waveform is returned.
+On error a negative status code will be returned.
+
+.br
+
+\fBExample\fP
+.br
+
+.EX
+$ pigs wvtxr 1
+.br
+75
+.br
+
+.br
+$ pigs wvtxr 2
+.br
+-66
+.br
+ERROR: non existent wave id
+.br
+
+.EE
+
+.br
+
+.SH PARAMETERS
+
+.br
+
+.IP "\fBb\fP - baud (100-250000)" 0
+The command expects a baud rate for serial data.
+
+.br
+
+.IP "\fBbit\fP - bit value (0-1)" 0
+The command expects 0 or 1.
+
+.br
+
+.IP "\fBbits\fP - a bit mask" 0
+A mask is used to select one or more gpios.  A gpio is selected
+if bit (1<<gpio) is set in the mask.
+
+.br
+E.g. a mask of 6 (binary 110) select gpios 1 and 2, a mask of
+0x103 (binary 100000011) selects gpios 0, 1, and 8.
+
+.br
+
+.IP "\fBbv\fP - a byte value (0-255)" 0
+The command expects a byte value.
+
+.br
+
+.IP "\fBbvs\fP - byte values (0-255)" 0
+The command expects one or more byte values.
+
+.br
+
+.IP "\fBc\fP - SPI channel (0-1)" 0
+The command expects a SPI channel.
+
+.br
+
+.IP "\fBdev\fP - a tty serial device (/dev/tty*)" 0
+The command expects the name of a tty serial device, e.g.
+
+.br
+
+.EX
+/dev/ttyAMA0
+.br
+/dev/ttyUSB0
+.br
+/dev/tty0
+.br
+
+.EE
+
+.br
+
+.IP "\fBg\fP - gpio (0-53)" 0
+The command expects a gpio.
+
+.br
+There are 54 General Purpose Input Outputs (gpios) named gpio0 through gpio53.
+
+.br
+They are split into two banks.  Bank 1 consists of gpio0 through gpio31.
+Bank 2 consists of gpio32 through gpio53.
+
+.br
+All the gpios which are safe for the user to read and write are in bank 1.
+Not all gpios in bank 1 are safe though. Rev.1 boards have 17 safe gpios.
+Rev.2 boards have 21. Rev.3 boards have 26.
+
+.br
+The user gpios are marked with an X in the following table.
+
+.br
+
+.EX
+         0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15
+Rev.1    X  X  -  -  X  -  -  X  X  X  X  X  -  -  X  X
+Rev.2    -  -  X  X  X  -  -  X  X  X  X  X  -  -  X  X
+Rev.3          X  X  X  X  X  X  X  X  X  X  X  X  X  X
+                                                     
+        16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+Rev.1    -  X  X  -  -  X  X  X  X  X  -  -  -  -  -  -
+Rev.2    -  X  X  -  -  -  X  X  X  X  -  X  X  X  X  X
+Rev.3    X  X  X  X  X  X  X  X  X  X  X  X  -  -  -  -
+
+.EE
+
+.br
+You are not prevented from writing to unsafe gpios.  The consequences
+of doing so range from no effect, to a crash, or corrupted data.
+
+.br
+
+.IP "\fBh\fP - handle (>=0)" 0
+The command expects a handle.
+
+.br
+A handle is a number referencing an object opened by one of \fBI2CO\fP, \fBNO\fP,
+\fBSERO\fP, \fBSPIO\fP.
+
+.br
+
+.IP "\fBib\fP - I2C bus (0-1)" 0
+The command expects an I2C bus.
+
+.br
+
+.IP "\fBid\fP - I2C device (0x08-0x77)" 0
+The command expects the address of an I2C device.
+
+.br
+
+.IP "\fBif\fP - I2C flags (0)" 0
+The command expects an I2C flags value.  No flags are currently defined.
+
+.br
+
+.IP "\fBL\fP - level (0-1)" 0
+The command expects a gpio level.
+
+.br
+
+.IP "\fBm\fP - mode (RW540123)" 0
+The command expects a mode character.
+
+.br
+Each gpio can be configured to be in one of 8 different modes. The modes
+are named Input, Output, ALT0, ALT1, ALT2, ALT3, ALT4, and ALT5.
+
+.br
+To set the mode use the code for the mode.
+
+.br
+The value is returned by the mode get command.
+
+.br
+
+.EX
+Mode   Input Output ALT0 ALT1 ALT2 ALT3 ALT4 ALT5
+Code       R      W    0    1    2    3    4    5
+Value      0      1    4    5    6    7    3    2
+
+.EE
+
+.br
+
+.IP "\fBnum\fP - number of bytes to read (1-)" 0
+The command expects the number of bytes to read.
+
+.br
+For the I2C and SPI commands the requested number of bytes will always
+be returned.
+
+.br
+For the serial commands the smaller of the number of bytes available to be
+read (which may be zero) and \fBnum\fP bytes will be returned.
+
+.br
+
+.IP "\fBo\fP - offset (>=0)" 0
+Serial data is stored offset microseconds from the start of the waveform.
+
+.br
+
+.IP "\fBp\fP - PUD (ODU)" 0
+The command expects a PUD character.
+
+.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
+A pull up will default the input to 1 (high).
+
+.br
+A pull down will default the input to 0 (low).
+
+.br
+To set the pull up down state use the command character for the state.
+
+.br
+
+.EX
+Pull Up Down      Off Pull Down Pull Up
+Command Character   O         D       U
+
+.EE
+
+.br
+There is no mechanism to read the pull up down state.
+
+.br
+
+.IP "\fBpars\fP - script parameters" 0
+The command expects 0 to 10 numbers as parameters to be passed to the script.
+
+.br
+
+.IP "\fBpl\fP - pulse length (1-50)" 0
+The command expects a pulse length in microseconds.
+
+.br
+
+.IP "\fBr\fP - register (0-255)" 0
+The command expects an I2C register number.
+
+.br
+
+.IP "\fBsef\fP - serial flags (32 bits)" 0
+The command expects a flag value.  No serial flags are currently defined.
+
+.br
+
+.IP "\fBsid\fP - script id (>= 0)" 0
+The command expects a script id as returned by a call to \fBPROC\fP.
+
+.br
+
+.IP "\fBspf\fP - SPI flags (32 bits)" 0
+The command expects a flag value.  The least significant two bits
+define the SPI mode.
+
+.br
+
+.IP "\fBt\fP - text (a string of text)" 0
+The command expects a text string.
+
+.br
+
+.IP "\fBtrips\fP - triplets" 0
+The command expects 1 or more triplets of gpios on, gpios off, delay.
+
+.br
+E.g. 0x400000 0 100000 0 0x400000 900000 defines two pulses as follows
+
+.br
+
+.EX
+     gpios on          gpios off          delay
+0x400000 (gpio 22)           0 (None) 100000 (1/10th s)
+          0 (None) 0x400000 (gpio 22) 900000 (9/10th s)
+
+.EE
+
+.br
+
+.IP "\fBu\fP - user gpio (0-31)" 0
+The command expects the number of a user gpio.
+
+.br
+A number of commands are restricted to gpios in bank 1,
+in particular the PWM commands, the servo command,
+the watchdog command, and the notification command.
+
+.br
+It is your responsibility to ensure that the PWM and servo commands
+are only used on safe gpios.
+
+.br
+See \fBg\fP
+
+.br
+
+.IP "\fBv\fP - value" 0
+The command expects a number.
+
+.br
+
+.IP "\fBwid\fP - wave id (>=0)" 0
+The command expects a wave id.
+
+.br
+When a waveform is created it is given an id (0, 1, 2, ...).
+
+.br
+
+.IP "\fBws\fP - wave stats sucommand (0-2)" 0
+The command expects a subcommand.
+
+.br
+0 = current value.
+.br
+1 = highest value so far.
+.br
+2 = maximum possible value.
+
+.br
+
+.IP "\fBwv\fP - word value (0-65535)" 0
+The command expects a word value.
+
+.br
+
+.SH SCRIPTS
+
+.br
+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.
+
+.br
+.SS Example
+.br
+A trivial example might be useful.  Suppose you want to toggle a gpio
+on and off as fast as possible.
+
+.br
+From the command line you could write
+
+.br
+
+.EX
+for ((i=0; i<1000;i++)); do pigs w 22 1 w 22 0; done
+.br
+
+.EE
+
+.br
+Timing that you will see it takes about 14 seconds, or roughly
+70 toggles per second.
+
+.br
+Using the pigpio Python module you could use code such as
+
+.br
+
+.EX
+#!/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
+
+.EE
+
+.br
+Timing that shows a speed improvement to roughly 800 toggles per second.
+
+.br
+Now let's use a script.
+
+.br
+
+.EX
+pigs proc tag 999 w 22 1 w 22 0 dcr p0 jp 999
+.br
+
+.EE
+
+.br
+Ignore the details for now.
+
+.br
+Let's time the script running.
+
+.br
+Again, ignore the details for now.
+
+.br
+
+.EX
+time (pigs procr 0 10000000; while a=$(pigs procp 0); [[ ${a::1} -eq 2 ]];\
+.br
+ do sleep 0.2; done)
+.br
+
+.EE
+
+.br
+The script takes roughly 12 seconds to complete, or 800,000 toggles per second.
+
+.br
+That is the advantage of a stored script.
+
+.br
+Some details.
+
+.br
+
+.EX
+pigs proc tag 999 w 22 1 w 22 0 dcr p0 jp 999
+.br
+
+.EE
+
+.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
+
+.EX
+time (pigs procr 0 10000000; while a=$(pigs procp 0); [[ ${a::1} -eq 2 ]];\
+.br
+ do sleep 0.2; done)
+.br
+
+.EE
+
+.br
+pigs procr 0 10000000 starts script 0 with parameter 0 of 10 million.
+
+.br
+The rest is bash apart from
+
+.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.
+
+.br
+.SS Virtual machine
+.br
+A script runs within a virtual machine with
+
+.br
+a 32 bit accumulator A.
+.br
+a flags register F.
+.br
+a program counter PC.
+
+.br
+Each script has
+
+.br
+10 parameters named 0 through 9.
+.br
+150 variables named 0 through 149.
+.br
+50 labels which are named by any unique number.
+
+.br
+.SS Commands
+.br
+All the normal pigs commands may be used within a script.
+
+.br
+The following commands are only legal within a script.
+
+.br
+
+.EX
+Command Description                                   Definition
+ADD x   Add x to accumulator                          A+=x; F=A
+AND x   And x with accumulator                        A&=x; F=A
+CALL L  Call subroutine at tag L                      push(PC+1); PC=L
+CMP x   Compare x with accumulator                    F=A-x
+DCR y   Decrement register                            --*y; F=*y
+DCRA    Decrement accumulator                         --A; F=A
+DIV x   Divide x into accumulator                     A/=x; F=A
+HALT    Halt                                          Halt
+INR y   Increment register                            ++*y; F=*y
+INRA    Increment accumulator                         ++A; F=A
+JM L    Jump if minus to tag L                        if (F<0) PC=L
+JMP L   Jump to tag L                                 PC=L
+JNZ L   Jump if non-zero to tag L                     if (F) PC=L
+JP L    Jump if positive to tag L                     if (F>=0) PC=L
+JZ L    Jump if zero to tag L                         if (!F) PC=L
+LD y x  Load register with x                          *y=x
+LDA x   Load accumulator with x                       A=x
+MLT x   Multiply x with accumulator                   A*=x; F=A
+MOD x   Modulus x with accumulator                    A%=x; F=A
+OR x    Or x with accumulator                         A|=x; F=A
+POP y   Pop register                                  y=pop()
+POPA    Pop accumulator                               A=pop()
+PUSH y  Push register                                 push(y)
+PUSHA   Push accumulator                              push(A)
+RET     Return from subroutine                        PC=pop()
+RL y x  Rotate left register x bits                   *y<<=x; F=*y
+RLA x   Rotate left accumulator x bits                A<<=x; F=A
+RR y x  Rotate right register x bits                  *y>>=x; F=*y
+RRA x   Rotate right accumulator x bits               A>>=x; F=A
+STA y   Store accumulator in register                 y=A
+SUB x   Subtract x from accumulator                   A-=x; F=A
+SYS str Run external script (/opt/pigpio/cgi/str)     system(str); F=A
+TAG L   Label the current script position             N/A
+WAIT x  Wait for a gpio in x to change state          A=wait(x); F=A
+X y1 y2 Exchange contents of registers y1 and y2      t=*y1;*y1=*y2;*y2=t
+XA y    Exchange contents of accumulator and register t=A;A=*y;*y=t
+XOR x   Xor x with accumulator                        A^=x; F=A
+
+.EE
+
+.br
+x may be a constant, a parameter (p0-p9), or a variable (v0-v149).
+
+.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
+The WAIT command parameter is a bit-mask with 1 set for gpios of interest.
+
+.br
+
+.SH SEE ALSO
+
+pigpiod(1), pig2vcd(1), pigpio(3), pigpiod_if(3)
+.SH AUTHOR
+
+joan@abyz.co.uk