View Source Porting

Upgrading Circuits.GPIO 1.0 projects to 2.0

Circuits.GPIO 2.0 supports alternative GPIO hardware and the ability to mock or emulate devices via backends. The Linux cdev backend is the default and usage is similar to Circuits.GPIO 1.0. Most projects won't need any changes other than to update the dependency in mix.exs. If upgrading a library, The following dependency specification is recommended to allow both circuits_gpio versions:

   {:circuits_gpio, "~> 2.0 or ~> 1.0"}

The following breaking changes were made:

  1. Circuits.GPIO.open/3 opens an exclusive reference to the GPIO. It's no longer possible to have multiple processes open the same GPIO. This sometimes comes up when GPIOs are not closed when they're done being used. The garbage collector will eventually close the GPIO, so you may see intermittent failed opens. The solution is either to open once and pass the handle around or to explicitly close handles after usage.
  2. Circuits.GPIO.open/3 accepts more general pin specifications called gpio_specs. This allows you to specify GPIO controllers and refer to pins by labels. Please see Circuits.GPIO.gpio_spec/0 since referring to pins by number is brittle and has broken in the past.
  3. Circuits.GPIO.open/3 no longer can preserve the previous output value on a pin automatically. I.e., initial_value: :not_set is no longer supported.
  4. Reading the values of output GPIOs is not supported. This does have a chance of working depending on the backend, but it's no longer a requirement of the API since some backends may not be readable. The workaround is to cache what you wrote.
  5. Circuits.GPIO.set_interrupts/3 does not send an initial notification. Notifications are ONLY sent on GPIO transitions now.
  6. The stub implementation still exists and is useful for testing the cdev NIF interface. It's possible to have alternative GPIO backends now. If you have simple needs, the stub is convenient since it provides pairs of connected GPIOs (e.g., 0 and 1, 2 and 3, etc.).
  7. Circuits.GPIO.pin/1 is no longer available.

You should hopefully find that the semantics of API are more explicit now or at least the function documentation is more clear. This was necessary to support more backends without requiring backend authors to implement features that are trickier than you'd expect.

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.