Two Wire Interface Slave with EasyDMA (TWIS) peripheral driver. More...

Topics
	TWIS peripheral driver configuration

Data Structures
struct	nrfx_twis_event_t
	TWIS driver event structure. More...

struct	nrfx_twis_t
	TWIS driver instance data structure. More...

struct	nrfx_twis_config_t
	Structure for TWIS configuration. More...

Macros
#define	NRFX_TWIS_INSTANCE(reg)
	Macro for creating a TWIS driver instance.

#define	NRFX_TWIS_DEFAULT_CONFIG(_pin_scl, _pin_sda, _addr)
	TWIS driver default configuration.

Typedefs
typedef void(*	nrfx_twis_event_handler_t) (nrfx_twis_event_t const *p_event)
	TWIS driver event handler type.

Enumerations
enum	nrfx_twis_substate_t { NRFX_TWIS_SUBSTATE_IDLE , NRFX_TWIS_SUBSTATE_READ_WAITING , NRFX_TWIS_SUBSTATE_READ_PENDING , NRFX_TWIS_SUBSTATE_WRITE_WAITING , NRFX_TWIS_SUBSTATE_WRITE_PENDING }
	Actual state of internal state machine. More...

enum	nrfx_twis_event_type_t { NRFX_TWIS_EVT_READ_REQ , NRFX_TWIS_EVT_READ_DONE , NRFX_TWIS_EVT_READ_ERROR , NRFX_TWIS_EVT_WRITE_REQ , NRFX_TWIS_EVT_WRITE_DONE , NRFX_TWIS_EVT_WRITE_ERROR , NRFX_TWIS_EVT_GENERAL_ERROR }
	Event callback function event definitions. More...

enum	nrfx_twis_error_t { NRFX_TWIS_ERROR_OVERFLOW = NRF_TWIS_ERROR_OVERFLOW , NRFX_TWIS_ERROR_DATA_NACK = NRF_TWIS_ERROR_DATA_NACK , NRFX_TWIS_ERROR_OVERREAD = NRF_TWIS_ERROR_OVERREAD , NRFX_TWIS_ERROR_UNEXPECTED_EVENT = 1 << 8 }
	Possible error sources. More...

Functions
int	nrfx_twis_init (nrfx_twis_t p_instance, nrfx_twis_config_t const p_config, nrfx_twis_event_handler_t event_handler)
	Function for initializing the TWIS driver instance.

int	nrfx_twis_reconfigure (nrfx_twis_t p_instance, nrfx_twis_config_t const p_config)
	Function for reconfiguring the TWIS driver instance.

void	nrfx_twis_uninit (nrfx_twis_t *p_instance)
	Function for uninitializing the TWIS driver instance.

bool	nrfx_twis_init_check (nrfx_twis_t const *p_instance)
	Function for checking if the TWIS driver instance is initialized.

void	nrfx_twis_enable (nrfx_twis_t *p_instance)
	Function for enabling the TWIS instance.

void	nrfx_twis_disable (nrfx_twis_t *p_instance)
	Function for disabling the TWIS instance.

uint32_t	nrfx_twis_error_get_and_clear (nrfx_twis_t *p_instance)
	Function for getting and clearing the last error flags.

int	nrfx_twis_tx_prepare (nrfx_twis_t p_instance, void const p_buf, size_t size)
	Function for preparing the data for sending.

NRFX_STATIC_INLINE size_t	nrfx_twis_tx_amount (nrfx_twis_t const *p_instance)
	Function for getting the number of transmitted bytes.

int	nrfx_twis_rx_prepare (nrfx_twis_t p_instance, void p_buf, size_t size)
	Function for preparing the data for receiving.

NRFX_STATIC_INLINE size_t	nrfx_twis_rx_amount (nrfx_twis_t const *p_instance)
	Function for getting the number of received bytes.

bool	nrfx_twis_is_busy (nrfx_twis_t *p_instance)
	Function for checking if the driver is busy right now.

bool	nrfx_twis_is_waiting_tx_buff (nrfx_twis_t *p_instance)
	Function for checking if the driver is waiting for a TX buffer.

bool	nrfx_twis_is_waiting_rx_buff (nrfx_twis_t *p_instance)
	Function for checking if the driver is waiting for an RX buffer.

bool	nrfx_twis_is_pending_tx (nrfx_twis_t *p_instance)
	Function for checking if the driver is sending data.

bool	nrfx_twis_is_pending_rx (nrfx_twis_t *p_instance)
	Function for checking if the driver is receiving data.

void	nrfx_twis_irq_handler (nrfx_twis_t *p_instance)
	Driver interrupt handler.

Detailed Description

Two Wire Interface Slave with EasyDMA (TWIS) peripheral driver.

Macro Definition Documentation

◆ NRFX_TWIS_DEFAULT_CONFIG

#define NRFX_TWIS_DEFAULT_CONFIG	(	_pin_scl,
		_pin_sda,
		_addr )

Value:

{                                                                \
    .addr               = { _addr, 0x00 },                       \
    .scl_pin            = _pin_scl,                              \
    .sda_pin            = _pin_sda,                              \
    .scl_pull           = NRF_GPIO_PIN_NOPULL,                   \
    .sda_pull           = NRF_GPIO_PIN_NOPULL,                   \
    .interrupt_priority = NRFX_TWIS_DEFAULT_CONFIG_IRQ_PRIORITY  \
}

TWIS driver default configuration.

This configuration sets up TWIS with the following options:

second slave address disabled
SCL pull-up disabled
SDA pull-up disabled

Parameters

[in]	_pin_scl	SCL pin.
[in]	_pin_sda	SDA pin.
[in]	_addr	Slave address on TWI bus.

◆ NRFX_TWIS_INSTANCE

#define NRFX_TWIS_INSTANCE ( reg )

Value:

{                                  \
    .p_reg = (NRF_TWIS_Type *)reg, \
    .cb    = {0},                  \
}

Macro for creating a TWIS driver instance.

Enumeration Type Documentation

◆ nrfx_twis_error_t

enum nrfx_twis_error_t

Possible error sources.

This is flag enum - values from this enum can be connected using logical or operator.

Note: You can use directly nrf_twis_error_t. Error type enum is redefined here because of possible future extension (eg. supporting timeouts and synchronous mode).

Enumerator
NRFX_TWIS_ERROR_OVERFLOW	RX buffer overflow detected, and prevented.
NRFX_TWIS_ERROR_DATA_NACK	NACK sent after receiving a data byte.
NRFX_TWIS_ERROR_OVERREAD	TX buffer over-read detected, and prevented.
NRFX_TWIS_ERROR_UNEXPECTED_EVENT	Unexpected event detected by state machine.

◆ nrfx_twis_event_type_t

enum nrfx_twis_event_type_t

Event callback function event definitions.

Enumerator
NRFX_TWIS_EVT_READ_REQ	Read request detected. If there is no buffer prepared, buf_req flag in the even will be set. Call then nrfx_twis_tx_prepare to give parameters for buffer.
NRFX_TWIS_EVT_READ_DONE	Read request finished - free any data.
NRFX_TWIS_EVT_READ_ERROR	Read request finished with error.
NRFX_TWIS_EVT_WRITE_REQ	Write request detected. If there is no buffer prepared, buf_req flag in the even will be set. Call then nrfx_twis_rx_prepare to give parameters for buffer.
NRFX_TWIS_EVT_WRITE_DONE	Write request finished - process data.
NRFX_TWIS_EVT_WRITE_ERROR	Write request finished with error.
NRFX_TWIS_EVT_GENERAL_ERROR	Error that happens not inside WRITE or READ transaction.

◆ nrfx_twis_substate_t

enum nrfx_twis_substate_t

Actual state of internal state machine.

Current substate of powered on state.

Enumerator
NRFX_TWIS_SUBSTATE_IDLE	No ongoing transmission.
NRFX_TWIS_SUBSTATE_READ_WAITING	Read request received, waiting for data.
NRFX_TWIS_SUBSTATE_READ_PENDING	Reading is actually pending (data sending)
NRFX_TWIS_SUBSTATE_WRITE_WAITING	Write request received, waiting for data buffer.
NRFX_TWIS_SUBSTATE_WRITE_PENDING	Writing is actually pending (data receiving)

Function Documentation

◆ nrfx_twis_disable()

void nrfx_twis_disable ( nrfx_twis_t * p_instance )

Function for disabling the TWIS instance.

This function disables the TWIS instance, which gives possibility to turn off the TWIS while holding configuration done by nrfx_twis_init.

Parameters

p_instance Pointer to the driver instance structure.

◆ nrfx_twis_enable()

void nrfx_twis_enable ( nrfx_twis_t * p_instance )

Function for enabling the TWIS instance.

This function enables the TWIS instance. Function defined if there is need for dynamically enabling and disabling the peripheral. Use nrfx_twis_enable and nrfx_twis_disable functions. They do not change any configuration registers.

Parameters

p_instance Pointer to the driver instance structure.

◆ nrfx_twis_error_get_and_clear()

uint32_t nrfx_twis_error_get_and_clear ( nrfx_twis_t * p_instance )

Function for getting and clearing the last error flags.

This function gets the information about errors. This is also the only possibility to exit from the error substate of the internal state machine.

Attention: This function clears error state and flags.

Parameters

[in] p_instance Pointer to the driver instance structure.

Returns: Error flags defined in nrfx_twis_error_t.

◆ nrfx_twis_init()

int nrfx_twis_init	(	nrfx_twis_t *	p_instance,
		nrfx_twis_config_t const *	p_config,
		nrfx_twis_event_handler_t	event_handler )

Function for initializing the TWIS driver instance.

Function initializes and enables the TWIS driver.

Attention: After driver initialization enable it with nrfx_twis_enable.

Parameters

[in] p_instance Pointer to the driver instance structure.

Attention: p_instance has to be global object. It will be used by interrupts so make it sure that object is not destroyed when function is leaving.

Parameters

[in]	p_config	Pointer to the structure with the initial configuration.
[in]	event_handler	Event handler provided by the user. If NULL, blocking mode is enabled.

Return values

0	Initialization is successful.
-EALREADY	The driver is already initialized.
-EBUSY	Some other peripheral with the same instance ID is already in use. This is possible only if NRFX_PRS_ENABLED is set to a value other than zero.

◆ nrfx_twis_init_check()

bool nrfx_twis_init_check ( nrfx_twis_t const * p_instance )

Function for checking if the TWIS driver instance is initialized.

Parameters

[in] p_instance Pointer to the driver instance structure.

Return values

true	Instance is already initialized.
false	Instance is not initialized.

◆ nrfx_twis_irq_handler()

void nrfx_twis_irq_handler ( nrfx_twis_t * p_instance )

Driver interrupt handler.

Parameters

[in] p_instance Pointer to the driver instance structure.

◆ nrfx_twis_is_busy()

bool nrfx_twis_is_busy ( nrfx_twis_t * p_instance )

Function for checking if the driver is busy right now.

This function tests the actual driver substate. If the driver is in any other state than IDLE or ERROR, this function returns true.

Parameters

[in] p_instance Pointer to the driver instance structure.

Return values

true	The driver is in state other than ERROR or IDLE.
false	There is no transmission pending.

◆ nrfx_twis_is_pending_rx()

bool nrfx_twis_is_pending_rx ( nrfx_twis_t * p_instance )

Function for checking if the driver is receiving data.

If this function returns true, there is an ongoing input transmission.

Parameters

[in] p_instance Pointer to the driver instance structure.

Return values

true	There is an ongoing input transmission.
false	The driver is in other state.

◆ nrfx_twis_is_pending_tx()

bool nrfx_twis_is_pending_tx ( nrfx_twis_t * p_instance )

Function for checking if the driver is sending data.

If this function returns true, there is an ongoing output transmission.

Parameters

[in] p_instance Pointer to the driver instance structure.

Return values

true	There is an ongoing output transmission.
false	The driver is in other state.

◆ nrfx_twis_is_waiting_rx_buff()

bool nrfx_twis_is_waiting_rx_buff ( nrfx_twis_t * p_instance )

Function for checking if the driver is waiting for an RX buffer.

If this function returns true, the driver is stalled expecting of the nrfx_twis_rx_prepare function call.

Parameters

[in] p_instance Pointer to the driver instance structure.

Return values

true	The driver is waiting for nrfx_twis_rx_prepare.
false	The driver is not in the state where it is waiting for preparing an RX buffer.

◆ nrfx_twis_is_waiting_tx_buff()

bool nrfx_twis_is_waiting_tx_buff ( nrfx_twis_t * p_instance )

Function for checking if the driver is waiting for a TX buffer.

If this function returns true, the driver is stalled expecting of the nrfx_twis_tx_prepare function call.

Parameters

[in] p_instance Pointer to the driver instance structure.

Return values

true	The driver is waiting for nrfx_twis_tx_prepare.
false	The driver is not in the state where it is waiting for preparing a TX buffer.

◆ nrfx_twis_reconfigure()

int nrfx_twis_reconfigure	(	nrfx_twis_t *	p_instance,
		nrfx_twis_config_t const *	p_config )

Function for reconfiguring the TWIS driver instance.

Parameters

[in]	p_instance	Pointer to the driver instance structure.
[in]	p_config	Pointer to the structure with the configuration.

Return values

0	Reconfiguration was successful.
-EBUSY	The driver is during transaction.
-EINPROGRESS	The driver is uninitialized.

◆ nrfx_twis_rx_amount()

NRFX_STATIC_INLINE size_t nrfx_twis_rx_amount ( nrfx_twis_t const * p_instance )

Function for getting the number of received bytes.

This function returns number of bytes received. It can be called after NRFX_TWIS_EVT_WRITE_DONE or NRFX_TWIS_EVT_WRITE_ERROR events.

Parameters

[in] p_instance Pointer to the driver instance structure.

Returns: Number of bytes received.

◆ nrfx_twis_rx_prepare()

int nrfx_twis_rx_prepare	(	nrfx_twis_t *	p_instance,
		void *	p_buf,
		size_t	size )

Function for preparing the data for receiving.

This function must be used in response to the NRFX_TWIS_EVT_WRITE_REQ event.

Note: Peripherals using EasyDMA (including TWIS) 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 -EINVAL.

Parameters

[in]	p_instance	Pointer to the driver instance structure.
[in]	p_buf	Buffer that is to be filled with received data.
[in]	size	Size of the buffer (maximum amount of data to receive).

Return values

0	The preparation finished properly.
-EACCES	The given p_buf is not placed inside the RAM.
-EINVAL	There is a wrong value in the size parameter.
-EINPROGRESS	The module is not initialized or not enabled.

◆ nrfx_twis_tx_amount()

NRFX_STATIC_INLINE size_t nrfx_twis_tx_amount ( nrfx_twis_t const * p_instance )

Function for getting the number of transmitted bytes.

This function returns the number of bytes sent. This function can be called after NRFX_TWIS_EVT_READ_DONE or NRFX_TWIS_EVT_READ_ERROR events.

Parameters

[in] p_instance Pointer to the driver instance structure.

Returns: Number of bytes sent.

◆ nrfx_twis_tx_prepare()

int nrfx_twis_tx_prepare	(	nrfx_twis_t *	p_instance,
		void const *	p_buf,
		size_t	size )

Function for preparing the data for sending.

This function is to be used in response to the NRFX_TWIS_EVT_READ_REQ event.

Note: Peripherals using EasyDMA (including TWIS) 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 -EINVAL.

Attention: Transmission buffer must be placed in RAM.

Parameters

[in]	p_instance	Pointer to the driver instance structure.
[in]	p_buf	Transmission buffer.
[in]	size	Maximum number of bytes that master may read from buffer given.

Return values

0	The preparation finished properly.
-EACCES	The given p_buf is not placed inside the RAM.
-EINVAL	There is a wrong value in the size parameter.
-EINPROGRESS	The module is not initialized or not enabled.

◆ nrfx_twis_uninit()

void nrfx_twis_uninit ( nrfx_twis_t * p_instance )

Function for uninitializing the TWIS driver instance.

Function uninitializes the peripheral and resets all registers to default values.

Note: It is safe to call nrfx_twis_uninit even before initialization. Actually, nrfx_twis_init function calls this function to make sure that TWIS state is known.; If TWIS driver was in uninitialized state before calling this function, the selected pins would not be reset to default configuration.

Parameters

[in] p_instance Pointer to the driver instance structure.

Topics

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ NRFX_TWIS_DEFAULT_CONFIG

◆ NRFX_TWIS_INSTANCE

Enumeration Type Documentation

◆ nrfx_twis_error_t

◆ nrfx_twis_event_type_t

◆ nrfx_twis_substate_t

Function Documentation

◆ nrfx_twis_disable()

◆ nrfx_twis_enable()

◆ nrfx_twis_error_get_and_clear()

◆ nrfx_twis_init()

◆ nrfx_twis_init_check()

◆ nrfx_twis_irq_handler()

◆ nrfx_twis_is_busy()

◆ nrfx_twis_is_pending_rx()

◆ nrfx_twis_is_pending_tx()

◆ nrfx_twis_is_waiting_rx_buff()

◆ nrfx_twis_is_waiting_tx_buff()

◆ nrfx_twis_reconfigure()

◆ nrfx_twis_rx_amount()

◆ nrfx_twis_rx_prepare()

◆ nrfx_twis_tx_amount()

◆ nrfx_twis_tx_prepare()

◆ nrfx_twis_uninit()