Arduino-compatible TwoWire I2C controller/target interface. More...

Topics
	Wire Result Codes

Classes
class	TwoWire
	Arduino Wire-compatible I2C controller/target interface. More...
class	TwoWireObject
	Convenience wrapper binding a TwoWire instance and device address. More...

Typedefs
typedef void	slave_rx_handler(int num_rx)
	Callback type for target (slave) receive events.
typedef void	slave_rq_handler()
	Callback type for target (slave) request events.

Variables
class TwoWire	Wire
	Pre-declared global TwoWire instance using platform default pins.

Detailed Description

Arduino-compatible TwoWire I2C controller/target interface.

#include< Wire.h>

The Wire interface provides an Arduino-compatible API for communicating with I2C devices using the TwoWire class. TwoWire always drives a hardware I2C peripheral. For software bit-banged I2C on arbitrary GPIO pins, see the separate BBI2C class, which is an independent driver and is not used as a fallback by TwoWire.

Key features:

Interrupt-driven hardware I2C peripheral access
Controller (master) and target (slave) modes
Register convenience functions (readRegN(), writeRegN(), etc.)
Thread-safe operation using semaphore-based locking
TwoWireObject helper class for device-address-bound register access

Basic usage flow:

Construct: TwoWire Wire; or TwoWire Wire(sclPin, sdaPin);
Optionally set clock: Wire.setClock(400000);
Initialize: Wire.begin();
Transmit / request data
Shut down: Wire.end();

Note: Every code example on this page is available as working code in the Wire API Documentation Examples example.

I2C Pin Mapping Reference

Each platform defines a valid_i2c[] table listing all supported SCL/SDA pin combinations and their associated hardware I2C modules. The parameterless TwoWire constructor selects the first entry (index 0) of this table.

Warning: If the requested SCL/SDA pair does not appear in the platform's valid_i2c[] table, no hardware module is bound to the object. There is no automatic bit-bang fallback. The resulting TwoWire is inert: begin() does nothing and every transaction fails. Always select a pin pair from the tables below.

Quick Reference: Default Pins Per Platform

Platform	CPU	Default SCL	Default SDA	I2C Module
SOMRT1061	i.MX RT1061	Pins[9] (EMC_12)	Pins[10] (EMC_11)	LPI2C4
MODRT1171	i.MX RT1170	P1[29] (AD_08)	P1[12] (AD_09)	LPI2C1
MODM7AE70	SAME70	P2[42] (PA4)	P2[39] (PA3)	TWIHS0
MOD5441X	MCF5441X	J2[42]	J2[39]	I2C0
NANO54415	MCF5441X	Pins[22]	Pins[20]	I2C1
SB800EX	MCF5441X	Pins[5]	Pins[4]	I2C4

How Default Pins Are Determined

The parameterless constructor always selects the first entry (index 0) of the platform's valid_i2c[] table:

TwoWire::TwoWire()
{
    CorePinSetup(valid_i2c[0].scl, valid_i2c[0].sda);
}

CorePinSetup() walks the valid_i2c[] table looking for a matching SCL/SDA pair, configures the pins to their I2C alternate function, and initializes the corresponding hardware I2C module.

Constructor Options

Constructor	Behavior
TwoWire()	Uses platform default (first entry in valid_i2c[])
TwoWire(int mod)	Binds the specified hardware I2C module. Does not configure pins, the caller owns them.
TwoWire(PinIO scl, PinIO sda)	Searches valid_i2c[] for a matching pin pair
TwoWire(int sclpin, int sdapin)	Same as above but using Pins[] array index numbers

A pin pair that does not appear in valid_i2c[] leaves the object with no hardware module bound. See the warning above.

Source Files

File	Description
nbrtos/include/Wire.h	TwoWire class definition
arch/cortex-m7/cpu/MIMXRT10xx/source/Wire.cpp	SOMRT1061 implementation
arch/cortex-m7/cpu/MIMXRT11xx/source/Wire.cpp	MODRT1171 implementation
arch/cortex-m7/cpu/SAME70/source/Wire.cpp	MODM7AE70 implementation
arch/coldfire/cpu/MCF5441X/source/Wire.cpp	MOD5441X, NANO54415, SB800EX implementation

Per-Platform Pin Tables

SOMRT1061 (MIMXRT10xx)

Hardware modules: LPI2C1, LPI2C2, LPI2C3, LPI2C4

The mod_index in valid_i2c[] is 1-based (1=LPI2C1, 2=LPI2C2, etc.). The last entry with mod_index=0 and PIN_FN_IN is a sentinel/terminator.

The Constructor Arguments column lists the numbers to pass to TwoWire(int sclpin, int sdapin). These are Pins[] indices. For most entries that is also the module connector pin number, but not for entry 1; see the note below the table.

#	SCL Pad	SDA Pad	Pin Function	Module	Constructor Arguments	Notes
0	Pin_EMC_12 (GPIO4[12])	Pin_EMC_11 (GPIO4[11])	PIN_FN_2	LPI2C4	Pins[9], Pins[10]	Default
1	Pin_EMC_22 (GPIO4[22])	Pin_EMC_21 (GPIO4[21])	PIN_FN_2	LPI2C3	Pins[92], Pins[91]	Secondary pads. See the note below
2	Pin_AD_B1_00 (GPIO1[16])	Pin_AD_B1_01 (GPIO1[17])	PIN_FN_3	LPI2C1	Pins[40], Pins[41]
3	Pin_AD_B1_07 (GPIO1[23])	Pin_AD_B1_06 (GPIO1[22])	PIN_FN_1	LPI2C3	Pins[47], Pins[46]
4	Pin_SD_B0_00 (GPIO3[12])	Pin_SD_B0_01 (GPIO3[13])	PIN_FN_2	LPI2C3	Pins[27], Pins[26]

Every entry is reachable on a SOMRT1061. The table lists only pad pairs that the CPU can mux to an LPI2C peripheral and that the module brings out on its connector. The i.MX RT1061 supports further combinations on pads this module does not expose; they are deliberately omitted, since no application on this hardware could use them.

LPI2C2 does not appear. Its pads are not brought out on the SOMRT1061, so it cannot be selected by pin pair. TwoWire(int mod) can still select it, but that constructor does not configure pins.

Note: Entry 1 is the one exception where the constructor argument is not the connector pin number. EMC_22 and EMC_21 are secondary CPU pads bonded to the same traces as module connector pins 83 and 84, and they carry their own Pins[] indices, 92 and 91. Wire the device to connector pins 83 and 84, but pass Pins[92] and Pins[91]. Passing Pins[83] and Pins[84] selects the primary pads EMC_26 and EMC_25, which have no I2C function, so no module is bound and every transaction fails. This entry also requires that nothing else drives those two traces, so leave Pins[83] and Pins[84] high-impedance.

Connector pin numbers and pin functions above are taken from the SOMRT1061 datasheet pinout. Note that a carrier board may already use some of these pins for other purposes; check the schematic for the board in use.

MODRT1171 (MIMXRT11xx)

Hardware modules: LPI2C1 through LPI2C6

The mod_index in valid_i2c[] is 1-based (1=LPI2C1, 2=LPI2C2, etc.). The last entry with mod_index=0 and PIN_FN_IN is a sentinel/terminator. The parameterless constructor selects entry 0 (LPI2C1 on P1[29]/P1[12]). The header-pin columns below are derived by mapping each valid_i2c[] CPU pad through the module's cpuPinMap[] to its P1/P2 connector pin.

#	SCL Pad	SDA Pad	Pin Function	Module	Header Pins (SCL, SDA)	Default
0	Pin_AD_08 (GPIO3[7])	Pin_AD_09 (GPIO3[8])	PIN_FN_1	LPI2C1	P1[29], P1[12]	Yes
1	Pin_AD_32 (GPIO3[31])	Pin_AD_33 (GPIO4[0])	PIN_FN_0	LPI2C1	P1[11], P1[13]
2	Pin_EMC_B2_00 (GPIO2[10])	Pin_EMC_B2_01 (GPIO2[11])	PIN_FN_9	LPI2C2
3	Pin_AD_18 (GPIO3[17])	Pin_AD_19 (GPIO3[18])	PIN_FN_9	LPI2C2	P2[7], P2[8]
4	Pin_DISP_B1_02 (GPIO4[23])	Pin_DISP_B1_03 (GPIO4[24])	PIN_FN_2	LPI2C3
5	Pin_DISP_B2_10 (GPIO5[11])	Pin_DISP_B2_11 (GPIO5[12])	PIN_FN_6	LPI2C3	P2[22], P2[21]
6	Pin_AD_24 (GPIO3[23])	Pin_AD_25 (GPIO3[24])	PIN_FN_9	LPI2C4	P2[4], P2[3]
7	Pin_DISP_B2_12 (GPIO5[13])	Pin_DISP_B2_13 (GPIO5[14])	PIN_FN_6	LPI2C4	P2[24], P2[23]
8	Pin_LPSR_05 (GPIO6[5])	Pin_LPSR_04 (GPIO6[4])	PIN_FN_0	LPI2C5	P1[45], P1[44]
9	Pin_LPSR_09 (GPIO6[9])	Pin_LPSR_08 (GPIO6[8])	PIN_FN_6	LPI2C5	P1[33], P1[32]
10	Pin_LPSR_07 (GPIO6[7])	Pin_LPSR_06 (GPIO6[6])	PIN_FN_0	LPI2C6	P1[47], P1[46]
11	Pin_LPSR_11 (GPIO6[11])	Pin_LPSR_10 (GPIO6[10])	PIN_FN_2	LPI2C6	P1[35], P1[34]

Entries with no header pins listed are valid CPU pin muxing options that are not routed to the MODRT1171 P1/P2 module connectors. Several of these pins also expose secondary SCLS / SDAS and HREQ I2C functions that the Wire driver does not use.

MODM7AE70 (SAME70)

Hardware modules: TWIHS0, TWIHS1, TWIHS2

The mod_index in valid_i2c[] is 1-based (1=TWIHS0, 2=TWIHS1, 3=TWIHS2). The last entry with mod_index=0 is a sentinel/terminator.

#	SCL Pin	SDA Pin	Pin Function	Module	Connector Pins	Default
0	PA4 (PinIO(0,4))	PA3 (PinIO(0,3))	PIN_FN_A	TWIHS0	P2[42], P2[39]	Yes
1	PB5 (PinIO(1,5))	PB4 (PinIO(1,4))	PIN_FN_A	TWIHS1	P2[12], P2[22]
2	PD28 (PinIO(3,28))	PD27 (PinIO(3,27))	PIN_FN_C	TWIHS2	P2[23], P2[26]

Note: Entry 1 needs a change to the platform headers before it will work. Its SCL is PB5, which reaches the connector only at P2[12], and that pin is multiplexed between PA5 and PB5. The shipped default in platform/MODM7AE70/include/pinconstant.h is P2_12_USE_A5, so as built P2[12] is PA5 and this pin pair is unavailable. Select P2_12_USE_B5 instead to use TWIHS1 here. Its SDA, PB4 at P2[22], is unaffected, as are entries 0 and 2.

MOD5441X (MCF5441X)

Hardware modules: I2C0, I2C1

The mod_index in valid_i2c[] is 0-based and used directly. The last entry with mod_index=-1 is a sentinel/terminator.

#	SCL Pin	SDA Pin	Pin Function	Module	Connector Pins	Default
0	J2[42]	J2[39]	3	I2C0	J2 pin 42, J2 pin 39	Yes
1	J2[44]	J2[41]	1	I2C1	J2 pin 44, J2 pin 41

NANO54415 (MCF5441X)

Hardware modules: I2C0, I2C1, I2C4, I2C5

#	SCL Pin	SDA Pin	Pin Function	Module	Connector Pins	Default
0	Pins[22]	Pins[20]	1	I2C1	Pin 22, Pin 20	Yes
1	Pins[26]	Pins[24]	2	I2C4	Pin 26, Pin 24
2	Pins[27]	Pins[29]	3	I2C0	Pin 27, Pin 29
3	Pins[34]	Pins[32]	2	I2C5	Pin 34, Pin 32

SB800EX (MCF5441X)

Hardware modules: I2C4

#	SCL Pin	SDA Pin	Pin Function	Module	Connector Pins	Default
0	Pins[5]	Pins[4]	2	I2C4	Pin 5, Pin 4	Yes

See examples in your NNDK under examples/I2C/Wire

Typedef Documentation

◆ slave_rq_handler

typedef void slave_rq_handler()

#include <Wire.h>

Callback type for target (slave) request events.

Called when the controller requests data from this device. The handler should call TwoWire::write() to queue response bytes.

◆ slave_rx_handler

typedef void slave_rx_handler(int num_rx)