nRF5 SDK v12.1.0
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions

TWI master APIs. More...

Modules

 TWI/TWIM peripheral driver configuration
 

Data Structures

struct  nrf_drv_twi_t
 Structure for the TWI master driver instance. More...
 
struct  nrf_drv_twi_config_t
 Structure for the TWI master driver instance configuration. More...
 
struct  nrf_drv_twi_xfer_desc_t
 Structure for a TWI transfer descriptor. More...
 
struct  nrf_drv_twi_evt_t
 Structure for a TWI event. More...
 

Macros

#define NRF_DRV_TWI_PERIPHERAL(id)   (void *)CONCAT_2(NRF_TWI, id)
 
#define TWI0_INSTANCE_INDEX   0
 
#define TWI1_INSTANCE_INDEX   TWI0_INSTANCE_INDEX+TWI0_ENABLED
 
#define NRF_DRV_TWI_INSTANCE(id)
 Macro for creating a TWI master driver instance. More...
 
#define NRF_DRV_TWI_DEFAULT_CONFIG
 TWI master driver instance default configuration. More...
 
#define NRF_DRV_TWI_FLAG_TX_POSTINC   (1UL << 0)
 
#define NRF_DRV_TWI_FLAG_RX_POSTINC   (1UL << 1)
 
#define NRF_DRV_TWI_FLAG_NO_XFER_EVT_HANDLER   (1UL << 2)
 
#define NRF_DRV_TWI_FLAG_HOLD_XFER   (1UL << 3)
 
#define NRF_DRV_TWI_FLAG_REPEATED_XFER   (1UL << 4)
 
#define NRF_DRV_TWI_FLAG_TX_NO_STOP   (1UL << 5)
 
#define NRF_DRV_TWI_XFER_DESC_TX(addr, p_data, length)
 Macro for setting the TX transfer descriptor. More...
 
#define NRF_DRV_TWI_XFER_DESC_RX(addr, p_data, length)
 Macro for setting the RX transfer descriptor. More...
 
#define NRF_DRV_TWI_XFER_DESC_TXRX(addr, p_tx, tx_len, p_rx, rx_len)
 Macro for setting the TXRX transfer descriptor. More...
 
#define NRF_DRV_TWI_XFER_DESC_TXTX(addr, p_tx, tx_len, p_tx2, tx_len2)
 Macro for setting the TXTX transfer descriptor. More...
 

Typedefs

typedef void(* nrf_drv_twi_evt_handler_t )(nrf_drv_twi_evt_t const *p_event, void *p_context)
 TWI event handler prototype.
 

Enumerations

enum  nrf_drv_twi_evt_type_t {
  NRF_DRV_TWI_EVT_DONE,
  NRF_DRV_TWI_EVT_ADDRESS_NACK,
  NRF_DRV_TWI_EVT_DATA_NACK
}
 TWI master driver event types. More...
 
enum  nrf_drv_twi_xfer_type_t {
  NRF_DRV_TWI_XFER_TX,
  NRF_DRV_TWI_XFER_RX,
  NRF_DRV_TWI_XFER_TXRX,
  NRF_DRV_TWI_XFER_TXTX
}
 TWI master driver transfer types. More...
 

Functions

ret_code_t nrf_drv_twi_init (nrf_drv_twi_t const *p_instance, nrf_drv_twi_config_t const *p_config, nrf_drv_twi_evt_handler_t event_handler, void *p_context)
 Function for initializing the TWI driver instance. More...
 
void nrf_drv_twi_uninit (nrf_drv_twi_t const *p_instance)
 Function for uninitializing the TWI instance. More...
 
void nrf_drv_twi_enable (nrf_drv_twi_t const *p_instance)
 Function for enabling the TWI instance. More...
 
void nrf_drv_twi_disable (nrf_drv_twi_t const *p_instance)
 Function for disabling the TWI instance. More...
 
ret_code_t nrf_drv_twi_tx (nrf_drv_twi_t const *p_instance, uint8_t address, uint8_t const *p_data, uint8_t length, bool no_stop)
 Function for sending data to a TWI slave. More...
 
ret_code_t nrf_drv_twi_rx (nrf_drv_twi_t const *p_instance, uint8_t address, uint8_t *p_data, uint8_t length)
 Function for reading data from a TWI slave. More...
 
ret_code_t nrf_drv_twi_xfer (nrf_drv_twi_t const *p_instance, nrf_drv_twi_xfer_desc_t const *p_xfer_desc, uint32_t flags)
 Function for preparing a TWI transfer. More...
 
uint32_t nrf_drv_twi_data_count_get (nrf_drv_twi_t const *const p_instance)
 Function for getting the transferred data count. More...
 
uint32_t nrf_drv_twi_start_task_get (nrf_drv_twi_t const *p_instance, nrf_drv_twi_xfer_type_t xfer_type)
 Function for returning the address of a TWI/TWIM start task. More...
 
uint32_t nrf_drv_twi_stopped_event_get (nrf_drv_twi_t const *p_instance)
 Function for returning the address of a STOPPED TWI/TWIM event. More...
 

Detailed Description

TWI master APIs.

Macro Definition Documentation

#define NRF_DRV_TWI_DEFAULT_CONFIG
Value:
{ \
.scl = 31, \
.sda = 31, \
.interrupt_priority = TWI_DEFAULT_CONFIG_IRQ_PRIORITY, \
.clear_bus_init = TWI_DEFAULT_CONFIG_CLR_BUS_INIT, \
.hold_bus_uninit = TWI_DEFAULT_CONFIG_HOLD_BUS_UNINIT, \
}

TWI master driver instance default configuration.

#define NRF_DRV_TWI_FLAG_HOLD_XFER   (1UL << 3)

Set up the transfer but do not start it.

#define NRF_DRV_TWI_FLAG_NO_XFER_EVT_HANDLER   (1UL << 2)

Interrupt after each transfer is suppressed, and the event handler is not called.

#define NRF_DRV_TWI_FLAG_REPEATED_XFER   (1UL << 4)

Flag indicating that the transfer will be executed multiple times.

#define NRF_DRV_TWI_FLAG_RX_POSTINC   (1UL << 1)

RX buffer address incremented after transfer.

#define NRF_DRV_TWI_FLAG_TX_NO_STOP   (1UL << 5)

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

#define NRF_DRV_TWI_FLAG_TX_POSTINC   (1UL << 0)

TX buffer address incremented after transfer.

#define NRF_DRV_TWI_INSTANCE (   id)
Value:
{ \
.reg = {NRF_DRV_TWI_PERIPHERAL(id)}, \
.drv_inst_idx = CONCAT_3(TWI, id, _INSTANCE_INDEX), \
.use_easy_dma = CONCAT_3(TWI, id, _USE_EASY_DMA) \
}

Macro for creating a TWI master driver instance.

#define NRF_DRV_TWI_XFER_DESC_RX (   addr,
  p_data,
  length 
)
Value:
{ \
.address = addr, \
.primary_length = length, \
.p_primary_buf = p_data, \
}

Macro for setting the RX transfer descriptor.

#define NRF_DRV_TWI_XFER_DESC_TX (   addr,
  p_data,
  length 
)
Value:
{ \
.address = addr, \
.primary_length = length, \
.p_primary_buf = p_data, \
}

Macro for setting the TX transfer descriptor.

#define NRF_DRV_TWI_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 TXRX transfer descriptor.

#define NRF_DRV_TWI_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 TXTX transfer descriptor.

Enumeration Type Documentation

TWI master driver event types.

Enumerator
NRF_DRV_TWI_EVT_DONE 

Transfer completed event.

NRF_DRV_TWI_EVT_ADDRESS_NACK 

Error event: NACK received after sending the address.

NRF_DRV_TWI_EVT_DATA_NACK 

Error event: NACK received after sending a data byte.

TWI master driver transfer types.

Enumerator
NRF_DRV_TWI_XFER_TX 

TX transfer.

NRF_DRV_TWI_XFER_RX 

RX transfer.

NRF_DRV_TWI_XFER_TXRX 

TX transfer followed by RX transfer with repeated start.

NRF_DRV_TWI_XFER_TXTX 

TX transfer followed by TX transfer with repeated start.

Function Documentation

uint32_t nrf_drv_twi_data_count_get ( nrf_drv_twi_t const *const  p_instance)

Function for getting the transferred data count.

This function provides valid results only in legacy mode.

Parameters
[in]p_instancePointer to the driver instance structure.
Returns
Data count.
void nrf_drv_twi_disable ( nrf_drv_twi_t const *  p_instance)

Function for disabling the TWI instance.

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

Function for enabling the TWI instance.

Parameters
[in]p_instancePointer to the driver instance structure.
ret_code_t nrf_drv_twi_init ( nrf_drv_twi_t const *  p_instance,
nrf_drv_twi_config_t const *  p_config,
nrf_drv_twi_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_configInitial configuration. If NULL, the default configuration is used.
[in]event_handlerEvent handler provided by the user. If NULL, blocking mode is enabled.
[in]p_contextContext passed to event handler.
Return values
NRF_SUCCESSIf initialization was successful.
NRF_ERROR_INVALID_STATEIf the driver is in invalid state.
NRF_ERROR_BUSYIf some other peripheral with the same instance ID is already in use. This is possible only if PERIPHERAL_RESOURCE_SHARING_ENABLED is set to a value other than zero.
ret_code_t nrf_drv_twi_rx ( nrf_drv_twi_t const *  p_instance,
uint8_t  address,
uint8_t *  p_data,
uint8_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 NRF_ERROR_BUSY.

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.
Return values
NRF_SUCCESSIf the procedure was successful.
NRF_ERROR_BUSYIf the driver is not ready for a new transfer.
NRF_ERROR_INTERNALIf an error was detected by hardware.
DRV_TWI_ERR_OVERRUNIf the unread data was replaced by new data
DRV_TWI_ERR_ANACKIf NACK received after sending the address.
DRV_TWI_ERR_DNACKIf NACK received after sending a data byte.
uint32_t nrf_drv_twi_start_task_get ( nrf_drv_twi_t const *  p_instance,
nrf_drv_twi_xfer_type_t  xfer_type 
)

Function for returning the address of a TWI/TWIM start task.

This function should be used if nrf_drv_twi_xfer was called with the flag NRF_DRV_TWI_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 nrf_drv_twi_xfer function.
Returns
Start task address (TX or RX) depending on the value of xfer_type.
uint32_t nrf_drv_twi_stopped_event_get ( nrf_drv_twi_t const *  p_instance)

Function for returning the address of a STOPPED TWI/TWIM event.

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

Parameters
[in]p_instancePointer to the driver instance structure.
Returns
STOPPED event address.
ret_code_t nrf_drv_twi_tx ( nrf_drv_twi_t const *  p_instance,
uint8_t  address,
uint8_t const *  p_data,
uint8_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 NRF_ERROR_BUSY.

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.
[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
NRF_SUCCESSIf the procedure was successful.
NRF_ERROR_BUSYIf the driver is not ready for a new transfer.
NRF_ERROR_INTERNALIf an error was detected by hardware.
NRF_ERROR_INVALID_ADDRIf the EasyDMA is used and memory adress in not in RAM.
DRV_TWI_ERR_ANACKIf NACK received after sending the address.
DRV_TWI_ERR_DNACKIf NACK received after sending a data byte.
void nrf_drv_twi_uninit ( nrf_drv_twi_t const *  p_instance)

Function for uninitializing the TWI instance.

Parameters
[in]p_instancePointer to the driver instance structure.
ret_code_t nrf_drv_twi_xfer ( nrf_drv_twi_t const *  p_instance,
nrf_drv_twi_xfer_desc_t const *  p_xfer_desc,
uint32_t  flags 
)

Function for preparing a TWI transfer.

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

Additional options are provided using the flags parameter:

Note
Some flag combinations are invalid:

If nrf_drv_twi_xfer_desc_t::type is set to NRF_DRV_TWI_XFER_TX and the NRF_DRV_TWI_FLAG_TX_NO_STOP and NRF_DRV_TWI_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
This function should be used only if the instance is configured to work in non-blocking mode. If the function is used in blocking mode, the driver asserts.
If you are using this function with TWI, the only supported flag is NRF_DRV_TWI_FLAG_TX_NO_STOP. All other flags require TWIM.
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
NRF_SUCCESSIf the procedure was successful.
NRF_ERROR_BUSYIf the driver is not ready for a new transfer.
NRF_ERROR_NOT_SUPPORTEDIf the provided parameters are not supported.
NRF_ERROR_INTERNALIf an error was detected by hardware.
NRF_ERROR_INVALID_ADDRIf the EasyDMA is used and memory adress in not in RAM
DRV_TWI_ERR_OVERRUNIf the unread data was replaced by new data (TXRX and RX)
DRV_TWI_ERR_ANACKIf NACK received after sending the address.
DRV_TWI_ERR_DNACKIf NACK received after sending a data byte.

Documentation feedback | Developer Zone | Subscribe | Updated