I2C Class Reference

#include <ArduboyI2C.h>

Static Public Member Functions
static void	init ()
	Initalizes I2C hardware.
static void	setAddress (uint8_t address, bool generalCall=false)
	Set the address of the device and enable/disable general calls on the I2C bus.
static void	write (uint8_t address, const void *buffer, uint8_t size, bool wait)
	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, bool wait)
	Attempts to become the bus controller (master) and sends data over I2C to the specified address.
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)
	Attempts to become the bus controller (master) and reads data over I2C from the specified address.
static void	transmit (const void *buffer, uint8_t size)
	Transmits data back to the controller (master).
template<typename T >
static void	transmit (const T *object)
	Transmits data back to the controller (master).
static void	onRequest (void(*function)())
	Sets up the callback to be called when data is requested from the device's address (a read).
static void	onReceive (void(*function)())
	Sets up the callback to be called when data is sent to the device's address (a write)
static uint8_t	getTWError ()
	Gets the hardware error which happened in a previous read or write.
static uint8_t *	getBuffer ()
	Gets a pointer to the I2C buffer holding received data.
static bool	detectEmulator ()
	Checks if an emulator without I2C support is being used to run the code.
static uint8_t	getAddressFromId (uint8_t id)
	Gets the address from a provided id.
static uint8_t	handshake ()
	Handshakes with other devices and returns a unique id once complete.

Detailed Description

Provides all I2C functionality.

Member Function Documentation

detectEmulator()

static bool I2C::detectEmulator ( )

static

Checks if an emulator without I2C support is being used to run the code.

Returns

True if an emulator without I2C support has been detected and false if it has not

getAddressFromId()

static uint8_t I2C::getAddressFromId ( uint8_t id )

static

Gets the address from a provided id.

Parameters

id	An id between 0 and I2C_MAX_ADDRESSES - 1

Returns

The address corresponding to that id.

This function is provided to standardize addresses for each id. It is used by I2C::handshake.

getBuffer()

static uint8_t * I2C::getBuffer ( )

static

Gets a pointer to the I2C buffer holding received data.

Intended to be used inside the onReceive callback.

See also

onReceive()

getTWError()

static uint8_t I2C::getTWError ( )

static

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

Returns

A byte indicating the error. TW_SUCCESS means no error has occurred. The full list of error codes are available in the avr utils\twi.h.

handshake()

static uint8_t I2C::handshake ( )

static

Handshakes with other devices and returns a unique id once complete.

Returns

A unique id for this device.

I2C_MAX_PLAYERS must be defined to 1 or more before including the header file to the number of players in the handshake. This function will wait until every single player has joined.

init()

static void I2C::init ( )

static

Initalizes I2C hardware.

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

onReceive()

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

static

Sets up 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.

Example Callback and Usage:

void dataReceive() {
  uint8_t *buffer = I2C::getBuffer();
  players[buffer[0]] = *(player_t *)buffer;
}
...
void setup() {
  ...
  I2C::onReceive(dataReceive);
}

See also

onRequest() write()

onRequest()

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

static

Sets up 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.

Example Callback and Usage:

void dataRequest() {
  I2C::transmit(&players[id], 2);
}
...
void setup() {
  ...
  I2C::onRequest(dataRequest);
}

Note

To respond to the controller (master), use transmit instead of write.

If no bytes are send in the callback, the result of the transmission is undefined.

See also

onReceive() transmit() read()

read() [1/2]

template<typename T >

static void I2C::read ( uint8_t address, T * object )

static

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

Template Parameters

T	The type of the data to read.

Parameters

address	The 7-bit address which 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.

Types with sizes larger than 255 should not be used with this function.

Note

Unlike the write function, this function is bufferless and is not limited to 32 bytes.

See also

write()

read() [2/2]

static 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 which 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 zero.

Note

Unlike the write function, this function is bufferless and is not limited to 32 bytes.

See also

write()

setAddress()

static void I2C::setAddress ( uint8_t address, bool generalCall = false )

static

Set the address of the device and enable/disable general calls on the I2C bus.

Parameters

address	The 7-bit address which to respond to. Addresses 0-7 and 120-127 are reserved by the standard and should not be used.
generalCall	Whether to enable or disable general calls. Defaults to false.

Note

General calls are a way for a device to broadcast data to every other device without addressing them individually. They are sent by sending a write to address 0. If they are disabled, the device will not respond to them.

transmit() [1/2]

template<typename T >

static void I2C::transmit ( const T * object )

static

Transmits data back to the controller (master).

Template Parameters

T	The type of data to transmit.

Parameters

object

A pointer to the data to send.

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

Note

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

See also

write() onRequest()

transmit() [2/2]

static void I2C::transmit ( const void * buffer, uint8_t size )

static

Transmits data back to the controller (master).

Parameters

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

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

Note

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

See also

write() onRequest()

write() [1/2]

template<typename T >

static void I2C::write ( uint8_t address, const T * object, bool wait )

static

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

Template Parameters

T	The type of the data to write.

Parameters

address	The 7-bit address which to send the data. To send a general call, use address 0. Addresses 1-7 and 120-127 are reserved by the standard and should not be used.
buffer	A pointer to the data to send.
wait	Whether or not to wait for the write to complete. If this is false, it will proceed with interrupts.

Note

Sending general calls will only function if the generalCall argument of setAddress is true on every other device.

Interally, this function uses a buffer to enable asynchronous writes. The buffer size is controlled by the macro I2C_BUFFER_SIZE and defaults to 32. If the program needs to send more than 32 bytes at a time, I2C_BUFFER_SIZE must be defined before including to be larger.

See also

transmit() read()

write() [2/2]

static void I2C::write ( uint8_t address, const void * buffer, uint8_t size, bool wait )

static

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

Parameters

address	The 7-bit address which to send the data. To send a general call, use address 0. Addresses 1-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.
wait	Whether or not to wait for the write to complete. If this is false, it will proceed with interrupts.

Note

Sending general calls will only function if the generalCall argument of setAddress is true on every other device.

Interally, this function uses a buffer to enable asynchronous writes. The buffer size is controlled by the macro I2C_BUFFER_SIZE and defaults to 32. If the program needs to send more than 32 bytes at a time, I2C_BUFFER_SIZE must be defined before including to be larger.

See also

transmit() read()

---

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

• ArduboyI2C.h