TwoWire Class Reference

An I2C bus: the Arduino Wire API on one of the chip's I2C peripherals (the global Wire on this board). More...

#include <Wire.h>

Inherits Stream.

Public Types
typedef std::function< void(int)>	cb_function_receive_t
	What onReceive() takes: called with the number of bytes received.
typedef std::function< void(void)>	cb_function_request_t
	What onRequest() takes: called when the master asks for data.

Public Member Functions
	TwoWire ()
	An I2C bus on the variant's SDA and SCL (PC18 and PC19 on this board).
	TwoWire (uint32_t sda, uint32_t scl)
	An I2C bus on the given pins.
void	setSCL (uint32_t scl)
	Sets the SCL pin; call before begin().
void	setSDA (uint32_t sda)
	Sets the SDA pin; call before begin().
void	setSCL (PinName scl)
	Sets the SCL pin; call before begin().
void	setSDA (PinName sda)
	Sets the SDA pin; call before begin().
void	begin (bool generalCall=false)
	Joins the bus as the master, at 100 kHz.
void	begin (uint32_t, uint32_t)
	Joins the bus as the master on the given pins, at 100 kHz.
void	begin (uint8_t, bool generalCall=false, bool NoStretchMode=false)
	Joins the bus as a slave at a 7-bit address (1 means the master, as begin() does).
void	begin (int, bool generalCall=false, bool NoStretchMode=false)
	Joins the bus as a slave at a 7-bit address (the int form).
void	end ()
	Leaves the bus: turns the I2C interrupts off, resets I2C1 and frees the buffers.
void	setClock (uint32_t)
	Sets the bus clock; call after begin().
void	beginTransmission (uint8_t)
	Starts collecting bytes for a slave; nothing goes on the bus until endTransmission().
void	beginTransmission (int)
	Starts collecting bytes for a slave (the int form).
uint8_t	endTransmission (void)
	Sends the bytes collected since beginTransmission(), then a STOP.
uint8_t	endTransmission (uint8_t)
	Sends the bytes collected since beginTransmission(), with or without a STOP.
uint8_t	requestFrom (uint8_t, uint8_t)
	Reads bytes from a slave into the receive buffer, for available() and read().
uint8_t	requestFrom (uint8_t, uint8_t, uint8_t)
	Reads bytes from a slave (Arduino's form with sendStop).
uint8_t	requestFrom (uint8_t, size_t, bool)
	Reads bytes from a slave (Arduino's form with sendStop).
uint8_t	requestFrom (uint8_t, uint8_t, uint32_t, uint8_t, uint8_t)
	Writes a register address to a slave, then reads bytes from it with a repeated start.
uint8_t	requestFrom (int, int)
	Reads bytes from a slave (the int form).
uint8_t	requestFrom (int, int, int)
	Reads bytes from a slave (the int form with sendStop).
virtual size_t	write (uint8_t)
	Adds a byte to the transmission, or, in a slave's onRequest() callback, sends it to the master.
virtual size_t	write (const uint8_t *, size_t)
	Adds bytes to the transmission, or, in a slave's onRequest() callback, sends them to the master.
virtual int	available (void)
	How many received bytes are left to read (after requestFrom(), or in an onReceive() callback).
virtual int	read (void)
	Takes the next received byte.
virtual int	peek (void)
	The next received byte, left in the buffer.
virtual void	flush (void)
	Throws away the received bytes and the transmission's bytes.
void	onReceive (cb_function_receive_t callback)
	Sets what a slave does when the master has sent it a message.
void	onRequest (cb_function_request_t callback)
	Sets what a slave does when the master asks it for data.
size_t	write (unsigned long n)
	Writes the low byte of n (see write(uint8_t)).
size_t	write (long n)
	Writes the low byte of n (see write(uint8_t)).
size_t	write (unsigned int n)
	Writes the low byte of n (see write(uint8_t)).
size_t	write (int n)
	Writes the low byte of n (see write(uint8_t)).
I2C_HandleTypeDef *	getHandle (void)
	The WCH peripheral library's view of this bus: its instance and init structure, for mixing in WCH's own I2C functions.

Detailed Description

An I2C bus: the Arduino Wire API on one of the chip's I2C peripherals (the global Wire on this board).

As a master: beginTransmission(), write() and endTransmission() to send; requestFrom(), then available() and read() to receive. As a slave: begin(address), with onReceive() and onRequest(). It is a Stream, so print() works inside a transmission too.

Member Typedef Documentation

cb_function_receive_t

typedef std::function<void(int)> TwoWire::cb_function_receive_t

What onReceive() takes: called with the number of bytes received.

cb_function_request_t

typedef std::function<void(void)> TwoWire::cb_function_request_t

What onRequest() takes: called when the master asks for data.

Constructor & Destructor Documentation

TwoWire() [1/2]

TwoWire::TwoWire

(

)

An I2C bus on the variant's SDA and SCL (PC18 and PC19 on this board).

TwoWire() [2/2]

TwoWire::TwoWire	(	uint32_t	sda,
		uint32_t	scl
	)

An I2C bus on the given pins.

Parameters

sda	the SDA pin (Arduino pin number).
scl	the SCL pin (Arduino pin number).

Member Function Documentation

setSCL() [1/2]

void TwoWire::setSCL ( uint32_t  scl )

inline

Sets the SCL pin; call before begin().

Parameters

scl	the pin's Arduino number (PC19 on this board).

setSDA() [1/2]

void TwoWire::setSDA ( uint32_t  sda )

inline

Sets the SDA pin; call before begin().

Parameters

sda	the pin's Arduino number (PC18 on this board).

setSCL() [2/2]

void TwoWire::setSCL ( PinName  scl )

inline

Sets the SCL pin; call before begin().

Parameters

scl	the pin's name (PC_19).

setSDA() [2/2]

void TwoWire::setSDA ( PinName  sda )

inline

Sets the SDA pin; call before begin().

Parameters

sda	the pin's name (PC_18).

begin() [1/4]

void TwoWire::begin

(

bool

generalCall = false

)

Joins the bus as the master, at 100 kHz.

Sets the pins up and resets I2C1. If a device holds SDA low (stuck after a reset), clocks SCL 20 times first to free it. Call it once, or end() first: it forgets (and leaks) the buffers it had.

Parameters

generalCall

stored, but not used by this port.

begin() [2/4]

void TwoWire::begin	(	uint32_t	,
		uint32_t
	)

Joins the bus as the master on the given pins, at 100 kHz.

Parameters

• sda: the SDA pin (Arduino pin number).
• scl: the SCL pin (Arduino pin number).

begin() [3/4]

void TwoWire::begin	(	uint8_t	,
		bool	generalCall = false,
		bool	NoStretchMode = false
	)

Joins the bus as a slave at a 7-bit address (1 means the master, as begin() does).

The I2C interrupt then answers the master: see onReceive() and onRequest(). A slave receives at most 32 bytes per message (I2C_TXRX_BUFFER_SIZE).

Parameters

• address: the slave's 7-bit address.

Parameters

generalCall	stored, but not used by this port.
NoStretchMode	stored, but not used by this port.

begin() [4/4]

void TwoWire::begin	(	int	,
		bool	generalCall = false,
		bool	NoStretchMode = false
	)

Joins the bus as a slave at a 7-bit address (the int form).

Parameters

• address: the slave's 7-bit address.

Parameters

generalCall	stored, but not used by this port.
NoStretchMode	stored, but not used by this port.

end()

void TwoWire::end

(

)

Leaves the bus: turns the I2C interrupts off, resets I2C1 and frees the buffers.

setClock()

void TwoWire::setClock

(

uint32_t

)

Sets the bus clock; call after begin().

Parameters

• frequency: in Hz: up to 100000 gives 100 kHz, up to 400000 gives 400 kHz, up to 1000000 gives 1 MHz. Higher values are not valid.

beginTransmission() [1/2]

void TwoWire::beginTransmission

(

uint8_t

)

Starts collecting bytes for a slave; nothing goes on the bus until endTransmission().

Parameters

• address: the slave's 7-bit address.

beginTransmission() [2/2]

void TwoWire::beginTransmission

(

int

)

Starts collecting bytes for a slave (the int form).

Parameters

• address: the slave's 7-bit address.

endTransmission() [1/2]

uint8_t TwoWire::endTransmission

(

void

)

Sends the bytes collected since beginTransmission(), then a STOP.

Blocks until done. With no bytes it only addresses the slave, which is how an I2C scanner finds devices.

Returns

As Arduino's: 0 sent; 2 no slave acknowledged the address; 3 the slave did not acknowledge a data byte; 4 another error (bus busy, timeout). A NACK ends the write with a STOP at once.

endTransmission() [2/2]

uint8_t TwoWire::endTransmission

(

uint8_t

)

Sends the bytes collected since beginTransmission(), with or without a STOP.

Parameters

• sendStop: true: end with a STOP; false: keep the bus, for a repeated start by the requestFrom() that follows.

Returns

0 sent; 2 address not acknowledged; 3 data not acknowledged; 4 another error (see endTransmission()).

requestFrom() [1/6]

uint8_t TwoWire::requestFrom	(	uint8_t	,
		uint8_t
	)

Reads bytes from a slave into the receive buffer, for available() and read().

Blocks until done; the read always ends with a STOP.

Parameters

• address: the slave's 7-bit address.
• quantity: how many bytes, 1 to 255.

Returns

quantity if they all arrived, 0 if the read failed.

Note

The whole read must finish within about 3 ms (I2C_TIMEOUT_TICK): at 100 kHz that is about 30 bytes, at 400 kHz about 120. Raise the clock with setClock(), or read in smaller pieces, for more.

requestFrom() [2/6]

uint8_t TwoWire::requestFrom	(	uint8_t	,
		uint8_t	,
		uint8_t
	)

Reads bytes from a slave (Arduino's form with sendStop).

Parameters

• address: the slave's 7-bit address.
• quantity: how many bytes, 1 to 255.
• sendStop: ignored: this port always ends a read with a STOP.

Returns

quantity if they all arrived, 0 if the read failed.

requestFrom() [3/6]

uint8_t TwoWire::requestFrom	(	uint8_t	,
		size_t	,
		bool
	)

Reads bytes from a slave (Arduino's form with sendStop).

Parameters

• address: the slave's 7-bit address.
• quantity: how many bytes, 1 to 255.
• sendStop: ignored: this port always ends a read with a STOP.

Returns

quantity if they all arrived, 0 if the read failed.

requestFrom() [4/6]

uint8_t TwoWire::requestFrom	(	uint8_t	,
		uint8_t	,
		uint32_t	,
		uint8_t	,
		uint8_t
	)

Writes a register address to a slave, then reads bytes from it with a repeated start.

Parameters

• address: the slave's 7-bit address.
• quantity: how many bytes, 1 to 255.
• iaddress: the register (internal) address, sent first.
• isize: how many bytes of iaddress to send, most significant first: 0 (none, a plain read) to 3.
• sendStop: ignored: this port always ends a read with a STOP.

Returns

quantity if they all arrived, 0 if the read failed.

requestFrom() [5/6]

uint8_t TwoWire::requestFrom	(	int	,
		int
	)

Reads bytes from a slave (the int form).

Parameters

• address: the slave's 7-bit address.
• quantity: how many bytes, 1 to 255.

Returns

quantity if they all arrived, 0 if the read failed.

requestFrom() [6/6]

uint8_t TwoWire::requestFrom	(	int	,
		int	,
		int
	)

Reads bytes from a slave (the int form with sendStop).

Parameters

• address: the slave's 7-bit address.
• quantity: how many bytes, 1 to 255.
• sendStop: ignored: this port always ends a read with a STOP.

Returns

quantity if they all arrived, 0 if the read failed.

write() [1/6]

virtual size_t TwoWire::write ( uint8_t  )

virtual

Adds a byte to the transmission, or, in a slave's onRequest() callback, sends it to the master.

Parameters

• data: the byte.

Returns

1, or 0 if the transmission would pass WIRE_MAX_TX_BUFF_LENGTH bytes (or a slave's byte was not taken).

write() [2/6]

virtual size_t TwoWire::write ( const uint8_t *  , size_t    )

virtual

Adds bytes to the transmission, or, in a slave's onRequest() callback, sends them to the master.

Parameters

• data: the bytes.
• quantity: how many.

Returns

quantity, or 0 if the transmission would pass WIRE_MAX_TX_BUFF_LENGTH bytes (none are added then).

available()

virtual int TwoWire::available ( void  )

virtual

How many received bytes are left to read (after requestFrom(), or in an onReceive() callback).

Returns

the number of bytes.

read()

virtual int TwoWire::read ( void  )

virtual

Takes the next received byte.

Returns

the byte (0-255), or -1 if there is none.

peek()

virtual int TwoWire::peek ( void  )

virtual

The next received byte, left in the buffer.

Returns

the byte (0-255), or -1 if there is none.

flush()

virtual void TwoWire::flush ( void  )

virtual

Throws away the received bytes and the transmission's bytes.

(Unlike Serial.flush(), it does not wait for anything.)

onReceive()

void TwoWire::onReceive

(

cb_function_receive_t

callback

)

Sets what a slave does when the master has sent it a message.

Parameters

callback

called from the I2C interrupt after the master's STOP, with the number of bytes received (1-32); it reads them with read().

onRequest()

void TwoWire::onRequest

(

cb_function_request_t

callback

)

Sets what a slave does when the master asks it for data.

Parameters

callback

called from the I2C interrupt; it answers with write().

write() [3/6]

size_t TwoWire::write ( unsigned long  n )

inline

Writes the low byte of n (see write(uint8_t)).

Parameters

n	the value; only its low 8 bits are sent.

Returns

1, or 0 if it did not fit.

write() [4/6]

size_t TwoWire::write ( long  n )

inline

Writes the low byte of n (see write(uint8_t)).

Parameters

n	the value; only its low 8 bits are sent.

Returns

1, or 0 if it did not fit.

write() [5/6]

size_t TwoWire::write ( unsigned int  n )

inline

Writes the low byte of n (see write(uint8_t)).

Parameters

n	the value; only its low 8 bits are sent.

Returns

1, or 0 if it did not fit.

write() [6/6]

size_t TwoWire::write ( int  n )

inline

Writes the low byte of n (see write(uint8_t)).

Parameters

n	the value; only its low 8 bits are sent.

Returns

1, or 0 if it did not fit.

getHandle()

I2C_HandleTypeDef * TwoWire::getHandle ( void  )

inline

The WCH peripheral library's view of this bus: its instance and init structure, for mixing in WCH's own I2C functions.

Use at your own risk.

Returns

the handle, valid for the object's lifetime.

---

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

• Wire/src/Wire.h