modm API documentation

#include <modm/architecture/interface/i2c_master.hpp>

Inheritance diagram for modm::I2cMaster:
modm::PeripheralDriver modm::I2c modm::I2cMultiplexerChannel< multiplexer, channel > modm::platform::BitBangI2cMaster< Scl, Sda >

Public Typedefs

using ConfigurationHandler = void (*)()
 The signature of the configuration function.
 

Public Types

enum  Error : uint8_t {
  Error::NoError, Error::SoftwareReset, Error::AddressNack, Error::DataNack,
  Error::ArbitrationLost, Error::BusCondition, Error::BusBusy, Error::Unknown
}
 Errors that can happen during master operation. More...
 
enum  PullUps { PullUps::External, PullUps::Internal }
 
enum  ResetDevices : uint32_t { ResetDevices::NoReset = 0, ResetDevices::LowSpeed = 10'000, ResetDevices::Standard = 100'000, ResetDevices::Fast = 400'000 }
 
enum  DetachCause : uint8_t { DetachCause::NormalStop, DetachCause::ErrorCondition, DetachCause::FailedToAttach }
 
enum  TransactionState : uint8_t { TransactionState::Idle, TransactionState::Busy, TransactionState::Error }
 State of a I2c Transaction. More...
 
enum  Operation : uint8_t { Operation::Stop = 0, Operation::Restart = 1, Operation::Write = 2, Operation::Read = 3 }
 All possible I2C Operations. More...
 
enum  OperationAfterRead : uint8_t { OperationAfterRead::Stop = uint8_t(Operation::Stop), OperationAfterRead::Restart = uint8_t(Operation::Restart) }
 Further operations after read operation. More...
 
enum  OperationAfterStart : uint8_t { OperationAfterStart::Stop = uint8_t(Operation::Stop), OperationAfterStart::Write = uint8_t(Operation::Write), OperationAfterStart::Read = uint8_t(Operation::Read) }
 Further operations after start operation. More...
 
enum  OperationAfterWrite : uint8_t { OperationAfterWrite::Stop = uint8_t(Operation::Stop), OperationAfterWrite::Restart = uint8_t(Operation::Restart), OperationAfterWrite::Write = uint8_t(Operation::Write) }
 Further operations after write operation. More...
 

Static Public Member Functions

template<class... Signals>
static void connect (PullUps pullups=PullUps::External, ResetDevices reset=ResetDevices::Standard)
 
template<class SystemClock , baudrate_t baudrate = 100_kBd, percent_t tolerance = 5_pct>
static void initialize ()
 
static bool start (I2cTransaction *transaction, ConfigurationHandler handler=nullptr)
 
static void reset ()
 
static Error getErrorState ()
 
static void acknowledgeInterruptFlag ()
 
template<baudrate_t available, baudrate_t requested, percent_t tolerance>
static void assertBaudrateInTolerance ()
 
static void configurePurpose ()
 configures a peripheral for a specific purpose
 
static bool getInterruptFlag ()
 Read an interrupt flag.
 
static void getParameter ()
 returns a parameter
 
static void initialize ()
 initializes the peripheral, must be called before use.
 
static void setParameter ()
 sets a parameter
 
template<class Scl >
static void resetDevices (uint32_t baudrate=100'000)
 

Static Public Attributes

static constexpr size_t TransactionBufferSize = 8
 Number of transactions which can be queued in this driver.
 
static constexpr uint8_t Read = 0x01
 Add the Read bit to the slave address.
 
static constexpr uint8_t Write = 0x00
 Add the Write bit to the slave address.
 

Detailed Description

Interface of a I2C master.

Performing transfers in background allows the use of DMA etc. and enables the program to do other things while the operation is going on.

Author
Georgi Grinshpun
Niklas Hauser

Member Enumeration Documentation

enum modm::I2c::DetachCause : uint8_t
inheritedstrong

This tells the I2cTransaction why it was detached

See also
I2cTransaction
Enum ValuesDocumentation
NormalStop 

All operations finished normally.

ErrorCondition 

A bus error occurred and the bus was reset.

FailedToAttach 

The I2cTransaction failed to attach to the I2cMaster.

enum modm::I2cMaster::Error : uint8_t
strong

Errors that can happen during master operation.

Enum ValuesDocumentation
NoError 

No Error occurred.

SoftwareReset 

The master was reset in software.

AddressNack 

Address was transmitted and NACK received.

DataNack 

Data was transmitted and NACK received.

ArbitrationLost 

Arbitration was lost during writing or reading.

BusCondition 

Misplaced Start or Stop condition.

BusBusy 

Bus is busy during Start condition.

Unknown 

Unknown error condition.

enum modm::I2c::Operation : uint8_t
inheritedstrong

All possible I2C Operations.

I2C Operations that the I2cTransaction can give the master on callback

See also
I2cTransaction
Enum ValuesDocumentation
Stop 

Generate a Stop Condition.

Restart 

Generate a Restart.

Write 

Write data to the slave.

Read 

Read data from the slave.

enum modm::I2c::OperationAfterRead : uint8_t
inheritedstrong

Further operations after read operation.

Enum ValuesDocumentation
Stop 

Generate a Stop Condition.

Restart 

Generate a Restart.

enum modm::I2c::OperationAfterStart : uint8_t
inheritedstrong

Further operations after start operation.

Enum ValuesDocumentation
Stop 

Generate a Stop Condition.

Write 

Write data to the slave.

Read 

Read data from the slave.

enum modm::I2c::OperationAfterWrite : uint8_t
inheritedstrong

Further operations after write operation.

Enum ValuesDocumentation
Stop 

Generate a Stop Condition.

Restart 

Generate a Restart.

Write 

Write data to the slave.

Enum ValuesDocumentation
External 

External pull-ups exists in SDA and SCL.

Internal 

Use weak internal pull-ups on SDA and SCL.

enum modm::I2cMaster::ResetDevices : uint32_t
strong
Enum ValuesDocumentation
NoReset 

Do not reset devices.

LowSpeed 

Low-Speed datarate of 10kHz.

Standard 

Standard datarate of 100kHz.

Fast 

Fast datarate of 400kHz.

enum modm::I2c::TransactionState : uint8_t
inheritedstrong

State of a I2c Transaction.

Enum ValuesDocumentation
Idle 

No error occurred, detached normally.

Busy 

The transaction object is busy with data transfer.

Error 

An error occurred, check the masters getErrorCode()

Member Function Documentation

static void modm::PeripheralDriver::acknowledgeInterruptFlag ( )
inheritedstatic

Acknowledge an interrupt flag.

We use acknowledge here, since it describes the intention rather than the actual implementation.

template<baudrate_t available, baudrate_t requested, percent_t tolerance>
static void modm::PeripheralDriver::assertBaudrateInTolerance ( )
inheritedinlinestatic

Since baudrates are usually generated by prescaling a system clock, only several distinct values can be generated. This method checks if the user requested baudrate is within error tolerance of the system achievable baudrate.

template<class... Signals>
static void modm::I2cMaster::connect ( PullUps  pullups = PullUps::External,
ResetDevices  reset = ResetDevices::Standard 
)
static

Configures the Scl and Sda signals and connects them.

This configures the Scl and Sda signals as open-drain outputs with optional weak internal pullups and optionally resets all slave devices on the bus.

Warning
Using weak internal pullups is not recommended and will require a slow baudrate. You must use external pullups for a reliable bus.
Template Parameters
SignalsOne Scl and one Sda signal are required and can be passed out-of-order.
Parameters
pullupsUse external or weak internal pullups.
resetChoose a speed to reset the I2C devices with. Can be disabled with ResetDevices::NoReset.
static Error modm::I2cMaster::getErrorState ( )
static

Check the error state of the driver.

The error states are hardware and implementation specific.

template<class SystemClock , baudrate_t baudrate = 100_kBd, percent_t tolerance = 5_pct>
static void modm::I2cMaster::initialize ( )
static

Initializes the hardware and sets the datarate.

Template Parameters
SystemClockthe currently active system clock
baudratethe desired baudrate in Hz
tolerancethe allowed absolute tolerance for the resulting baudrate
static void modm::I2cMaster::reset ( )
static

Perform a software reset of the driver in case of an error and detach the transaction object.

It is strongly recommended to reset the slave devices on the bus after a master reset. You can use the connect() method for that.

template<class Scl >
static void modm::I2c::resetDevices ( uint32_t  baudrate = 100'000)
inheritedinlinestatic

Reset all slave devices connected to an I2C bus.

During normal operation, I2C slave device may pull the SDA line low. However, if the master is reset during a transaction, the I2C clock may stop while the slave is outputting a low data bit and the slave will continue to hold this bit (forever, and ever and ever). The I2C master is then unable to generate a I2C start condition, since SDA is still held low by the slave device, resulting in a deadlock.

"You can always get it back to standby mode by allowing the SDA line to float high and give it 9 clocks. This assures that the device will not receive the acknowledge bit at the end the current byte and will abort the command and go to standby."

See also
Application Note AN572 by Microchip
Warning
Must be called before connecting SDA and SCL to I2cMaster!
Template Parameters
SclThe clock pin of the bus to be reset.
static bool modm::I2cMaster::start ( I2cTransaction transaction,
ConfigurationHandler  handler = nullptr 
)
static

Requests transaction attachment.

Parameters
transactionobject that inherits from the I2cTransaction class.
configurationfunction which configures the master for this transaction.
Returns
Caller gains control if true. Call has no effect if false.

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