circuits_gpio v0.4.6

Porting Elixir/ALE to Circuits.GPIO

The Circuits.GPIO package is the next version of Elixir/ALE's GPIO support. If you're currently using Elixir/ALE, you're encouraged to switch. Here are some benefits:

  1. Supported by both the maintainer of Elixir/ALE and a couple others. They'd prefer to support Circuits.GPIO issues.
  2. Much faster than Elixir/ALE - like it's not even close. The guideline is still to use GPIOs for buttons, LEDs, and other low frequency devices and use specialized device drivers for the rest. However, we know that's not always easy and the extra performance is really nice to have.
  3. Included pull up/pull down support for Raspberry Pi. We'd like to include this for other platforms as well. This was the single-most requested feature for Elixir/ALE.
  4. Timestamped interrupt reports - This is makes it possible to measure time deltas between GPIO changes with higher accuracy by removing variability from messages sitting in queues and passing between processes
  5. Interrupt glitch detection - When the GPIO toggles faster than Circuits.GPIO can handle, it can either synthesize an interrupt event or suppress the event.
  6. Lower resource usage - Elixir/ALE created a GenServer and OS process for each GPIO. Circuits.GPIO creates a NIF resource (Elixir Reference) for each GPIO.

Circuits.GPIO uses Erlang's NIF interface. NIFs have the downside of being able to crash the Erlang VM. Experience with Elixir/ALE has given many of us confidence that this won't be a problem.

Code modifications

Circuits.GPIO is not a GenServer, so if you've added ElixirALE.GPIO to a supervision tree, you'll have to take it out and manually call Circuits.GPIO.open to obtain a reference. A common pattern is to create a GenServer that wraps the GPIO and is descriptive of what the GPIO controls or signals. Put the Circuits.GPIO.open call in your init/1 callback.

The remain modifications should mostly be mechanical:

  1. Rename references to ElixirALE.GPIO to Circuits.GPIO and elixir_ale to circuits_gpio
  2. Change calls to ElixirALE.GPIO.start_link/2 to Circuits.GPIO.open/2. While you're at it, review the arguments to open to not include any GenServer options.
  3. Change calls to ElixirALE.GPIO.set_int/2 to Circuits.GPIO.set_interrupts/3.
  4. Change the pattern match for the GPIO interrupt events to match 4 tuples. They have the form {:circuits_gpio, <pin_number>, <timestamp>, <value>}
  5. Review calls to write/2 to ensure that they pass 0 or 1. ElixirALE allowed users to pass true and false. That won't work. Running Dialyzer should catch this change as well.
  6. Consider adding a call to Circuits.GPIO.close/1 if there's an obvious place to release the GPIO. This is not strictly necessary since the garbage collector will free unreferenced GPIOs.

If you find that you have to make any other changes, please let us know via an issue or PR so that other users can benefit.