| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
TWIS driver
Two Wire master interface (TWI/TWIM)

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:
{ \
.frequency = (nrf_twi_frequency_t)TWI_DEFAULT_CONFIG_FREQUENCY, \
.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:
{ \
.type = NRF_DRV_TWI_XFER_RX, \
.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:
{ \
.type = NRF_DRV_TWI_XFER_TX, \
.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:
{ \
.type = NRF_DRV_TWI_XFER_TXRX, \
.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:
{ \
.type = NRF_DRV_TWI_XFER_TXTX, \
.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

enum nrf_drv_twi_evt_type_t

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.

enum nrf_drv_twi_xfer_type_t

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_instance | Pointer 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_instance | Pointer 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_instance | Pointer 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_instance | Pointer to the driver instance structure.
  [in] | p_config | Initial configuration. If NULL, the default configuration is used.
  [in] | event_handler | Event handler provided by the user. If NULL, blocking mode is enabled.
  [in] | p_context | Context passed to event handler.

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_INVALID_STATE | If the driver is in invalid state.
  NRF_ERROR_BUSY | If 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_instance | Pointer to the driver instance structure.
  [in] | address | Address of a specific slave device (only 7 LSB).
  [in] | p_data | Pointer to a receive buffer.
  [in] | length | Number of bytes to be received.

Return values

  NRF_SUCCESS | If the procedure was successful.
  NRF_ERROR_BUSY | If the driver is not ready for a new transfer.
  NRF_ERROR_INTERNAL | If an error was detected by hardware.
  DRV_TWI_ERR_OVERRUN | If the unread data was replaced by new data
  DRV_TWI_ERR_ANACK | If NACK received after sending the address.
  DRV_TWI_ERR_DNACK | If 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_instance | Pointer to the driver instance structure.
  [in] | xfer_type | Transfer 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_instance | Pointer 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_instance | Pointer to the driver instance structure.
  [in] | address | Address of a specific slave device (only 7 LSB).
  [in] | p_data | Pointer to a transmit buffer.
  [in] | length | Number of bytes to send.
  [in] | no_stop | If 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_SUCCESS | If the procedure was successful.
  NRF_ERROR_BUSY | If the driver is not ready for a new transfer.
  NRF_ERROR_INTERNAL | If an error was detected by hardware.
  NRF_ERROR_INVALID_ADDR | If the EasyDMA is used and memory adress in not in RAM.
  DRV_TWI_ERR_ANACK | If NACK received after sending the address.
  DRV_TWI_ERR_DNACK | If 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_instance | Pointer 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):

- NRF_DRV_TWI_XFER_TXRX: Write operation followed by a read operation (without STOP condition in between).
- NRF_DRV_TWI_XFER_TXTX: Write operation followed by a write operation (without STOP condition in between).
- NRF_DRV_TWI_XFER_TX: Write operation (with or without STOP condition).
- NRF_DRV_TWI_XFER_RX: Read operation (with STOP condition).

Additional options are provided using the flags parameter:

- NRF_DRV_TWI_FLAG_TX_POSTINC and NRF_DRV_TWI_FLAG_RX_POSTINC: Post-incrementation of buffer addresses. Supported only by TWIM.
- NRF_DRV_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.
- NRF_DRV_TWI_FLAG_HOLD_XFER: Driver is not starting the transfer. Use this flag if the transfer is triggered externally by PPI. Supported only by TWIM. Use nrf_drv_twi_start_task_get to get the address of the start task.
- NRF_DRV_TWI_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 NRF_DRV_TWI_FLAG_RX_POSTINC, NRF_DRV_TWI_FLAG_NO_XFER_EVT_HANDLER, and NRF_DRV_TWI_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. nrf_drv_twi_stopped_event_get can be used to get the address of the STOPPED event, which can be used to count the number of transfers. If NRF_DRV_TWI_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. Supported only by TWIM.
- NRF_DRV_TWI_FLAG_TX_NO_STOP: No stop condition after TX transfer.

Note
  Some flag combinations are invalid:
  - NRF_DRV_TWI_FLAG_TX_NO_STOP with nrf_drv_twi_xfer_desc_t::type different than NRF_DRV_TWI_XFER_TX
  - NRF_DRV_TWI_FLAG_REPEATED_XFER with nrf_drv_twi_xfer_desc_t::type set to NRF_DRV_TWI_XFER_TXTX

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_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

  NRF_SUCCESS | If the procedure was successful.
  NRF_ERROR_BUSY | If the driver is not ready for a new transfer.
  NRF_ERROR_NOT_SUPPORTED | If the provided parameters are not supported.
  NRF_ERROR_INTERNAL | If an error was detected by hardware.
  NRF_ERROR_INVALID_ADDR | If the EasyDMA is used and memory adress in not in RAM
  DRV_TWI_ERR_OVERRUN | If the unread data was replaced by new data (TXRX and RX)
  DRV_TWI_ERR_ANACK | If NACK received after sending the address.
  DRV_TWI_ERR_DNACK | If NACK received after sending a data byte.