TWI/I2C (Wire) controller, usable as master or slave. More...

#include <Wire.h>

Inheritance diagram for TwoWire:

Public Types
typedef std::function< void(int)>	cb_function_receive_t
	Callback type for slave receive events, called with the number of bytes received.

typedef std::function< void(void)>	cb_function_request_t
	Callback type for slave request events.

Public Member Functions
	TwoWire (pin_size_t sda=SDA, pin_size_t scl=SCL)
	Construct a TwoWire instance using the given pins.

	~TwoWire ()
	Destroy the instance, stopping the TWI interface and releasing its buffers (calls end()).

void	setSCL (pin_size_t scl)
	Set the SCL pin.

void	setSDA (pin_size_t sda)
	Set the SDA pin.

void	setSCL (PinName scl)
	Set the SCL pin.

void	setSDA (PinName sda)
	Set the SDA pin.

void	begin (bool generalCall)
	Initialize the TWI interface as master.

void	begin (pin_size_t sda, pin_size_t scl)
	Initialize the TWI interface as master using the given pins.

void	begin (uint8_t address, bool generalCall=false, bool NoStretchMode=false)
	Initialize the TWI interface as master or slave.

void	begin (int address, bool generalCall=false, bool NoStretchMode=false)
	Initialize the TWI interface as master or slave.

void	begin () override
	Initialize the TWI interface as master with the default pins.

void	begin (uint8_t address) override
	Initialize the TWI interface as master or slave with the default pins.

void	end () override
	Stop the TWI interface and free the Rx and Tx buffers.

void	setClock (uint32_t freq) override
	Set the TWI clock frequency.

void	beginTransmission (uint8_t address) override
	Begin a transmission to a slave device.

void	beginTransmission (int address)
	Begin a transmission to a slave device.

uint8_t	endTransmission (void) override
	Send the buffered data to the slave device, ending with a STOP.

uint8_t	endTransmission (bool stopBit) override
	Send the buffered data to the slave device and end the transmission.

size_t	requestFrom (uint8_t address, size_t len, bool stopBit) override
	Request bytes from a slave device.

size_t	requestFrom (uint8_t address, size_t len) override
	Request bytes from a slave device, sending a STOP after the request.

size_t	requestFrom (uint8_t address, size_t len, uint32_t iaddress, uint8_t isize, bool stopBit)
	Request bytes from a slave device after writing an internal register address.

size_t	write (uint8_t data) override
	Write a byte.

size_t	write (const uint8_t *data, size_t quantity) override
	Write bytes.

int	available (void) override
	Get the number of bytes available for reading from the Rx buffer.

int	read (void) override
	Read a byte from the Rx buffer.

int	peek (void) override
	Read the next byte from the Rx buffer without consuming it.

void	flush (void) override
	Discard the content of the Rx and Tx buffers.

void	onReceive (cb_function_receive_t function)
	Register the function called when a slave receives data from a master.

void	onReceive (void(*function)(int)) override
	Register the function called when a slave receives data from a master.

void	onRequest (cb_function_request_t function)
	Register the function called when a master requests data from this slave.

void	onRequest (void(*function)(void)) override
	Register the function called when a master requests data from this slave.

size_t	write (unsigned long n)
	Write a value as a single byte.

size_t	write (long n)
	Write a value as a single byte.

size_t	write (unsigned int n)
	Write a value as a single byte.

size_t	write (int n)
	Write a value as a single byte.

I2C_HandleTypeDef *	getHandle (void)
	Get the I2C handle, to mix the Arduino API and the STM32Cube HAL API (e.g.

Detailed Description

TWI/I2C (Wire) controller, usable as master or slave.

Constructor & Destructor Documentation

◆ TwoWire()

TwoWire::TwoWire	(	pin_size_t	sda = `SDA`,
		pin_size_t	scl = `SCL`
	)

Construct a TwoWire instance using the given pins.

Parameters

sda	Pin used for SDA. Default: SDA.
scl	Pin used for SCL. Default: SCL.

Member Function Documentation

◆ available()

int TwoWire::available ( void )

override

Get the number of bytes available for reading from the Rx buffer.

Must be called in the slave rx event callback or after requestFrom().

Returns: Number of bytes available.

◆ begin() [1/5]

void TwoWire::begin ( bool generalCall )

Initialize the TWI interface as master.

Parameters

generalCall true to enable the general call address. Default: false.

◆ begin() [2/5]

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

Initialize the TWI interface as master or slave.

The reserved address 0x01 initializes the interface as master, any other address initializes it as slave using this address.

Parameters

address	7-bit own address for slave mode, 0x01 for master mode.
generalCall	true to enable the general call address. Default: false.
NoStretchMode	true to disable clock stretching. Default: false.

◆ begin() [3/5]

void TwoWire::begin	(	pin_size_t	sda,
		pin_size_t	scl
	)

Initialize the TWI interface as master using the given pins.

Parameters

sda	Pin used for SDA.
scl	Pin used for SCL.

◆ begin() [4/5]

void TwoWire::begin ( uint8_t address )

inlineoverride

Initialize the TWI interface as master or slave with the default pins.

Parameters

address 7-bit own address for slave mode, 0x01 for master mode.

◆ begin() [5/5]

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

Initialize the TWI interface as master or slave.

The reserved address 0x01 initializes the interface as master, any other address initializes it as slave using this address.

Parameters

address	7-bit own address for slave mode, 0x01 for master mode.
generalCall	true to enable the general call address. Default: false.
NoStretchMode	true to disable clock stretching. Default: false.

◆ beginTransmission() [1/2]

void TwoWire::beginTransmission ( int address )

Begin a transmission to a slave device.

Data is stored with write() and sent by endTransmission().

Parameters

address 7-bit address of the slave device.

◆ beginTransmission() [2/2]

void TwoWire::beginTransmission ( uint8_t address )

override

Begin a transmission to a slave device.

Data is stored with write() and sent by endTransmission().

Parameters

address 7-bit address of the slave device.

◆ endTransmission() [1/2]

uint8_t TwoWire::endTransmission ( bool stopBit )

override

Send the buffered data to the slave device and end the transmission.

Originally endTransmission() had no parameter. The stopBit parameter indicates whether or not a STOP is performed on the bus: calling endTransmission(false) allows a sketch to perform a repeated start.

Warning: Nothing keeps track of whether the bus tenure has been ended with a STOP. It is very possible to leave the bus in a hung state if no call to endTransmission(true) is made. Some I2C devices behave oddly if they do not see a STOP.

Parameters

stopBit true to send a STOP at the end of the transmission, false to keep the bus for a repeated start.

Returns: 0: success, 1: data too long, 2: NACK on address, 3: NACK on data, 4: other error.

◆ endTransmission() [2/2]

uint8_t TwoWire::endTransmission ( void )

override

Send the buffered data to the slave device, ending with a STOP.

Equivalent to endTransmission(true). Provided for backward compatibility with the original definition and behaviour of endTransmission().

Returns: 0: success, 1: data too long, 2: NACK on address, 3: NACK on data, 4: other error.

◆ getHandle()

I2C_HandleTypeDef * TwoWire::getHandle ( void )

inline

Get the I2C handle, to mix the Arduino API and the STM32Cube HAL API (e.g.

DMA). Use at your own risk.

Returns: Pointer to the I2C handle.

◆ onReceive() [1/2]

void TwoWire::onReceive ( cb_function_receive_t function )

Register the function called when a slave receives data from a master.

Parameters

function Function called with the number of bytes received.

Note: Read the data with available() and read() from this callback.

◆ onReceive() [2/2]

void TwoWire::onReceive ( void(*)(int) function )

override

Register the function called when a slave receives data from a master.

The callback is called with the number of bytes received. Read the data with available() and read() from this callback.

Parameters

function Function called with the number of bytes received.

◆ onRequest() [1/2]

void TwoWire::onRequest ( cb_function_request_t function )

Register the function called when a master requests data from this slave.

Parameters

function Function called on request.

Note: Reply to the master with write() from this callback.

◆ onRequest() [2/2]

void TwoWire::onRequest ( void(*)(void) function )

override

Register the function called when a master requests data from this slave.

Reply to the master with write() from this callback.

Parameters

function Function called on request.

◆ peek()

int TwoWire::peek ( void )

override

Read the next byte from the Rx buffer without consuming it.

Must be called in the slave rx event callback or after requestFrom().

Returns: Next byte, -1 if no data is available.

◆ read()

int TwoWire::read ( void )

override

Read a byte from the Rx buffer.

Must be called in the slave rx event callback or after requestFrom().

Returns: Next byte, -1 if no data is available.

◆ requestFrom() [1/3]

size_t TwoWire::requestFrom	(	uint8_t	address,
		size_t	len
	)

override

Request bytes from a slave device, sending a STOP after the request.

Parameters

address	7-bit address of the slave device.
len	Number of bytes to request.

Returns: Number of bytes read, 0 on error. Read them with available() and read().

◆ requestFrom() [2/3]

size_t TwoWire::requestFrom	(	uint8_t	address,
		size_t	len,
		bool	stopBit
	)

override

Request bytes from a slave device.

Parameters

address	7-bit address of the slave device.
len	Number of bytes to request.
stopBit	true to send a STOP after the request, false to keep the bus for a repeated start.

Returns: Number of bytes read, 0 on error. Read them with available() and read().

◆ requestFrom() [3/3]

size_t TwoWire::requestFrom	(	uint8_t	address,
		size_t	len,
		uint32_t	iaddress,
		uint8_t	isize,
		bool	stopBit
	)

Request bytes from a slave device after writing an internal register address.

This allows a repeated start to access the internal registers of a device.

Parameters

address	7-bit address of the slave device.
len	Number of bytes to request.
iaddress	Internal register address to write before the request.
isize	Size in bytes of the internal address (most significant byte first), limited to 3.
stopBit	true to send a STOP after the request, false to keep the bus for a repeated start.

Returns: Number of bytes read, 0 on error. Read them with available() and read().

◆ setClock()

void TwoWire::setClock ( uint32_t freq )

override

Set the TWI clock frequency.

Parameters

freq	Clock frequency in Hz.

◆ setSCL() [1/2]

void TwoWire::setSCL ( pin_size_t scl )

inline

Set the SCL pin.

Must be called before begin().

Parameters

scl	Pin used for SCL.

◆ setSCL() [2/2]

void TwoWire::setSCL ( PinName scl )

inline

Set the SCL pin.

Must be called before begin().

Parameters

scl	PinName used for SCL.

◆ setSDA() [1/2]

void TwoWire::setSDA ( pin_size_t sda )

inline

Set the SDA pin.

Must be called before begin().

Parameters

sda	Pin used for SDA.

◆ setSDA() [2/2]

void TwoWire::setSDA ( PinName sda )

inline

Set the SDA pin.

Must be called before begin().

Parameters

sda	PinName used for SDA.

◆ write() [1/6]

size_t TwoWire::write	(	const uint8_t *	data,
		size_t	quantity
	)

override

Write bytes.

Must be called in the slave tx event callback or after beginTransmission() and before endTransmission().

Parameters

data	Pointer to the buffer data.
quantity	Number of bytes to write.

Returns: Number of bytes ready to write.

◆ write() [2/6]

size_t TwoWire::write ( int n )

inline

Write a value as a single byte.

Parameters

n	Value to write, truncated to a byte.

Returns: Number of bytes written.

◆ write() [3/6]

size_t TwoWire::write ( long n )

inline

Write a value as a single byte.

Parameters

n	Value to write, truncated to a byte.

Returns: Number of bytes written.

◆ write() [4/6]

size_t TwoWire::write ( uint8_t data )

override

Write a byte.

In master transmitter mode the byte is stored in the Tx buffer, in slave mode it is sent to the master. Must be called in the slave tx event callback or after beginTransmission() and before endTransmission().

Parameters

data	Byte to write.

Returns: Number of bytes ready to write: 1 on success, 0 on error.

◆ write() [5/6]

size_t TwoWire::write ( unsigned int n )

inline

Write a value as a single byte.

Parameters

n	Value to write, truncated to a byte.

Returns: Number of bytes written.

◆ write() [6/6]

size_t TwoWire::write ( unsigned long n )

inline

Write a value as a single byte.

Parameters

n	Value to write, truncated to a byte.

Returns: Number of bytes written.

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

libraries/Wire/src/Wire.h
libraries/Wire/src/Wire.cpp

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ TwoWire()

Member Function Documentation

◆ available()

◆ begin() [1/5]

◆ begin() [2/5]

◆ begin() [3/5]

◆ begin() [4/5]

◆ begin() [5/5]

◆ beginTransmission() [1/2]

◆ beginTransmission() [2/2]

◆ endTransmission() [1/2]

◆ endTransmission() [2/2]

◆ getHandle()

◆ onReceive() [1/2]

◆ onReceive() [2/2]

◆ onRequest() [1/2]

◆ onRequest() [2/2]

◆ peek()

◆ read()

◆ requestFrom() [1/3]

◆ requestFrom() [2/3]

◆ requestFrom() [3/3]

◆ setClock()

◆ setSCL() [1/2]

◆ setSCL() [2/2]

◆ setSDA() [1/2]

◆ setSDA() [2/2]

◆ write() [1/6]

◆ write() [2/6]

◆ write() [3/6]

◆ write() [4/6]

◆ write() [5/6]

◆ write() [6/6]