TWIM driver

group nrfx_twim

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

Defines

NRFX_TWIM_INSTANCE(id): Macro for creating a TWI master driver instance.

NRFX_TWIM_DEFAULT_CONFIG(_pin_scl, _pin_sda)

TWIM driver default configuration.

This configuration sets up TWIM 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_TWIM_FLAG_TX_POSTINC: Flag indicating that TX buffer address will be incremented after the transfer.

NRFX_TWIM_FLAG_RX_POSTINC: Flag indicating that RX buffer address will be incremented after the transfer.

NRFX_TWIM_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_TWIM_FLAG_HOLD_XFER: Flag indicating that the transfer will be set up, but not started.

NRFX_TWIM_FLAG_REPEATED_XFER: Flag indicating that the transfer will be executed multiple times.

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

NRFX_TWIM_FLAG_NO_SPURIOUS_STOP_CHECK: Flag indicating that checks for spurious STOP condition will not be performed.

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

NRFX_TWIM_XFER_DESC_TX(addr, p_data, length): Macro for setting the TX transfer descriptor.

NRFX_TWIM_XFER_DESC_RX(addr, p_data, length): Macro for setting the RX transfer descriptor.

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

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

NRFX_TWIM_INST_HANDLER_GET(idx)

Macro returning TWIM interrupt handler.

param[in] idx TWIM index.

Returns:: Interrupt handler.

Typedefs

typedef void (*nrfx_twim_evt_handler_t)(nrfx_twim_evt_t const *p_event, void *p_context): TWI event handler prototype.

Enums

enum nrfx_twim_evt_type_t

TWI master driver event types.

Values:

enumerator NRFX_TWIM_EVT_DONE: Transfer completed event.

enumerator NRFX_TWIM_EVT_ADDRESS_NACK: Error event: NACK received after sending the address.

enumerator NRFX_TWIM_EVT_DATA_NACK: Error event: NACK received after sending a data byte.

enumerator NRFX_TWIM_EVT_OVERRUN: Error event: The unread data is replaced by new data.

enumerator NRFX_TWIM_EVT_BUS_ERROR: Error event: An unexpected transition occurred on the bus.

enum nrfx_twim_xfer_type_t

TWI master driver transfer types.

Values:

enumerator NRFX_TWIM_XFER_TX: TX transfer.

enumerator NRFX_TWIM_XFER_RX: RX transfer.

enumerator NRFX_TWIM_XFER_TXRX: TX transfer followed by RX transfer with repeated start.

enumerator NRFX_TWIM_XFER_TXTX: TX transfer followed by TX transfer with repeated start.

Functions

nrfx_err_t nrfx_twim_init(nrfx_twim_t const *p_instance, nrfx_twim_config_t const *p_config, nrfx_twim_evt_handler_t event_handler, void *p_context)

Function for initializing the TWI driver instance.

Warning

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

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 was successful.
NRFX_ERROR_INVALID_STATE – The driver is in invalid state.
NRFX_ERROR_INVALID_PARAM – Requested frequency is not available on the specified pins.
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_twim_reconfigure(nrfx_twim_t const *p_instance, nrfx_twim_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_twim_uninit(nrfx_twim_t const *p_instance)

Function for uninitializing the TWI instance.

Parameters:

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

void nrfx_twim_enable(nrfx_twim_t const *p_instance)

Function for enabling the TWI instance.

Parameters:

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

void nrfx_twim_disable(nrfx_twim_t const *p_instance)

Function for disabling the TWI instance.

Parameters:

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

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

Function for performing a TWI 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).

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.

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

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

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

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 NRFX_ERROR_INVALID_ADDR.

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_ADDR – The provided buffers are not placed in the Data RAM region.
NRFX_ERROR_DRV_TWI_ERR_OVERRUN – The unread data is replaced by new data.
NRFX_ERROR_DRV_TWI_ERR_ANACK – NACK is received after sending the address.
NRFX_ERROR_DRV_TWI_ERR_DNACK – NACK is received after sending a data byte.

bool nrfx_twim_is_busy(nrfx_twim_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.

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:

p_instance – [in] Pointer to the driver instance structure.
xfer_type – [in] 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.

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:

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

Returns:

STOPPED event address.

NRFX_STATIC_INLINE nrfx_err_t 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:

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_twim_t

#include <nrfx_twim.h>

Structure for the TWI master driver instance.

Public Members

NRF_TWIM_Type *p_twim: Pointer to a structure with TWIM registers.

uint8_t drv_inst_idx: Index of the driver instance. For internal use only.

struct nrfx_twim_config_t

#include <nrfx_twim.h>

Structure for the TWI master driver instance configuration.

Public Members

uint32_t scl_pin: SCL pin number.

uint32_t sda_pin: SDA pin number.

nrf_twim_frequency_t frequency: TWIM 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_twim_xfer_desc_t

#include <nrfx_twim.h>

Structure for a TWI transfer descriptor.

Public Members

nrfx_twim_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_twim_evt_t

#include <nrfx_twim.h>

Structure for a TWI event.

Public Members

nrfx_twim_evt_type_t type: Event type.

nrfx_twim_xfer_desc_t xfer_desc: Transfer details.