nRF5 SDK v17.1.0
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
TWIM driver

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

Modules

 TWIM peripheral driver configuration
 

Data Structures

struct  nrfx_twim_t
 Structure for the TWI master driver instance. More...
 
struct  nrfx_twim_config_t
 Structure for the TWI master driver instance configuration. More...
 
struct  nrfx_twim_xfer_desc_t
 Structure for a TWI transfer descriptor. More...
 
struct  nrfx_twim_evt_t
 Structure for a TWI event. More...
 

Macros

#define NRFX_TWIM_INSTANCE(id)
 Macro for creating a TWI master driver instance. More...
 
#define NRFX_TWIM_DEFAULT_CONFIG
 TWI master driver instance default configuration. More...
 
#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_TX(addr, p_data, length)
 Macro for setting the TX transfer descriptor. More...
 
#define NRFX_TWIM_XFER_DESC_RX(addr, p_data, length)
 Macro for setting the RX transfer descriptor. More...
 
#define NRFX_TWIM_XFER_DESC_TXRX(addr, p_tx, tx_len, p_rx, rx_len)
 Macro for setting the TX-RX transfer descriptor. More...
 
#define NRFX_TWIM_XFER_DESC_TXTX(addr, p_tx, tx_len, p_tx2, tx_len2)
 Macro for setting the TX-TX transfer descriptor. More...
 

Typedefs

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

Enumerations

enum  nrfx_twim_evt_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
}
 TWI master driver event types. More...
 
enum  nrfx_twim_xfer_type_t {
  NRFX_TWIM_XFER_TX,
  NRFX_TWIM_XFER_RX,
  NRFX_TWIM_XFER_TXRX,
  NRFX_TWIM_XFER_TXTX
}
 TWI master driver transfer types. More...
 

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. More...
 
void nrfx_twim_uninit (nrfx_twim_t const *p_instance)
 Function for uninitializing the TWI instance. More...
 
void nrfx_twim_enable (nrfx_twim_t const *p_instance)
 Function for enabling the TWI instance. More...
 
void nrfx_twim_disable (nrfx_twim_t const *p_instance)
 Function for disabling the TWI instance. More...
 
nrfx_err_t nrfx_twim_tx (nrfx_twim_t const *p_instance, uint8_t address, uint8_t const *p_data, size_t length, bool no_stop)
 Function for sending data to a TWI slave. More...
 
nrfx_err_t nrfx_twim_rx (nrfx_twim_t const *p_instance, uint8_t address, uint8_t *p_data, size_t length)
 Function for reading data from a TWI slave. More...
 
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. More...
 
bool nrfx_twim_is_busy (nrfx_twim_t const *p_instance)
 Function for checking the TWI driver state. More...
 
uint32_t nrfx_twim_start_task_get (nrfx_twim_t const *p_instance, nrfx_twim_xfer_type_t xfer_type)
 Function for returning the address of a TWIM start task. More...
 
uint32_t nrfx_twim_stopped_event_get (nrfx_twim_t const *p_instance)
 Function for returning the address of a STOPPED TWIM event. More...
 
__STATIC_INLINE nrfx_err_t nrfx_twim_bus_recover (uint32_t scl_pin, uint32_t sda_pin)
 Function for recovering the bus. More...
 

Detailed Description

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

Macro Definition Documentation

#define NRFX_TWIM_DEFAULT_CONFIG
Value:
{ \
.scl = 31, \
.sda = 31, \
.interrupt_priority = NRFX_TWIM_DEFAULT_CONFIG_IRQ_PRIORITY, \
}

TWI master driver instance default configuration.

#define NRFX_TWIM_INSTANCE (   id)
Value:
{ \
.p_twim = NRFX_CONCAT_2(NRF_TWIM, id), \
.drv_inst_idx = NRFX_CONCAT_3(NRFX_TWIM, id, _INST_IDX), \
}

Macro for creating a TWI master driver instance.

#define NRFX_TWIM_XFER_DESC_RX (   addr,
  p_data,
  length 
)
Value:
{ \
.type = NRFX_TWIM_XFER_RX, \
.address = (addr), \
.primary_length = (length), \
.secondary_length = 0, \
.p_primary_buf = (p_data), \
.p_secondary_buf = NULL, \
}

Macro for setting the RX transfer descriptor.

#define NRFX_TWIM_XFER_DESC_TX (   addr,
  p_data,
  length 
)
Value:
{ \
.type = NRFX_TWIM_XFER_TX, \
.address = (addr), \
.primary_length = (length), \
.secondary_length = 0, \
.p_primary_buf = (p_data), \
.p_secondary_buf = NULL, \
}

Macro for setting the TX transfer descriptor.

#define NRFX_TWIM_XFER_DESC_TXRX (   addr,
  p_tx,
  tx_len,
  p_rx,
  rx_len 
)
Value:
{ \
.address = (addr), \
.primary_length = (tx_len), \
.secondary_length = (rx_len), \
.p_primary_buf = (p_tx), \
.p_secondary_buf = (p_rx), \
}

Macro for setting the TX-RX transfer descriptor.

#define NRFX_TWIM_XFER_DESC_TXTX (   addr,
  p_tx,
  tx_len,
  p_tx2,
  tx_len2 
)
Value:
{ \
.address = (addr), \
.primary_length = (tx_len), \
.secondary_length = (tx_len2), \
.p_primary_buf = (p_tx), \
.p_secondary_buf = (p_tx2), \
}

Macro for setting the TX-TX transfer descriptor.

Enumeration Type Documentation

TWI master 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.

TWI master 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

__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
[in]scl_pinSCL pin number.
[in]sda_pinSDA pin number.
Return values
NRFX_SUCCESSBus recovery was successful.
NRFX_ERROR_INTERNALBus recovery failed.
void nrfx_twim_disable ( nrfx_twim_t const *  p_instance)

Function for disabling the TWI instance.

Parameters
[in]p_instancePointer to the driver instance structure.
void nrfx_twim_enable ( nrfx_twim_t const *  p_instance)

Function for enabling the TWI instance.

Parameters
[in]p_instancePointer to the driver instance structure.
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.

Parameters
[in]p_instancePointer to the driver instance structure.
[in]p_configPointer to the structure with the initial configuration.
[in]event_handlerEvent handler provided by the user. If NULL, blocking mode is enabled.
[in]p_contextContext passed to event handler.
Return values
NRFX_SUCCESSInitialization was successful.
NRFX_ERROR_INVALID_STATEThe driver is in invalid state.
NRFX_ERROR_BUSYSome other peripheral with the same instance ID is already in use. This is possible only if Peripheral Resource Sharing (PRS) module is enabled.
bool nrfx_twim_is_busy ( nrfx_twim_t const *  p_instance)

Function for checking the TWI driver state.

Parameters
[in]p_instanceTWI instance.
Return values
trueThe TWI driver is currently busy performing a transfer.
falseThe TWI driver is ready for a new transfer.
nrfx_err_t nrfx_twim_rx ( nrfx_twim_t const *  p_instance,
uint8_t  address,
uint8_t *  p_data,
size_t  length 
)

Function for reading data from a TWI slave.

The transmission will be stopped when an error occurs. If a transfer is ongoing, the function returns the error code NRFX_ERROR_BUSY.

Note
This function is deprecated. Use nrfx_twim_xfer instead.
Parameters
[in]p_instancePointer to the driver instance structure.
[in]addressAddress of a specific slave device (only 7 LSB).
[in]p_dataPointer to a receive buffer.
[in]lengthNumber of bytes to be received. Maximum possible length is dependent on the used SoC (see the MAXCNT register description in the Product Specification). The driver checks it with assertion.
Return values
NRFX_SUCCESSThe procedure is successful.
NRFX_ERROR_BUSYThe driver is not ready for a new transfer.
NRFX_ERROR_INTERNALAn unexpected transition occurred on the bus.
NRFX_ERROR_DRV_TWI_ERR_OVERRUNThe unread data is replaced by new data.
NRFX_ERROR_DRV_TWI_ERR_ANACKNACK is received after sending the address in polling mode.
NRFX_ERROR_DRV_TWI_ERR_DNACKNACK is received after sending a data byte in polling mode.
uint32_t nrfx_twim_start_task_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_instancePointer to the driver instance structure.
[in]xfer_typeTransfer 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_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_instancePointer to the driver instance structure.
Returns
STOPPED event address.
nrfx_err_t nrfx_twim_tx ( nrfx_twim_t const *  p_instance,
uint8_t  address,
uint8_t const *  p_data,
size_t  length,
bool  no_stop 
)

Function for sending data to a TWI slave.

The transmission will be stopped when an error occurs. If a transfer is ongoing, the function returns the error code NRFX_ERROR_BUSY.

Note
This function is deprecated. Use nrfx_twim_xfer instead.
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 fails with the error code NRFX_ERROR_INVALID_ADDR.
Parameters
[in]p_instancePointer to the driver instance structure.
[in]addressAddress of a specific slave device (only 7 LSB).
[in]p_dataPointer to a transmit buffer.
[in]lengthNumber of bytes to send. Maximum possible length is dependent on the used SoC (see the MAXCNT register description in the Product Specification). The driver checks it with assertion.
[in]no_stopIf set, the stop condition is not generated on the bus after the transfer has completed successfully (allowing for a repeated start in the next transfer).
Return values
NRFX_SUCCESSThe procedure is successful.
NRFX_ERROR_BUSYThe driver is not ready for a new transfer.
NRFX_ERROR_INTERNALAn unexpected transition occurred on the bus.
NRFX_ERROR_INVALID_ADDRThe provided buffer is not placed in the Data RAM region.
NRFX_ERROR_DRV_TWI_ERR_ANACKNACK is received after sending the address in polling mode.
NRFX_ERROR_DRV_TWI_ERR_DNACKNACK is received after sending a data byte in polling mode.
void nrfx_twim_uninit ( nrfx_twim_t const *  p_instance)

Function for uninitializing the TWI instance.

Parameters
[in]p_instancePointer 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):

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

Additional options are provided using the flags parameter:

Note
Some flag combinations are invalid:

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 NRFX_ERROR_INVALID_ADDR.
Parameters
[in]p_instancePointer to the driver instance structure.
[in]p_xfer_descPointer to the transfer descriptor.
[in]flagsTransfer options (0 for default settings).
Return values
NRFX_SUCCESSThe procedure is successful.
NRFX_ERROR_BUSYThe driver is not ready for a new transfer.
NRFX_ERROR_NOT_SUPPORTEDThe provided parameters are not supported.
NRFX_ERROR_INTERNALAn unexpected transition occurred on the bus.
NRFX_ERROR_INVALID_ADDRThe provided buffers are not placed in the Data RAM region.
NRFX_ERROR_DRV_TWI_ERR_OVERRUNThe unread data is replaced by new data.
NRFX_ERROR_DRV_TWI_ERR_ANACKNACK is received after sending the address.
NRFX_ERROR_DRV_TWI_ERR_DNACKNACK is received after sending a data byte.

Documentation feedback | Developer Zone | Subscribe | Updated