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
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
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
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"]
close the I2C bus
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.
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.
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
read!(i2c_bus(), i2c_address(), pos_integer(), [opt()]) :: binary()
Initiate a read transaction and raise on error
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)
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)
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)
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)
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)