I²C driver

A simple I²C driver. More...

Files
file	i2cDriver.h

Macros
#define	I2C_NO   1
	I²C hardware module number.
#define	I2C_TRX_BUFFER_SIZE   32

Enumerations
enum	i2c_states {   I2C_STATE_idle, I2C_STATE_sendingStart, I2C_STATE_dataTX, I2C_STATE_sendingRestart,   I2C_STATE_sendingStop, I2C_STATE_dataRX, I2C_STATE_ack, I2C_STATE_error,   I2C_STATE_disabled }
	I²C driver states. More...
enum	i2c_errors {   I2C_ERR_noError = 0, I2C_ERR_internal = 1, I2C_ERR_inErrorState = 2, I2C_ERR_busy = 3,   I2C_ERR_TXBufferOverflow = 4, I2C_ERR_RXBufferOverflow = 5, I2C_ERR_slaveNACK = 6, I2C_ERR_nothingReceived = 7,   I2C_ERR_collisionDetected = 8, I2C_ERR_disabled = 9 }
	I²C driver errors. More...

Functions
void	i2c_reset ()
	Enter idle state and reset error variable.
bool	i2c_busy ()
	Check if I²C driver is busy.
void	i2c_init (int brg, bool enableSlewRateControl, int priority)
	Initialise the I²C driver.
void	i2c_disable ()
	Temporarily disable the I²C driver.
void	i2c_enable ()
	Re-enable the I²C driver.
int	i2c_putc (unsigned char address, unsigned char reg, unsigned char data)
	Sends a byte to a device on the I²C bus.
int	i2c_puts (unsigned char address, unsigned char reg, unsigned char *data, size_t len)
	Sends a series of bytes to a device on the I²C bus.
int	i2c_getc (unsigned char address, unsigned char reg)
	Query a byte from a device on the I²C bus. If the reception succeeded, the I²C driver will be in the idle state when the operation is done.
int	i2c_gets (unsigned char address, unsigned char reg, size_t len)
	Query a series of bytes from a device on the I²C bus. If the reception succeeded, the I²C driver will be in the idle state when the operation is done.
int	i2c_getData (unsigned char *data, size_t len)
	Retrieve data captured from a previous i2c_getc()/i2c_gets() call.

Variables
enum i2c_states	i2c_state
	The current I²C driver state.
volatile bool	i2c_stayInErrorState
	Decides whether the I²C driver should remain in the error state once it has entered it.
enum i2c_errors	i2c_error
	Contains the type of error that occured since last reset.

Detailed Description

A simple I²C driver.

Author

Andreas Misje

Date

21.02.13

This is yet another I²C driver. It was written because Microchip's I²C driver left most of the low-level work to the user. This driver attempts to eliminate as much busy-waiting as possible. A state machine is implemented in the I²C interrupt routine. Data transmission and reception is performed in this state machine using a shared TX/RX data buffer.

Note

All slave device addresses will be left bit-shifted inside this driver and the eight read/write bit will be set/unset automatically. Please provide an unshifted address.

Macro Definition Documentation

#define I2C_NO   1

I²C hardware module number.

For many PIC24s this number must be between 1 and 3.

#define I2C_TRX_BUFFER_SIZE   32

Software TX/RX buffer (including address/register bytes)

Enumeration Type Documentation

enum i2c_errors

I²C driver errors.

Enumerator:

I2C_ERR_noError	No error occurred
I2C_ERR_internal	An internal error occurred
I2C_ERR_inErrorState	A function was called while the driver was in an error state
I2C_ERR_busy	The driver is busy
I2C_ERR_TXBufferOverflow	The TX/RX buffer cannot fit the provided data
I2C_ERR_RXBufferOverflow	The provided buffer cannot fit the received data waiting in the TX/RX buffer
I2C_ERR_slaveNACK	The slave did not acknowledge
I2C_ERR_nothingReceived	No bytes has been received
I2C_ERR_collisionDetected	A bus collision was detected
I2C_ERR_disabled	The driver is currently disabled (by i2c_disable())

enum i2c_states

I²C driver states.

Enumerator:

I2C_STATE_idle	Driver is idle
I2C_STATE_sendingStart	Driver is sending start condition
I2C_STATE_dataTX	Driver is sending data from the TX/RX buffer
I2C_STATE_sendingRestart	Driver is sending repeated start condition
I2C_STATE_sendingStop	Driver is sending stop condition
I2C_STATE_dataRX	Driver is receiving data and writing to the TX/RX buffer
I2C_STATE_ack	Driver is acknowledging reception
I2C_STATE_error	Driver is in an error state (see i2c_error). The driver enters this state if any of the following occurs: Slave did not acknowledge An unexpected I²C interrupt occurred A bus collision was detected TX/RX buffer could not fit provided data If i2c_stayInErrorState is true, the I²C driver must be reset manually by calling i2c_reset() if it has entered the error state.
I2C_STATE_disabled	Driver is temporarily disabled (by i2c_disable())

Function Documentation

bool i2c_busy

(

)

Check if I²C driver is busy.

Returns

true if I²C driver is not busy and not in an error state;

void i2c_disable

(

)

Temporarily disable the I²C driver.

I²C interrupt will be disabled. All pending data transmission and reception will be aborted.

void i2c_enable

(

)

Re-enable the I²C driver.

I²C interrupt will be re-enabled. The driver will start in the I2C_STATE_idle state. Any previous data transmission or reception will not be continued.

int i2c_getc	(	unsigned char	address,
		unsigned char	reg
	)

Query a byte from a device on the I²C bus. If the reception succeeded, the I²C driver will be in the idle state when the operation is done.

Parameters

address	slave address (see note about I²C addresses)
reg	register in slave device

Return values

I2C_ERR_noError	no errors occurred. Start condition has been sent
I2C_ERR_inErrorState	the I²C driver is in an error state
I2C_ERR_busy	the I²C driver is busy
I2C_ERR_RXBufferOverflow	the TX/RX buffer is not large enough to contain address, register
I2C_ERR_disabled	the I²C driver is disabled

int i2c_getData	(	unsigned char *	data,
		size_t	len
	)

Retrieve data captured from a previous i2c_getc()/i2c_gets() call.

The I²C driver has to be in the idle state.

Parameters

data	buffer to copy retrieved data into
len	size of the data array. It must be large enough to hold the number of bytes previously requested, otherwise I2C_ERR_RXBufferOverflow will be returned.

Return values

I2C_ERR_noError	no errors occurred. Start condition has been sent
I2C_ERR_inErrorState	the I²C driver is in an error state
I2C_ERR_busy	the I²C driver is busy
I2C_ERR_nothingReceived	no bytes was received
I2C_ERR_RXBufferOverflow	the provided data buffer is not large enough to contain the number of bytes received in the TX/RX buffer
I2C_ERR_disabled	the I²C driver is disabled

int i2c_gets	(	unsigned char	address,
		unsigned char	reg,
		size_t	len
	)

Query a series of bytes from a device on the I²C bus. If the reception succeeded, the I²C driver will be in the idle state when the operation is done.

Parameters

address	slave address (see note about I²C addresses)
reg	register in slave device
len	the number of bytes aniticipated. address must be large enough to contain len bytes.

Return values

I2C_ERR_noError	no errors occurred. Start condition has been sent
I2C_ERR_inErrorState	the I²C driver is in an error state
I2C_ERR_busy	the I²C driver is busy
I2C_ERR_RXBufferOverflow	the TX/RX buffer is not large enough to contain address, register and number of expected bytes to receive
I2C_ERR_disabled	the I²C driver is disabled

void i2c_init	(	int	brg,
		bool	enableSlewRateControl,
		int	priority
	)

Initialise the I²C driver.

Parameters

brg	baud rate generator reload value
enableSlewRateControl	enable slew rate control
priority	interrupt prioriy level. Must be between 0 and 7.

int i2c_putc	(	unsigned char	address,
		unsigned char	reg,
		unsigned char	data
	)

Sends a byte to a device on the I²C bus.

Parameters

address	slave address (see note about I²C addresses)
reg	register in slave device
data	data to write

Return values

I2C_ERR_noError	no errors occurred. Start condition has been sent and transmission has started
I2C_ERR_inErrorState	the I²C driver is in an error state
I2C_ERR_busy	the I²C driver is busy
I2C_ERR_TXBufferOverflow	the TX/RX buffer is not large enought to contain address, register and data
I2C_ERR_disabled	the I²C driver is disabled

int i2c_puts	(	unsigned char	address,
		unsigned char	reg,
		unsigned char *	data,
		size_t	len
	)

Sends a series of bytes to a device on the I²C bus.

Parameters

address	slave address (see note about I²C addresses)
reg	register in slave device
data	data to write
len	number of bytes to write. If 0, the data is assumed to be a null-terminated string, and the length of the string is used instead.

Return values

I2C_ERR_noError	no errors occurred. Start condition has been sent and transmission has started
I2C_ERR_inErrorState	the I²C driver is in an error state
I2C_ERR_busy	the I²C driver is busy
I2C_ERR_TXBufferOverflow	the TX/RX buffer is not large enought to contain address, register and data
I2C_ERR_disabled	the I²C driver is disabled

Variable Documentation

enum i2c_errors i2c_error

Contains the type of error that occured since last reset.

See Also

i2c_errors

enum i2c_states i2c_state

The current I²C driver state.

See Also

i2c_states

volatile bool i2c_stayInErrorState

Decides whether the I²C driver should remain in the error state once it has entered it.

If the I²C driver enters the error state, it will stay in the error state until reset by using i2c_reset() if this parameter is true. If not, the I²C driver will immediately go to the idle state. The error will be stored in i2c_error in either case.

See Also

i2c_states