TWIM peripheral driver. More...

Modules
	TWIM peripheral driver configuration

Data Structures
struct	nrfx_twim_t
	Structure for the TWI master driver instance. More...

struct	nrfx_twim_config_t
	Structure for the TWI master driver instance configuration. More...

struct	nrfx_twim_xfer_desc_t
	Structure for a TWI transfer descriptor. More...

struct	nrfx_twim_evt_t
	Structure for a TWI event. More...

Macros
#define	NRFX_TWIM_INSTANCE (id)
	Macro for creating a TWI master driver instance. More...

#define	NRFX_TWIM_DEFAULT_CONFIG
	TWI master driver instance default configuration. More...

#define	NRFX_TWIM_FLAG_TX_POSTINC (1UL << 0)

#define	NRFX_TWIM_FLAG_RX_POSTINC (1UL << 1)

#define	NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER (1UL << 2)

#define	NRFX_TWIM_FLAG_HOLD_XFER (1UL << 3)

#define	NRFX_TWIM_FLAG_REPEATED_XFER (1UL << 4)

#define	NRFX_TWIM_FLAG_TX_NO_STOP (1UL << 5)

#define	NRFX_TWIM_XFER_DESC_TX (addr, p_data, length)
	Macro for setting the TX transfer descriptor. More...

#define	NRFX_TWIM_XFER_DESC_RX (addr, p_data, length)
	Macro for setting the RX transfer descriptor. More...

#define	NRFX_TWIM_XFER_DESC_TXRX (addr, p_tx, tx_len, p_rx, rx_len)
	Macro for setting the TXRX transfer descriptor. More...

#define	NRFX_TWIM_XFER_DESC_TXTX (addr, p_tx, tx_len, p_tx2, tx_len2)
	Macro for setting the TXTX transfer descriptor. More...

Typedefs
typedef void(*	nrfx_twim_evt_handler_t )( nrfx_twim_evt_t const p_event, void p_context)
	TWI event handler prototype.

Enumerations
enum	{ NRFX_TWIM_ENABLED_COUNT }

enum	nrfx_twim_evt_type_t { NRFX_TWIM_EVT_DONE , NRFX_TWIM_EVT_ADDRESS_NACK , NRFX_TWIM_EVT_DATA_NACK }
	TWI master driver event types. More...

enum	nrfx_twim_xfer_type_t { NRFX_TWIM_XFER_TX , NRFX_TWIM_XFER_RX , NRFX_TWIM_XFER_TXRX , NRFX_TWIM_XFER_TXTX }
	TWI master driver transfer types. More...

Functions
nrfx_err_t	nrfx_twim_init ( nrfx_twim_t const p_instance, nrfx_twim_config_t const p_config, nrfx_twim_evt_handler_t event_handler, void *p_context)
	Function for initializing the TWI driver instance. More...

void	nrfx_twim_uninit ( nrfx_twim_t const *p_instance)
	Function for uninitializing the TWI instance. More...

void	nrfx_twim_enable ( nrfx_twim_t const *p_instance)
	Function for enabling the TWI instance. More...

void	nrfx_twim_disable ( nrfx_twim_t const *p_instance)
	Function for disabling the TWI instance. More...

nrfx_err_t	nrfx_twim_tx ( nrfx_twim_t const p_instance, uint8_t address, uint8_t const p_data, size_t length, bool no_stop)
	Function for sending data to a TWI slave. More...

nrfx_err_t	nrfx_twim_rx ( nrfx_twim_t const p_instance, uint8_t address, uint8_t p_data, size_t length)
	Function for reading data from a TWI slave. More...

nrfx_err_t	nrfx_twim_xfer ( nrfx_twim_t const p_instance, nrfx_twim_xfer_desc_t const p_xfer_desc, uint32_t flags)
	Function for preparing a TWI transfer. More...

bool	nrfx_twim_is_busy ( nrfx_twim_t const *p_instance)
	Function for checking the TWI driver state. More...

uint32_t	nrfx_twim_start_task_get ( nrfx_twim_t const *p_instance, nrfx_twim_xfer_type_t xfer_type)
	Function for returning the address of a TWIM start task. More...

uint32_t	nrfx_twim_stopped_event_get ( nrfx_twim_t const *p_instance)
	Function for returning the address of a STOPPED TWIM event. More...

void	nrfx_twim_0_irq_handler (void)

void	nrfx_twim_1_irq_handler (void)

Detailed Description

TWIM peripheral driver.

Macro Definition Documentation

#define NRFX_TWIM_DEFAULT_CONFIG

Value:

         {                                                                                   \
        
         .frequency          = (
         
          nrf_twim_frequency_t
         
         )
         
          NRFX_TWIM_DEFAULT_CONFIG_FREQUENCY
         
         , \
        
         .scl                = 31,                                                       \
        
         .sda                = 31,                                                       \
        
         .interrupt_priority =
         
          NRFX_TWIM_DEFAULT_CONFIG_IRQ_PRIORITY
         
         ,                    \
        
         .hold_bus_uninit    =
         
          NRFX_TWIM_DEFAULT_CONFIG_HOLD_BUS_UNINIT
         
         ,                 \
        
         }

TWI master driver instance default configuration.

#define NRFX_TWIM_FLAG_HOLD_XFER (1UL << 3)

Set up the transfer but do not start it.

#define NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER (1UL << 2)

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

#define NRFX_TWIM_FLAG_REPEATED_XFER (1UL << 4)

Flag indicating that the transfer will be executed multiple times.

#define NRFX_TWIM_FLAG_RX_POSTINC (1UL << 1)

RX buffer address incremented after transfer.

#define NRFX_TWIM_FLAG_TX_NO_STOP (1UL << 5)

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

#define NRFX_TWIM_FLAG_TX_POSTINC (1UL << 0)

TX buffer address incremented after transfer.

#define NRFX_TWIM_INSTANCE ( id )

Value:

         {                                                            \
        
         .p_twim       =
         
          NRFX_CONCAT_2
         
         (NRF_TWIM,
         
          id
         
         ),             \
        
         .drv_inst_idx =
         
          NRFX_CONCAT_3
         
         (NRFX_TWIM,
         
          id
         
         , _INST_IDX), \
        
         }

Macro for creating a TWI master driver instance.

#define NRFX_TWIM_XFER_DESC_RX	(	addr,
		p_data,
		length
	)

Value:

         {                                                \
        
         .type           =
         
          NRFX_TWIM_XFER_RX
         
         ,         \
        
         .address        = addr,                      \
        
         .primary_length = length,                    \
        
         .p_primary_buf  = p_data,                    \
        
         }

Macro for setting the RX transfer descriptor.

#define NRFX_TWIM_XFER_DESC_TX	(	addr,
		p_data,
		length
	)

Value:

         {                                                \
        
         .type =
         
          NRFX_TWIM_XFER_TX
         
         ,                   \
        
         .address = addr,                             \
        
         .primary_length = length,                    \
        
         .p_primary_buf  = p_data,                    \
        
         }

Macro for setting the TX transfer descriptor.

#define NRFX_TWIM_XFER_DESC_TXRX	(	addr,
		p_tx,
		tx_len,
		p_rx,
		rx_len
	)

Value:

         {                                                              \
        
         .type             =
         
          NRFX_TWIM_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 NRFX_TWIM_XFER_DESC_TXTX	(	addr,
		p_tx,
		tx_len,
		p_tx2,
		tx_len2
	)

Value:

         {                                                                \
        
         .type             =
         
          NRFX_TWIM_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 nrfx_twim_evt_type_t

TWI master driver event types.

Enumerator
NRFX_TWIM_EVT_DONE	Transfer completed event.
NRFX_TWIM_EVT_ADDRESS_NACK	Error event: NACK received after sending the address.
NRFX_TWIM_EVT_DATA_NACK	Error event: NACK received after sending a data byte.

enum nrfx_twim_xfer_type_t

TWI master driver transfer types.

Enumerator
NRFX_TWIM_XFER_TX	TX transfer.
NRFX_TWIM_XFER_RX	RX transfer.
NRFX_TWIM_XFER_TXRX	TX transfer followed by RX transfer with repeated start.
NRFX_TWIM_XFER_TXTX	TX transfer followed by TX transfer with repeated start.

Function Documentation

void nrfx_twim_disable ( nrfx_twim_t const * p_instance )

Function for disabling the TWI instance.

Parameters

[in] p_instance Pointer to the driver instance structure.

void nrfx_twim_enable ( nrfx_twim_t const * p_instance )

Function for enabling the TWI instance.

Parameters

[in] p_instance Pointer to the driver instance structure.

nrfx_err_t nrfx_twim_init	(	nrfx_twim_t const *	p_instance ,
		nrfx_twim_config_t const *	p_config ,
		nrfx_twim_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	Pointer to the structure with initial configuration.
[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

NRFX_SUCCESS	If initialization was successful.
NRFX_ERROR_INVALID_STATE	If the driver is in invalid state.
NRFX_ERROR_BUSY	If some other peripheral with the same instance ID is already in use. This is possible only if Peripheral Resource Sharing (PRS) module is enabled.

bool nrfx_twim_is_busy ( nrfx_twim_t const * p_instance )

Function for checking the TWI driver state.

Parameters

[in] p_instance TWI instance.

Return values

true	If the TWI driver is currently busy performing a transfer.
false	If the TWI driver is ready for a new transfer.

nrfx_err_t nrfx_twim_rx	(	nrfx_twim_t const *	p_instance ,
		uint8_t	address ,
		uint8_t *	p_data ,
		size_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 NRFX_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. Maximum possible length is dependent on the used SoC (see the MAXCNT register description in the Product Specification). The driver checks it with assertion.

Return values

NRFX_SUCCESS	If the procedure was successful.
NRFX_ERROR_BUSY	If the driver is not ready for a new transfer.
NRFX_ERROR_INTERNAL	If an error was detected by hardware.
NRFX_ERROR_DRV_TWI_ERR_ANACK	If NACK received after sending the address in polling mode.
NRFX_ERROR_DRV_TWI_ERR_DNACK	If NACK received after sending a data byte in polling mode.

uint32_t nrfx_twim_start_task_get	(	nrfx_twim_t const *	p_instance ,
		nrfx_twim_xfer_type_t	xfer_type
	)

Function for returning the address of a TWIM start task.

This function should be used if nrfx_twim_xfer was called with the flag NRFX_TWIM_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 nrfx_twim_xfer function.

Returns: Start task address (TX or RX) depending on the value of xfer_type.

uint32_t nrfx_twim_stopped_event_get ( nrfx_twim_t const * p_instance )

Function for returning the address of a STOPPED TWIM event.

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

Parameters

[in] p_instance Pointer to the driver instance structure.

Returns: STOPPED event address.

nrfx_err_t nrfx_twim_tx	(	nrfx_twim_t const *	p_instance ,
		uint8_t	address ,
		uint8_t const *	p_data ,
		size_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 NRFX_ERROR_BUSY .

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

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. Maximum possible length is dependent on the used SoC (see the MAXCNT register description in the Product Specification). The driver checks it with assertion.
[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

NRFX_SUCCESS	If the procedure was successful.
NRFX_ERROR_BUSY	If the driver is not ready for a new transfer.
NRFX_ERROR_INTERNAL	If an error was detected by hardware.
NRFX_ERROR_INVALID_ADDR	If the provided buffer is not placed in the Data RAM region.
NRFX_ERROR_DRV_TWI_ERR_ANACK	If NACK received after sending the address in polling mode.
NRFX_ERROR_DRV_TWI_ERR_DNACK	If NACK received after sending a data byte in polling mode.

void nrfx_twim_uninit ( nrfx_twim_t const * p_instance )

Function for uninitializing the TWI instance.

Parameters

[in] p_instance Pointer to the driver instance structure.

nrfx_err_t nrfx_twim_xfer	(	nrfx_twim_t const *	p_instance ,
		nrfx_twim_xfer_desc_t const *	p_xfer_desc ,
		uint32_t	flags
	)

Function for preparing a TWI transfer.

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

NRFX_TWIM_XFER_TXRX : Write operation followed by a read operation (without STOP condition in between).
NRFX_TWIM_XFER_TXTX : Write operation followed by a write operation (without STOP condition in between).
NRFX_TWIM_XFER_TX : Write operation (with or without STOP condition).
NRFX_TWIM_XFER_RX : Read operation (with STOP condition).

Note: TXRX and TXTX transfers are supported only in non-blocking mode.

Additional options are provided using the flags parameter:

NRFX_TWIM_FLAG_TX_POSTINC and NRFX_TWIM_FLAG_RX_POSTINC : Post-incrementation of buffer addresses. Supported only by TWIM.
NRFX_TWIM_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.
NRFX_TWIM_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 nrfx_twim_start_task_get to get the address of the start task.
NRFX_TWIM_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 NRFX_TWIM_FLAG_RX_POSTINC , NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER , and NRFX_TWIM_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. nrfx_twim_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 NRFX_TWIM_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.
NRFX_TWIM_FLAG_TX_NO_STOP : No stop condition after TX transfer.

Note

Some flag combinations are invalid:

NRFX_TWIM_FLAG_TX_NO_STOP with nrfx_twim_xfer_desc_t::type different than NRFX_TWIM_XFER_TX
NRFX_TWIM_FLAG_REPEATED_XFER with nrfx_twim_xfer_desc_t::type set to NRFX_TWIM_XFER_TXTX

If nrfx_twim_xfer_desc_t::type is set to NRFX_TWIM_XFER_TX and the NRFX_TWIM_FLAG_TX_NO_STOP and NRFX_TWIM_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: Peripherals using EasyDMA (including TWIM) 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 NRFX_ERROR_INVALID_ADDR.

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

NRFX_SUCCESS	If the procedure was successful.
NRFX_ERROR_BUSY	If the driver is not ready for a new transfer.
NRFX_ERROR_NOT_SUPPORTED	If the provided parameters are not supported.
NRFX_ERROR_INTERNAL	If an error was detected by hardware.
NRFX_ERROR_INVALID_ADDR	If the provided buffers are not placed in the Data RAM region.
NRFX_ERROR_DRV_TWI_ERR_ANACK	If NACK received after sending the address.
NRFX_ERROR_DRV_TWI_ERR_DNACK	If NACK received after sending a data byte.

TWIM driver

nRF5 SDK v15.0.0

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation