TwoWire Class Reference

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

#include <Wire.h>

Public Member Functions
	TwoWire (void)
	Construct a TwoWire using the platform default I2C module.
	TwoWire (int mod)
	Construct a TwoWire using a specific hardware I2C module.
	TwoWire (PinIO scl, PinIO sda)
	Construct a TwoWire using specific SCL/SDA pins.
	TwoWire (int sclpin_num, int sdapin_num)
	Construct a TwoWire using Pins[] array index numbers.
	~TwoWire ()
	Destructor.
void	setClock (uint32_t clockbaud)
	Set the I2C clock speed.
void	begin (uint8_t slave_addr=0)
	Initialize the I2C interface.
void	end ()
	Shut down the I2C interface.
void	beginTransmission (uint8_t address)
	Begin a write transaction to a target device.
int	endTransmission (bool bStop=true)
	End a write transaction and send data on the bus.
size_t	write (const uint8_t *pdata, int len)
	Queue data bytes for transmission.
size_t	write (char v)
	Queue a single char for transmission.
size_t	write (uint8_t v)
	Queue a single byte for transmission.
size_t	write (const char *pStr, int len=-1)
	Queue a string for transmission.
int	requestFrom (uint8_t address, size_t quantity, bool stop=true)
	Request bytes from a target device.
size_t	available ()
	Check how many bytes are available to read.
size_t	read (uint8_t *pbuf, size_t maxlen)
	Read available data into a buffer (non-standard extension)
uint8_t	read ()
	Read the next byte from the receive buffer.
Target functions
void	onReceive (slave_rx_handler *handler)
	Register a callback for target (slave) receive events.
void	onRequest (slave_rq_handler *handler)
	Register a callback for target (slave) request events.
void	setWireTimeout (int timeout_usec=0, bool reset_on_timeout=false)
	Set the transaction completion timeout.
void	clearTimeout ()
	Clear the transaction completion timeout.
bool	getWireTimeoutFlag ()
	Check whether a timeout has occurred.
Non-standard extensions
void	reset ()
	Reset the I2C bus and recover from a hung state.
bool	ping (uint8_t addr)
	Check whether a device is present at the given address.
int	writeRegN (uint8_t dAddr, uint32_t reg, const uint8_t *buf, uint32_t blen)
	Write a number of bytes to a device register.
int	readRegN (uint8_t dAddr, uint32_t reg, uint8_t *buf, uint32_t blen)
	Read a number of bytes from a device register.
int	writeReg8 (uint8_t dAddr, uint32_t reg, uint8_t data)
	Write a single byte to a device register.
int	readReg8 (uint8_t dAddr, uint32_t reg, uint8_t &data)
	Read a single byte from a device register.

Detailed Description

Arduino Wire-compatible I2C controller/target interface.

Provides a TwoWire interface for communicating with I2C devices, compatible with the Arduino Wire library API. Internal 256-byte TX and RX buffers are used to stage data for each transaction. All bus operations are thread-safe using semaphore-based locking.

In addition to the standard Wire API, non-standard extensions are provided for register-level I2C access (writeRegN(), readRegN()), bus scanning (ping()), and bus recovery (reset()).

See also

TwoWireObject for a convenience wrapper that binds a TwoWire instance and device address together.

TwoWire I2C Pin Reference

Overview

The NetBurner TwoWire class (defined in Wire.h) provides an I2C interface compatible with the popular Arduino Wire library. Each CPU architecture defines a valid_i2c[] table that lists all supported SCL/SDA pin combinations and their associated hardware I2C modules.

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

Constructor Options

Constructor	Behavior
TwoWire()	Uses platform default (first entry in valid_i2c[])
TwoWire(int mod)	Uses the specified hardware I2C module number
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

If BBI2C is defined and the specified pins don't match any hardware I2C entry, a software bit-banged I2C implementation is used automatically.

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/SAME70/source/Wire.cpp	MODM7AE70 implementation
arch/coldfire/cpu/MCF5441X/source/Wire.cpp	MOD5441X, NANO54415, SB800EX implementation

---

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.

#	SCL Pin	SDA Pin	Pin Function	Module	Connector Pins	Default
0	Pin_EMC_12 (GPIO4[12])	Pin_EMC_11 (GPIO4[11])	PIN_FN_2	LPI2C4	Pins[9], Pins[10]	Yes
1	Pin_EMC_22 (GPIO4[22])	Pin_EMC_21 (GPIO4[21])	PIN_FN_2	LPI2C3	Pins[83], Pins[84] (secondary/shared trace)
2	Pin_AD_B1_00 (GPIO1[16])	Pin_AD_B0_01 (GPIO1[1])	PIN_FN_0	LPI2C4	Pins[40], —
3	Pin_AD_B1_00 (GPIO1[16])	Pin_AD_B1_01 (GPIO1[17])	PIN_FN_3	LPI2C1	—
4	Pin_AD_B1_07 (GPIO1[23])	Pin_AD_B1_06 (GPIO1[22])	PIN_FN_1	LPI2C3	Pins[47], Pins[46]
5	Pin_B0_04 (GPIO2[4])	Pin_B0_05 (GPIO2[5])	PIN_FN_2	LPI2C3	—
6	Pin_SD_B0_00 (GPIO3[12])	Pin_SD_B0_01 (GPIO3[13])	PIN_FN_2	LPI2C3	Pins[27], Pins[26]
7	Pin_SD_B1_04 (GPIO3[4])	Pin_SD_B1_05 (GPIO3[5])	PIN_FN_2	LPI2C1	—
8	Pin_SD_B1_11 (GPIO3[11])	Pin_SD_B1_10 (GPIO3[10])	PIN_FN_3	LPI2C2	—

Entries without connector pin assignments (marked "—") represent valid CPU pin muxing options that may not be routed to the SOMRT1061 module connector, or may be available on carrier boards or other platforms sharing the MIMXRT10xx CPU.

---

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: P2[12] is a multiplexed pin. Depending on the P2_12_USE_B5 define, it maps to either PB5 (for I2C use) or PA5.

---

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

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

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	Pins[5]	Pins[4]	2	I2C4	Pin 5, Pin 4	Yes

---

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

Constructor & Destructor Documentation

TwoWire() [1/4]

TwoWire::TwoWire

(

void

)

Construct a TwoWire using the platform default I2C module.

Selects the first entry (index 0) in the platform's valid_i2c[] table. See I2C Pin Mapping Reference for default pins on each platform.

TwoWire() [2/4]

TwoWire::TwoWire

(

int

mod

)

Construct a TwoWire using a specific hardware I2C module.

Module numbering is platform-dependent:

• SOMRT1061 (MIMXRT10xx): 1-based (1 = LPI2C1, 2 = LPI2C2, etc.)
• MODM7AE70 (SAME70): 1-based (1 = TWIHS0, 2 = TWIHS1, etc.)
• MOD5441X / NANO54415 (MCF5441X): 0-based (0 = I2C0, 1 = I2C1, etc.)

Parameters

mod	I2C module number (platform-dependent, see above)

TwoWire() [3/4]

TwoWire::TwoWire	(	PinIO	scl,
		PinIO	sda )

Construct a TwoWire using specific SCL/SDA pins.

Searches the platform's valid_i2c[] table for a matching pin pair and configures the corresponding hardware I2C module. If BBI2C is defined and no hardware match is found, software bit-banged I2C is used automatically.

Parameters

scl	SCL pin
sda	SDA pin

See also

I2C Pin Mapping Reference for supported pin combinations per platform

TwoWire() [4/4]

TwoWire::TwoWire	(	int	sclpin_num,
		int	sdapin_num )

Construct a TwoWire using Pins[] array index numbers.

Behaves identically to TwoWire(PinIO, PinIO), but accepts integer indexes into the platform's Pins[] array instead of PinIO objects.

Parameters

sclpin_num	SCL pin index in the Pins[] array
sdapin_num	SDA pin index in the Pins[] array

~TwoWire()

TwoWire::~TwoWire

(

)

Destructor.

Releases I2C hardware resources. Calls end() if the interface is still active.

Member Function Documentation

available()

size_t TwoWire::available

(

)

Check how many bytes are available to read.

Returns the number of unread bytes remaining in the receive buffer after a requestFrom() call.

Return values

Number

of bytes available in the buffer

See also

requestFrom(), read()

begin()

void TwoWire::begin

(

uint8_t

slave_addr = 0

)

Initialize the I2C interface.

Call with no argument (or 0) for controller (master) mode, or with a non-zero 7-bit address for target (slave) mode.

Uses an internal reference counter: multiple begin() calls require a matching number of end() calls before the hardware is released. Call setClock() before the first begin() if a non-default speed is desired.

Parameters

slave_addr

7-bit target address (0 = controller/master mode)

See also

end(), setClock()

beginTransmission()

void TwoWire::beginTransmission

(

uint8_t

address

)

Begin a write transaction to a target device.

Sets the target address and clears the transmit buffer. Queue data bytes with write() calls, then call endTransmission() to execute the transaction on the bus. Nothing is sent until endTransmission() is called.

---

Expand for Example Usage

Write Transaction Example

Example: Write Two Bytes to a Device Register

#include <wire.h>
 
TwoWire Wire;
 
void UserMain(void *pd)
{
    Wire.begin();
 
    Wire.beginTransmission(0x48);   // Target address
    Wire.write(0x01);               // Register address
    Wire.write(0x80);               // Data byte
    int result = Wire.endTransmission();
    if (result != wire_success)
    {
        iprintf("I2C write failed: %d\r\n", result);
    }
}

---

Parameters

address

7-bit I2C address of the target device

See also

endTransmission(), write()

clearTimeout()

void TwoWire::clearTimeout

(

)

Clear the transaction completion timeout.

Disables any timeout previously set by setWireTimeout().

See also

setWireTimeout()

end()

void TwoWire::end

(

)

Shut down the I2C interface.

Decrements the internal reference counter. The hardware is only released when the counter reaches zero (i.e., every begin() has been matched by an end()).

See also

begin()

endTransmission()

int TwoWire::endTransmission

(

bool

bStop = true

)

End a write transaction and send data on the bus.

Transmits the data queued since beginTransmission(). By default sends a stop condition and releases the bus; pass false to send a repeated start instead (useful for combined write-then-read sequences).

Parameters

bStop

If true (default), sends a stop condition and releases the bus. If false, sends a repeated start for a follow-up transaction.

Return values

wire_success	(0) Transaction completed successfully
wire_data_too_big	(1) Data exceeds the 256-byte transmit buffer
wire_NACK_on_address	(2) Target did not acknowledge its address
wire_NACK_on_data	(3) Target did not acknowledge a data byte
wire_other_error	(4) Unspecified bus error
wire_timeout	(5) Transaction timed out

See also

beginTransmission(), Wire Result Codes

getWireTimeoutFlag()

bool TwoWire::getWireTimeoutFlag

(

)

Check whether a timeout has occurred.

Returns true if a transaction has timed out since the last call to clearTimeout() or setWireTimeout().

Return values

true	A timeout has occurred
false	No timeout has occurred

See also

setWireTimeout(), clearTimeout()

onReceive()

void TwoWire::onReceive

(

slave_rx_handler *

handler

)

Register a callback for target (slave) receive events.

The handler is called from interrupt context when this device (operating in target mode) receives data from a controller. Keep the handler short and avoid blocking calls. Not supported on the BBI2C software interface.

Parameters

handler

Pointer to the function to call when bytes are received

See also

onRequest(), begin()

onRequest()

void TwoWire::onRequest

(

slave_rq_handler *

handler

)

Register a callback for target (slave) request events.

The handler is called from interrupt context when a controller requests data from this device. The handler should call write() to queue response bytes. Keep the handler short and avoid blocking calls. Not supported on the BBI2C software interface.

Parameters

handler

Pointer to the function to call when bytes are requested

See also

onReceive(), begin()

ping()

bool TwoWire::ping

(

uint8_t

addr

)

Check whether a device is present at the given address.

Sends a start condition and address byte, then checks for an ACK. Useful for scanning the I2C bus to discover connected devices.

---

Expand for Example Usage

I2C Bus Scan Example

Example: Scan the I2C Bus

iprintf("Scanning I2C bus...\r\n");
for (uint8_t addr = 1; addr < 127; addr++)
{
    if (Wire.ping(addr))
    {
        iprintf("  Device found at 0x%02X\r\n", addr);
    }
}

---

Parameters

addr	7-bit I2C address to probe

Return values

true	Device acknowledged the address
false	No acknowledgment (device not present or not responding)

read() [1/2]

uint8_t TwoWire::read ( )

inline

Read the next byte from the receive buffer.

Return values

The	next byte of data, or 0 if no data is available

read() [2/2]

size_t TwoWire::read	(	uint8_t *	pbuf,
		size_t	maxlen )

Read available data into a buffer (non-standard extension)

Copies up to maxlen bytes from the receive buffer into pbuf. This is a non-standard extension not found in the Arduino Wire library.

Parameters

pbuf	Pointer to a buffer to read bytes into
maxlen	Maximum number of bytes to read

Return values

Number

of bytes copied, or 0 if no data is available

readReg8()

int TwoWire::readReg8 ( uint8_t dAddr, uint32_t reg, uint8_t & data )

inline

Read a single byte from a device register.

Convenience wrapper around readRegN() for single-byte reads.

Parameters

dAddr	7-bit I2C device address
reg	Register address to read
data	Reference to variable in which to store the register data

Returns

Wire Result Codes

See also

readRegN(), writeReg8()

readRegN()

int TwoWire::readRegN	(	uint8_t	dAddr,
		uint32_t	reg,
		uint8_t *	buf,
		uint32_t	blen )

Read a number of bytes from a device register.

Performs a combined I2C write-read transaction: start → address+W → register byte → repeated-start → address+R → data bytes → stop.

Parameters

dAddr	7-bit I2C device address
reg	Register address to read
*buf	Pointer to buffer to store received data
blen	Number of bytes to read

Returns

Wire Result Codes

See also

writeRegN(), readReg8()

requestFrom()

int TwoWire::requestFrom	(	uint8_t	address,
		size_t	quantity,
		bool	stop = true )

Request bytes from a target device.

Sends a read request to the specified address and stores the response in the internal receive buffer. Use available() and read() to retrieve the received data.

---

Expand for Example Usage

Read Transaction Example

Example: Read 2 Bytes from a Device

Wire.requestFrom(0x48, 2);       // Request 2 bytes from address 0x48
while (Wire.available())
{
    uint8_t b = Wire.read();
    iprintf("Received: 0x%02X\r\n", b);
}

---

Parameters

address	7-bit I2C address of the target device
quantity	Number of bytes to request
stop	If true (default), sends a stop condition after the read. If false, sends a repeated start, keeping the bus for a follow-up transaction.

Return values

Number

of bytes actually read and placed in the receive buffer

See also

available(), read()

reset()

void TwoWire::reset

(

)

Reset the I2C bus and recover from a hung state.

Performs a bus recovery sequence by toggling the SCL line to clock out any stuck target device, then re-initializes the I2C peripheral. Use this when the bus is unresponsive, typically after a timeout or incomplete transaction.

See also

setWireTimeout()

setClock()

void TwoWire::setClock ( uint32_t clockbaud )

inline

Set the I2C clock speed.

Must be called before begin() to take effect. Common values:

• 100000 — Standard mode (100 kHz)
• 400000 — Fast mode (400 kHz)

The maximum supported speed is platform-dependent. The default is 200 kHz.

Parameters

clockbaud

Clock speed in Hz

setWireTimeout()

void TwoWire::setWireTimeout	(	int	timeout_usec = 0,
		bool	reset_on_timeout = false )

Set the transaction completion timeout.

Configures a timeout for I2C bus transactions. If a transaction does not complete within the specified time, it is aborted and endTransmission() / requestFrom() returns wire_timeout.

Parameters

timeout_usec	Timeout in microseconds (0 = disable timeout)
reset_on_timeout	If true, automatically calls reset() to recover the bus when a timeout occurs

See also

clearTimeout(), getWireTimeoutFlag(), reset()

write() [1/4]

size_t TwoWire::write ( char v )

inline

Queue a single char for transmission.

Convenience overload that queues one byte. Must be called between beginTransmission() and endTransmission().

Parameters

v	Character value to queue

Return values

Number

of bytes written (1 on success)

write() [2/4]

size_t TwoWire::write ( const char * pStr, int len = -1 )

inline

Queue a string for transmission.

Copies string data into the transmit buffer. If len is -1, the string length is determined automatically via strlen(). Must be called between beginTransmission() and endTransmission().

Parameters

pStr	C-style string to send
len	Number of bytes to send, or -1 to auto-detect length

Return values

Number

of bytes written to the buffer

write() [3/4]

size_t TwoWire::write	(	const uint8_t *	pdata,
		int	len )

Queue data bytes for transmission.

Copies data into the internal 256-byte transmit buffer. Must be called between beginTransmission() and endTransmission(). The total data queued per transaction must not exceed 256 bytes.

Parameters

pdata	Pointer to data to send
len	Number of bytes to queue

Return values

Number

of bytes written to the buffer

See also

beginTransmission(), endTransmission()

write() [4/4]

size_t TwoWire::write ( uint8_t v )

inline

Queue a single byte for transmission.

Convenience overload that queues one byte. Must be called between beginTransmission() and endTransmission().

Parameters

v	Byte value to queue

Return values

Number

of bytes written (1 on success)

writeReg8()

int TwoWire::writeReg8 ( uint8_t dAddr, uint32_t reg, uint8_t data )

inline

Write a single byte to a device register.

Convenience wrapper around writeRegN() for single-byte writes.

Parameters

dAddr	7-bit I2C device address
reg	Register address to write
data	Data byte to write

Returns

Wire Result Codes

See also

writeRegN(), readReg8()

writeRegN()

int TwoWire::writeRegN	(	uint8_t	dAddr,
		uint32_t	reg,
		const uint8_t *	buf,
		uint32_t	blen )

Write a number of bytes to a device register.

Performs a complete I2C write transaction: start → address+W → register byte → data bytes → stop. This is equivalent to:

Wire.beginTransmission(dAddr);
Wire.write(reg);
Wire.write(buf, blen);
Wire.endTransmission();

Note that the register address is not auto-incremented; whether the target device increments its internal pointer is device-specific.

---

Expand for Example Usage

Register Write / Read Example

Example: Write and Read a Device Register

// Write 2 bytes to register 0x10 of device at 0x68
uint8_t txBuf[2] = {0xAB, 0xCD};
int result = Wire.writeRegN(0x68, 0x10, txBuf, 2);
 
// Read 2 bytes from register 0x10 of device at 0x68
uint8_t rxBuf[2];
result = Wire.readRegN(0x68, 0x10, rxBuf, 2);
iprintf("Reg 0x10: 0x%02X 0x%02X\r\n", rxBuf[0], rxBuf[1]);

---

Parameters

dAddr	7-bit I2C device address
reg	Register address to write
*buf	Pointer to buffer containing data to write
blen	Number of bytes to write

Returns

Wire Result Codes

See also

readRegN(), writeReg8()

---

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

• Wire.h