Wrapper around the nRF51 TWI peripheral. More...

#include <nrfcxx/periph.hpp>

Inheritance diagram for nrfcxx::periph::TWI:

Data Structures
struct	configuration_type

Public Types
using	scoped_enabler = details::scoped_enabler< TWI >
	The scoped enabler uses a TWI instance.

Public Types inherited from nrfcxx::periph::details::comm_error_support
using	size_type = unsigned int
	The type used for transfer sizes (unsigned)

using	ssize_type = int
	The type used for transfer sizes (non-negative) or errors (negative). More...

using	error_type = unsigned int
	The type used to encode TWI peripheral errors. More...

Public Member Functions
const nrf5::TWI_Type &	peripheral () const
	Reference the underlying peripheral.

bool	enabled () const
	Return `true` iff the device is enabled.

scoped_enabler	scoped_enable () noexcept
	Construct an RAII object that controls whether the instance is enabled. More...

ssize_type	bus_configure (int psel_scl, int psel_sda, uint32_t frequency, unsigned int timeout_us)
	Configure the TWI bus. More...

ssize_type	enable ()
	Enable the TWI peripheral. More...

void	disable ()
	Disable the TWI peripheral.

ssize_type	read (unsigned int addr, uint8_t *buf, size_type count)
	Read a block of data from an I2C device. More...

ssize_type	write (unsigned int addr, const uint8_t *buf, size_type count)
	Write a block of data to an I2C device. More...

ssize_type	write_read (unsigned int addr, const uint8_t sbuf, size_type scount, uint8_t dbuf, size_type dcount)
	Write to then read from an I2C device. More...

Static Public Member Functions
static TWI &	instance (int idx)
	Reference the abstraction instance for a specific peripheral instance. More...

Static Public Member Functions inherited from nrfcxx::periph::details::comm_error_support
constexpr static error_type	error_decoded (ssize_type rc)
	Extract an encoded error value from an API return value. More...

constexpr static ssize_type	error_encoded (error_type ec)
	Pack an error value into a negative return value. More...

Static Public Attributes
constexpr static unsigned int	minimum_timeout_us = 100
	The minimum allowed per-byte bus timeout, in microseconds.

Static Public Attributes inherited from nrfcxx::periph::details::comm_error_support
constexpr static unsigned int	ERR_OVERRUN = 0x001
	NRF_TWI_Type::ERRORSRC bit indicating incomplete reception at start.

constexpr static unsigned int	ERR_ANACK = 0x002
	NRF_TWI_Type::ERRORSRC bit indicating NACK received during address transmission.

constexpr static unsigned int	ERR_DNACK = 0x004
	NRF_TWI_Type::ERRORSRC bit indicating NACK received during data transmission.

constexpr static unsigned int	ERR_TIMEOUT = 0x100
	Bit set in an error code when the TWI bus transaction timed out.

constexpr static unsigned int	ERR_CLEAR = 0x200
	Bit set in an error code when the TWI bus could not be cleared.

constexpr static unsigned int	ERR_INVALID = 0x400
	Bit set in an error code to indicate that the bus was not properly configured or a parameter was invalid.

constexpr static unsigned int	ERR_CHECKSUM = 0x800
	Bit set in an error code to indicate a checksum error. More...

constexpr static unsigned int	ERR_UNKNOWN = 0x1000
	Bit set in an error code to indicate an undescribable error.

Protected Member Functions
constexpr	TWI (const nrf5::TWI_Type &twi)

error_type	set_enabled_ (bool enabled)

error_type	clear_bus_ ()
	Reset the I2C bus to idle state if a secondary device is holding it active. More...

error_type	clear_error_ ()
	Invoked when a read or write operation detects a bus error. More...

error_type	reset_periph_ ()
	Power cycle the peripheral and re-initialize it. More...

Protected Attributes
const nrf5::TWI_Type &	twi_

configuration_type	configuration_

Detailed Description

Wrapper around the nRF51 TWI peripheral.

This is what the rest of the world calls I2C.

Warning: TWI0 and SPI0 share an interrupt and peripheral address space and cannot be simultaneously enabled. Similarly for TWI1, SPI1, and SPIS1.

Member Function Documentation

◆ bus_configure()

ssize_type nrfcxx::periph::TWI::bus_configure	(	int	psel_scl,
		int	psel_sda,
		uint32_t	frequency,
		unsigned int	timeout_us
	)

Configure the TWI bus.

Parameters

psel_scl	the GPIO pin number to be used for the SCL (clock) signal.
psel_sdc	the GPIO pin number to be used for the SDA (data) signal.
frequency	the bus frequency, being one of #TWI_FREQUENCY_FREQUENCY_K100, #TWI_FREQUENCY_FREQUENCY_K250, #TWI_FREQUENCY_FREQUENCY_K400, or another value to be assigned directly to the FREQUENCY register of the TWI peripheral.
timeout_us	the maximum time to wait for completion of each byte in the transaction. Values below minimum_timeout_us are clamped to that value.

Returns: Zero if successfully configured, otherwise a negative encoded error.

Note: There is no clear relationship between frequency and the numeric frequency in Hz, nor does this API validate the parameter. Use the Nordic defined constants.

◆ clear_bus_()

error_type nrfcxx::periph::TWI::clear_bus_ ( )

protected

Reset the I2C bus to idle state if a secondary device is holding it active.

The bus is enabled if and only if the return value is zero (no error, bus left in idle state: SCL and SDA not pulled low).

Returns: zero, or ERR_CLEAR

◆ clear_error_()

error_type nrfcxx::periph::TWI::clear_error_ ( )

protected

Invoked when a read or write operation detects a bus error.

The error cause(s) are read and returned as a bit set. If no TWI error is detected, ERR_UNKNOWN is set. An attempt is made to restore the bus to a cleared state; failure to do so is also indicated in the return value.

◆ enable()

ssize_type nrfcxx::periph::TWI::enable ( void )

inline

Enable the TWI peripheral.

Returns: 0 on success or negative encoded error.

See also: bus_configure

◆ instance()

static TWI& nrfcxx::periph::TWI::instance ( int idx )

static

Reference the abstraction instance for a specific peripheral instance.

Parameters

idx	the peripheral instance desired.

Warning: If idx specifies a peripheral instance that does not exist on the device the system will reset into failsafe mode.

◆ read()

ssize_type nrfcxx::periph::TWI::read	(	unsigned int	addr,
		uint8_t *	buf,
		size_type	count
	)

Read a block of data from an I2C device.

Parameters

addr	the 7-bit I2C address of the device
buf	where the received data should be stored
count	the number of bytes to be read

Returns: count successfully read bytes, or a negative encoded error.

◆ reset_periph_()

error_type nrfcxx::periph::TWI::reset_periph_ ( )

protected

Power cycle the peripheral and re-initialize it.

Returns zero if the reset was successful, otherwise an error code.

◆ scoped_enable()

scoped_enabler nrfcxx::periph::TWI::scoped_enable ( )

inlinenoexcept

Construct an RAII object that controls whether the instance is enabled.

Example:

// twi may or may not be enabled
if (auto enabler = twi.scoped_enable()) {
  // twi is enabled, use it
} else {
  // enable() failed, result in enabler.result()
}
// twi is disabled if it was enabled by previous statement
// twi remains enabled if it was enabled before previous statement

◆ write()

ssize_type nrfcxx::periph::TWI::write	(	unsigned int	addr,
		const uint8_t *	buf,
		size_type	count
	)

Write a block of data to an I2C device.

Parameters

addr	the 7-bit I2C address of the device
buf	the data to be written
count	the number of bytes to write. A value of zero is permitted; this can be used as a check that a device is responsive at `addr`.

Returns: count successfully written bytes, or a negative encoded error.

◆ write_read()

ssize_type nrfcxx::periph::TWI::write_read	(	unsigned int	addr,
		const uint8_t *	sbuf,
		size_type	scount,
		uint8_t *	dbuf,
		size_type	dcount
	)

inline

Write to then read from an I2C device.

Parameters

addr	the 7-bit I2C address of the device.
sbuf	the data to be written.
scount	the number of bytes to write. If zero the write phase is skipped.
dbuf	where the data to be read should be stored. The object may overlap `sbuf`.
dcount	the number of bytes to read

Returns: count successfully read bytes, or a negative encoded error.

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

nrfcxx/periph.hpp

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ bus_configure()

◆ clear_bus_()

◆ clear_error_()

◆ enable()

◆ instance()

◆ read()

◆ reset_periph_()

◆ scoped_enable()

◆ write()

◆ write_read()