plebgpio provides a file-based API for GPIO operation of LEDs and buttons.
Poke a value into a file to set an LED, or read a file to learn state of a button.
A config file is offered to allow programmers to map GPIO pins to buttons or LEDs.
All of the files are in the "pleb" directory (/etc/pleb/gpio/).
A SystemD service runs in background which wrangles the GPIO and monitors/changes files, presenting a simple interface to applications.
● Easy to set up — even easier to operate
● Negligible usage of system resources (memory and cpu)
● Accessible by any language running on Linux
● Uses the very latest GPIO kernel API
Some folks wanna do edgy things with GPIO; we plebeians just wanted an easy way to manage LEDs and buttons. Our searches did not reveal much, and most of that was discontinued. plebgpio is intended to fill this void.
plebgpio is based on the V2 ioctl interface (aka GPIO Character Device Userspace API). This is the latest interface and, God willing, will be with us for a very long time.
The concept is simple: writing to a file sets a value for the LED that file represents. Reading a button's value is done by reading from the file representing that button.
$ echo 0 > /etc/pleb-gpio/led1 # turn off LED1
#
$ cat /etc/pleb-gpio/btn0 # see whether BTN0 is depressed
# ('has been pressed' not 'is sad')
It's universally accessibile.
Reading and writing to files with names like btn0 and led1 can be done from Bash, Python, JavaScript, C and other languages.
The configuration file (/etc/pleb/gpio/config.txt) allows one to specify some LEDs and buttons.
Once specified, they can be controlled/monitored by using their filename.
Since ground pins are not specified, the entry for a button is a two line configuration — label the button and name the non-ground pin.
[btn0]
hot=17
The entry above defines a button btn0, using the non-ground lead at GPIO #17.
All pin numbers are GPIO references.
(https://pinout.xyz/)
A single color LED will likewise be two configuration lines.
[led1]
pwr=25
That was easy!
The lines above configure a button, labeled btn0, using a ground pin and GPIO #17, and also an LED, labeled led1, using a ground pin and GPIO #25.
Now we can put them to use.
Turning on the LED1 is now a matter of writing into its file. A '1' for on and a '0' for off. Done like this:
$ echo 1 > /etc/pleb/gpio/led1 # turn on LED1
Buttons work the same, but you read the file, instead of writing. The operation below will return a '1' or a '0'.
$ cat /etc/pleb/gpio/btn0 # see whether BTN0 is depressed
If you want your software to monitor btn0, you will want to poll this file.
A poll rate of 100ms to 200ms is suggested.
plebgpio supports multi-color LEDs.
To set multiple colors, we add a colors= line to the config file.
Also, we replace the pwr= line with a separate line for each color.
See this example.
[led2]
colors=3
red=11
green=9
blue=10
Putting a multi-color LED to work is similar to a monochrome LED. While monochrome LEDs accept a binary value (0 or 1), 3-color LEDs take an octal code (0 through 7). The coding is rgb; red == 4, green == 2 and blue == 1. Now, we do it this way:
$ echo 5 > /etc/pleb-gpio/led2 # magenta in LED2
To make life more human friendly, plebgpio supports use of letters to specify a color. In the example above, 'm' may be substituted for '5', giving you the syntax below.
$ echo m > /etc/pleb-gpio/led2 # magenta in LED2
Our gang found this nomenclature especially handy when writing programs (described below).
This is the full glossary:
• o 0 (off)
• n 1 (on)
• b 1 (blue)
• g 2 (green)
• c 3 (cyan)
• r 4 (red)
• m 5 (magenta)
• y 6 (yellow)
• w 7 (white)
We frequently signal information with time-related behavior — like a fast blink or a slow blink. This can be done in the application software but plebgpio supports it to offload housekeeping, using "programs". A program is a time-series of display, normally running in a loop. Let's look at one.
[prog6]
next=-----------------------<
led1=ggooggoooooooooooooooooo
Program 6 blinks green twice. Later, it does it again. Forever.
Each period of the program is one eighth of a second, 125ms.
The top row, next= describes what happens next — - means "continue" < means "loop from the start", and x means stop.
The second row, led1= assigns an octal value to LED1 for that period.
Program 6 above illuminates LED1 green for 250ms, then off for 250ms then green again.
Note that 0 and 2 could be substituted for o and g, respectively.
We like the alphabetic approach better.
A program can be up to 80 segments (10 seconds) long before it repeats or stops. It may specify multiple LEDs which will display in lock step. This program is very pretty.
[prog2]
next=-----------------------------------------------------------------------<
led1=rrrrggggbbbbrrrrggggbbbbrrrrggggbbbbrrrrggggbbbbrrrrggggbbbbrrrrggggbbbb
led2=ccccmmmmyyyyccccmmmmyyyyccccmmmmyyyyccccmmmmyyyyccccmmmmyyyyccccmmmmyyyy
Up to 35 programs may be specified, using a single character, base 35. Zero is not allowed. So, the first program would be '1' and the last program would be 'Z'. These are just labels; ordinal value has no significance.
To run a program, put its base 35 digit into /etc/pleb/gpio/prog.
When a program is running, values in the individual LED files (e.g. led1) are ignored.
Programs do not affect button operation — that continues per normal.
Program Zero is special; it means no program, and plebgpio looks to the individual LED files to set the LEDs. When the system starts, it will run program 0, unless otherwise configured.
plebgpio runs in the background. It loops, monitoring and filling the files described above. The normal interval is 125ms but it can be set for 62.5ms.
Ideally plebgpio is launched by SystemD and is a quietly provides a simplified interface for GPIO.
There is no installation program for plebgpio yet but the steps should be easy for people comfortable with the craft.
The installing user must have root privilege.
The Makefile describes how to compile and install the plebgpio program.
There is a sample systemd service file that should get you going.
Short of making it a systemd process, one can invoke plebgpio in background by calling.
$ plebgpio &
WAIT! Stop. Before invoking it, you should create the pleb directory. (As noted, there is no installation program.) Soooo . . .
$ sudo mkdir /etc/pleb
$ sudo mkdir /etc/pleb/gpio
$ sudo chown root:dialout /etc/pleb/gpio
$ sudo chmod 2770 /etc/pleb/gpio
And you probably want to put an item or two in config.txt.
Here is a comprehensive list of the available sections:
• pleb
• led0
• led1
• led2
• led3
• btn0
• btn1
• btn2
• prog1
• prog2
•
•
•
• prog9
config.txt will stop everything and error reporting is negligible right now.
Someone going by drankinatty in the Raspberry Pi Forums wrote the V2 functions that are being used here. Thanks drankinatty wherever you are.
The config file parser uses the simple but effective code we found here. We just popped it in, it compiled and worked!