nRF5 SDK v13.0.0
Modules | Data Structures | Macros | Typedefs | Functions
TWI transaction manager

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_cb_t
 TWI instance control block. 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_DEF(_app_twi_name, _queue_size, _twi_idx)
 Macro that simplifies defining 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 const *p_app_twi, nrf_drv_twi_config_t const *p_default_twi_config)
 Function for initializing a TWI transaction manager instance. More...
 
void app_twi_uninit (app_twi_t const *p_app_twi)
 Function for uninitializing a TWI transaction manager instance. More...
 
ret_code_t app_twi_schedule (app_twi_t const *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 const *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 const *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_DEF (   _app_twi_name,
  _queue_size,
  _twi_idx 
)
Value:
_app_twi_name##_queue, \
(_queue_size), \
static app_twi_cb_t CONCAT_2(_app_twi_name, _cb); \
static const app_twi_t _app_twi_name = \
{ \
.p_app_twi_cb = &CONCAT_2(_app_twi_name, _cb), \
.p_queue = &_app_twi_name##_queue, \
.twi = NRF_DRV_TWI_INSTANCE(_twi_idx) \
}

Macro that simplifies defining 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.

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]_app_twi_nameName of instance to be created.
[in]_queue_sizeSize of the transaction queue (maximum number of pending transactions).
[in]_twi_idxIndex of hardware TWI instance to be used.
#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
addressSlave address.
[in]p_dataPointer to the buffer where received data should be placed.
lengthNumber of bytes to transfer.
flagsTransfer 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
[in]addressSlave address.
[in]p_dataPointer to the data to be sent.
[in]lengthNumber of bytes to transfer.
[in]flagsTransfer 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
resultResult of operation (NRF_SUCCESS on success, otherwise a relevant error code).
[in]p_user_dataPointer to user data defined in transaction descriptor.

Function Documentation

ret_code_t app_twi_init ( app_twi_t const *  p_app_twi,
nrf_drv_twi_config_t const *  p_default_twi_config 
)

Function for initializing a TWI transaction manager instance.

Parameters
[in]p_app_twiPointer to the instance to be initialized.
[in]p_default_twi_configPointer to the TWI master driver configuration. This configuration will be used whenever the scheduled transaction will have p_twi_configuration set to NULL value.
Returns
Values returned by the nrf_drv_twi_init function.
__STATIC_INLINE bool app_twi_is_idle ( app_twi_t const *  p_app_twi)

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

Parameters
[in]p_app_twiPointer to the TWI transaction manager instance.
Return values
trueIf all scheduled transactions have been finished.
falseOtherwise.
ret_code_t app_twi_perform ( app_twi_t const *  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_twiPointer to the TWI transaction manager instance.
[in]p_transfersPointer to an array of transfers to be performed.
number_of_transfersNumber of transfers to be performed.
user_functionUser-specified function to be called while waiting. NULL if such functionality is not needed.
Return values
NRF_SUCCESSIf the transfers have been successfully realized.
NRF_ERROR_BUSYIf some transfers are already being performed.
-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 const *  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).

Note
If app_twi_transaction_t::p_required_twi_cfg is set to a non-NULL value the module will compare it with app_twi_cb_t::p_current_configuration and reinitialize hardware TWI instance with new parameters if any differences are found. If app_twi_transaction_t::p_required_twi_cfg is set to NULL then it will treat it as it would be set to app_twi_cb_t::default_configuration.
Parameters
[in]p_app_twiPointer to the TWI transaction manager instance.
[in]p_transactionPointer to the descriptor of the transaction to be scheduled.
Return values
NRF_SUCCESSIf the transaction has been successfully scheduled.
NRF_ERROR_NO_MEMIf the queue is full (Only if queue in NRF_QUEUE_MODE_NO_OVERFLOW).
void app_twi_uninit ( app_twi_t const *  p_app_twi)

Function for uninitializing a TWI transaction manager instance.

Parameters
[in]p_app_twiPointer to the instance to be uninitialized.

Documentation feedback | Developer Zone | Subscribe | Updated