TWI driver

group nrfx_twi

Two Wire Interface master (TWI) peripheral driver.

Defines

NRFX_TWI_INSTANCE(id)

Macro for creating a TWI master driver instance.

NRFX_TWI_DEFAULT_CONFIG(_pin_scl, _pin_sda)

TWI master driver instance default configuration.

This configuration sets up TWI with the following options:

  • clock frequency: 100 kHz

  • disable bus holding after uninit

Parameters:

  • _pin_scl – [in] SCL pin.

  • _pin_sda – [in] SDA pin.

NRFX_TWI_FLAG_NO_XFER_EVT_HANDLER

Flag indicating that the interrupt after each transfer will be suppressed, and the event handler will not be called.

NRFX_TWI_FLAG_TX_NO_STOP

Flag indicating that the TX transfer will not end with a stop condition.

NRFX_TWI_FLAG_SUSPEND

Flag indicating that the transfer will be suspended.

NRFX_TWI_XFER_DESC_TX(addr, p_data, length)

Macro for setting the TX transfer descriptor.

NRFX_TWI_XFER_DESC_RX(addr, p_data, length)

Macro for setting the RX transfer descriptor.

NRFX_TWI_XFER_DESC_TXRX(addr, p_tx, tx_len, p_rx, rx_len)

Macro for setting the TX-RX transfer descriptor.

NRFX_TWI_XFER_DESC_TXTX(addr, p_tx, tx_len, p_tx2, tx_len2)

Macro for setting the TX-TX transfer descriptor.

NRFX_TWI_INST_HANDLER_GET(idx)

Macro returning TWI interrupt handler.

param[in] idx TWI index.

Returns:

Interrupt handler.

Typedefs

typedef void (*nrfx_twi_evt_handler_t)(nrfx_twi_evt_t const *p_event, void *p_context)

TWI event handler prototype.

Enums

enum nrfx_twi_evt_type_t

TWI master driver event types.

Values:

enumerator NRFX_TWI_EVT_DONE

Transfer completed event.

enumerator NRFX_TWI_EVT_ADDRESS_NACK

Error event: NACK received after sending the address.

enumerator NRFX_TWI_EVT_DATA_NACK

Error event: NACK received after sending a data byte.

enumerator NRFX_TWI_EVT_OVERRUN

Error event: The unread data is replaced by new data.

enumerator NRFX_TWI_EVT_BUS_ERROR

Error event: An unexpected transition occurred on the bus.

enum nrfx_twi_xfer_type_t

TWI master driver transfer types.

Values:

enumerator NRFX_TWI_XFER_TX

TX transfer.

enumerator NRFX_TWI_XFER_RX

RX transfer.

enumerator NRFX_TWI_XFER_TXRX

TX transfer followed by RX transfer with repeated start.

enumerator NRFX_TWI_XFER_TXTX

TX transfer followed by TX transfer with repeated start.

Functions

nrfx_err_t nrfx_twi_init(nrfx_twi_t const *p_instance, nrfx_twi_config_t const *p_config, nrfx_twi_evt_handler_t event_handler, void *p_context)

Function for initializing the TWI driver instance.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

  • p_config – [in] Pointer to the structure with the initial configuration.

  • event_handler – [in] Event handler provided by the user. If NULL, blocking mode is enabled.

  • p_context – [in] Context passed to event handler.

Return values:

  • NRFX_SUCCESS – Initialization is successful.

  • NRFX_ERROR_ALREADY – The driver is already initialized.

  • NRFX_ERROR_INVALID_STATE – The driver is already initialized. Deprecated - use NRFX_ERROR_ALREADY instead.

  • NRFX_ERROR_BUSY – 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_err_t nrfx_twi_reconfigure(nrfx_twi_t const *p_instance, nrfx_twi_config_t const *p_config)

Function for reconfiguring the TWI instance.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

  • p_config – [in] Pointer to the structure with the configuration.

Return values:

  • NRFX_SUCCESS – Reconfiguration was successful.

  • NRFX_ERROR_BUSY – The driver is during transaction.

  • NRFX_ERROR_INVALID_STATE – The driver is uninitialized.

void nrfx_twi_uninit(nrfx_twi_t const *p_instance)

Function for uninitializing the TWI instance.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

bool nrfx_twi_init_check(nrfx_twi_t const *p_instance)

Function for checking if the TWI driver instance is initialized.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

Return values:

  • true – Instance is already initialized.

  • false – Instance is not initialized.

void nrfx_twi_enable(nrfx_twi_t const *p_instance)

Function for enabling the TWI instance.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

void nrfx_twi_disable(nrfx_twi_t const *p_instance)

Function for disabling the TWI instance.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

nrfx_err_t nrfx_twi_xfer(nrfx_twi_t const *p_instance, nrfx_twi_xfer_desc_t const *p_xfer_desc, uint32_t flags)

Function for performing a TWI transfer.

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

Additional options are provided using the flags parameter:

  • NRFX_TWI_FLAG_NO_XFER_EVT_HANDLER - No user event handler after transfer completion. In most cases, this also means no interrupt at the end of the transfer.

  • NRFX_TWI_FLAG_TX_NO_STOP - No stop condition after TX transfer.

  • NRFX_TWI_FLAG_SUSPEND - Transfer will be suspended. This allows for combining multiple transfers into one transaction. Only transactions with the same direction can be combined. To finish the transaction, call the function without this flag.

Note

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

Note

Some flag combinations are invalid:

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

  • p_xfer_desc – [in] Pointer to the transfer descriptor.

  • flags – [in] Transfer options (0 for default settings).

Return values:

  • NRFX_SUCCESS – The procedure is successful.

  • NRFX_ERROR_BUSY – The driver is not ready for a new transfer.

  • NRFX_ERROR_NOT_SUPPORTED – The provided parameters are not supported.

  • NRFX_ERROR_INTERNAL – An unexpected transition occurred on the bus.

  • NRFX_ERROR_INVALID_STATE – Other direction of transaction is suspended on the bus.

  • NRFX_ERROR_DRV_TWI_ERR_OVERRUN – The unread data is replaced by new data (TXRX and RX)

  • NRFX_ERROR_DRV_TWI_ERR_ANACK – Negative acknowledgement (NACK) is received after sending the address in polling mode.

  • NRFX_ERROR_DRV_TWI_ERR_DNACK – Negative acknowledgement (NACK) is received after sending a data byte in polling mode.

bool nrfx_twi_is_busy(nrfx_twi_t const *p_instance)

Function for checking the TWI driver state.

Parameters:

  • p_instance – [in] TWI instance.

Return values:

  • true – The TWI driver is currently busy performing a transfer.

  • false – The TWI driver is ready for a new transfer.

size_t nrfx_twi_data_count_get(nrfx_twi_t const *p_instance)

Function for getting the transferred data count.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

Returns:

Data count.

uint32_t nrfx_twi_stopped_event_get(nrfx_twi_t const *p_instance)

Function for returning the address of a STOPPED TWI event.

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

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

Returns:

STOPPED event address.

NRFX_STATIC_INLINE nrfx_err_t nrfx_twi_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 TWI driver is uninitialized.

Parameters:

  • scl_pin – [in] SCL pin number.

  • sda_pin – [in] SDA pin number.

Return values:

  • NRFX_SUCCESS – Bus recovery was successful.

  • NRFX_ERROR_INTERNAL – Bus recovery failed.

struct nrfx_twi_t
#include <nrfx_twi.h>

Structure for the TWI master driver instance.

Public Members

NRF_TWI_Type *p_twi

Pointer to a structure with TWI registers.

uint8_t drv_inst_idx

Index of the driver instance. For internal use only.

struct nrfx_twi_config_t
#include <nrfx_twi.h>

Structure for the configuration of the TWI master driver instance.

Public Members

uint32_t scl

SCL pin number.

uint32_t sda

SDA pin number.

nrf_twi_frequency_t frequency

TWI frequency.

uint8_t interrupt_priority

Interrupt priority.

bool hold_bus_uninit

Hold pull up state on GPIO pins after uninit.

bool skip_gpio_cfg

Skip GPIO configuration of pins.

When set to true, the driver does not modify any GPIO parameters of the used pins. Those parameters are supposed to be configured externally before the driver is initialized.

bool skip_psel_cfg

Skip pin selection configuration.

When set to true, the driver does not modify pin select registers in the peripheral. Those registers are supposed to be set up externally before the driver is initialized.

Note

When both GPIO configuration and pin selection are to be skipped, the structure fields that specify pins can be omitted, as they are ignored anyway.

struct nrfx_twi_xfer_desc_t
#include <nrfx_twi.h>

Structure for a TWI transfer descriptor.

Public Members

nrfx_twi_xfer_type_t type

Type of transfer.

uint8_t address

Slave address.

size_t primary_length

Number of bytes transferred.

size_t secondary_length

Number of bytes transferred.

uint8_t *p_primary_buf

Pointer to transferred data.

uint8_t *p_secondary_buf

Pointer to transferred data.

struct nrfx_twi_evt_t
#include <nrfx_twi.h>

Structure for a TWI event.

Public Members

nrfx_twi_evt_type_t type

Event type.

nrfx_twi_xfer_desc_t xfer_desc

Transfer details.