Description

C interface for the the Linux I2C driver.

Developed and tested on the BeagleBone Black but should work fine on any Linux system.

Author: James Strawson

Date: 1/19/2018

Macros
#define	I2C_MAX_BUS 5
	Maximum I2C bus identifier. Default is 5 for a total of 6 busses. This can be increased by the user for special cases. More...

#define	I2C_BUFFER_SIZE 128
	size of i2c buffer in bytes for writing to registers. Only increase if you know what you are doing. More...

Functions
int	rc_i2c_init (int bus, uint8_t devAddr)
	Initializes a bus and sets it to talk to a particular device address. More...

int	rc_i2c_close (int bus)
	Closes an I2C bus. More...

int	rc_i2c_set_device_address (int bus, uint8_t devAddr)
	Changes the device address the bus is configured to talk to. More...

int	rc_i2c_read_byte (int bus, uint8_t regAddr, uint8_t *data)
	Reads a single byte from a device register. More...

int	rc_i2c_read_bytes (int bus, uint8_t regAddr, size_t count, uint8_t *data)
	Reads multiple bytes from a device register. More...

int	rc_i2c_read_word (int bus, uint8_t regAddr, uint16_t *data)
	Reads a single word (16 bits) from a device register. More...

int	rc_i2c_read_words (int bus, uint8_t regAddr, size_t count, uint16_t *data)
	Reads multiple words (16 bytes each) from a device register. More...

int	rc_i2c_write_byte (int bus, uint8_t regAddr, uint8_t data)
	Writes a single byte to a specified register address. More...

int	rc_i2c_write_bytes (int bus, uint8_t regAddr, size_t count, uint8_t *data)
	Writes multiple bytes to a specified register address. More...

int	rc_i2c_write_word (int bus, uint8_t regAddr, uint16_t data)
	Writes a single word (16 bits) to a specified register address. More...

int	rc_i2c_write_words (int bus, uint8_t regAddr, size_t count, uint16_t *data)
	Writes multiple words (16 bits each) to a specified register address. More...

int	rc_i2c_send_bytes (int bus, size_t count, uint8_t *data)
	Sends exactly user-defined data without prepending a register address. More...

int	rc_i2c_send_byte (int bus, uint8_t data)
	Sends exactly user-defined data without prepending a register address. More...

int	rc_i2c_lock_bus (int bus)
	Locks the bus so other threads in the process know the bus is in use. More...

int	rc_i2c_unlock_bus (int bus)
	Unlocks a bus to indicate to other threads in the process that the bus is now free. More...

int	rc_i2c_get_lock (int bus)
	Fetches the current lock state of the bus. More...

int	rc_i2c_get_fd (int bus)
	Gets file descriptor. More...

Macro Definition Documentation

◆ I2C_MAX_BUS

#define I2C_MAX_BUS 5

Maximum I2C bus identifier. Default is 5 for a total of 6 busses. This can be increased by the user for special cases.

◆ I2C_BUFFER_SIZE

#define I2C_BUFFER_SIZE 128

size of i2c buffer in bytes for writing to registers. Only increase if you know what you are doing.

Function Documentation

◆ rc_i2c_init()

int rc_i2c_init	(	int	bus,
		uint8_t	devAddr
	)

Initializes a bus and sets it to talk to a particular device address.

Parameters

[in]	bus	The bus
[in]	devAddr	The device address

Returns: 0 on success or -1 on failure

◆ rc_i2c_close()

int rc_i2c_close ( int bus )

Closes an I2C bus.

Parameters

[in] bus The bus

Returns: 0 on success or -1 on failure

◆ rc_i2c_set_device_address()

int rc_i2c_set_device_address	(	int	bus,
		uint8_t	devAddr
	)

Changes the device address the bus is configured to talk to.

Actually changing the device address in the I2C driver requires a system call and is relatively slow. This function records which device address the bus is set to and will only make the system call if the requested address is different than the set address. This makes it safe to call this function repeatedly with no performance penalty.

Parameters

[in]	bus	The bus
[in]	devAddr	The new device address

Returns: { description_of_the_return_value }

◆ rc_i2c_read_byte()

int rc_i2c_read_byte	(	int	bus,
		uint8_t	regAddr,
		uint8_t *	data
	)

Reads a single byte from a device register.

This sends the device address and register address to be read from before reading the response, works for most i2c devices.

Parameters

[in]	bus	The bus
[in]	regAddr	The register address
[out]	data	The data pointer to write response to.

Returns: 0 on success or -1 on failure

◆ rc_i2c_read_bytes()

int rc_i2c_read_bytes	(	int	bus,
		uint8_t	regAddr,
		size_t	count,
		uint8_t *	data
	)

Reads multiple bytes from a device register.

This sends the device address and register address to be read from before reading the response, works for most i2c devices.

Parameters

[in]	bus	The bus
[in]	regAddr	The register address
[in]	count	number of bytes to read
[out]	data	The data pointer to write response to.

Returns: returns number of bytes read or -1 on failure

◆ rc_i2c_read_word()

int rc_i2c_read_word	(	int	bus,
		uint8_t	regAddr,
		uint16_t *	data
	)

Reads a single word (16 bits) from a device register.

This sends the device address and register address to be read from before reading the response, works for most i2c devices.

Parameters

[in]	bus	The bus
[in]	regAddr	The register address
[out]	data	The data pointer to write response to.

Returns: 0 on success or -1 on failure

◆ rc_i2c_read_words()

int rc_i2c_read_words	(	int	bus,
		uint8_t	regAddr,
		size_t	count,
		uint16_t *	data
	)

Reads multiple words (16 bytes each) from a device register.

This sends the device address and register address to be read from before reading the response, works for most i2c devices.

Parameters

[in]	bus	The bus
[in]	regAddr	The register address
[in]	count	Number of 16-bit words to read, NOT number of bytes to read
[out]	data	The data pointer to write response to.

Returns: 0 on success or -1 on failure

◆ rc_i2c_write_byte()

int rc_i2c_write_byte	(	int	bus,
		uint8_t	regAddr,
		uint8_t	data
	)

Writes a single byte to a specified register address.

This sends the device address and register address followed by the actual data to be written. Works for most i2c devices.

Parameters

[in]	bus	The bus
[in]	regAddr	The register address
[in]	data	Single byte to be writen

Returns: 0 on success or -1 on failure

◆ rc_i2c_write_bytes()

int rc_i2c_write_bytes	(	int	bus,
		uint8_t	regAddr,
		size_t	count,
		uint8_t *	data
	)

Writes multiple bytes to a specified register address.

This sends the device address and register address followed by the actual data to be written. Works for most i2c devices.

Parameters

[in]	bus	The bus
[in]	regAddr	The register address to write to
[in]	count	The number of bytes to write
	data	pointer to user's data to be writen

Returns: 0 on success or -1 on failure

◆ rc_i2c_write_word()

int rc_i2c_write_word	(	int	bus,
		uint8_t	regAddr,
		uint16_t	data
	)

Writes a single word (16 bits) to a specified register address.

This sends the device address and register address followed by the actual data to be written. Works for most i2c devices.

Parameters

[in]	bus	The bus
[in]	regAddr	The register address to write to
[in]	data	16-bit word to be written

Returns: 0 on success or -1 on failure

◆ rc_i2c_write_words()

int rc_i2c_write_words	(	int	bus,
		uint8_t	regAddr,
		size_t	count,
		uint16_t *	data
	)

Writes multiple words (16 bits each) to a specified register address.

This sends the device address and register address followed by the actual data to be written. Works for most i2c devices.

Parameters

[in]	bus	The bus
[in]	regAddr	The register address
[in]	count	Number of 16-bit words to write, NOT number of bytes
[in]	data	The data

Returns: 0 on success or -1 on failure

◆ rc_i2c_send_bytes()

int rc_i2c_send_bytes	(	int	bus,
		size_t	count,
		uint8_t *	data
	)

Sends exactly user-defined data without prepending a register address.

Instead of automatically sending a device address before the data which is typical for reading/writing registers, the rc_i2c_send_bytes function send only the data given by the data argument. This is useful for more complicated IO such as uploading firmware to a device.

Parameters

[in]	bus	The bus
[in]	count	Number of bytes to send
[in]	data	The data

Returns: 0 on success or -1 on failure

◆ rc_i2c_send_byte()

int rc_i2c_send_byte	(	int	bus,
		uint8_t	data
	)

Sends exactly user-defined data without prepending a register address.

Instead of automatically sending a device address before the data which is typical for reading/writing registers, the rc_i2c_send_bytes function send only the data given by the data argument. This is useful for more complicated IO such as uploading firmware to a device.

Parameters

[in]	bus	The bus
[in]	data	The data

Returns: 0 on success or -1 on failure

◆ rc_i2c_lock_bus()

int rc_i2c_lock_bus ( int bus )

Locks the bus so other threads in the process know the bus is in use.

Locking a bus is similar to locking a mutex, it is a way for threads to communicate within one process when sharing a bus. This, however, is not a hard lock in the sense that it does not block and does not stop any of the other functions in this API from being called. It only serves as a flag that can be checked between threads if the user chooses to do so. This is encouraged in multithraded applications to prevent timing-sensitive i2c communication from being interrupted but is not enforced.

All read/write functions in this API will lock the bus during the transaction and return the lockstate to what it was at the beginning of the transaction. Ideally the user should lock the bus themselves before a sequence of transactions and unlock it afterwards.

Parameters

[in] bus The bus ID

Returns: Returns the lock state (0 or 1) when this function is called, or -1 on error.

◆ rc_i2c_unlock_bus()

int rc_i2c_unlock_bus ( int bus )

Unlocks a bus to indicate to other threads in the process that the bus is now free.

see rc_i2c_lock_bus for further description.

Parameters

[in] bus The bus ID

Returns: Returns the lock state (0 or 1) when this function is called, or -1 on error.

◆ rc_i2c_get_lock()

int rc_i2c_get_lock ( int bus )

Fetches the current lock state of the bus.

Parameters

[in] bus The bus ID

Returns: Returns 0 if unlocked, 1 if locked, or -1 on error.

◆ rc_i2c_get_fd()

int rc_i2c_get_fd ( int bus )

Gets file descriptor.

Parameters

[in] bus The bus

Returns: returns file descriptor of the specified bus or -1 on failure

Description

Macros

Functions

Macro Definition Documentation

◆ I2C_MAX_BUS

◆ I2C_BUFFER_SIZE

Function Documentation

◆ rc_i2c_init()

◆ rc_i2c_close()

◆ rc_i2c_set_device_address()

◆ rc_i2c_read_byte()

◆ rc_i2c_read_bytes()

◆ rc_i2c_read_word()

◆ rc_i2c_read_words()

◆ rc_i2c_write_byte()

◆ rc_i2c_write_bytes()

◆ rc_i2c_write_word()

◆ rc_i2c_write_words()

◆ rc_i2c_send_bytes()

◆ rc_i2c_send_byte()

◆ rc_i2c_lock_bus()

◆ rc_i2c_unlock_bus()

◆ rc_i2c_get_lock()

◆ rc_i2c_get_fd()