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 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 }
- Public Types inherited from modm::I2c
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  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...
enum  OperationAfterRead : uint8_t { OperationAfterRead::Stop = uint8_t(Operation::Stop), OperationAfterRead::Restart = uint8_t(Operation::Restart) }
 Further operations after read 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 Public Member Functions inherited from modm::PeripheralDriver
static void initialize ()
 initializes the peripheral, must be called before use.
static void configurePurpose ()
 configures a peripheral for a specific purpose
static void setParameter ()
 sets a parameter
static void getParameter ()
 returns a parameter
static bool getInterruptFlag ()
 Read an interrupt flag.
static void acknowledgeInterruptFlag ()
template<baudrate_t available, baudrate_t requested, percent_t tolerance>
static void assertBaudrateInTolerance ()
- Static Public Member Functions inherited from modm::I2c
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 Public Attributes inherited from modm::I2c
static constexpr uint8_t Write = 0x00
 Add the Write bit to the slave address.
static constexpr uint8_t Read = 0x01
 Add the Read bit to the slave address.

Additional Inherited Members

- Public Typedefs inherited from modm::I2c
using ConfigurationHandler = void (*)()
 The signature of the configuration function.

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.

Georgi Grinshpun
Niklas Hauser

Member Enumeration Documentation

enum modm::I2cMaster::Error : uint8_t

Errors that can happen during master operation.

Enum ValuesDocumentation

No Error occurred.


The master was reset in software.


Address was transmitted and NACK received.


Data was transmitted and NACK received.


Arbitration was lost during writing or reading.


Misplaced Start or Stop condition.


Bus is busy during Start condition.


Unknown error condition.

Enum ValuesDocumentation

External pull-ups exists in SDA and SCL.


Use weak internal pull-ups on SDA and SCL.

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

Do not reset devices.


Low-Speed datarate of 10kHz.


Standard datarate of 100kHz.


Fast datarate of 400kHz.

Member Function Documentation

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

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.

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.
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 ( )

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 ( )

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 ( )

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.

static bool modm::I2cMaster::start ( I2cTransaction transaction,
ConfigurationHandler  handler = nullptr 

Requests transaction attachment.

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

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