| 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 | Functions
TWI transaction manager
SDK common libraries

Module for scheduling TWI transactions. More...

## Modules
| TWI transaction manager configuration

## Data Structures
struct | app_twi_transfer_t
| TWI transfer descriptor. More...
struct | app_twi_transaction_t
| TWI transaction descriptor. More...
struct | app_twi_queue_t
| TWI transaction queue. More...
struct | app_twi_t
| TWI transaction manager instance. More...

## Macros
#define | APP_TWI_NO_STOP 0x01
| Flag indicating that a given transfer should not be ended with a stop condition. More...
#define | APP_TWI_WRITE(address, p_data, length, flags) APP_TWI_TRANSFER(APP_TWI_WRITE_OP(address), p_data, length, flags)
| Macro for creating a write transfer. More...
#define | APP_TWI_READ(address, p_data, length, flags) APP_TWI_TRANSFER(APP_TWI_READ_OP(address), p_data, length, flags)
| Macro for creating a read transfer. More...
#define | APP_TWI_TRANSFER(_operation, _p_data, _length, _flags)
| Helper macro, should not be used directly. More...
#define | APP_TWI_WRITE_OP(address) (((address) << 1) | 0)
| Helper macro, should not be used directly.
#define | APP_TWI_READ_OP(address) (((address) << 1) | 1)
| Helper macro, should not be used directly.
#define | APP_TWI_IS_READ_OP(operation) ((operation) & 1)
| Helper macro, should not be used directly.
#define | APP_TWI_OP_ADDRESS(operation) ((operation) >> 1)
| Helper macro, should not be used directly.
#define | APP_TWI_INSTANCE(twi_idx)
| Macro for creating an instance of the TWI transaction manager. More...
#define | APP_TWI_INIT(p_app_twi, p_twi_config, queue_size, err_code)
| Macro that simplifies the initialization of a TWI transaction manager instance. More...

## Typedefs
typedef void(* | app_twi_callback_t )(ret_code_t result, void *p_user_data)
| TWI transaction callback prototype. More...

## Functions
ret_code_t | app_twi_init (app_twi_t *p_app_twi, nrf_drv_twi_config_t const *p_twi_config, uint8_t queue_size, app_twi_transaction_t const **p_queue_buffer)
| Function for initializing a TWI transaction manager instance. More...
void | app_twi_uninit (app_twi_t *p_app_twi)
| Function for uninitializing a TWI transaction manager instance. More...
ret_code_t | app_twi_schedule (app_twi_t *p_app_twi, app_twi_transaction_t const *p_transaction)
| Function for scheduling a TWI transaction. More...
ret_code_t | app_twi_perform (app_twi_t *p_app_twi, app_twi_transfer_t const *p_transfers, uint8_t number_of_transfers, void(*user_function)(void))
| Function for scheduling a transaction and waiting until it is finished. More...
__STATIC_INLINE bool | app_twi_is_idle (app_twi_t *p_app_twi)
| Function for getting the current state of a TWI transaction manager instance. More...

## Detailed Description

Module for scheduling TWI transactions.

## Macro Definition Documentation

#define APP_TWI_INIT | ( |  | p_app_twi,
|  |  | p_twi_config,
|  |  | queue_size,
|  |  | err_code
| ) |  |

Value:
do { \
static app_twi_transaction_t const * queue_buffer[queue_size + 1]; \
err_code = app_twi_init(p_app_twi, p_twi_config, \
queue_size, queue_buffer); \
} while (0)

Macro that simplifies the initialization of a TWI transaction manager instance.

This macro allocates a static buffer for the transaction queue. Therefore, it should be used in only one place in the code for a given instance.

Parameters

  [in] | p_app_twi | Pointer to the instance to be initialized.
  [in] | p_twi_config | Pointer to the TWI master driver configuration.
  | queue_size | Size of the transaction queue (maximum number of pending transactions). See this note.
  [out] | err_code | The result of the app_twi_init() function call is written to this parameter.

#define APP_TWI_INSTANCE | ( |  | twi_idx | ) |

Value:
{ \
.twi = NRF_DRV_TWI_INSTANCE(twi_idx) \
}

Macro for creating an instance of the TWI transaction manager.

Parameters

  [in] | twi_idx | Index of the TWI master driver instance to be utilized by this manager instance.

#define APP_TWI_NO_STOP 0x01

Flag indicating that a given transfer should not be ended with a stop condition.

Use this flag when a stop condition is undesirable between two transfers, for example, when the first transfer is a write that sets an address in the slave device and the second one is a read that fetches certain data using this address. In this case, the second transfer should follow directly after the first transfer, with a repeated start condition instead of a stop and then a new start condition.

#define APP_TWI_READ | ( |  | address,
|  |  | p_data,
|  |  | length,
|  |  | flags
| ) |  | APP_TWI_TRANSFER(APP_TWI_READ_OP(address), p_data, length, flags)

Macro for creating a read transfer.

Parameters

  | address | Slave address.
  [in] | p_data | Pointer to the buffer where received data should be placed.
  | length | Number of bytes to transfer.
  | flags | Transfer flags (see APP_TWI_NO_STOP).

#define APP_TWI_TRANSFER | ( |  | _operation,
|  |  | _p_data,
|  |  | _length,
|  |  | _flags
| ) |  |

Value:
{ \
.p_data = (uint8_t *)(_p_data), \
.length = _length, \
.operation = _operation, \
.flags = _flags \
}

Helper macro, should not be used directly.

#define APP_TWI_WRITE | ( |  | address,
|  |  | p_data,
|  |  | length,
|  |  | flags
| ) |  | APP_TWI_TRANSFER(APP_TWI_WRITE_OP(address), p_data, length, flags)

Macro for creating a write transfer.

Parameters

  | address | Slave address.
  [in] | p_data | Pointer to the data to be sent.
  | length | Number of bytes to transfer.
  | flags | Transfer flags (see APP_TWI_NO_STOP).

## Typedef Documentation

typedef void(* app_twi_callback_t)(ret_code_t result, void *p_user_data)

TWI transaction callback prototype.

Parameters

  | result | Result of operation (NRF_SUCCESS on success, otherwise a relevant error code).
  [in] | p_user_data | Pointer to user data defined in transaction descriptor.

## Function Documentation

ret_code_t app_twi_init | ( | app_twi_t * | p_app_twi,
|  | nrf_drv_twi_config_t const * | p_twi_config,
|  | uint8_t | queue_size,
|  | app_twi_transaction_t const ** | p_queue_buffer
| ) |  |

Function for initializing a TWI transaction manager instance.

This function initializes the utilized TWI master driver instance and prepares the transaction queue.

Note
  The queue size is the maximum number of pending transactions not counting the one that is currently realized. This means that for an empty queue with size of, for example, 4 elements, it is possible to schedule up to 5 transactions.

Parameters

  [in] | p_app_twi | Pointer to the instance to be initialized.
  [in] | p_twi_config | Pointer to the TWI master driver configuration.
  | queue_size | Size of the transaction queue (maximum number of pending transactions).
  [in] | p_queue_buffer | Pointer to a buffer for queued transactions storage. Due to the queue implementation, the buffer must be big enough to hold queue_size + 1 entries (pointers to transaction descriptors).

Return values

  NRF_SUCCESS | If initialization was successful. Otherwise, the error code returned by the nrf_drv_twi_init() function is returned.

__STATIC_INLINE bool app_twi_is_idle | ( | app_twi_t * | p_app_twi | ) |

Function for getting the current state of a TWI transaction manager instance.

Parameters

  [in] | p_app_twi | Pointer to the TWI transaction manager instance.

Return values

  true | If all scheduled transactions have been finished.
  false | Otherwise.

ret_code_t app_twi_perform | ( | app_twi_t * | p_app_twi,
|  | app_twi_transfer_t const * | p_transfers,
|  | uint8_t | number_of_transfers,
|  | void(*)(void) | user_function
| ) |  |

Function for scheduling a transaction and waiting until it is finished.

This function schedules a transaction that consists of one or more transfers and waits until it is finished.

Parameters

  [in] | p_app_twi | Pointer to the TWI transaction manager instance.
  [in] | p_transfers | Pointer to an array of transfers to be performed.
  | number_of_transfers | Number of transfers to be performed.
  | user_function | User-specified function to be called while waiting. NULL if such functionality is not needed.

Return values

  NRF_SUCCESS | If the transfers have been successfully realized.
  NRF_ERROR_BUSY | If some transfers are already performed (if this function was called from another context).
  - | Other error codes mean that the transaction has ended with the error that is specified in the error code.

ret_code_t app_twi_schedule | ( | app_twi_t * | p_app_twi,
|  | app_twi_transaction_t const * | p_transaction
| ) |  |

Function for scheduling a TWI transaction.

The transaction is enqueued and started as soon as the TWI bus is available, thus when all previously scheduled transactions have been finished (possibly immediately).

Parameters

  [in] | p_app_twi | Pointer to the TWI transaction manager instance.
  [in] | p_transaction | Pointer to the descriptor of the transaction to be scheduled.

Return values

  NRF_SUCCESS | If the transaction has been successfully scheduled.
  NRF_ERROR_BUSY | If the limit of pending transactions has been reached (the transaction queue is full).

void app_twi_uninit | ( | app_twi_t * | p_app_twi | ) |

Function for uninitializing a TWI transaction manager instance.

Parameters

  [in] | p_app_twi | Pointer to the instance to be uninitialized.