Base class for all I2C devices. More...

#include <fastarduino/i2c_device.h>

Public Types
using	MANAGER = MANAGER_
	the type of I2C Manager that can handle this device. More...

Protected Types
using	ABSTRACT_FUTURE = typename MANAGER::ABSTRACT_FUTURE
	The abstract base class of all futures to be defined for a device. More...

template<typename OUT , typename IN >
using	FUTURE = typename MANAGER::template FUTURE< OUT, IN >
	The template base class of all futures to be defined for a device. More...

Protected Member Functions
template<I2CMode MODE>
	I2CDevice (MANAGER &manager, uint8_t device, UNUSED Mode< MODE > mode, bool auto_stop)
	Create a new I2C device. More...

	I2CDevice (const I2CDevice &)=delete

I2CDevice &	operator= (const I2CDevice &)=delete

void	set_device (uint8_t device)
	Change the I2C address of this device. More...

int	launch_commands (ABSTRACT_FUTURE &future, utils::range< I2CLightCommand > commands)
	Launch execution (asynchronously or synchronously, depending on MANAGER) of a chain of I2CLightCommand items (constructed with `read()` and `write()` methods). More...

template<typename F >
int	async_read (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing one write followed by one read (typically for device register reading). More...

template<typename F , typename T = uint8_t>
bool	sync_read (T &result)
	Helper method that launches I2C commands for a simple Future performing one write followed by one read (typically for device register reading); the method blocks until the end of the I2C transaction. More...

template<typename F >
int	async_write (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing only one write (typically for device register writing). More...

template<typename F >
int	async_multi_write (F &future, bool stop=true)
	Helper method that asynchronously launches I2C commands for a simple Future performing several register writes. More...

template<typename F , typename T = uint8_t>
bool	sync_write (const T &value)
	Helper method that launches I2C commands for a simple Future performing only one write (typically for device register writing); the method blocks until the end of the I2C transaction. More...

template<typename F >
bool	sync_write ()
	Helper method that launches I2C commands for a simple Future performing only one write (typically for device register writing); the method blocks until the end of the I2C transaction. More...

Static Protected Member Functions
static constexpr I2CLightCommand	read (uint8_t read_count=0, bool finish_future=false, bool stop=false)
	Build a read I2CLightCommand that can be later pushed to the I2C Manager for proper handling. More...

static constexpr I2CLightCommand	write (uint8_t write_count=0, bool finish_future=false, bool stop=false)
	Build a write I2CLightCommand that can be later pushed to the I2C Manager for proper handling. More...

Friends
class	I2CFutureHelper< MANAGER >

Detailed Description

template<typename MANAGER_>
class i2c::I2CDevice< MANAGER_ >

Base class for all I2C devices.

Template Parameters

MANAGER_ the type of I2C Manager used to handle I2C communication

See also: i2c::I2CSyncManager; i2c::I2CAsyncManager

Definition at line 83 of file i2c_device.h.

Member Typedef Documentation

◆ MANAGER

template<typename MANAGER_ >

using i2c::I2CDevice< MANAGER_ >::MANAGER = MANAGER_

the type of I2C Manager that can handle this device.

Definition at line 87 of file i2c_device.h.

◆ ABSTRACT_FUTURE

template<typename MANAGER_ >

using i2c::I2CDevice< MANAGER_ >::ABSTRACT_FUTURE = typename MANAGER::ABSTRACT_FUTURE

protected

The abstract base class of all futures to be defined for a device.

This may be future::AbstractFuture or future::AbstractFakeFuture; this is defined by MANAGER type, whether it is asynchronous or synchronous.

Definition at line 101 of file i2c_device.h.

◆ FUTURE

template<typename MANAGER_ >

template<typename OUT , typename IN >

using i2c::I2CDevice< MANAGER_ >::FUTURE = typename MANAGER::template FUTURE<OUT, IN>

protected

The template base class of all futures to be defined for a device.

This may be future::Future or future::FakeFuture; this is defined by MANAGER type, whether it is asynchronous or synchronous.

Definition at line 108 of file i2c_device.h.

Constructor & Destructor Documentation

◆ I2CDevice()

template<typename MANAGER_ >

template<I2CMode MODE>

i2c::I2CDevice< MANAGER_ >::I2CDevice	(	MANAGER &	manager,
		uint8_t	device,
		UNUSED Mode< MODE >	mode,
		bool	auto_stop
	)

inlineprotected

Create a new I2C device.

This constructor must be called by a subclass implementing an actua I2C device.

Parameters

manager	the I2C Manager that is in charge of I2C bus
device	the 8-bits device address on the I2C bus; it is constructed from the actual 7-bits address, after left-shifting 1 bit. This can be changed dynamically later for devices that support address changes.
mode	the best I2C mode for this device; this determines the I2C Manager types that can manage this device.
auto_stop	if `true`, then any chain of commands (started with `launch_commands()`) will end with a STOP condition generated on the I2C bus; if `false`, then STOP condition will generated only when requested in `read()` or `write()` calls)

See also: set_device()

Definition at line 128 of file i2c_device.h.

Member Function Documentation

◆ set_device()

template<typename MANAGER_ >

void i2c::I2CDevice< MANAGER_ >::set_device ( uint8_t device )

inlineprotected

Change the I2C address of this device.

Parameters

device the 8-bits device address on the I2C bus; it is constructed from the actual 7-bits address, after left-shifting 1 bit. This can be changed dynamically later for devices that support address changes.

Definition at line 146 of file i2c_device.h.

◆ read()

template<typename MANAGER_ >

static constexpr I2CLightCommand i2c::I2CDevice< MANAGER_ >::read	(	uint8_t	read_count = `0`,
		bool	finish_future = `false`,
		bool	stop = `false`
	)

inlinestaticconstexprprotected

Build a read I2CLightCommand that can be later pushed to the I2C Manager for proper handling.

Calling this method has no effect on the bus until the returned command is actually pushed to the I2C Manager through a launch_commands() call.

Parameters

read_count	the number of bytes to read from the device to fill the output value in the Future associated with the I2C transaction; if `0`, the whole output value should be filled by this command.
finish_future	force finishing the Future associated with the created read I2C command; in general, you would never use this value in your own implementation for a device, because FastArduino I2C support already ensures this is done at the end of a complete I2C transaction (with mutiple read and write commands); this could be useful in the exceptional case where your I2C transaction is made of many commands, but you would like to finish the associated Future before the last command is executed, which should be an extraordinarily rare situation.
stop	force a STOP condition on the I2C bus at the end of this command

See also: launch_commands(); write()

Definition at line 173 of file i2c_device.h.

◆ write()

template<typename MANAGER_ >

static constexpr I2CLightCommand i2c::I2CDevice< MANAGER_ >::write	(	uint8_t	write_count = `0`,
		bool	finish_future = `false`,
		bool	stop = `false`
	)

inlinestaticconstexprprotected

Build a write I2CLightCommand that can be later pushed to the I2C Manager for proper handling.

Calling this method has no effect on the bus until the returned command is actually pushed to the I2C Manager through a launch_commands() call.

Parameters

write_count	the number of bytes to get from the storage value in the Future associated with the I2C transaction, in order to write them to the device; if `0`, the whole storage value should be used by this command.
finish_future	force finishing the Future associated with the created write I2C command; in general, you would never use this value in your own implementation for a device, because FastArduino I2C support already ensures this is done at the end of a complete I2C transaction (with mutiple read and write commands); this could be useful in the exceptional case where your I2C transaction is made of many commands, but you would like to finish the associated Future before the last command is executed, which should be an extraordinarily rare situation.
stop	force a STOP condition on the I2C bus at the end of this command

See also: launch_commands(); read()

Definition at line 202 of file i2c_device.h.

◆ launch_commands()

template<typename MANAGER_ >

int i2c::I2CDevice< MANAGER_ >::launch_commands	(	ABSTRACT_FUTURE &	future,
		utils::range< I2CLightCommand >	commands
	)

inlineprotected

Launch execution (asynchronously or synchronously, depending on MANAGER) of a chain of I2CLightCommand items (constructed with read() and write() methods).

With an asynchronous MANAGER, the method returns immediately and one has to use future status to know when all commands have been executed.

With a synchronous MANAGER, this command is blocking and returns only once all commands have been executed on the I2C bus.

I2C commands execution is based on a Future that is used to:

provide data to write commands
store data returned by read commands

Parameters

future	a reference to the Future containing all write data and ready to store all read data; it is shared by all `commands` .
commands	the list of I2CCommand to be executed, one after another; this list must be embedded within braces {}.

Return values

0	when the method did not encounter any error
errors::EINVAL	if passed arguments are invalid e.g. if `commands` is empty, or if the total number of bytes read or written by all `commands` does not match `future` future input and output sizes.
errors::EAGAIN	if the associated `MANAGER` has not enough space in its queue of commands; in such situation, you may retry the same call at a later time.
errors::EPROTO	if an error occured during command execution

See also: read(); write(); errors

Definition at line 243 of file i2c_device.h.

◆ async_read()

template<typename MANAGER_ >

template<typename F >

int i2c::I2CDevice< MANAGER_ >::async_read	(	F &	future,
		bool	stop = `true`
	)

inlineprotected

Helper method that asynchronously launches I2C commands for a simple Future performing one write followed by one read (typically for device register reading).

Warning: Asynchronous API!

Template Parameters

F	the type of `future` automatically deduced from `future`

Parameters

future	a reference to the Future to be updated by the launched I2C commands
stop	force a STOP condition on the I2C bus at the end of the read command

Returns: the same result codes as launch_commands()

See also: launch_commands(); write(); read(); sync_read()

Definition at line 309 of file i2c_device.h.

◆ sync_read()

template<typename MANAGER_ >

template<typename F , typename T = uint8_t>

bool i2c::I2CDevice< MANAGER_ >::sync_read ( T & result )

inlineprotected

Helper method that launches I2C commands for a simple Future performing one write followed by one read (typically for device register reading); the method blocks until the end of the I2C transaction.

Warning: Blocking API!

Template Parameters

F	the type of Future to be used for the I2C transaction; this template argument must be provided as it cannot be deduced from other arguments.
T	the type of expected `result` automatically deduced from `result`

Parameters

result the result read from the I2C transaction

Return values

true	if the action was performed successfully, i.e. `result` contains a correct value

See also: launch_commands(); write(); read(); async_read()

Definition at line 334 of file i2c_device.h.

◆ async_write()

template<typename MANAGER_ >

template<typename F >

int i2c::I2CDevice< MANAGER_ >::async_write	(	F &	future,
		bool	stop = `true`
	)

inlineprotected

Helper method that asynchronously launches I2C commands for a simple Future performing only one write (typically for device register writing).

Warning: Asynchronous API!

Template Parameters

F	the type of `future` automatically deduced from `future`

Parameters

future	a reference to the Future to be updated by the launched I2C commands
stop	force a STOP condition on the I2C bus at the end of the write command

Returns: the same result codes as launch_commands()

See also: launch_commands(); write(); sync_write()

Definition at line 357 of file i2c_device.h.

◆ async_multi_write()

template<typename MANAGER_ >

template<typename F >

int i2c::I2CDevice< MANAGER_ >::async_multi_write	(	F &	future,
		bool	stop = `true`
	)

inlineprotected

Helper method that asynchronously launches I2C commands for a simple Future performing several register writes.

Warning: Asynchronous API!

Template Parameters

F	the type of `future` automatically deduced from `future`; this must be a `TWriteMultiRegisterFuture` specialization or a subclass.

Parameters

future	a reference to the Future to be updated by the launched I2C commands
stop	force a STOP condition on the I2C bus at the end of each write command

Returns: the same result codes as launch_commands()

See also: launch_commands(); write(); TWriteMultiRegisterFuture()

Definition at line 379 of file i2c_device.h.

◆ sync_write() [1/2]

template<typename MANAGER_ >

template<typename F , typename T = uint8_t>

bool i2c::I2CDevice< MANAGER_ >::sync_write ( const T & value )

inlineprotected

Helper method that launches I2C commands for a simple Future performing only one write (typically for device register writing); the method blocks until the end of the I2C transaction.

Warning: Blocking API!

Template Parameters

F	the type of Future to be used for the I2C transaction; this template argument must be provided as it cannot be deduced from other arguments. This must have a constructor with one argument of type `T`.
T	the type of `value` automatically deduced from `value`

Parameters

value the value to write in the I2C transaction

Return values

true	if the action was performed successfully, i.e. `value` was correctly transmitted to the device

See also: launch_commands(); write(); async_write()

Definition at line 406 of file i2c_device.h.

◆ sync_write() [2/2]

template<typename MANAGER_ >

template<typename F >

bool i2c::I2CDevice< MANAGER_ >::sync_write ( )

inlineprotected

Helper method that launches I2C commands for a simple Future performing only one write (typically for device register writing); the method blocks until the end of the I2C transaction.

Warning: Blocking API!

Template Parameters

F	the type of Future to be used for the I2C transaction; this template argument must be provided as it cannot be deduced from other arguments. This must have a default constructor.

Return values

true	if the action was performed successfully, i.e. `value` was correctly transmitted to the device

See also: launch_commands(); write(); async_write()

Definition at line 429 of file i2c_device.h.

Friends And Related Function Documentation

◆ I2CFutureHelper< MANAGER >

template<typename MANAGER_ >

friend class I2CFutureHelper< MANAGER >

friend

Definition at line 465 of file i2c_device.h.

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

fastarduino/i2c_device.h

Public Types

Protected Types

Protected Member Functions

Static Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ MANAGER

◆ ABSTRACT_FUTURE

◆ FUTURE

Constructor & Destructor Documentation

◆ I2CDevice()

Member Function Documentation

◆ set_device()

◆ read()

◆ write()

◆ launch_commands()

◆ async_read()

◆ sync_read()

◆ async_write()

◆ async_multi_write()

◆ sync_write() [1/2]

◆ sync_write() [2/2]

Friends And Related Function Documentation

◆ I2CFutureHelper< MANAGER >