Skip to main content

Advanced GPIO for the Raspberry Pi. Extends RPi.GPIO with GPIO interrups, TCP socket interrupts, a command line tool and more

Project description

Visit pythonhosted.org/RPIO for a pretty version of this documentation.

RPIO is an advanced GPIO module for the Raspberry Pi.

  • GPIO Input and Output (drop-in replacement for RPi.GPIO)

  • GPIO Interrupts (callbacks when events occur on input gpios)

  • TCP Socket Interrupts (callbacks when tcp socket clients send data)

  • Well documented, tested, fast source code

  • Minimal CPU and memory profile

RPIO consists of two main components:

  • RPIO.py, which you can import in Python 2 or 3 with import RPIO

  • rpio, a command-line multitool for inspecting and manipulating GPIOs system-wide

New in v0.8.2

  • Socket server callbacks with RPIO.add_tcp_callback(port, callback, threaded_callback=False)

Installation

The easiest way to install/update RPIO on a Raspberry Pi is with either easy_install or pip:

$ sudo apt-get install python-setuptools
$ sudo easy_install -U RPIO

You can also get RPIO from Github repository, which is usually a step ahead of pypi:

$ git clone https://github.com/metachris/RPIO.git
$ cd RPIO
$ sudo python setup.py install

Or from Github but without Git:

$ curl -L https://github.com/metachris/RPIO/archive/master.tar.gz | tar -xz
$ cd RPIO-master
$ sudo python setup.py install

After the installation you can use import RPIO as well as the command-line tool rpio.

rpio, the command line tool

rpio allows you to inspect and manipulate GPIO’s system wide, including those used by other processes. rpio needs to run with superuser privileges (root), else it will restart using sudo. The BCM GPIO numbering scheme is used by default. rpio --inspect-all (or -I) is the most popular command; it shows you all gpios on the board, with function and state. Here is an overview of all the functions:

Show the help page:

    $ rpio -h

Inspect the function and state of gpios (with -i/--inspect):

    $ rpio -i 7
    $ rpio -i 7,8,9
    $ rpio -i 1-9

    # Example output for `rpio -i 1-9` (non-existing are ommitted):
    GPIO 2: ALT0   (1)
    GPIO 3: ALT0   (1)
    GPIO 4: INPUT  (0)
    GPIO 7: OUTPUT (0)
    GPIO 8: INPUT  (1)
    GPIO 9: INPUT  (0)

Inspect all GPIO's on this board (with -I/--inspect-all):

    $ rpio -I

Set GPIO 7 output to `1` (or `0`) (with -s/--set):

    $ rpio -s 7:1

    You can only write to pins that have been set up as OUTPUT. You can
    set this yourself with `--setoutput <gpio-id>`.

Wait for interrupt events on GPIOs (with -w/--wait_for_interrupts). You
can specify an edge (eg. `:rising`; default='both') as well as `:pullup`,
`:pulldown` or `pulloff`.

    $ rpio -w 7
    $ rpio -w 7:rising
    $ rpio -w 7:falling:pullup

    $ rpio -w 7:rising:pullup,17,18
    $ rpio -w 1-9

Setup a pin as INPUT (optionally with software resistor):

    $ rpio --setinput 7
    $ rpio --setinput 7:pullup
    $ rpio --setinput 7:pulldown

Setup a pin as OUTPUT (optionally with an initial value (0 or 1)):

    $ rpio --setoutput 8
    $ rpio --setoutput 8:1

Show Raspberry Pi system info:

    $ rpio --sysinfo

    # Example output:
    000e: Model B, Revision 2.0, RAM: 256 MB, Maker: Sony

You can update the RPIO package to the latest version:

$ rpio --update-rpio

Install (and update) the rpio manpage:

$ rpio --update-man
$ man rpio

RPIO.py, the Python module

RPIO.py extends RPi.GPIO in various ways, and uses the BCM GPIO numbering scheme by default.

  • GPIO Interrupts

  • TCP Socket Interrupts

  • GPIO Input & Output

  • more

GPIO Interrupts

Interrupts are used to receive notifications from the kernel when GPIO state changes occur. Advantages include minimized cpu consumption, very fast notification times, and the ability to trigger on specific edge transitions (rising, falling or both). You can also set a software pull-up or pull-down resistor.

RPIO.add_interrupt_callback(gpio_id, callback, edge=’both’, pull_up_down=RPIO.PUD_OFF, threaded_callback=False)

Adds a callback to receive notifications when a GPIO changes it’s value. Possible pull_up_down values are RPIO.PUD_UP, RPIO.PUD_DOWN and RPIO.PUD_OFF (default). Possible edges are rising, falling and both (default). Note that rising and falling edges may receive values not corresponding to the edge, so be sure to double check.

TCP Socket Interrupts

Its easy to open ports for incoming TCP connections with just this one method:

RPIO.add_tcp_callback(port, callback, threaded_callback=False)

Adds a socket server callback, which will be started when a connected socket client sends something. This is implemented by RPIO creating a TCP server socket at the specified port. Incoming connections will be accepted when RPIO.wait_for_interrupts() runs. The callback must accept exactly two parameters: socket and message (eg. def callback(socket, msg)). The callback can use the socket parameter to send values back to the client (eg. socket.send("hi there\n")).

You can test the TCP socket interrupts with $ telnet <your-ip> <your-port> (eg. $ telnet localhost 8080). An empty string tells the server to close the client connection (for instance if you just press enter in telnet, you’ll get disconnected).

Example

The following example shows how to react to events on three gpios, and one socket server on port 8080:

import RPIO

def gpio_callback(gpio_id, val):
    print("gpio %s: %s" % (gpio_id, val))

def socket_callback(socket, val):
    print("socket %s: '%s'" % (socket.fileno(), val))
    socket.send("echo: %s\n" % val)

def do_something(gpio_id, value):
    logging.info("New value for GPIO %s: %s" % (gpio_id, value))

# Three GPIO interrupt callbacks
RPIO.add_interrupt_callback(7, gpio_callback)
RPIO.add_interrupt_callback(8, gpio_callback, edge='rising')
RPIO.add_interrupt_callback(9, gpio_callback, pull_up_down=RPIO.PUD_UP)

# One TCP socket server callback on port 8080
RPIO.add_tcp_callback(8080, socket_callback)

# Start the blocking epoll loop, and catch Ctrl+C KeyboardInterrupt
try:
    RPIO.wait_for_interrupts()
except KeyboardInterrupt:
    RPIO.cleanup_interrupts()

If you want to receive a callback inside a Thread (to not block RPIO from returning to wait for interrupts), set threaded_callback to True when adding it:

# for GPIO interrupts
RPIO.add_interrupt_callback(7, do_something, threaded_callback=True)

# for socket interrupts
RPIO.add_tcp_callback(8080, socket_callback, threaded_callback=True)

To stop the wait_for_interrupts() loop you can call RPIO.stop_waiting_for_interrupts(). After using RPIO.wait_for_interrupts() you should call RPIO.cleanup_interrupts() before your program quits, to shut everything down nicely.

Log Output

To enable RPIO log output, import logging and set the loglevel to DEBUG before importing RPIO:

import logging
log_format = '%(levelname)s | %(asctime)-15s | %(message)s'
logging.basicConfig(format=log_format, level=logging.DEBUG)
import RPIO

GPIO Input & Output

RPIO extends RPi.GPIO; all the input and output handling works just the same:

import RPIO

# set up input channel without pull-up
RPIO.setup(7, RPIO.IN)

# set up input channel with pull-up control. Can be
# PUD_UP, PUD_DOWN or PUD_OFF (default)
RPIO.setup(7, RPIO.IN, pull_up_down=RPIO.PUD_UP)

# read input from gpio 7
input_value = RPIO.input(7)

# set up GPIO output channel
RPIO.setup(8, RPIO.OUT)

# set gpio 8 to high
RPIO.output(8, True)

# set up output channel with an initial state
RPIO.setup(8, RPIO.OUT, initial=RPIO.LOW)

# change to BOARD numbering schema
RPIO.setmode(RPIO.BOARD)

# set software pullup on channel 17
RPIO.set_pullupdn(17, RPIO.PUD_UP)  # new in RPIO

# get the function of channel 8
RPIO.gpio_function(8)

# reset every channel that has been set up by this program,
# and unexport interrupt gpio interfaces
RPIO.cleanup()

You can use RPIO as a drop-in replacement for RPi.GPIO in your existing code like this:

import RPIO as GPIO  # (if you've previously used `import RPi.GPIO as GPIO`)

To find out more about the methods and constants in RPIO you can run $ sudo pydoc RPIO, or use the help method inside Python:

import RPIO
help(RPIO)

Additions to RPi.GPIO

Additional Constants

  • RPIO.RPI_REVISION - the current board’s revision (either 1 or 2)

  • RPIO.RPI_REVISION_HEX - the cpu hex revision code (0002 .. 000f)

Additional Methods

  • RPIO.gpio_function(gpio_id) - returns the current setup of a gpio (IN, OUT, ALT0)

  • RPIO.set_pullupdn(gpio_id, pud) - set a pullup or -down resistor on a GPIO

  • RPIO.forceinput(gpio_id) - reads the value of any gpio without needing to call setup() first

  • RPIO.forceoutput(gpio_id, value) - writes a value to any gpio without needing to call setup() first (warning: this can potentially harm your Raspberry)

  • RPIO.sysinfo() - returns (hex_rev, model, revision, mb-ram and maker) of this Raspberry

  • RPIO.version() - returns (version_rpio, version_cgpio)

Interrupt Handling

  • RPIO.add_interrupt_callback(gpio_id, callback, edge='both', pull_up_down=RPIO.PUD_OFF, threaded_callback=False)

  • RPIO.add_tcp_callback(port, callback, threaded_callback=False)

  • RPIO.del_interrupt_callback(gpio_id)

  • RPIO.wait_for_interrupts(epoll_timeout=1)

  • RPIO.stop_waiting_for_interrupts()

  • implemented with epoll

Other Changes

Feedback

Please send feedback and ideas to chris@linuxuser.at, and open an issue at Github if you’ve encountered a bug.

FAQ

How does RPIO work?

RPIO extends RPi.GPIO, a GPIO controller written in C which uses a low-level memory interface. Interrupts are implemented with epoll via /sys/class/gpio/. For more detailled information take a look at the source, it’s well documented and easy to build.

Should I update RPIO often?

Yes, because RPIO is getting better by the day. You can use $ rpio --update-rpio or see Installation for more information about methods to update.

I’ve encountered a bug, what next?

  • Make sure you are using the latest version of RPIO (see Installation)

  • Open an issue at Github

pip is throwing an error during the build: source/c_gpio/py_gpio.c:9:20: fatal error: Python.h: No such file or directory

You need to install the python-dev package (eg. $ sudo apt-get install python-dev), or use easy_install (see Installation).

License

RPIO is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

RPIO is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

Changes

  • v0.8.3: pypi release update with updated documentation and bits of refactoring

  • v0.8.2

    • Added TCP socket callbacks

    • RPIO does not auto-clean interfaces on exceptions anymore, but will auto-clean them as needed. This means you should now call RPIO.cleanup_interrupts() to properly close the sockets and unexport the interfaces.

    • Renamed RPIO.rpi_sysinfo() to RPIO.sysinfo()

  • v0.8.0

    • Improved auto-cleaning of interrupt interfaces

    • BOARD numbering scheme support for interrupts

    • Support for software pullup and -down resistor with interrupts

    • New method RPIO.set_pullupdn(..)

    • rpio now supports P5 header gpios (28, 29, 30, 31) (only in BCM mode)

    • Tests added in source/run_tests.py and fabfile.py

    • Major refactoring of C GPIO code

    • Various minor updates and fixes

  • v0.7.1

    • Refactoring and cleanup of c_gpio

    • Added new constants and methods (see documentation above)

    • Bugfixes

      • wait_for_interrupts() now auto-cleans interfaces when an exception occurs. Before you needed to call RPIO.cleanup() manually.

  • v0.6.4

    • Python 3 bugfix in rpio

    • Various minor updates

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

RPIO-0.8.3.tar.gz (26.4 kB view details)

Uploaded Source

Built Distributions

RPIO-0.8.3-py3.2-linux-armv6l.egg (40.8 kB view details)

Uploaded Egg

RPIO-0.8.3-py2.7-linux-armv6l.egg (40.0 kB view details)

Uploaded Egg

RPIO-0.8.3-py2.6-linux-armv6l.egg (40.1 kB view details)

Uploaded Egg

File details

Details for the file RPIO-0.8.3.tar.gz.

File metadata

  • Download URL: RPIO-0.8.3.tar.gz
  • Upload date:
  • Size: 26.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for RPIO-0.8.3.tar.gz
Algorithm Hash digest
SHA256 96285c48327b225a30a7146491c4a0a6ffbf7b63f19805722e9962f30e4f4b04
MD5 40e5275030667cf75aeca110a3567917
BLAKE2b-256 d56cf1c6feb04c76593d50fafef05f4b213b211a12eff0e6be52ae6d25dc86dd

See more details on using hashes here.

File details

Details for the file RPIO-0.8.3-py3.2-linux-armv6l.egg.

File metadata

File hashes

Hashes for RPIO-0.8.3-py3.2-linux-armv6l.egg
Algorithm Hash digest
SHA256 24dd47cb22e391709e7139597e72b66b658d26b82bcbe0b12eb863c43849a311
MD5 c084c52f2a3009c7f832bad746e9f624
BLAKE2b-256 752e69274f08a0d2a058d134023100c59fec39fb4f85b454097d54ca4a6f5acc

See more details on using hashes here.

File details

Details for the file RPIO-0.8.3-py2.7-linux-armv6l.egg.

File metadata

File hashes

Hashes for RPIO-0.8.3-py2.7-linux-armv6l.egg
Algorithm Hash digest
SHA256 85a45c9260fb18cb7bcf0730118e66d1b6a172a7f437794e996b4fc02a45c0df
MD5 4623f24e265334e220583f7310378e0a
BLAKE2b-256 833613c91d6a532a651687c94894ee09a99e4ca6fc03be9dc1f0f0911cfe87f8

See more details on using hashes here.

File details

Details for the file RPIO-0.8.3-py2.6-linux-armv6l.egg.

File metadata

File hashes

Hashes for RPIO-0.8.3-py2.6-linux-armv6l.egg
Algorithm Hash digest
SHA256 c0738aa8901ddb1fd2f8467605841a3acc1b7eae8b755ab204e604d0a1db14ac
MD5 94f230342be5962f1d3d9aa3752d9cf1
BLAKE2b-256 b52f1a86ebf4f852cc816e5cfdba09a7fc8bb2cccfdbf2869495d767d6e75295

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page