FastArduino  v1.7
C++ library to build fast but small Arduino/AVR projects
i2c::I2CDevice< MANAGER_ > Class Template Reference

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.
 

Protected Types

template<typename T >
using PROXY = typename MANAGER::template PROXY< T >
 The actual type used for all proxies; may be lifecycle::LightProxy or lifecycle::DirectProxy. More...
 
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
 
I2CDeviceoperator= (const I2CDevice &)=delete
 
void set_device (uint8_t device)
 Change the I2C address of this device. More...
 
int launch_commands (PROXY< ABSTRACT_FUTURE > proxy, std::initializer_list< 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 T >
T & resolve (PROXY< T > proxy) const
 Resolve proxy to an actual T (typically a Future). 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...
 
template<typename T >
static PROXY< T > make_proxy (const T &target)
 Create a PROXY from target. More...
 

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 77 of file i2c_device.h.

Member Typedef Documentation

◆ PROXY

template<typename MANAGER_ >
template<typename T >
using i2c::I2CDevice< MANAGER_ >::PROXY = typename MANAGER::template PROXY<T>
protected

The actual type used for all proxies; may be lifecycle::LightProxy or lifecycle::DirectProxy.

This is defined by MANAGER type, whether it uses a lifecycle::AbstractLifeCycleManager or not.

Definition at line 95 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 102 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 109 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
managerthe I2C Manager that is in charge of I2C bus
devicethe 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.
modethe best I2C mode for this device; this determines the I2C Manager types that can manage this device.
auto_stopif 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 129 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
devicethe 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 147 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_countthe 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_futureforce 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.
stopforce a STOP condition on the I2C bus at the end of this command
See also
launch_commands()
write()

Definition at line 174 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_countthe 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_futureforce 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.
stopforce a STOP condition on the I2C bus at the end of this command
See also
launch_commands()
read()

Definition at line 203 of file i2c_device.h.

◆ launch_commands()

template<typename MANAGER_ >
int i2c::I2CDevice< MANAGER_ >::launch_commands ( PROXY< ABSTRACT_FUTURE proxy,
std::initializer_list< 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
proxya proxy (actual type defined by PROXY alias) to the Future containing all write data and ready to store all read data; it is shared by all commands ; passing a Future will be accepted as the compiler will automatically construct the proper proxy for it.
commandsthe list of I2CCommand to be executed, one after another; this list must be embedded within braces {}.
Return values
0when the method did not encounter any error
errors::EINVALif passed arguments are invalid e.g. if commands is empty, if proxy is dynamic but associated MANAGER does not have a lifecycle::LifeCycleManager, or if the total number of bytes read or written by all commands does not match proxy future input and output sizes.
errors::EAGAINif 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::EPROTOif an error occured during command execution
See also
read()
write()
errors

Definition at line 246 of file i2c_device.h.

◆ resolve()

template<typename MANAGER_ >
template<typename T >
T& i2c::I2CDevice< MANAGER_ >::resolve ( PROXY< T >  proxy) const
inlineprotected

Resolve proxy to an actual T (typically a Future).

Template Parameters
Tthe type pointed to by proxy
Parameters
proxythe proxy (actual type defined by PROXY alias) to a Future to resolve
Returns
a reference to the proxied Future

Definition at line 302 of file i2c_device.h.

◆ make_proxy()

template<typename MANAGER_ >
template<typename T >
static PROXY<T> i2c::I2CDevice< MANAGER_ >::make_proxy ( const T &  target)
inlinestaticprotected

Create a PROXY from target.

Depending on actual PROXY type, that may lead to a lifecycle::LightProxy or a lifecycle::DirectProxy. This can be used by device methods working in blocking mode.

Definition at line 313 of file i2c_device.h.


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