GPIO

Recommended ways of interacting with GPIO on balena devices.

Raspberry Pi

The Raspberry Pi's General Purpose I/O (GPIO) pins can be used to send and receive arbitrary data from external hardware. In the diagram shown below the GPIO pins are located in the top-right hand corner of the device:-

Raspberry Pi

Library Access

There are many libraries available for GPIO access. For node.js users, npm has a number of GPIO libraries available.

We recommend Pi Pins for node.js projects - we've found it works reliably on balena. Check out our example GPIO application which uses this library.

There are also specialist libraries available for powering particular classes of devices via GPIO, e.g. the MAX7219 node library for MAX7219 LED displays.

File System Access

You can use the file system directly to access GPIO pins using a terminal connection, scripts deployed to your Pi, or the file system interface of your programming environment.

GPIO pins are exposed via the Linux sysfs file system at /sys/class/gpio/gpio[pin number], e.g. pin 17 would be accessible via /sys/class/gpio/gpio17.

In order to gain access to a pin it first has to be exported - you can do this by outputting the desired pin number to /sys/class/gpio/export. You can later 'unexport' this GPIO pin by outputting this number to /sys/class/gpio/unexport.

Once a pin is exported you need to set its 'direction' - in or out - via /sys/class/gpio/gpio[pin number]/direction.

From then on you can output raw data to /sys/class/gpio/gpio[pin number]/value bit-by-bit - 0 is interpreted as a low signal, 1 or any other non-zero value is interpreted as a high signal.

E.g. accessing GPIO port 17 and sending some data:-

# ls /sys/class/gpio/gpio17
ls: cannot access /sys/class/gpio/gpio17: No such file or directory
# echo 17 > /sys/class/gpio/export
# ls /sys/class/gpio/gpio17
/sys/class/gpio/gpio17
# echo out > /sys/class/gpio/gpio17/direction
# echo 1 > /sys/class/gpio/gpio17/value
# echo 0 > /sys/class/gpio/gpio17/value
# echo 1 > /sys/class/gpio/gpio17/value
...
# echo 17 > /sys/class/gpio/unexport
# ls /sys/class/gpio/gpio17
ls: cannot access /sys/class/gpio/gpio17: No such file or directory

For more details on sysfs GPIO access see the official kernel documentation.

Voltage

All numbered data pins operate at 3.3v, however there are two 5v ports which output 5v DC output.

Please note that these are operating at a different voltage from the data pins - if you need to drive a 5v (or higher) device, you will need to use a level converter to step up the data pin's voltage or your device will not be able to correctly interpret high signals from the Pi.

Beaglebone

Currently the Beaglebone devices are running a very new 4.1 kernel (which is obviously awesome), unfortunately many of the userspace libraries haven't caught up yet so they only work with the older 3.8 kernel. Luckily ruth0000 was kind enough to patch the Octalbonescript JS library and made a lovely node.js module over here: https://www.npmjs.com/package/octalbonescript_capemgr4_1 .

With this module you should be able to carry out basic GPIO and analog-to-digital conversion operations. To get you started we have a simple example using this module here.

If you would prefer a python implementation, then look at this github issue and get involved in making it happen.

Intel Edison

All the Intel Edison base images on our Docker Hub come pre-installed with libmraa, which allows you to easily interact with the GPIO.

To get started with GPIO on edison have a look at our "Edison GPIO in node.js" example, or if you prefer python check out our "Simple Edison GPIO with python".