Circuits GPIO, I2C and SPI - Use Elixir to control hardware and read sensors

Elixir Circuits is a set of libraries for interacting with hardware. We previously announced Circuits.UART, and now we’re ready to announce Circuits.GPIO, Circuits.I2C, and Circuits.SPI. Here are examples of devices that you can control with the libraries:

  • Circuits.GPIO - buttons, switches, and lights
  • Circuits.I2C - accelerometers, gyroscopes, compasses, some thermometers, displays, lighting and motor controllers and more
  • Circuits.SPI - analog to digital converters, small displays, and custom programs running on FPGAs

These libraries work on Raspberry Pis with Raspbian, other embedded Linux devices and the official Nerves platforms. The libraries also include test backends for compilation and limited testing on development machines.

The Circuits GPIO, I2C, and SPI libraries can be thought of as Elixir ALE 2.0. During the development of Elixir ALE 2.0, we decided to break apart the library based on hardware interface. The APIs are similar to Elixir ALE, but different enough that if you are currently using ALE, we recommend that you review the porting guides in the documentation. All users of Elixir ALE are highly encouraged to update their projects to the appropriate Circuits libraries.

Changes from Elixir ALE 1.0 include:

  1. Circuits GPIO, I2C, and SPI now use NIFs. The performance improvement is noticeable - especially for GPIOs. Yes, there’s a trade off in stability. Based on our experience with ALE, we felt we could achieve a similar level of stability with NIFs and support use cases that were limited by ALE’s performance.
  2. Various API improvements and conveniences like supporting iodata when writing to the I2C and SPI buses and more configuration in open calls to support “glitch-free” initialization
  3. Support for internal pull-ups and pull-downs on GPIOs on Raspberry Pis. This saves you from having to connect a resister to buttons
  4. More user-friendly support for finding devices on I2C buses
  5. Timestamped GPIO interrupt messages to improve pulse measurement precision

Check out for more information.

We really enjoy using the Elixir programming language with hardware and we hope that you will too.

Happy hardware hacking!

Frank Hunleth
Mark Sebald
Matt Ludwigs


We just released circuits_gpio v0.4.1 which has important updates for Raspbian. All Circuits projects should work well on Raspbian now.

While many of us primarily work with Nerves, we want Circuits to have a great out-of-box experience with Raspbian and other Linux distros running on Raspberry Pis, Beaglebones, etc. If you’re using one of these, please let us know (via GitHub issue) if anything doesn’t work or is confusing.


circuits_gpio v0.4.2 is available now. It has an important update that makes GPIO pullup and pulldown settings work with the Raspberry Pi 4. This feature is frequently used by Raspberry Pi hats that have buttons on them.


circuits_gpio v0.4.3 and circuits_i2c v0.3.5 are available now.

circuits_gpio has a fix for handling fast GPIO transitions. One example of these are the spurious transitions from button presses. The normal route is to add debounce handling code to remove them. circuits_gpio does some debouncing due to it being slow. In some cases you don’t want to miss the GPIO transition. This release fixes a bug when turning it off. See the :suppress_glitches option.

circuits_gpio also supports forcing GPIO emulation on for testing libraries that use it. See CIRCUITS_MIX_ENV.

circuits_i2c fixes an issue when scanning the I2C bus for devices. There’s no spec for enumerating an I2C bus, so it’s done heuristically. There’s still an outstanding issue for an improvement in this area.

A final note: Several people have contacted me about cdev support for circuits_gpio. This would be a significant and important update. I am not working on this, but others have expressed interest. Since this is a sizable unfunded effort, I’m not sure when this work will be available - no changes have been pushed to any public repo yet. If you are interested in contributing to this effort, I will gladly put you in contact with others.