Software (bit-banged) I2C master driver. More...

#include <bb_i2c.h>

Public Types
enum	Result_t { I2C_RES_ACK , I2C_RES_NACK , I2C_RES_ARB_LST , I2C_RES_BUSY , I2C_RES_ARG , I2C_RES_IN_PROGRESS , I2C_RES_ERR }

Public Member Functions
	BBI2C (PinIO scl, PinIO sda)
	Construct a software I2C bus on the specified GPIO pins.
	BBI2C (const BBI2C &rhs)
	Copy constructor.
void	setup (uint32_t maxBusSpeed)
	Configure the pins and prepare the software I2C bus for use.
void	resetBus ()
	Reset the I2C bus.
void	setNumAddressBytes (uint8_t numAddressBytes=1)
	Specify the register address size for a read or write transaction. A number of bytes, from 0 to 3, can be sent to specify an address up to 24-bit (3 bytes): 0 = none, 1 = 8-bits, 2 = 16-bits, 3 = 24-bits.
virtual Result_t	writeReg8 (uint8_t devAddr, uint32_t reg, uint8_t data)
	Write an 8-bit value to a I2C slave device register.
virtual Result_t	writeReg16 (uint8_t devAddr, uint32_t reg, uint16_t data, int byteOrder)
	Write a 16-bit value to an I2C device register.
virtual Result_t	writeReg32 (uint8_t devAddr, uint32_t reg, uint32_t data, int byteOrder)
	Write a 32-bit value to an I2C device register.
virtual Result_t	readReg8 (uint8_t devAddr, uint32_t reg, uint8_t &data)
	Read an 8-bit value form an I2C slave device register.
virtual Result_t	writeRegN (uint8_t devAddr, uint32_t reg, uint8_t *buf, uint32_t blen)
	Write a number of 8-bit values to an I2C slave to the specified register address.
virtual Result_t	readRegN (uint8_t devAddr, uint32_t reg, uint8_t *buf, uint32_t blen)
	Read a number of 8-bit values from an I2C slave at the specified register address.
void	SetMaxBusDelay (uint16_t milliseconds)
	Set the maximum duration that the bus is allowed to be in use without being clocked before being forcibly reset.
uint32_t	GetBusSpeed ()
	Return the bus speed the software timing is currently set to.

Detailed Description

Software (bit-banged) I2C master driver.

BBI2C implements an I2C master in software by toggling two GPIO pins. It does not use the I2C peripheral hardware. Use it when a design needs an I2C bus on pins that are not routed to a hardware I2C module, or when all hardware modules are already in use.

For hardware I2C, use the TwoWire class in Wire.h, which drives the I2C peripheral modules and provides an Arduino-compatible API.

BBI2C provides register-level convenience calls (readRegN(), writeRegN() and the fixed-width variants) and supports device register addresses of 0 to 3 bytes via setNumAddressBytes(), for parts with no register pointer, or with 8-, 16- or 24-bit register addressing.

Objects are constructed with the SCL and SDA pins to use; nothing is instantiated automatically. Call setup() before the first transaction.

Member Enumeration Documentation

◆ Result_t

enum BBI2C::Result_t

Enumerator
I2C_RES_ACK	Acknowledged.
I2C_RES_NACK	Not acknowledged.
I2C_RES_ARB_LST	Arbitration listening.
I2C_RES_BUSY	Bus is busy.
I2C_RES_ARG	Bad argument.
I2C_RES_IN_PROGRESS	Another transaction is currently in progress.
I2C_RES_ERR	Unknown Error.

Constructor & Destructor Documentation

◆ BBI2C() [1/2]

BBI2C::BBI2C	(	PinIO	scl,
		PinIO	sda )

Construct a software I2C bus on the specified GPIO pins.

Any two GPIO-capable pins may be used. Call setup() before the first transaction to configure the pins and bus speed.

Parameters

scl	Pin to use for the clock line
sda	Pin to use for the data line

◆ BBI2C() [2/2]

BBI2C::BBI2C ( const BBI2C & rhs )

inline

Copy constructor.

Copies the pin assignment together with the bus timing set by setup() and the register address width set by setNumAddressBytes(), so the copy talks to the bus exactly as the original does. Note that both objects then drive the same two pins; there is no arbitration between them.

Member Function Documentation

◆ GetBusSpeed()

uint32_t BBI2C::GetBusSpeed ( )

Return the bus speed the software timing is currently set to.

Reports the nominal speed implied by the clock delay set up by the last setup() call, which may be lower than the speed requested because the delay is a whole number of timer counts.

This is the timing the driver aims for, not measured throughput. The rate actually seen on the bus is lower, because the time spent toggling the GPIO pins between delays is not accounted for here.

Return values

Bus	speed in Hz, or 0 if the requested speed was high enough that no software delay is inserted, in which case the bus runs as fast as the GPIO pins can be toggled.

◆ readReg8()

virtual Result_t BBI2C::readReg8	(	uint8_t	devAddr,
		uint32_t	reg,
		uint8_t &	data )

virtual

Read an 8-bit value form an I2C slave device register.

Parameters

devAddr	Address of I2C device
reg	Register address to read
data	Reference to variable in which to store the register data

Returns: Result_t

◆ readRegN()

virtual Result_t BBI2C::readRegN	(	uint8_t	devAddr,
		uint32_t	reg,
		uint8_t *	buf,
		uint32_t	blen )

virtual

Read a number of 8-bit values from an I2C slave at the specified register address.

Parameters

devAddr	Address of I2C device
reg	Register address to read
*buf	Pointer to buffer to store received data
blen	Number of bytes to read

Returns: Result_t

◆ SetMaxBusDelay()

void BBI2C::SetMaxBusDelay ( uint16_t milliseconds )

Set the maximum duration that the bus is allowed to be in use without being clocked before being forcibly reset.

Deprecated: This function has no effect and never has. Its body is empty, so the timeout it describes is not applied and calling it changes nothing. It is retained only so that existing code continues to compile.

The driver already bounds how long it will wait. Individual bus operations time out on their own, and a transaction that leaves the bus stuck triggers resetBus(). Call resetBus() directly to recover a hung bus.

Parameters

milliseconds Ignored

See also: resetBus()

◆ setNumAddressBytes()

void BBI2C::setNumAddressBytes ( uint8_t numAddressBytes = 1 )

inline

Specify the register address size for a read or write transaction. A number of bytes, from 0 to 3, can be sent to specify an address up to 24-bit (3 bytes): 0 = none, 1 = 8-bits, 2 = 16-bits, 3 = 24-bits.

If you are using a single I2C device, or all devices use the same address size, this function only needs to be called once. If you have multiple I2C devices with different address/register bit sizes, then this function should be called before each read/write operation for each different device.

Parameters

numAddressBytes The number of address bytes to send: 0 - 3. The default value is 1 byte.

◆ setup()

void BBI2C::setup ( uint32_t maxBusSpeed )

Configure the pins and prepare the software I2C bus for use.

Sets both pins to open-drain outputs, releases the bus, and derives the timing for the requested speed. Must be called before the first transaction.

Parameters

maxBusSpeed Target bus speed in Hz. If the specified speed cannot be achieved, a lower bus speed may be used.

◆ writeReg16()

virtual Result_t BBI2C::writeReg16	(	uint8_t	devAddr,
		uint32_t	reg,
		uint16_t	data,
		int	byteOrder )

virtual

Write a 16-bit value to an I2C device register.

Parameters

devAddr	Address of I2C device
reg	Register address to write
data	Data to write to the register
byteOrder	Non-zero sends the most significant byte first (big endian), zero sends the least significant byte first

Returns: Result_t

◆ writeReg32()

virtual Result_t BBI2C::writeReg32	(	uint8_t	devAddr,
		uint32_t	reg,
		uint32_t	data,
		int	byteOrder )

virtual

Write a 32-bit value to an I2C device register.

Parameters

devAddr	Address of I2C device
reg	Register address to write
data	Data to write to the register
byteOrder	Non-zero sends the most significant byte first (big endian), zero sends the least significant byte first

Returns: Result_t

◆ writeReg8()

virtual Result_t BBI2C::writeReg8	(	uint8_t	devAddr,
		uint32_t	reg,
		uint8_t	data )

virtual

Write an 8-bit value to a I2C slave device register.

Parameters

devAddr	Address of I2C device
reg	Register address to write
data	Data to write to register

Returns: Result_t

◆ writeRegN()

virtual Result_t BBI2C::writeRegN	(	uint8_t	devAddr,
		uint32_t	reg,
		uint8_t *	buf,
		uint32_t	blen )

virtual

Write a number of 8-bit values to an I2C slave to the specified register address.

Executing this function will send the following: a start bit, the slave device address and read/write bit, the 8-bit data bytes, and finally a stop bit. Note that the address is not incremented with each 8-bit data value.

Parameters

devAddr	Address of I2C device
reg	Register address to write
*buf	Pointer to buffer containing data to write
blen	Number of bytes to write

Returns: Result_t

The documentation for this class was generated from the following file:

bb_i2c.h

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Result_t

Constructor & Destructor Documentation

◆ BBI2C() [1/2]

◆ BBI2C() [2/2]

Member Function Documentation

◆ GetBusSpeed()

◆ readReg8()

◆ readRegN()

◆ SetMaxBusDelay()

◆ setNumAddressBytes()

◆ setup()

◆ writeReg16()

◆ writeReg32()

◆ writeReg8()

◆ writeRegN()