As the first trickle of Raspberry Pi computers reach developers, we’re seeing more and more sample code for driving the GPIO pins on the Pi’s expansion port.
We like that – after all, our business is based on the belief that lots of Pi users will want to interact with the physical world, building environmental monitoring stations, test equipment, robots, and projects we can’t even begin to imagine. And to do that they’ll need access to GPIO.
A typical bit of GPIO code does several things:
- the code starts by exporting the pin you want to use. In effect, this tells Linux that you want control of that pin.
- then the code sets that pin as an input or output, and reads from or writes to the pin.
- finally, the code unexports the pin so that it’s available to others.
You’ll find plenty of code examples that do just that. There’s just one problem: all the code we’ve seen has to be run as root, and that’s really, really bad.
The root of all evil
One of the first things you learn when you start using Linux is that the root account is really dangerous. A short command can wipe the entire filesystem, losing all your work and requiring you to build a new SD card image and start again from scratch. Because the root account is so powerful, you should normally log on as an ordinary user (pi, for example) and use the sudo command to elevate your access to root level only when absolutely necessary and only for short tasks that require special privileges. (That’s on debian-based installations; other distros may expect you to do things slightly differently in order to work as root.)
So software that requires you to work as root in order to drive the GPIO pins is, in our opinion, a real no-no.
gpio-admin to the rescue
Now there’s a solution. We’ve created a program called gpio-admin which does two things:
- It can export and unexport GPIO pins..
- When a pin is exported, access to the pin is granted to users in the gpio group; those users can set the pin as an input or output, and then read from or write to the pin.
Anyone in the gpio group can run gpio-admin once it has been installed. You have to install it as root, but that’s OK; just use sudo for the installation process, and then continue as an ordinary user. (For details, see below.)
In order to make use of an exported GPIO pin, you’ll need to add yourself to the gpio group. We’ll look at how to do that shortly.
There are several ways in which you can configure and use the GPIO pin once it’s been exported. You can do it by typing shell commands, but most users will want to manipulate the GPIO pins under program control. We’re also working on a Python class which you can use in your Python code. The Python class will allow you to configure and use a GPIO pin, and will also invoke gpio-admin as necessary.
The naming of pins
If you want to use GPIO there is another complication lurking in the background.
There are (at least) three plausible ways you can refer to pins on the Pi expansion header.
- You can refer to the physical pin number. The pins are numbered from 1-26, and the numbering is well-defined.
- You can use the same designation as is used by the Raspberry Pi documentation. There are eight GPIO pins, GPIO0-GPIO7, and other pins that can be used for GPIO called (for example) SDA0 and SCL0. These are normally used for I2C, but can be used for GPIO instead if I2C is not required.
- You can use the same designation that is used by Broadcom and the linux kernel. We refer to these as SOC pin numbers. in this numbering system there are 54 GPIO pins numbered from GPIO0 to GPIO53. Not all of these are accessible, and most are not connected to the header in the current design. More may be connected in future hardware revisions.
For now, we are using the SOC pin numbering system for gpio-admin, but will use physical pin numbering for our Python code. We’re expecting almost everyone to use Python, and Python will take care of the mapping from physical pin number to SOC pin numbering.
In the Python code, use the following mappings:
All of this is pretty new, but we’ve released gpio-admin so you can have a play with it if you’re feeling brave.
These instructions assume that you are running the latest debian squeeze image; we have no idea if this code will work on other distributions, and advise you not to try it.
The project is hosted on github, where all sorts of Pi-related things are available. To install gpio-admin on your Pi, you’ll need to install git, if you haven’t done so already, by running sudo apt-get install git-core in a command window.
Then change to a suitable directory and clone the project there. We use a git directory within our home directory for all git-related stuff.
Create the clone by running git clone git://github.com/quick2wire/quick2wire-gpio-admin.git in a command window. That will create a sub-directory called gpio-admin. Run cd gpio-admin to move into that directory.
Next, install the software by running make and then sudo make install in a command window.
Join the gpio group and run some software.
Now you need to add yourself to the gpio group. Run sudo adduser $USER gpio and then log off and log on again. The group membership won’t take effect until you do.
Now you can make use of the pins:
% gpio-admin export 22
% cat /sys/devices/virtual/gpio/gpio22/value
% echo out > /sys/devices/virtual/gpio/gpio22/direction
% echo 1 > /sys/devices/virtual/gpio/gpio22/value
The first command exports pin 22. The pin is initially configured as an input pin. The second command reads the value of the pin: it is zero (low). The third command sets the pin to be an output pin, and the final command sets the value to be 1 (high). If pin 22 is connected to a a voltmeter, you’ll see its voltage go from 0 to 3.3 volts.
The example above uses SOC GPIO 22, which corresponds to header pin 8 on the Raspberry Pi, and that pin is named GPIO 3 in the Raspberry Pi documentation.
Tidy up before you leave
Once you’ve finished, The last thing to do is to unexport the pin so that it’s free for other programs to use. Run gpio-admin unexport 22 and celebrate your first physical computing with the Pi.
As mentioned above, we’re working on a little Python library that will make it even easier to use GPIO pins under program control. You’ll still need to install gpio-admin, as described above, but your Python program will be able to use objects that, under the hood, handle the gpio-admin calls as well as reading from or writing to GPIO pins.
Credits: Thanks to Nat Pryce for doing the heavy lifting. Nat wrote the gpio-admin code and is developing the Python API.