Two Wire Interface Master with EasyDMA (TWIM) peripheral driver. More...

Topics
	TWIM peripheral driver configuration

Data Structures
struct	nrfx_twim_xfer_desc_t
	Structure for a TWIM transfer descriptor. More...

struct	nrfx_twim_event_t
	Structure for a TWIM event. More...

struct	nrfx_twim_t
	Structure for the TWIM driver instance. More...

struct	nrfx_twim_config_t
	Structure for the TWIM driver instance configuration. More...

Macros
#define	NRFX_TWIM_INSTANCE(reg)
	Macro for creating a TWIM driver instance.

#define	NRFX_TWIM_DEFAULT_CONFIG(_pin_scl, _pin_sda)
	TWIM driver default configuration.

#define	NRFX_TWIM_FLAG_TX_POSTINC (1UL << 0)
	Flag indicating that TX buffer address will be incremented after the transfer.

#define	NRFX_TWIM_FLAG_RX_POSTINC (1UL << 1)
	Flag indicating that RX buffer address will be incremented after the transfer.

#define	NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER (1UL << 2)
	Flag indicating that the interrupt after each transfer will be suppressed, and the event handler will not be called.

#define	NRFX_TWIM_FLAG_HOLD_XFER (1UL << 3)
	Flag indicating that the transfer will be set up, but not started.

#define	NRFX_TWIM_FLAG_REPEATED_XFER (1UL << 4)
	Flag indicating that the transfer will be executed multiple times.

#define	NRFX_TWIM_FLAG_TX_NO_STOP (1UL << 5)
	Flag indicating that the TX transfer will not end with a stop condition.

#define	NRFX_TWIM_FLAG_NO_SPURIOUS_STOP_CHECK (1UL << 6)
	Flag indicating that checks for spurious STOP condition will not be performed.

#define	NRFX_TWIM_XFER_DESC(transfer, addr, p_buf1, buf_len1, p_buf2, buf_len2)
	Macro for setting the transfer descriptor.

#define	NRFX_TWIM_XFER_DESC_TX(addr, p_data, length)
	Macro for setting the TX transfer descriptor.

#define	NRFX_TWIM_XFER_DESC_RX(addr, p_data, length)
	Macro for setting the RX transfer descriptor.

#define	NRFX_TWIM_XFER_DESC_TXRX(addr, p_tx, tx_len, p_rx, rx_len)
	Macro for setting the TX-RX transfer descriptor.

#define	NRFX_TWIM_XFER_DESC_TXTX(addr, p_tx, tx_len, p_tx2, tx_len2)
	Macro for setting the TX-TX transfer descriptor.

Typedefs
typedef void(*	nrfx_twim_event_handler_t) (nrfx_twim_event_t const p_event, void p_context)
	TWIM driver event handler type.

Enumerations
enum	nrfx_twim_xfer_type_t { NRFX_TWIM_XFER_TX , NRFX_TWIM_XFER_RX , NRFX_TWIM_XFER_TXRX , NRFX_TWIM_XFER_TXTX }
	TWIM driver transfer types. More...

enum	nrfx_twim_event_type_t { NRFX_TWIM_EVT_DONE , NRFX_TWIM_EVT_ADDRESS_NACK , NRFX_TWIM_EVT_DATA_NACK , NRFX_TWIM_EVT_OVERRUN , NRFX_TWIM_EVT_BUS_ERROR }
	TWIM driver event types. More...

Functions
int	nrfx_twim_init (nrfx_twim_t p_instance, nrfx_twim_config_t const p_config, nrfx_twim_event_handler_t event_handler, void *p_context)
	Function for initializing the TWIM driver instance.

int	nrfx_twim_reconfigure (nrfx_twim_t p_instance, nrfx_twim_config_t const p_config)
	Function for reconfiguring the TWIM instance.

void	nrfx_twim_callback_get (nrfx_twim_t const p_instance, nrfx_twim_event_handler_t p_event_handler, void **pp_context)
	Function for getting current TWIM event handler and associated context.

int	nrfx_twim_callback_set (nrfx_twim_t p_instance, nrfx_twim_event_handler_t event_handler, void p_context)
	Function for setting event handler of a TWIM instance.

void	nrfx_twim_uninit (nrfx_twim_t *p_instance)
	Function for uninitializing the TWIM instance.

bool	nrfx_twim_init_check (nrfx_twim_t const *p_instance)
	Function for checking if the TWIM driver instance is initialized.

void	nrfx_twim_enable (nrfx_twim_t *p_instance)
	Function for enabling the TWIM instance.

void	nrfx_twim_disable (nrfx_twim_t *p_instance)
	Function for disabling the TWIM instance.

int	nrfx_twim_xfer (nrfx_twim_t p_instance, nrfx_twim_xfer_desc_t const p_xfer_desc, uint32_t flags)
	Function for performing a TWIM transfer.

bool	nrfx_twim_is_busy (nrfx_twim_t *p_instance)
	Function for checking the TWIM driver state.

uint32_t	nrfx_twim_start_task_address_get (nrfx_twim_t const *p_instance, nrfx_twim_xfer_type_t xfer_type)
	Function for returning the address of a TWIM start task.

uint32_t	nrfx_twim_stopped_event_address_get (nrfx_twim_t const *p_instance)
	Function for returning the address of a STOPPED TWIM event.

NRFX_STATIC_INLINE int	nrfx_twim_bus_recover (uint32_t scl_pin, uint32_t sda_pin)
	Function for recovering the bus.

void	nrfx_twim_irq_handler (nrfx_twim_t *p_instance)
	Driver interrupt handler.

Detailed Description

Two Wire Interface Master with EasyDMA (TWIM) peripheral driver.

Macro Definition Documentation

◆ NRFX_TWIM_DEFAULT_CONFIG

#define NRFX_TWIM_DEFAULT_CONFIG	(		_pin_scl,
			_pin_sda )

Value:

{                                                                \
    .scl_pin            = _pin_scl,                              \
    .sda_pin            = _pin_sda,                              \
    .frequency          = NRF_TWIM_FREQ_100K,                    \
    .interrupt_priority = NRFX_TWIM_DEFAULT_CONFIG_IRQ_PRIORITY, \
    .hold_bus_uninit    = false,                                 \
}

TWIM driver default configuration.

This configuration sets up TWIM with the following options:

clock frequency: 100 kHz
disable bus holding after uninit

Parameters

[in]	_pin_scl	SCL pin.
[in]	_pin_sda	SDA pin.

◆ NRFX_TWIM_INSTANCE

#define NRFX_TWIM_INSTANCE ( reg )

Value:

{                                   \
    .p_twim = (NRF_TWIM_Type *)reg, \
    .cb    = {0},                   \
}

Macro for creating a TWIM driver instance.

◆ NRFX_TWIM_XFER_DESC

#define NRFX_TWIM_XFER_DESC	(	transfer,
		addr,
		p_buf1,
		buf_len1,
		p_buf2,
		buf_len2 )

Value:

{                                                                               \
    .type             = (transfer),                                             \
    .address          = (addr),                                                 \
    .primary_length   = (buf_len1),                                             \
    .secondary_length = (buf_len2),                                             \
    .p_primary_buf    = (p_buf1),                                               \
    .p_secondary_buf  = (p_buf2)                                                \
}

Macro for setting the transfer descriptor.

◆ NRFX_TWIM_XFER_DESC_RX

#define NRFX_TWIM_XFER_DESC_RX	(	addr,
		p_data,
		length )

Value:

NRFX_TWIM_XFER_DESC(NRFX_TWIM_XFER_RX, addr, p_data, length, NULL, 0)

NRFX_TWIM_XFER_DESC

#define NRFX_TWIM_XFER_DESC(transfer, addr, p_buf1, buf_len1, p_buf2, buf_len2)

Macro for setting the transfer descriptor.

Definition nrfx_twim.h:189

NRFX_TWIM_XFER_RX

@ NRFX_TWIM_XFER_RX

RX transfer.

Definition nrfx_twim.h:56

Macro for setting the RX transfer descriptor.

◆ NRFX_TWIM_XFER_DESC_TX

#define NRFX_TWIM_XFER_DESC_TX	(	addr,
		p_data,
		length )

Value:

NRFX_TWIM_XFER_DESC(NRFX_TWIM_XFER_TX, addr, p_data, length, NULL, 0)

NRFX_TWIM_XFER_TX

@ NRFX_TWIM_XFER_TX

TX transfer.

Definition nrfx_twim.h:55

Macro for setting the TX transfer descriptor.

◆ NRFX_TWIM_XFER_DESC_TXRX

#define NRFX_TWIM_XFER_DESC_TXRX	(	addr,
		p_tx,
		tx_len,
		p_rx,
		rx_len )

Value:

NRFX_TWIM_XFER_DESC(NRFX_TWIM_XFER_TXRX, addr, p_tx, tx_len, p_rx, rx_len)

NRFX_TWIM_XFER_TXRX

@ NRFX_TWIM_XFER_TXRX

TX transfer followed by RX transfer with repeated start.

Definition nrfx_twim.h:57

Macro for setting the TX-RX transfer descriptor.

◆ NRFX_TWIM_XFER_DESC_TXTX

#define NRFX_TWIM_XFER_DESC_TXTX	(	addr,
		p_tx,
		tx_len,
		p_tx2,
		tx_len2 )

Value:

NRFX_TWIM_XFER_DESC(NRFX_TWIM_XFER_TXTX, addr, p_tx, tx_len, p_tx2, tx_len2)

NRFX_TWIM_XFER_TXTX

@ NRFX_TWIM_XFER_TXTX

TX transfer followed by TX transfer with repeated start.

Definition nrfx_twim.h:58

Macro for setting the TX-TX transfer descriptor.

Enumeration Type Documentation

◆ nrfx_twim_event_type_t

enum nrfx_twim_event_type_t

TWIM driver event types.

Enumerator
NRFX_TWIM_EVT_DONE	Transfer completed event.
NRFX_TWIM_EVT_ADDRESS_NACK	Error event: NACK received after sending the address.
NRFX_TWIM_EVT_DATA_NACK	Error event: NACK received after sending a data byte.
NRFX_TWIM_EVT_OVERRUN	Error event: The unread data is replaced by new data.
NRFX_TWIM_EVT_BUS_ERROR	Error event: An unexpected transition occurred on the bus.

◆ nrfx_twim_xfer_type_t

enum nrfx_twim_xfer_type_t

TWIM driver transfer types.

Enumerator
NRFX_TWIM_XFER_TX	TX transfer.
NRFX_TWIM_XFER_RX	RX transfer.
NRFX_TWIM_XFER_TXRX	TX transfer followed by RX transfer with repeated start.
NRFX_TWIM_XFER_TXTX	TX transfer followed by TX transfer with repeated start.

Function Documentation

◆ nrfx_twim_bus_recover()

NRFX_STATIC_INLINE int nrfx_twim_bus_recover	(	uint32_t	scl_pin,
		uint32_t	sda_pin )

Function for recovering the bus.

This function checks if the bus is not stuck because of a slave holding the SDA line in the low state, and if needed it performs required number of pulses on the SCL line to make the slave release the SDA line. Finally, the function generates a STOP condition on the bus to put it into a known state.

Note: This function can be used only if the TWIM driver is uninitialized.

Parameters

[in]	scl_pin	SCL pin number.
[in]	sda_pin	SDA pin number.

Return values

0	Bus recovery was successful.
-ECANCELED	Bus recovery failed.

◆ nrfx_twim_callback_get()

void nrfx_twim_callback_get	(	nrfx_twim_t const *	p_instance,
		nrfx_twim_event_handler_t *	p_event_handler,
		void **	pp_context )

Function for getting current TWIM event handler and associated context.

Parameters

[in]	p_instance	Pointer to the driver instance structure.
[out]	p_event_handler	Pointer to be filled with the current event handler.
[out]	pp_context	Pointer to be filled with a pointer to the current event handler context.

◆ nrfx_twim_callback_set()

int nrfx_twim_callback_set	(	nrfx_twim_t *	p_instance,
		nrfx_twim_event_handler_t	event_handler,
		void *	p_context )

Function for setting event handler of a TWIM instance.

This function overwrites the internally stored values of event_handler and p_context parameters passed to the nrfx_twim_init function. To be able to restore previous event handler you can use the nrfx_twim_callback_get .

Warning: This function can be used only for reconfiguring handler in the non-blocking mode. Use nrfx_twim_uninit and nrfx_twim_init to reconfigure driver in the blocking mode.

Parameters

[in]	p_instance	Pointer to the driver instance structure.
[in]	event_handler	Event handler provided by the user. Cannot be NULL.
[in]	p_context	Context passed to event handler.

Return values

0	Reconfiguration was successful.
-EBUSY	The driver is performing transaction.
-EINPROGRESS	The driver is configured in blocking mode.

◆ nrfx_twim_disable()

void nrfx_twim_disable ( nrfx_twim_t * p_instance )

Function for disabling the TWIM instance.

Parameters

[in] p_instance Pointer to the driver instance structure.

◆ nrfx_twim_enable()

void nrfx_twim_enable ( nrfx_twim_t * p_instance )

Function for enabling the TWIM instance.

Parameters

[in] p_instance Pointer to the driver instance structure.

◆ nrfx_twim_init()

int nrfx_twim_init	(	nrfx_twim_t *	p_instance,
		nrfx_twim_config_t const *	p_config,
		nrfx_twim_event_handler_t	event_handler,
		void *	p_context )

Function for initializing the TWIM driver instance.

Parameters

[in]	p_instance	Pointer to the driver instance structure.
[in]	p_config	Pointer to the structure with the initial configuration.
[in]	event_handler	Event handler provided by the user. If NULL, blocking mode is enabled.
[in]	p_context	Context passed to event handler.

Warning: On nRF5340, 1 MHz setting is supported only on the dedicated pins. See the chapter Pin assignments in the Product Specification.

Return values

0	Initialization was successful.
-EALREADY	The driver is already initialized.
-EINVAL	Requested frequency is not available on the specified pins.
-EBUSY	Some other peripheral with the same instance ID is already in use. This is possible only if Peripheral Resource Sharing (PRS) module is enabled.

◆ nrfx_twim_init_check()

bool nrfx_twim_init_check ( nrfx_twim_t const * p_instance )

Function for checking if the TWIM driver instance is initialized.

Parameters

[in] p_instance Pointer to the driver instance structure.

Return values

true	Instance is already initialized.
false	Instance is not initialized.

◆ nrfx_twim_irq_handler()

void nrfx_twim_irq_handler ( nrfx_twim_t * p_instance )

Driver interrupt handler.

Parameters

[in] p_instance Pointer to the driver instance structure.

◆ nrfx_twim_is_busy()

bool nrfx_twim_is_busy ( nrfx_twim_t * p_instance )

Function for checking the TWIM driver state.

Parameters

[in] p_instance TWIM instance.

Return values

true	The TWIM driver is currently busy performing a transfer.
false	The TWIM driver is ready for a new transfer.

◆ nrfx_twim_reconfigure()

int nrfx_twim_reconfigure	(	nrfx_twim_t *	p_instance,
		nrfx_twim_config_t const *	p_config )

Function for reconfiguring the TWIM instance.

Parameters

[in]	p_instance	Pointer to the driver instance structure.
[in]	p_config	Pointer to the structure with the configuration.

Return values

0	Reconfiguration was successful.
-EBUSY	The driver is during transaction.
-EINPROGRESS	The driver is uninitialized.
-EINVAL	Requested frequency is not available on the specified pins.

◆ nrfx_twim_start_task_address_get()

uint32_t nrfx_twim_start_task_address_get	(	nrfx_twim_t const *	p_instance,
		nrfx_twim_xfer_type_t	xfer_type )

Function for returning the address of a TWIM start task.

This function is to be used if nrfx_twim_xfer was called with the flag NRFX_TWIM_FLAG_HOLD_XFER. In that case, the transfer is not started by the driver, but it must be started externally by PPI.

Parameters

[in]	p_instance	Pointer to the driver instance structure.
[in]	xfer_type	Transfer type used in the last call of the nrfx_twim_xfer function.

Returns: Start task address (TX or RX) depending on the value of xfer_type.

◆ nrfx_twim_stopped_event_address_get()

uint32_t nrfx_twim_stopped_event_address_get ( nrfx_twim_t const * p_instance )

Function for returning the address of a STOPPED TWIM event.

A STOPPED event can be used to detect the end of a transfer if the NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER option is used.

Parameters

[in] p_instance Pointer to the driver instance structure.

Returns: STOPPED event address.

◆ nrfx_twim_uninit()

void nrfx_twim_uninit ( nrfx_twim_t * p_instance )

Function for uninitializing the TWIM instance.

Parameters

[in] p_instance Pointer to the driver instance structure.

◆ nrfx_twim_xfer()

int nrfx_twim_xfer	(	nrfx_twim_t *	p_instance,
		nrfx_twim_xfer_desc_t const *	p_xfer_desc,
		uint32_t	flags )

Function for performing a TWIM transfer.

The following transfer types can be configured (nrfx_twim_xfer_desc_t::type):

NRFX_TWIM_XFER_TXRX - Write operation followed by a read operation (without STOP condition in between).
NRFX_TWIM_XFER_TXTX - Write operation followed by a write operation (without STOP condition in between).
NRFX_TWIM_XFER_TX - Write operation (with or without STOP condition).
NRFX_TWIM_XFER_RX - Read operation (with STOP condition).

Note: TX-RX and TX-TX transfers are supported only in non-blocking mode.

Additional options are provided using the flags parameter:

NRFX_TWIM_FLAG_TX_POSTINC and NRFX_TWIM_FLAG_RX_POSTINC - Post-incrementation of buffer addresses.
NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER - No user event handler after the transfer completion. In most cases, this also means no interrupt at the end of the transfer.
NRFX_TWIM_FLAG_HOLD_XFER - Driver is not starting the transfer. Use this flag if the transfer is triggered externally by PPI. Use nrfx_twim_start_task_address_get to get the address of the start task.
NRFX_TWIM_FLAG_REPEATED_XFER - Prepare for repeated transfers. You can set up a number of transfers that will be triggered externally (for example by PPI). An example is a TXRX transfer with the options NRFX_TWIM_FLAG_RX_POSTINC, NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER, and NRFX_TWIM_FLAG_REPEATED_XFER. After the transfer is set up, a set of transfers can be triggered by PPI that will read, for example, the same register of an external component and put it into a RAM buffer without any interrupts. nrfx_twim_stopped_event_address_get can be used to get the address of the STOPPED event, which can be used to count the number of transfers. If NRFX_TWIM_FLAG_REPEATED_XFER is used, the driver does not set the driver instance into busy state, so you must ensure that the next transfers are set up when TWIM is not active.
NRFX_TWIM_FLAG_TX_NO_STOP - No stop condition after the TX transfer.
NRFX_TWIM_FLAG_NO_SPURIOUS_STOP_CHECK - Checks for spurious STOP conditions are disabled. Used together with NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER can result in lower power consumption when transfers are triggered externally and CPU is sleeping. Use only with I2C standard-compliant slave devices.

Note

Some flag combinations are invalid:

NRFX_TWIM_FLAG_TX_NO_STOP with nrfx_twim_xfer_desc_t::type different than NRFX_TWIM_XFER_TX
NRFX_TWIM_FLAG_REPEATED_XFER with nrfx_twim_xfer_desc_t::type set to NRFX_TWIM_XFER_TXTX

If nrfx_twim_xfer_desc_t::type is set to NRFX_TWIM_XFER_TX and the NRFX_TWIM_FLAG_TX_NO_STOP and NRFX_TWIM_FLAG_REPEATED_XFER flags are set, two tasks must be used to trigger a transfer: TASKS_RESUME followed by TASKS_STARTTX. If no stop condition is generated, TWIM is in SUSPENDED state. Therefore, it must be resumed before the transfer can be started.

Note: Peripherals using EasyDMA (including TWIM) require the transfer buffers to be placed in the Data RAM region. If this condition is not met, this function will fail with the error code -EACCES.

Parameters

[in]	p_instance	Pointer to the driver instance structure.
[in]	p_xfer_desc	Pointer to the transfer descriptor.
[in]	flags	Transfer options (0 for default settings).

Return values

0	The procedure is successful.
-EBUSY	The driver is not ready for a new transfer.
-ENOTSUP	The provided parameters are not supported.
-ECANCELED	An unexpected transition occurred on the bus.
-EACCES	The provided buffers are not placed in the Data RAM region.
-EOVERFLOW	The unread data is replaced by new data.
-EFAULT	NACK is received after sending the address.
-EAGAIN	NACK is received after sending a data byte.

Topics

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ NRFX_TWIM_DEFAULT_CONFIG

◆ NRFX_TWIM_INSTANCE

◆ NRFX_TWIM_XFER_DESC

◆ NRFX_TWIM_XFER_DESC_RX

◆ NRFX_TWIM_XFER_DESC_TX

◆ NRFX_TWIM_XFER_DESC_TXRX

◆ NRFX_TWIM_XFER_DESC_TXTX

Enumeration Type Documentation

◆ nrfx_twim_event_type_t

◆ nrfx_twim_xfer_type_t

Function Documentation

◆ nrfx_twim_bus_recover()

◆ nrfx_twim_callback_get()

◆ nrfx_twim_callback_set()

◆ nrfx_twim_disable()

◆ nrfx_twim_enable()

◆ nrfx_twim_init()

◆ nrfx_twim_init_check()

◆ nrfx_twim_irq_handler()

◆ nrfx_twim_is_busy()

◆ nrfx_twim_reconfigure()

◆ nrfx_twim_start_task_address_get()

◆ nrfx_twim_stopped_event_address_get()

◆ nrfx_twim_uninit()

◆ nrfx_twim_xfer()