#include <ArduboyI2C.h>

Public Types
enum class	Mode : uint8_t { Async = 0 , Sync = 1 }
	The mode of an I2C write operation. More...
enum class	Error : uint8_t { WriteAddrNack = TW_MT_SLA_NACK , WriteDataNack = TW_MT_DATA_NACK , ReadAddrNack = TW_MR_SLA_NACK , Bus = TW_BUS_ERROR , None = 0xFF }
	The error code of the last I2C controller (master) operation. More...
enum class	Role : uint8_t { Controller = 0 , Target = 1 }

Static Public Member Functions
static void	begin ()
	Initializes I2C hardware.
static void	end ()
	Deinitializes I2C hardware.
static void	setAddress (uint8_t address)
	Sets the 7-bit address of this device.
static uint8_t	getAddress ()
	Gets the 7-bit address of this device.
static void	write (uint8_t address, const void *buffer, uint8_t size, I2C::Mode mode)
	Attempts to become the bus controller (master) and sends data over I2C to the specified address.
template<typename T>
static void	write (uint8_t address, const T &object, I2C::Mode mode)
template<typename T, size_t N>
static void	write (uint8_t address, const T(&buffer)[N], I2C::Mode mode)
static void	read (uint8_t address, void *buffer, uint8_t size)
	Attempts to become the bus controller (master) and reads data over I2C from the specified address.
template<typename T>
static void	read (uint8_t address, T &object)
template<typename T, size_t N>
static void	read (uint8_t address, T(&buffer)[N])
static void	reply (const void *buffer, uint8_t size)
	Replies back to the controller (master).
template<typename T>
static void	reply (const T &object)
template<typename T, size_t N>
static void	reply (const T(&buffer)[N])
static void	onRequest (void(*function)())
	Sets up/disables the callback to be called when data is requested from the device's address (a read).
static void	onReceive (void(*function)())
	Sets up/disables the callback to be called when data is sent to the device's address (a write).
static Error	getError ()
	Gets the hardware error which happened in a previous read or write.
static uint8_t *	getBuffer ()
	Gets a pointer to the internal buffer used for I2C communication.
static uint8_t	getBufferSize ()
	Gets the size of the data in the internal buffer.
static bool	isActive ()
	Gets whether or not the controller (master) is currently transmitting or receiving data.
static void	checkCableFlipped (void(startFunction)()=nullptr, void(loopFunction)()=nullptr)
	Checks if the I2C cable is flipped, calling a function if it is and waiting for it to be flipped back.
static I2C::Role	handshake (void(startFunction)()=nullptr, void(loopFunction)()=nullptr)
	Waits for another device and returns whether this device is the controller (master) or target (slave).

Static Public Attributes
static constexpr uint8_t	targetAddress = 0x08
	The 7-bit address of the target (slave) device, set by I2C::handshake().
static constexpr uint8_t	nullAddress = 0x09
	The 7-bit address used to indicate a null or invalid address.

Detailed Description

Provides all I2C functionality.

Member Enumeration Documentation

◆ Mode

enum class I2C::Mode : uint8_t

strong

The mode of an I2C write operation.

Enumerator
Async	Asynchronous write. The function will return immediately, and the write will be completed in the background. isActive() checks if the write is still in progress.
Sync	Synchronous write. The function will block until the write is complete.

◆ Error

enum class I2C::Error : uint8_t

strong

The error code of the last I2C controller (master) operation.

Enumerator
WriteAddrNack	The controller (master) sent a write address and the target (slave) did not acknowledge it.
WriteDataNack	The controller (master) sent data and the target (slave) did not acknowledge it.
ReadAddrNack	The controller (master) sent a read address and the target (slave) did not acknowledge it.
Bus	An illegal start or stop condition was detected on the bus.
None	No error. The last operation was successful.

◆ Role

enum class I2C::Role : uint8_t

strong

Enumerator
Controller	The device is the controller (master) and can read/write to the target (slave).
Target	The device is the target (slave) and can only read/write when requested by the controller (master).

Member Function Documentation

◆ begin()

void I2C::begin ( )

static

Initializes I2C hardware.

This function powers on, initializes, and sets up the clock on the TWI hardware. Must be called after Arduboy hardware is initialized as arduboy.boot() (inside arduboy.begin()) disables the I2C (TWI) hardware.

See also: end()

◆ end()

void I2C::end ( )

static

Deinitializes I2C hardware.

This function powers off and deinitializes the TWI hardware. It may be reinitialized by calling begin() again.

See also: begin()

◆ setAddress()

void I2C::setAddress ( uint8_t address )

static

Sets the 7-bit address of this device.

Parameters

address The 7-bit address to set. Addresses 0-7 and 120-127 are reserved by the standard and should not be used.

See also: getAddress()

◆ getAddress()

uint8_t I2C::getAddress ( )

static

Gets the 7-bit address of this device.

Returns: The 7-bit address of this device.

See also: setAddress()

◆ write() [1/3]

void I2C::write	(	uint8_t	address,
		const void *	buffer,
		uint8_t	size,
		I2C::Mode	mode )

static

Attempts to become the bus controller (master) and sends data over I2C to the specified address.

Parameters

address	The 7-bit address to send the data to. Addresses 0-7 and 120-127 are reserved by the standard and should not be used.
buffer	A pointer to the data to send.
size	The amount of data in bytes to send. This cannot be zero.
mode	The mode of the write operation. I2C::Mode::Sync blocks until the write is complete; I2C::Mode::Async returns immediately and completes in the background.

Note: Internally, this function uses a buffer to enable asynchronous writes. The buffer size is controlled by the macro I2C_BUFFER_CAPACITY and defaults to 32. If the program needs to send more than 32 bytes at a time, I2C_BUFFER_CAPACITY must be defined before including ArduboyI2C.h to be greater.; To poll whether asynchronous writes have completed, see if isActive() returns false.; This function will not work inside the onRequest() callback. Send data with reply() instead.

See also: reply() read() isActive()

◆ write() [2/3]

template<typename T>

void I2C::write	(	uint8_t	address,
		const T &	object,
		I2C::Mode	mode )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Template Parameters

T	The type of the object to send. To prevent bugs, T cannot be a pointer.

Parameters

address	The 7-bit address to send the data to. Addresses 0-7 and 120-127 are reserved by the standard and should not be used.
object	A reference to the object to send.
mode	The mode of the write operation. I2C::Mode::Sync blocks until the write is complete; I2C::Mode::Async returns immediately and completes in the background.

This function will automatically deduce the size of the object. Objects with sizes greater than or equal to 255 should not be used with this function.

◆ write() [3/3]

template<typename T, size_t N>

void I2C::write	(	uint8_t	address,
		const T(&)	buffer[N],
		I2C::Mode	mode )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Template Parameters

T	The type of the array to send.
N	The number of elements in the array.

Parameters

address	The 7-bit address to send the data to. Addresses 0-7 and 120-127 are reserved by the standard and should not be used.
buffer	A reference to the array to send.
mode	The mode of the write operation. I2C::Mode::Sync blocks until the write is complete; I2C::Mode::Async returns immediately and completes in the background.

This function will automatically deduce the size of the array. Arrays with sizes greater than or equal to 255 should not be used with this function.

◆ read() [1/3]

void I2C::read	(	uint8_t	address,
		void *	buffer,
		uint8_t	size )

static

Attempts to become the bus controller (master) and reads data over I2C from the specified address.

Parameters

address	The 7-bit address to receive the data from. Addresses 0-7 and 120-127 are reserved by the standard and should not be used.
buffer	A pointer to the buffer in which to store the data.
size	The maximum amount of bytes to receive. This cannot be 0 or 255.

Note: Unlike the write function, this function is bufferless and is not limited to I2C_BUFFER_CAPACITY bytes.

See also: write()

◆ read() [2/3]

template<typename T>

void I2C::read	(	uint8_t	address,
		T &	object )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Template Parameters

T	The type of the object to read. To prevent bugs, T cannot be a pointer.

Parameters

address	The 7-bit address to receive the data from. Addresses 0-7 and 120-127 are reserved by the standard and should not be used.
object	A reference to the object in which to store the data.

This function will automatically deduce the size of the object. Objects with sizes greater than or equal to 255 should not be used with this function.

◆ read() [3/3]

template<typename T, size_t N>

void I2C::read	(	uint8_t	address,
		T(&)	buffer[N] )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Template Parameters

T	The type of the array to read.
N	The number of elements in the array.

Parameters

address	The 7-bit address to receive the data from. Addresses 0-7 and 120-127 are reserved by the standard and should not be used.
buffer	A reference to the array in which to store the data.

This function will automatically deduce the size of the array. Arrays with sizes greater than or equal to 255 should not be used with this function.

◆ reply() [1/3]

void I2C::reply	(	const void *	buffer,
		uint8_t	size )

static

Replies back to the controller (master).

Parameters

buffer	A pointer to the data to reply with.
size	The amount of the data in bytes to reply with.

This function is intended to be called inside the onRequest callback. It fills the I2C buffer with data to then be sent one byte at a time. If it is called more than once, only the last call will be sent.

Note: Internally, this function uses a buffer. The buffer size is controlled by the macro I2C_BUFFER_CAPACITY and defaults to 32. If the program needs to send more than 32 bytes at a time, I2C_BUFFER_CAPACITY must be defined before including ArduboyI2C.h to be greater.

See also: write() onRequest()

◆ reply() [2/3]

template<typename T>

void I2C::reply ( const T & object )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Template Parameters

T	The type of the object to reply with. To prevent bugs, T cannot be a pointer.

Parameters

object A reference to the object to reply with.

This function will automatically deduce the size of the object. Objects with sizes greater than or equal to 255 should not be used with this function.

◆ reply() [3/3]

template<typename T, size_t N>

void I2C::reply ( const T(&) buffer[N] )

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Template Parameters

T	The type of the array to reply with.
N	The number of elements in the array.

Parameters

buffer A reference to the array to reply with.

This function will automatically deduce the size of the array. Arrays with sizes greater than or equal to 255 should not be used with this function.

◆ onRequest()

void I2C::onRequest ( void(* function )() )

static

Sets up/disables the callback to be called when data is requested from the device's address (a read).

Parameters

function The function to be called when data is requested, or nullptr to disable.

Example Callback and Usage:

void dataRequest() {
  I2C::reply(players[id]);
}
...
void setup() {
  ...
  I2C::onRequest(dataRequest);
}

Note: Interrupts are disabled during this callback. Any functions called within it should not rely on interrupts (i.e. no Serial, delay, millis, etc.). To respond to the controller (master), use reply() instead of write().

See also: onReceive() reply() read()

◆ onReceive()

void I2C::onReceive ( void(* function )() )

static

Sets up/disables the callback to be called when data is sent to the device's address (a write).

Parameters

function The function to be called when data is received, or nullptr to disable.

Example Callback and Usage:

void dataReceive() {
    const uint8_t *buffer = I2C::getBuffer();
}
...
void setup() {
  ...
  I2C::onReceive(dataReceive);
}

Note: Interrupts are disabled during this callback. Any functions called within it should not rely on interrupts (i.e. no Serial, delay, millis, etc.).

See also: onRequest() read()

◆ getError()

Error I2C::getError ( )

static

Gets the hardware error which happened in a previous read or write.

Returns: An enum value indicating the error.

◆ getBuffer()

uint8_t * I2C::getBuffer ( )

static

Gets a pointer to the internal buffer used for I2C communication.

Returns: A pointer to the internal buffer.

This function is intended to be used in the onReceive callback to get the data sent by the controller (master).

See also: onReceive()

◆ getBufferSize()

uint8_t I2C::getBufferSize ( )

static

Gets the size of the data in the internal buffer.

Returns: The size of the data in the internal buffer.

This function is intended to be used in the onReceive callback to get the size of the data sent by the controller (master).

See also: onReceive()

◆ isActive()

bool I2C::isActive ( )

static

Gets whether or not the controller (master) is currently transmitting or receiving data.

Returns: true if the controller (master) is currently transmitting or receiving data, false otherwise.

This function is intended to be used to check if an asynchronous write has completed.

See also: write()

◆ checkCableFlipped()

void I2C::checkCableFlipped	(	void(*	startFunction )() = nullptr,
		void(*	loopFunction )() = nullptr )

static

Checks if the I2C cable is flipped, calling a function if it is and waiting for it to be flipped back.

Parameters

startFunction	The function to be called if the cable is flipped. Pass nullptr to disable.
loopFunction	The function to be called while waiting for the cable to be flipped back. Pass nullptr to disable.

This is only needed on the FX-C, as the Arduboy Mini does not have a way to flip the cable. This method must be used with I2C::handshake or an equivalent handshaking method that sends 0b00000000 at a regular interval. Example Usage:

I2C::checkCableFlipped([] {
    arduboy.clear();
    arduboy.print(F("Please flip the cable\non this device."));
    arduboy.display();
});
bool isController = I2C::handshake();

Note: Custom functions should not call I2C functions. They may rely on interrupts. Setting a custom loop function is advanced and requires careful tuning of the I2C_*_CHECKS macros to ensure everything works reliably. Loop functions should be as fast as possible; it is not recommended to use arduboy.nextFrame() within a loop function.

◆ handshake()

I2C::Role I2C::handshake	(	void(*	startFunction )() = nullptr,
		void(*	loopFunction )() = nullptr )

static

Waits for another device and returns whether this device is the controller (master) or target (slave).

Parameters

startFunction	The function to be called while waiting for another device. Pass nullptr to disable.
loopFunction	The function to be called while waiting for another device. Pass nullptr to disable.

Returns: I2C::Role::Controller if this device is the controller (master), I2C::Role::Target if it is the target (slave).

Note: Custom functions should not call I2C functions. They may rely on interrupts. Setting a custom loop function is advanced and requires careful tuning of the I2C_*_CHECKS macros to ensure everything works reliably. Loop functions should be as fast as possible; it is not recommended to use arduboy.nextFrame() within a loop function.

Member Data Documentation

◆ nullAddress

uint8_t I2C::nullAddress = 0x09

staticconstexpr

The 7-bit address used to indicate a null or invalid address.

This is provided for convenience to let a target (slave) soft disconnect from the bus.

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

ArduboyI2C.h

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ Mode

◆ Error

◆ Role

Member Function Documentation

◆ begin()

◆ end()

◆ setAddress()

◆ getAddress()

◆ write() [1/3]

◆ write() [2/3]

◆ write() [3/3]

◆ read() [1/3]

◆ read() [2/3]

◆ read() [3/3]

◆ reply() [1/3]

◆ reply() [2/3]

◆ reply() [3/3]

◆ onRequest()

◆ onReceive()

◆ getError()

◆ getBuffer()

◆ getBufferSize()

◆ isActive()

◆ checkCableFlipped()

◆ handshake()

Member Data Documentation

◆ nullAddress