Provided by: rgpiod_0.1.6.1-0ubuntu3_amd64 
NAME
rgpiod - a daemon to allow remote access to a SBC's GPIO.
SYNOPSIS
rgpiod [OPTION]...&
DESCRIPTION
rgpiod is a daemon to allow remote access to a SBC's GPIO.
Once launched the daemon runs in the background accepting commands from the socket
interface.
The daemon requires no special privileges and commands may be issued by normal users.
Features
The following features are available by issuing socket commands to the daemon.
o reading and writing GPIO singly and in groups
o software timed PWM
o GPIO callbacks
o pipe notification of GPIO events
o I2C wrapper
o SPI wrapper
o serial link wrapper
o file handling
o creating and running scripts
Launch options
rgpiod [options] &
OPTIONS
-c dir set the configuration directory (default current directory)
-l disable remote socket interface (default enabled)
-n address
allow IP address to use the socket interface, name (e.g. paul) or dotted quad (e.g.
192.168.1.66). If the -n option is not used all addresses are allowed (unless
overridden by the -l option). Multiple -n options are allowed. If -l has been used
only -n localhost has any effect
-p value
set the socket port (1024-32000, default 8889)
-v display rgpiod version and exit
-w dir set working directory (default launch directory)
-x enable access control (default off)
Permissions
The rgpiod daemon has an optional access control system to control access to its
functions.
See Permits.
Scripts
Scripts are programs to be stored and executed by the rgpiod daemon. They are intended to
mitigate any performance problems associated with the rgpiod daemon server/client model.
See Scripts.
Socket commands
Each socket command consists of a header and for commands with parameters an extension.
The header is a lgCmd_t with the following structure.
typedef struct
{
union
{
uint32_t magic;
int32_t status;
};
uint32_t size;
uint16_t cmd;
uint16_t doubles;
uint16_t longs;
uint16_t shorts;
} lgCmd_t, *lgCmd_p;
The magic value is 0x6c67646d (ASCII lgdm).
The size is the overall size in bytes of the optional extension.
The cmd is the command code. See the file lgSocketCommandCodes.h for the command codes.
The doubles, longs, shorts is the number of 8-byte, 4-byte, and 2-byte quantities in the
extension. This information is used to network order the bytes of the message. The
extension should consist of doubles 8-byte quantites, followed by longs 4-byte quantities,
followed by shorts 2-byte quantities, followed by as many 1-byte quantities needed to make
a total of size bytes.
If you wish to construct a client to talk to the rgpiod daemon the following are a good
source of information.
o rpgio.py - a Python client
o rgpio.c - a C client
o rgs.c - a C command line client
o lgCmd.c - a useful summary of the socket commands
Daemon Access Control
The rpgpio daemon operates in two modes - with or without access control.
The default setting is without access control and the permissions system does not apply
(so the rest of this section may be ignored).
If the rgpiod daemon is started with the -x option it implements an access control
permissions system to its functions.
There are three parts to the permissions system.
o An .lg_secret file in the users home directory.
o An .lg_secret file in the daemon's configuration directory.
o A permits file in the daemon's configuration directory.
The daemon client "logs in" to the daemon by choosing a user name. If the client and
daemon copies of the password for the user match the user is "logged in".
The client program is then authorised to carry out any functions permitted to the user as
specified in the permits file.
User secret file
The user .lg_secret file contains a list of user names with an associated password.
These passwords have no relationship to the passwords used by Linux and should not be the
same. The format is user=password.
An example .lg_secret file.
# user secrets file
# user=password
pete=t4pf4kvPOXjLfDnKBrMu
The file should be readable/writable by the owner only.
chmod 600 .lg_secret
Daemon secret file
The daemon .lg_secret file contains a list of user names with an associated password.
These passwords have no relationship to the passwords used by Linux and should not be the
same. The format is user=password.
An example daemon .lg_secret file.
# rgpiod secrets file
# user=password
joan=kr6g89XmFQvLDWh6UcJH
sally=fARrxSKqdHaPHBu6Vtet
pete=t4pf4kvPOXjLfDnKBrMu
fred=tugXUuRdPqGux6t7jhhv
The file should be readable/writable by the owner only.
chmod 600 .lg_secret
Daemon permits file
The permits file can contain the following sections. If a section is absent it means that
access to those features is forbidden.
[debug]
[files]
[gpio]
[i2c]
[notify]
[scripts]
[serial]
[shell]
[spi]
[debug]
Each entry in this section takes one of the following forms: user=y or user=n.
If the form user=y is used that user is allowed to use the debug commands.
If the form user=n is used, or there is no entry for the user, that user is not allowed to
use the debug command.
If the [debug] section is not present no user is allowed to use the debug commands.
The debug commands are set and get sbc internals and reload configuration.
[files]
Each entry in this section takes the form user=path x where path indicates a file path and
x refers to a permission. E.g. /home/peter/data.txt r refers to Linux
file/home/peter/data.txt and read permission.
There may be more than one path entry per user, each must be separated by a : character.
path may contain the wild card characters * (matches any characters) or ? (matches a
single character).
If the path entry starts with / it is relative to root (/) otherwise it is relative to the
daemons's working directory.
The permission may be R for read, W for write, U for read/write, and N for no access. If
a directory allows read/write access then files may be created in that directory.
Where more than one entry matches a file the most specific rule applies. If no entry
matches a file then access is denied.
Example
joan=/tmp/* u:* n:TEST/* r:TEST/TEST/* u
User joan may create, read, and write files in the /tmp directory (/tmp/* u).
User joan has no access to files in the working directory (* n).
Overridden by user joan has read permission for files in the TEST directory of the working
directory (TEST/* r).
Overridden by user joan may create, read, and write files in the TEST/TEST directory of
the working directory (TEST/TEST* u).
[gpio]
Each entry in this section takes the form user=x.y where x indicates a gpiochip device and
y indicates a GPIO. E.g. 1.2 refers to Linux device /dev/gpiochip1 GPIO 2.
There may be more than one x.y entry per user, each must be separated by a : character.
Both x and y may have the following forms.
* all gpiochips or all GPIO.
n a single gpiochip or GPIO.
n,n a list of gpiochips or GPIO.
n-n a range of gpiochips or GPIO.
Example
fred=0.2-27 # user fred can access gpiochip 0 GPIO 2-27.
peter=*.1,2 # user peter can access all gpiochips GPIO 1 and 2.
jill=1,2.* # user jill can access all GPIO of gpiochips 1 and 2.
boss=*.* # user boss can access all gpiochips and GPIO.
sally=0.2-27:3.* # user sally can access gpiochip 0 GPIO 2-27 and
# all GPIO of gpiochip 3.
[i2c]
Each entry in this section takes the form user=x.y where x indicates an I2C bus and y
indicates a device on the bus. E.g. 1.27 refers to Linux device /dev/i2c-1 device 27.
There may be more than one x.y entry per user, each must be separated by a : character.
Both x and y may have the following forms.
* all I2C buses or all devices.
n a single I2C bus or device.
n,n a list of I2C buses or devices.
n-n a range of I2C buses or devices.
Example
fred=0.3-127 # user fred can access I2C bus 0 devices 3-127.
peter=*.83,89 # user peter can access all I2C buses devices 83 and 89.
jill=1,2.* # user jill can access all devices on I2C buses 1 and 2.
boss=*.* # user boss can access all I2C buses and devices.
sally=0.80-99:3.* # user sally can access I2C bus 0 devices 80-99 and
# all devices of I2C bus 3.
[notify]
Each entry in this section takes one of the following forms: user=y or user=n.
If the form user=y is used that user is allowed to use the notify commands.
If the form user=n is used, or there is no entry for the user, that user is not allowed to
use the notifiy commands.
If the [notify] section is not present no user is allowed to use the notify commands.
[scripts]
Each entry in this section takes one of the following forms: user=y or user=n.
If the form user=y is used that user is allowed to use the script commands.
If the form user=n is used, or there is no entry for the user, that user is not allowed to
use the script command.
If the [debug] section is not present no user is allowed to use the script commands.
[serial]
Each entry in this section takes the form user=device where device indicates a serial
device. E.g. serial0 refers to Linux device /dev/serial0
There may be more than one device entry per user, each must be separated by a : character.
device may contain the wild card characters * (matches any characters) or ? (matches a
single character).
Example
fred=serial0 # user fred can access /dev/serial0.
peter=tty* # user peter can access /dev/tty*.
boss=* # user boss can access /dev/*.
sally=serial?:ttyS* # user sally can access /dev/serial? and /dev/ttyS*.
[shell]
Each entry in this section takes one of the following forms: user=y or user=n.
If the form user=y is used that user is allowed to use the shell commands.
If the form user=n is used, or there is no entry for the user, that user is not allowed to
use the shell commands.
If the [shell] section is not present no user is allowed to use the shell commands.
[spi]
Each entry in this section takes the form user=x.y where x indicates a SPI bus and y
indicates a slave select. E.g. 1.2 refers to Linux device /dev/spidev1.2
There may be more than one x.y entry per user, each must be separated by a : character.
Both x and y may have the following forms.
* all SPI buses or all slaves.
n a single SPI bus or slave.
n,n a list of SPI buses or slaves.
n-n a range of SPI buses or slaves.
Example
fred=0.0-2 # user fred can access SPI bus 0 slaves 0-2.
peter=*.0 # user peter can access all SPI buses slave 0.
jill=1,2.* # user jill can access all slaves on SPI buses 1 and 2.
boss=*.* # user boss can access all SPI buses and slaves.
sally=0.0-2:1.* # user sally can access SPI bus 0 slaves 0-2 and
# all slaves of SPI bus 1.
Example permits file
# rgpiod test file for user access
# user=permission
[files]
default=:
test1=/tmp/* u:* n:TEST/* r:TEST/TEST/* u:
[gpio]
test1=*.2-27
test2=0.2-27
test3=0.5-10
[i2c]
test1=1-999.*
test2=1-2.*
test3=2.5-20
[notify]
test1=n
test2=y
test3=y
[scripts]
test1=y
test2=n
test3=y
[serial]
test1=serial*:ttyUSB*:ttyS*
test2=ttyUSB1:tty0:ttyS0
test3=null
[spi]
test1=0.0:0.1:1.0:1.1:1.2:2.0:2.1
test2=0.*
test3=*.0
[debug]
admin=y
[shell]
test1=n
test2=n
test3=y
Scripts
Scripts are programs to be stored and executed by the rgpiod daemon. They are intended to
mitigate any performance problems associated with the daemon server/client model.
Scripts are work in progress.
Virtual machine
A script runs within a virtual machine with
a 32 bit accumulator A.
a flags register F.
a program counter PC.
Each script has
10 parameters named 0 through 9.
150 variables named 0 through 149.
50 labels which are named by any unique number.
Commands
Many lg commands may be used within a script. However some commands do not work within the
script model as designed and are not permitted.
The following commands are not permitted within a script:
File - FL FO FR FW
I2C - I2CPK I2CRD I2CRI I2CRK I2CWD I2CWI I2CWK I2CZ
Script control - PARSE PROC PROCD PROCP PROCR PROCS PROCU
Serial - SERO SERR SERW SLR
SPI - SPIR SPIW SPIX
The following commands are only permitted within a script:
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
JGE L Jump if >= 0 to tag L if (F>=0) PC=L
JGT L Jump if > 0 to tag L if (F>0) PC=L
JLE L Jump if <= 0 to tag L if (F<=0) PC=L
JLT L Jump if < 0 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
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
SHL y x Shift left register x bits *y<<=x; F=*y
SHLA x Shift left accumulator x bits A<<=x; F=A
SHR y x Shift right register x bits *y>>=x; F=*y
SHRA x Shift 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 system(str); F=A
TAG L Label the current position N/A
X y1 y2 Exchange registers y1 and y2 t=*y1;*y1=*y2;*y2=t
XA y Exchange accumulator and register t=A;A=*y;*y=t
XOR x Xor x with accumulator A^=x; F=A
x may be a constant, a parameter (p0-p9), or a variable (v0-v149).
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.
The SYS script receives two unsigned parameters: the accumulator A and the current GPIO
levels.
SEE ALSO
rgs(1), lgpio(3), rgpio(3)