TWIS driver¶
-
group
nrfx_twis
Two Wire Interface Slave with EasyDMA (TWIS) peripheral driver.
Defines
-
NRFX_TWIS_INSTANCE
(id)¶ Macro for creating a TWIS driver instance.
-
NRFX_TWIS_DEFAULT_CONFIG
(_pin_scl, _pin_sda, _addr)¶ 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
_pin_scl – [in] SCL pin.
_pin_sda – [in] SDA pin.
_addr – [in] Slave address on TWI bus.
Typedefs
-
typedef void (*
nrfx_twis_event_handler_t
)(nrfx_twis_evt_t const *p_event)¶ TWI slave event callback function type.
- Parameters
p_event – [in] Event information structure.
Enums
-
enum
nrfx_twis_evt_type_t
¶ Event callback function event definitions.
Values:
-
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.
-
enumerator
NRFX_TWIS_EVT_READ_DONE
¶ Read request finished - free any data.
-
enumerator
NRFX_TWIS_EVT_READ_ERROR
¶ Read request finished with error.
-
enumerator
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.
-
enumerator
NRFX_TWIS_EVT_WRITE_DONE
¶ Write request finished - process data.
-
enumerator
NRFX_TWIS_EVT_WRITE_ERROR
¶ Write request finished with error.
-
enumerator
NRFX_TWIS_EVT_GENERAL_ERROR
¶ Error that happens not inside WRITE or READ transaction.
-
enumerator
-
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).
Values:
-
enumerator
NRFX_TWIS_ERROR_OVERFLOW
¶ RX buffer overflow detected, and prevented.
-
enumerator
NRFX_TWIS_ERROR_DATA_NACK
¶ NACK sent after receiving a data byte.
-
enumerator
NRFX_TWIS_ERROR_OVERREAD
¶ TX buffer over-read detected, and prevented.
-
enumerator
NRFX_TWIS_ERROR_UNEXPECTED_EVENT
¶ Unexpected event detected by state machine.
-
enumerator
Functions
-
nrfx_err_t
nrfx_twis_init
(nrfx_twis_t const *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.
- 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
p_instance – [in] Pointer to the driver instance structure.
p_config – [in] Pointer to the structure with the initial configuration.
event_handler – [in] Event handler provided by the user.
- Returns NRFX_SUCCESS
Initialization is successful.
- Returns NRFX_ERROR_INVALID_STATE
The driver is already initialized.
- Returns NRFX_ERROR_BUSY
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.
-
void
nrfx_twis_uninit
(nrfx_twis_t const *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.
Note
If TWIS driver was in uninitialized state before calling this function, the selected pins would not be reset to default configuration.
- Parameters
p_instance – [in] Pointer to the driver instance structure.
-
void
nrfx_twis_enable
(nrfx_twis_t const *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.
-
void
nrfx_twis_disable
(nrfx_twis_t const *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.
-
uint32_t
nrfx_twis_error_get_and_clear
(nrfx_twis_t const *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
p_instance – [in] Pointer to the driver instance structure.
- Returns
Error flags defined in nrfx_twis_error_t.
-
nrfx_err_t
nrfx_twis_tx_prepare
(nrfx_twis_t const *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.
- Attention
Transmission buffer must be placed in RAM.
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 NRFX_ERROR_INVALID_ADDR.
- Parameters
p_instance – [in] Pointer to the driver instance structure.
p_buf – [in] Transmission buffer.
size – [in] Maximum number of bytes that master may read from buffer given.
- Returns NRFX_SUCCESS
The preparation finished properly.
- Returns NRFX_ERROR_INVALID_ADDR
The given p_buf is not placed inside the RAM.
- Returns NRFX_ERROR_INVALID_LENGTH
There is a wrong value in the size parameter.
- Returns NRFX_ERROR_INVALID_STATE
The module is not initialized or not enabled.
-
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
p_instance – [in] Pointer to the driver instance structure.
- Returns
Number of bytes sent.
-
nrfx_err_t
nrfx_twis_rx_prepare
(nrfx_twis_t const *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 NRFX_ERROR_INVALID_ADDR.
- Parameters
p_instance – [in] Pointer to the driver instance structure.
p_buf – [in] Buffer that is to be filled with received data.
size – [in] Size of the buffer (maximum amount of data to receive).
- Returns NRFX_SUCCESS
The preparation finished properly.
- Returns NRFX_ERROR_INVALID_ADDR
The given p_buf is not placed inside the RAM.
- Returns NRFX_ERROR_INVALID_LENGTH
There is a wrong value in the size parameter.
- Returns NRFX_ERROR_INVALID_STATE
The module is not initialized or not enabled.
-
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
p_instance – [in] Pointer to the driver instance structure.
- Returns
Number of bytes received.
-
bool
nrfx_twis_is_busy
(nrfx_twis_t const *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
p_instance – [in] Pointer to the driver instance structure.
- Returns true
The driver is in state other than ERROR or IDLE.
- Returns false
There is no transmission pending.
-
bool
nrfx_twis_is_waiting_tx_buff
(nrfx_twis_t const *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
p_instance – [in] Pointer to the driver instance structure.
- Returns true
The driver is waiting for nrfx_twis_tx_prepare.
- Returns false
The driver is not in the state where it is waiting for preparing a TX buffer.
-
bool
nrfx_twis_is_waiting_rx_buff
(nrfx_twis_t const *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
p_instance – [in] Pointer to the driver instance structure.
- Returns true
The driver is waiting for nrfx_twis_rx_prepare.
- Returns false
The driver is not in the state where it is waiting for preparing an RX buffer.
-
bool
nrfx_twis_is_pending_tx
(nrfx_twis_t const *p_instance)¶ Function for checking if the driver is sending data.
If this function returns true, there is an ongoing output transmission.
- Parameters
p_instance – [in] Pointer to the driver instance structure.
- Returns true
There is an ongoing output transmission.
- Returns false
The driver is in other state.
-
bool
nrfx_twis_is_pending_rx
(nrfx_twis_t const *p_instance)¶ Function for checking if the driver is receiving data.
If this function returns true, there is an ongoing input transmission.
- Parameters
p_instance – [in] Pointer to the driver instance structure.
- Returns true
There is an ongoing input transmission.
- Returns false
The driver is in other state.
-
struct
nrfx_twis_t
¶ - #include <nrfx_twis.h>
TWIS driver instance data structure.
-
struct
nrfx_twis_evt_t
¶ - #include <nrfx_twis.h>
TWIS driver event structure.
Public Members
-
nrfx_twis_evt_type_t
type
¶ Event type.
-
bool
buf_req
¶ Flag for NRFX_TWIS_EVT_READ_REQ and NRFX_TWIS_EVT_WRITE_REQ.
Information if transmission buffer requires to be prepared.
-
uint32_t
tx_amount
¶ Data for NRFX_TWIS_EVT_READ_DONE.
-
uint32_t
rx_amount
¶ Data for NRFX_TWIS_EVT_WRITE_DONE.
-
uint32_t
error
¶ Data for NRFX_TWIS_EVT_GENERAL_ERROR.
-
union nrfx_twis_evt_t.[anonymous]
data
¶ Union to store event data.
-
nrfx_twis_evt_type_t
-
struct
nrfx_twis_config_t
¶ - #include <nrfx_twis.h>
Structure for TWIS configuration.
Public Members
-
uint32_t
addr
[2]¶ Set addresses that this slave should respond. Set 0 to disable.
-
uint32_t
scl
¶ SCL pin number.
-
uint32_t
sda
¶ SDA pin number.
-
nrf_gpio_pin_pull_t
scl_pull
¶ SCL pin pull.
-
nrf_gpio_pin_pull_t
sda_pull
¶ SDA pin pull.
-
uint8_t
interrupt_priority
¶ The priority of interrupt for the module to be set.
-
uint32_t
-