pigpio library
pigpio pigpio C I/F pigpiod pigpiod C I/F Python pigs piscope Misc Examples Download FAQ Site Map

Socket Interface

pigpio provides a socket interface to many of its functions.

The socket interface is available whenever pigpio is running, either because it has been started as a daemon, or it has been linked in to a running user program.

The socket interface can be disabled by the program which initialises the library.  pigpiod offers the -k option to disable the socket interface.  User programs should call gpioCfgInterfaces if they wish to disable the socket interface.

pigpio listens for connections on port 8888 by default.  This default may be overridden when pigpio starts by the gpioCfgSocketPort function call.  The pigpio daemon uses this function to provide an option to change the port number.

The pigs utility is an example of using the socket interface from C.

Request

pigpio expects messages of type cmdCmd_t immediately followed with an extension for a few commands.

The caller should fill in cmd, p1, p2, p3/res, and any extension as needed.  p3 will always be zero unless the command requires an extension in which case p3 will be the length in bytes of the extension.

The cmdCmd_t is echoed back with the result, if any, in p3/res, and an extension immediately afterwards for a few commands.

COMMAND cmd
p1 p2 p3 Extension
MODES 0 gpio mode 0 -
MODEG 1 gpio 0 0 -
PUD 2 gpio pud 0 -
READ 3 gpio 0 0 -
WRITE 4 gpio level 0 -
PWM 5 gpio dutycycle 0 -
PRS 6 gpio range 0 -
PFS 7 gpio frequency 0 -
SERVO 8 gpio pulsewidth 0 -
WDOG 9 gpio timeout 0 -
BR1 10 0 0 0 -
BR2 11 0 0 0 -
BC1 12 bits 0 0 -
BC2 13 bits 0 0 -
BS1 14 bits 0 0 -
BS2 15 bits 0 0 -
TICK 16 0 0 0 -
HWVER 17 0 0 0 -
NO 18 0 0 0 -
NB 19 handle bits 0 -
NP 20 handle 0 0 -
NC 21 handle 0 0 -
PRG 22 gpio 0 0 -
PFG 23 gpio 0 0 -
PRRG 24 gpio 0 0 -
HELP
25 N/A
N/A
N/A
N/A
PIGPV 26 0 0 0 -
WVCLR 27 0 0 0 -
WVAG 28 0 0 12*X gpioPulse_t pulse[X]
WVAS 29 gpio baud 12+X uint32_t databits
uint32_t stophalfbits
uint32_t offset
uint8_t data[X]
N/A
30 0 0 0 -
N/A
31 0 0 0 -
WVBSY 32 0 0 0 -
WVHLT 33 0 0 0 -
WVSM 34 subcmd 0 0 -
WVSP 35 subcmd 0 0 -
WVSC 36 subcmd 0 0 -
TRIG 37 gpio pulselen 4 uint32_t level
PROC 38 0 0 X uint8_t text[X]
PROCD 39 script_id 0 0 -
PROCR 40 script_id 0 4*X
uint32_t pars[X]
PROCS 41 script_id 0 0 -
SLRO 42 gpio baud 4 uint32_t databits
SLR 43 gpio count 0 -
SLRC 44 gpio 0 0 -
PROCP 45 script_id 0 0 -
MICS 46 micros 0 0 -
MILS 47 millis 0 0 -
PARSE 48 N/A N/A
N/A
N/A
WVCRE 49 0 0 0 -
WVDEL 50 wave_id 0 0 -
WVTX 51 wave_id 0 0 -
WVTXR 52 wave_id 0 0 -
WVNEW 53 0 0 0 -
I2CO 54 bus device 4 uint32_t flags
I2CC 55 handle 0 0 -
I2CRD 56 handle count 0 -
I2CWD 57 handle 0 X uint8_t data[X]
I2CWQ 58 handle bit 0 -
I2CRS 59 handle 0 0 -
I2CWS 60 handle byte 0 -
I2CRB 61 handle register 0 -
I2CWB 62 handle register 4 uint32_t byte
I2CRW 63 handle register 0 -
I2CWW 64 handle register 4 uint32_t word
I2CRK 65 handle register
0 -
I2CWK 66 handle register
X uint8_t bvs[X]
I2CRI 67 handle register
4 uint32_t num
I2CWI 68 handle register
X
uint8_t bvs[X]
I2CPC 69 handle register
4 uint32_t word
I2CPK 70 handle register
X
uint8_t data[X]
SPIO
71 channel baud 4 uint32_t flags
SPIC 72 handle 0 0 -
SPIR 73 handle count 0 -
SPIW 74 handle 0 X uint8_t data[X]
SPIX 75 handle 0 X uint8_t data[X]
SERO 76 baud flags X uint8_t device[X]
SERC 77 handle 0 0 -
SERRB 78 handle 0 0 -
SERWB 79 handle byte 0 -
SERR 80 handle count 0 -
SERW 81 handle 0 X uint8_t data[X]
SERDA 82 handle 0 0 -
GDC
83
gpio
0
0
-
GPW
84
gpio
0
0
-
HC
85
gpio
frequency
0
-
HP
86
gpio
frequency
4
uint32_t dutycycle
CF1
87
arg1
arg2
X
uint8_t argx[X]
CF2
88
arg1
retMax
X
uint8_t argx[X]
BI2CC
89
sda
0
0
-
BI2CO
90
sda
scl
4
uint32_t baud
BI2CZ
91
sda
0
X
uint8_t data[X]
I2CZ
92
handle
0
X
uint8_t data[X]
WVCHA
93
0
0
X
uint8_t data[X]
SLRI
94
gpio
invert
0
-
CGI
95
0
0
0
-
CSI
96
config
0
0
-
FG
97
gpio
steady
0
-
FN
98
gpio
steady
4
uint32_t active
NOIB 99 0 0 0 -
WVTXM
100
wave_id
mode
0
-
WVTAT
101
0
0
0
-
PADS
102
pad
strength
0
-
PADG
103
pad
0
0
-
FO
104
mode
0
X
uint8_t file[X]
FC
105
handle
0
0
-
FR
106
handle
count
0
-
FW
107
handle
0
X
uint8_t data[X]
FS
108
handle
offset
4
uint32_t from
FL
109
count
0
X
uint8_t pattern[X]
SHELL
110
len(name)
0
len(name)+
1+
len(string)
uint8_t name[len(name)]
uint8_t null (0)
uint8_t string[len(string)]
BSPIC
111
CS
0
0
-
BSPIO
112
CS
0
20
uint32_t MISO
uint32_t MOSI
uint32_t SCLK
uint32_t baud
uint32_t spi_flags
BSPIX
113
CS
0
X
uint8_t data[X]
BSCX
114
control
0
X
uint8_t data[X]
EVM
115
handle
bits
0
-
EVT
116
event
0
0
-
PROCU
117
script_id
0
4*X
uint32_t pars[X]

Response

The response has cmd/p1/p2 as in the request.  p3/res holds the return value.  If the command returns additional values they will be in the immediately following extension.

Normally res should be treated as a 32 bit signed value and will be greater than or equal to zero.  Upon failure res will be less than 0 and contains an error code.

There are a few commands where the returned value should be treated as a 32 bit unsigned value.  These commands can not fail.  They are indicated with a * after the command name.

Commands with an extension have the size of the extension in bytes returned in res (or <0 on error as above).

COMMAND cmd
p1
p2
res
Extension
MODES 0 -
-
0 -
MODEG 1 -
-
mode
-
PUD 2 -
-
0 -
READ 3 -
-
level
-
WRITE 4 -
-
0 -
PWM 5 -
-
0 -
PRS 6 -
-
0 -
PFS 7 -
-
0 -
SERVO 8 -
-
0 -
WDOG 9 -
-
0 -
BR1 * 10 -
-
bits
-
BR2 * 11 -
-
bits
-
BC1 12 -
-
0 -
BC2 13 -
-
0 -
BS1 14 -
-
0 -
BS2 15 -
-
0 -
TICK *
16 -
-
tick
-
HWVER *
17 -
-
version
-
NO 18 -
-
handle
-
NB 19 -
-
0 -
NP 20 -
-
0 -
NC 21 -
-
0 -
PRG 22 -
-
range
-
PFG 23 -
-
frequency
-
PRRG 24 -
-
real range
-
HELP 25 -
-
N/A
N/A
PIGPV *
26 -
-
version
-
WVCLR 27 -
-
0 -
WVAG 28 -
-
wave pulses
-
WVAS 29 -
-
wave pulses
-
N/A
30 -
-
-
-
N/A
31 -
-
-
-
WVBSY 32 -
-
busy (1) or not busy (0)
-
WVHLT 33 -
-
0 -
WVSM 34 -
-
wave micros
wave micros - high
wave micros - max
-
WVSP 35 -
-
wave pulses
wave pulses - high
wave pulses - max
-
WVSC 36 -
-
wave DMA CBs
wave DMA CBs - high
wave DMA CBs - max
-
TRIG 37 -
-
0
-
PROC 38 -
-
script id
-
PROCD 39 -
-
0 -
PROCR 40 -
-
script status
-
PROCS 41 -
-
0 -
SLRO 42 -
-
0
-
SLR 43 -
-
X
uint8_t data[X]
SLRC 44 -
-
0 -
PROCP 45 -
-
44 uint32_t script_status
uint32_t pars[10]
MICS 46 -
-
0 -
MILS 47 -
-
0 -
PARSE 48 -
-
N/A
-
WVCRE 49 -
-
wave id
-
WVDEL 50 -
-
0 -
WVTX 51 -
-
wave DMA CBs
-
WVTXR 52 -
-
wave DMA CBs
-
WVNEW 53 -
-
0 -
I2CO 54 -
-
handle -
I2CC 55 -
-
0 -
I2CRD 56 -
-
X
uint8_t data[X]
I2CWD 57 -
-
0
-
I2CWQ 58 -
-
0 -
I2CRS 59 -
-
byte value
-
I2CWS 60 -
-
0 -
I2CRB 61 -
-
byte value
-
I2CWB 62 -
-
0
-
I2CRW 63 -
-
word value
-
I2CWW 64 -
-
0
-
I2CRK 65 -
-
0 -
I2CWK 66 -
-
0
-
I2CRI 67 -
-
X
uint8_t data[X]
I2CWI 68 -
-
0
-
I2CPC 69 -
-
word value
-
I2CPK 70 -
-
X
uint8_t data[X]
SPIO
71 -
-
handle
-
SPIC 72 -
-
0 -
SPIR 73 -
-
X
uint8_t data[X]
SPIW 74 -
-
0
-
SPIX 75 -
-
X uint8_t data[X]
SERO 76 -
-
handle
-
SERC 77 -
-
0 -
SERRB 78 -
-
byte value
-
SERWB 79 -
-
0 -
SERR 80 -
-
X
uint8_t data[X]
SERW 81 -
-
0
-
SERDA 82 -
-
data ready count
-
GDC
83
-
-
dutycycle
-
GPW
84
-
-
pulsewidth
-
HC
85
-
-
0
-
HP
86
-
-
0
-
CF1
87
-
-
value
-
CF2
88
-
-
X
uint8_t retBuf[X]
BI2CC
89
-
-
0
-
BI2CO
90
-
-
handle
-
BI2CZ
91
-
-
X
uint8_t data[X]
I2CZ
92
-
-
X
uint8_t data[X]
WVCHA
93
-
-
0
-
SLRI
94
-
-
0
-
CGI
95
-
-
config
-
CSI
96
-
-
0
-
FG
97
-
-
0
-
FN
98
-
-
0
-
NOIB 99 -
-
0 -
WVTXM
100
-
-
wave DMA CBs
-
WVTAT
101
-
-
wave id
-
PADS
102
-
-
0
-
PADG
103
-
-
strength
-
FO
104
-
-
handle
-
FC
105
-
-
0
-
FR
106
-
-
X
uint8_t data[X]
FW
107
-
-
0
-
FS
108
-
-
position
-
FL
109
-
-
X
uint8_t filenames[X]
SHELL
110
-
-
exit status
-
BSPIC
111
-
-
0
-
BSPIO
112
-
-
0
-
BSPIX
113
-
-
X
uint8_t data[X]
BSCX
114
-
-
X+4
uint32_t status
uint8_t data[X]
EVM
115
-
-
0
-
EVT
116
-
-
0
-
PROCU
117
-
-
0
-

cmdCmd_t

typedef struct
{
   uint32_t cmd;
   uint32_t p1;
   uint32_t p2;
   union
   {
      uint32_t p3;
      uint32_t ext_len;
      uint32_t res;
   };
} cmdCmd_t;

[pigpio] [pigpio C I/F] [pigpiod] [pigpiod C I/F] [Python] [pigs] [piscope] [Misc] [Examples] [Download] [FAQ] [Site Map]
© 2012-2023
e-mail: pigpio @ abyz.me.uk
Updated: 01/01/2023