I2C Python Module

The Onion I2C Library, libonioni2c is a dynamic C library that provides functions to easily read from and write to devices communicating with the Omega via I2C. The library can be used in C and C++ programs.

Also available is a Python module that implements an I2C object using functions from the C library. The module is called onionI2C and is part of the OmegaExpansion package.

Linux and I2C

I2C devices are usually controlled by a kernel driver, however, it is also possible to access devices through an adapter in the Linux filesystem. The adapter can be found at /dev/i2c-X, where X is the adapter number which can range from 0 to 255. On the Omega, /dev/i2c-0 is available by default. This allows users to interact with I2C slaves from the Linux environment.

The Onion I2C library uses the /dev/i2c-0 adapter, and implements read and write functions I2C devices.

The Python Module

The onionI2C Python module in the OmegaExpansion package provides a Python object that serves as a wrapper around the C library functions. The usage is slightly different since the Python module is object oriented and the C library is just a set of functions.

Source Code

The source code can be found in the Onion i2c-exp-driver GitHub Repo.

Programming Flow

Once the I2C object is initialized, the read and write functions can be called freely using the object.

Installing the Module

To install the Python module, run the following commands:

opkg update
opkg install python-light pyOnionI2C

This will install the module to /usr/lib/python2.7/OmegaExpansion/

This only needs to be done once.

To add the Onion I2C Module to your Python program, include the following in your code:

Example

An example of how the onionI2C library is used can be found in the i2c-exp-driver repo.

The example code programs the Relay Expansion directly.

Functions

Function Prototype
Initialization onionI2C.OnionI2C()
Reading Bytes readBytes(devAddr, addr, size)
Write a Single Byte writeByte(devAddr, addr, value)
Write a List of Bytes writeBytes(devAddr, addr, values)
Write a List of Bytes without Specifying an Address write(devAddr, values)

Initialization - onionI2C.OnionI2C()

The object needs to be initialized before it can be used for reading and writing:

After this call, the object can be used for reading and writing.

Arguments

The constructor has an optional argument that defines the I2C device adapter number. This corresponds to the X in /dev/i2c-X.

If no argument is supplied, the adapter will be set to /dev/i2c-0. This is the only default adapter on the Omega and should suit most use cases.

If your use case requires a different adapter, add an integer argument to the constructor call.

Reading from an I2C Slave

Reading Bytes - readBytes()

This function reads a specified number of bytes from a specific device on the I2C bus, and returns them in a list:

Arguments

The devAddr argument defines the I2C slave device address.

The addr argument defines the address on the device from which to read.

The number of bytes to be read should be placed in the size argument.

Examples

Read 4 bytes from address 0x00 on a device with an address of 0x48:

Read a byte from address 0x24 on a device with an address of 0x27:

Note that even though only a single byte is being read, the variable byteList will be in the form of a list.

Writing to an I2C Slave

All writing functions share the same schema for return values: * For a successful write, 0 will be returned * An unsuccessful write will return 1

Write a Single Byte - writeByte()

This function will write a single byte to a specific device on the I2C bus:

Arguments

The devAddr argument defines the I2C slave device address.

The addr argument defines the address on the device that will be written to.

The value argument is the single byte to be written.

Examples

Write 0xef to address 0xf1 on a device with an address of 0x11:

Write 0xbe to address 0xaa on a device with an address of0x33:

Write a List of Bytes - writeBytes()

This function will write a list of bytes to an address on a specific device on the I2C bus:

Arguments

The devAddr argument defines the I2C slave device address.

The addr argument defines the address on the device that will be written to.

The values argument is the list of bytes to be written.

Examples

Write 0xde, 0xad, 0xbe, 0xef to address 0x1a on a device with an address of 0x66:

Write 0xbe to address 0xaa on a device with an address of 0x33:

Write 0x01, 0x03, 0x05 to address 0x55 on a device with an address of 0x24:

Write a List of Bytes without Specifying an Address - write()

This function will write a list of bytes to a specific device on the I2C bus:

It can be used when no specific on address on the device needs to be specified.

Arguments

The devAddr argument defines the I2C slave device address.

The values argument is the list of bytes to be written.

Examples

Write 0xde, 0xad, 0xbe, 0xef to a device with an address of 0x67:

Write 0xaa, 0xbe to a device with an address of 0x34:

Write 0x01, 0x03, 0x05, 0x02, 0x04, 0x06, 0xaa to a device with an address of 0x13: