circuits_i2c v0.1.0 Circuits.I2C View Source

i2c provides high level abstractions for interfacing to I2C buses on Linux platforms. Internally, it uses the Linux sysclass interface so that it does not require platform-dependent code.

Link to this section Summary

Types

I2C device address

I2C bus

Functions

Return a list of available I2C bus names. If nothing is returned, it’s possible that the kernel driver for that I2C bus is not enabled or the kernel’s device tree is not configured. On Raspbian, run raspi-config and look in the advanced options

close the I2C bus

Provide a helpful message when forgetting to pass a bus name

Scan the I2C bus for devices by performing a read at each device address and returning a list of device addresses that respond

Return info about the low level I2C interface

Open an I2C bus

Initiate a read transaction and raise on error

Initiate a read transaction to the I2C device at the specified address

Write data to the I2C device at address and raise on error

Write data to the I2C device at address

Write data to an I2C device and then immediately issue a read. Raise on errors

Write data to an I2C device and then immediately issue a read

Link to this section Types

Link to this type i2c_address() View Source
i2c_address() :: 0..127

I2C device address

This is a “7-bit” address for the device. Some devices specify an “8-bit” address in their documentation. You can tell if you have an “8-bit” address if it’s greater than 127 (0x7f) or if the documentation talks about different read and write addresses. If you have an 8-bit address, divide it by 2.

I2C bus

Call open/1 to obtain an I2C bus reference and then pass it to the read and write functions for interacting with devices.

Link to this section Functions

Link to this function bus_names() View Source
bus_names() :: [binary()]

Return a list of available I2C bus names. If nothing is returned, it’s possible that the kernel driver for that I2C bus is not enabled or the kernel’s device tree is not configured. On Raspbian, run raspi-config and look in the advanced options.

iex> Circuits.I2C.bus_names()
["i2c-1"]
Link to this function close(i2c_bus) View Source
close(i2c_bus()) :: :ok

close the I2C bus

Link to this function detect_devices() View Source
detect_devices() :: {:error, :no_device}

Provide a helpful message when forgetting to pass a bus name

This is only intended to be called from the iex prompt and it’s almost certainly done by accident.

Link to this function detect_devices(i2c_bus) View Source
detect_devices(i2c_bus() | binary()) :: [i2c_address()] | {:error, term()}

Scan the I2C bus for devices by performing a read at each device address and returning a list of device addresses that respond.

WARNING: This is intended to be a debugging aid. Reading bytes from devices can advance internal state machines and might cause them to get out of sync with other code.

iex> Circuits.I2C.detect_devices("i2c-1")
[4]

The return value is a list of device addresses that were detected on the specified I2C bus. If you get back 'Hh' or other letters, then IEx converted the list to an Erlang string. Run i v() to get information about the return value and look at the raw string representation for addresses.

If you already have a reference to an open device, then you may pass its reference to detect_devices/1 instead.

Return info about the low level I2C interface

This may be helpful when debugging I2C issues.

Link to this function open(device) View Source
open(binary() | charlist()) :: {:ok, i2c_bus()} | {:error, term()}

Open an I2C bus

I2C bus names depend on the platform. Names are of the form “i2c-n” where the “n” is the bus number. The correct bus number can be found in the documentation for the device or on a schematic. Another option is to call Circuits.I2C.bus_names/0 to list them for you.

I2c buses may be opened more than once. There is no need to share an I2C bus reference between modules.

On success, this returns a reference to the I2C bus. Use the reference in subsequent calls to read and write I2C devices

Link to this function read!(i2c_bus, address, bytes_to_read, opts \\ []) View Source
read!(i2c_bus(), i2c_address(), pos_integer(), [opt()]) :: binary()

Initiate a read transaction and raise on error

Link to this function read(i2c_bus, address, bytes_to_read, opts \\ []) View Source
read(i2c_bus(), i2c_address(), pos_integer(), [opt()]) ::
  {:ok, binary()} | {:error, term()}

Initiate a read transaction to the I2C device at the specified address

Options:

  • :retries - number of retries before failing (defaults to no retries)
Link to this function write!(i2c_bus, address, data, opts \\ []) View Source
write!(i2c_bus(), i2c_address(), binary(), [opt()]) :: :ok

Write data to the I2C device at address and raise on error

Options:

  • :retries - number of retries before failing (defaults to no retries)
Link to this function write(i2c_bus, address, data, opts \\ []) View Source
write(i2c_bus(), i2c_address(), binary(), [opt()]) :: :ok | {:error, term()}

Write data to the I2C device at address.

Options:

  • :retries - number of retries before failing (defaults to no retries)
Link to this function write_read!(i2c_bus, address, write_data, bytes_to_read, opts \\ []) View Source
write_read!(i2c_bus(), i2c_address(), binary(), pos_integer(), [opt()]) ::
  binary()

Write data to an I2C device and then immediately issue a read. Raise on errors.

Options:

  • :retries - number of retries before failing (defaults to no retries)
Link to this function write_read(i2c_bus, address, write_data, bytes_to_read, opts \\ []) View Source
write_read(i2c_bus(), i2c_address(), binary(), pos_integer(), [opt()]) ::
  {:ok, binary()} | {:error, term()}

Write data to an I2C device and then immediately issue a read.

This function is useful for devices that want you to write the “register” location to them first and then issue a read to get its contents. Many devices operate this way and this function will issue the commands back-to-back on the I2C bus. Some I2C devices actually require that the read immediately follows the write. If the target supports this, the I2C transaction will be issued that way. On the Raspberry Pi, this can be enabled globally with File.write!("/sys/module/i2c_bcm2708/parameters/combined", "1")

Options:

  • :retries - number of retries before failing (defaults to no retries)