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.


Hi @fhunleth

I am trying to figure out how to start working with Nerves, and Circuits on Waveshare Sense-Hat an expansion board with different sensors, the site seems to be down.

Any recommendation where to start will be of great help.

Board features:

  • Standard Raspberry Pi 40PIN GPIO extension header, supports Raspberry Pi series boards.

  • Onboard ICM20948 (3-axis accelerometer, 3-axis gyroscope, and 3-axis magnetometer), detects movement, orientation, and magnetic.

  • Onboard SHTC3 digital temperature and humidity sensor, allows monitoring the environment

  • Onboard LPS22HB barometric pressure sensor, allows monitoring the environment

  • Onboard TCS34725 color sensor, identifies the color of nearby object

  • Onboard ADS1015 ADC, 4-ch 12-bit precision, AD expansion to support more external sensors

  • Brings I2C control pins, for connecting other host boards like STM32

Thanks for the heads up on the Elixir Circuits website. It’s back up now.

Elixir Circuits handles the communication to each of those devices. I’m not sure if anyone has published libraries for those sensors. I feel like the ADC and color sensor have code out there some where.

There are three main approaches to adding support for a chip if no one has made an Elixir library already:

  1. Download the part’s datasheet and implement it yourself by making calls to Circuits.I2C. The SHTC3 part is probably a good one to start since it has a short datasheet and you could experiment with it at the iex prompt.
  2. Port a Python library. This works with the datasheet is hard to understand.
  3. Don’t use Elixir Circuits at all and go through a Linux device driver

I’d start with the SHTC3 or TCS34725 since those seem more straightforward than the others. I think that it depends on what you want to do with the IMU (ICM20948) and ADC. If you just want to get values out of it, Elixir is fine. If you’re using those to control a drone or something where dropping a sample would be really bad, then I’d look at Linux’s IIO drivers. This isn’t meant to be a critique of Elixir, but more that writing timing critical device drivers in Linux userland can be hard.

One last thing: if you want to experiment with the devices at the IEx prompt, the Circuits Quickstart can help. That project has pre-built images for many Nerves boards. You can copy/paste short Elixir modules into the prompt if you’d like. Of course, you’ll eventually want to make your own firmware image and get away from copy/paste programming at the iex prompt, but for little things and experimentation, I find it pretty convenient.

1 Like

there is an sht3x lib out there:

it’s not updated to circuits - so I would grab above file add to my project - change things to Circuits and try and get going… compare what the code does to the datasheet…

then do TCS34725, usually helpful to find a python library and port it eg

but arduino libs are sometimes also decent, say for the LPS22HB

by then you should have a good understanding of i2c and the elixir part - and be able to tackle the ICM20948 etc.

1 Like

Hello @fhunleth thank you for the info, although I had already found some libraries that maybe I can use.

They are very very similar data sheets, the only library that is in “Circuits” is ADS1115, so I have an example to see how to port other libraries.

The idea is only to collect data from sensors and images to send them through an NB-IoT module with “VintageNet” if we manage to run the SIM7080G module via MQTT or TCP to a server in Phoenix and find a way to do some magic with “Tensorflex” library

The point is that I just started with Elixir a short time ago and I’m still looking at how to put all the pieces of the puzzle together.

Hi @outlog thanks for the info.

1 Like

Hi @fhunleth any tip on how to solve that problem with versions. I was trying to do some test with Circuits.I2C and the ADS115 that is already in Circuits using the Quickstart sample.

Nerves environment
  MIX_TARGET:   rpi0
  MIX_ENV:      dev

** (Mix) Major version mismatch between host and target Erlang/OTP versions
  Host version: 23
  Target version: 22

I already have Erlang 23 on my system, so I tried to follow the Install Doc but I’m having some error with:

➜ circuits_quickstart git:(main) ✗ asdf install erlang

And unistalling Erlang with brew and try to use asdf have the same result, so I finally reinstalled Erlang 23 and get stucked in the first problem with the target version. How can I update the target version to 23 if solve the problem?

sdf_22.3.4.1 is not a kerl-managed Erlang/OTP installation
The asdf_22.3.4.1 build has been deleted
Extracting source code
Building Erlang/OTP (asdf_22.3.4.1), please wait...
APPLICATIONS DISABLED (See: /Users/fgm/.asdf/plugins/erlang/kerl-home/builds/asdf_22.3.4.1/otp_build_22.3.4.1.log)
 * jinterface     : Java compiler disabled by user
 * odbc           : ODBC library - link check failed

DOCUMENTATION INFORMATION (See: /Users/fgm/.asdf/plugins/erlang/kerl-home/builds/asdf_22.3.4.1/otp_build_22.3.4.1.log)
 * documentation  : 
 *                  fop is missing.
 *                  Using fakefop to generate placeholder PDF files.

And the last question, if possible. Could you please point me the best way to port a ElixirALE library to start testing. I’ve been following the doc to port but I’m still missing some initial steps. If I include the library in my deps y need to use ElixirALE also in deps to have the library into the project. And then make needed changes according to porting guide, no good approach when I use mix.deps. I have also look the mix deps documentation for local dependencies, but I’m not sure what is the best way to do it.

Hello @fhunleth if unfortunately or necessity you are working with MacOS 11 Big Sur. And you try to install Elixir Nerves 1.6.3 Keep in mind that if you uninstall Erlang 23 with Hombrew, according with Nerves install documentation, it seems that you will not be able to reinstall that version with asdf, kerl or brew, even building Erlang / OTP from scratch will not be possible for OTP 23.0.3.

It seems that the only version that builds for MacOSX 11 is Erlang/OTP24. With what you will have:

** (Mix) Major version mismatch between host and target Erlang/OTP versions

I have only been able to build Erlang on MacOSX 11 by following this bug note. But only in OTP 24.


I hope it helps, it was a long journey to get here.