| 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 | Enumerations | Functions
TWIS driver
Two Wire slave interface (TWIS)

TWI slave APIs. More...

## Modules
| TWIS peripheral driver configuration

## Data Structures
struct | nrf_drv_twis_t
| TWIS driver instance structure. More...
struct | nrf_drv_twis_evt_t
| TWIS driver event structure. More...
struct | nrf_drv_twis_config_t
| Structure for TWIS configuration. More...

## Macros
#define | NRF_DRV_TWIS_INSTANCE_x(id)
#define | NRF_DRV_TWIS_INSTANCE(id) NRF_DRV_TWIS_INSTANCE_x(id)
| Macro for creating TWIS driver instance. More...
#define | TWIS0_INSTANCE_INDEX 0
#define | TWIS1_INSTANCE_INDEX TWIS0_INSTANCE_INDEX+TWIS0_ENABLED
#define | NRF_DRV_TWIS_DEFAULT_CONFIG
| Generate default configuration for TWIS driver instance. More...

## Typedefs
typedef void(* | nrf_drv_twis_event_handler_t )(nrf_drv_twis_evt_t const *const p_event)
| TWI slave event callback function type. More...

## Enumerations
enum | nrf_drv_twis_evt_type_t { TWIS_EVT_READ_REQ, TWIS_EVT_READ_DONE, TWIS_EVT_READ_ERROR, TWIS_EVT_WRITE_REQ, TWIS_EVT_WRITE_DONE, TWIS_EVT_WRITE_ERROR, TWIS_EVT_GENERAL_ERROR }
| Event callback function event definitions. More...
enum | nrf_drv_twis_error_t { NRF_DRV_TWIS_ERROR_OVERFLOW = NRF_TWIS_ERROR_OVERFLOW, NRF_DRV_TWIS_ERROR_DATA_NACK = NRF_TWIS_ERROR_DATA_NACK, NRF_DRV_TWIS_ERROR_OVERREAD = NRF_TWIS_ERROR_OVERREAD, NRF_DRV_TWIS_ERROR_UNEXPECTED_EVENT = 1 << 8 }
| Possible error sources. More...

## Functions
ret_code_t | nrf_drv_twis_init (nrf_drv_twis_t const *const p_instance, nrf_drv_twis_config_t const *p_config, nrf_drv_twis_event_handler_t const event_handler)
| Function for initializing the TWIS driver instance. More...
void | nrf_drv_twis_uninit (nrf_drv_twis_t const *const p_instance)
| Function for uninitializing the TWIS driver instance. More...
void | nrf_drv_twis_enable (nrf_drv_twis_t const *const p_instance)
| Enable TWIS instance. More...
void | nrf_drv_twis_disable (nrf_drv_twis_t const *const p_instance)
| Disable TWIS instance. More...
uint32_t | nrf_drv_twis_error_get_and_clear (nrf_drv_twis_t const *const p_instance)
| Get and clear last error flags. More...
ret_code_t | nrf_drv_twis_tx_prepare (nrf_drv_twis_t const *const p_instance, void const *const p_buf, size_t size)
| Prepare data for sending. More...
size_t | nrf_drv_twis_tx_amount (nrf_drv_twis_t const *const p_instance)
| Get number of transmitted bytes. More...
ret_code_t | nrf_drv_twis_rx_prepare (nrf_drv_twis_t const *const p_instance, void *const p_buf, size_t size)
| Prepare data for receiving. More...
size_t | nrf_drv_twis_rx_amount (nrf_drv_twis_t const *const p_instance)
| Get number of received bytes. More...
bool | nrf_drv_twis_is_busy (nrf_drv_twis_t const *const p_instance)
| Function checks if driver is busy right now. More...
bool | nrf_drv_twis_is_waiting_tx_buff (nrf_drv_twis_t const *const p_instance)
| Function checks if driver is waiting for tx buffer. More...
bool | nrf_drv_twis_is_waiting_rx_buff (nrf_drv_twis_t const *const p_instance)
| Function checks if driver is waiting for rx buffer. More...
bool | nrf_drv_twis_is_pending_tx (nrf_drv_twis_t const *const p_instance)
| Check if driver is sending data. More...
bool | nrf_drv_twis_is_pending_rx (nrf_drv_twis_t const *const p_instance)
| Check if driver is receiving data. More...

## Detailed Description

TWI slave APIs.

## Macro Definition Documentation

#define NRF_DRV_TWIS_DEFAULT_CONFIG

Value:
{ \
.addr = { TWIS_DEFAULT_CONFIG_ADDR0, TWIS_DEFAULT_CONFIG_ADDR1 }, \
.scl = 31, \
.scl_pull = (nrf_gpio_pin_pull_t)TWIS_DEFAULT_CONFIG_SCL_PULL, \
.sda = 31, \
.sda_pull = (nrf_gpio_pin_pull_t)TWIS_DEFAULT_CONFIG_SDA_PULL, \
.interrupt_priority = TWIS_DEFAULT_CONFIG_IRQ_PRIORITY \
}

Generate default configuration for TWIS driver instance.

#define NRF_DRV_TWIS_INSTANCE | ( |  | id | ) | NRF_DRV_TWIS_INSTANCE_x(id)

Macro for creating TWIS driver instance.

Parameters

  [in] | id | Instance index. Use 0 for TWIS0 and 1 for TWIS1

#define NRF_DRV_TWIS_INSTANCE_x | ( |  | id | ) |

Value:
{ \
TWIS##id##_INSTANCE_INDEX \
}

## Typedef Documentation

typedef void(* nrf_drv_twis_event_handler_t)(nrf_drv_twis_evt_t const *const p_event)

TWI slave event callback function type.

Parameters

  [in] | p_event | Event information structure.

## Enumeration Type Documentation

enum nrf_drv_twis_error_t

Possible error sources.

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

Note
  We could use directly nrf_twis_error_t. Error type enum is redefined here becouse of possible future extension (eg. supporting timeouts and synchronous mode).

Enumerator
NRF_DRV_TWIS_ERROR_OVERFLOW | RX buffer overflow detected, and prevented
NRF_DRV_TWIS_ERROR_DATA_NACK | NACK sent after receiving a data byte
NRF_DRV_TWIS_ERROR_OVERREAD | TX buffer over-read detected, and prevented
NRF_DRV_TWIS_ERROR_UNEXPECTED_EVENT | Unexpected event detected by state machine

enum nrf_drv_twis_evt_type_t

Event callback function event definitions.

Enumerator
TWIS_EVT_READ_REQ | Read request detected. If there is no buffer prepared, buf_req flag in the even will be set. Call then nrf_drv_twis_tx_prepare to give parameters for buffer.
TWIS_EVT_READ_DONE | Read request has finished - free any data.
TWIS_EVT_READ_ERROR | Read request finished with error.
TWIS_EVT_WRITE_REQ | Write request detected. If there is no buffer prepared, buf_req flag in the even will be set. Call then nrf_drv_twis_rx_prepare to give parameters for buffer.
TWIS_EVT_WRITE_DONE | Write request has finished - process data.
TWIS_EVT_WRITE_ERROR | Write request finished with error.
TWIS_EVT_GENERAL_ERROR | Error that happens not inside WRITE or READ transaction.

## Function Documentation

void nrf_drv_twis_disable | ( | nrf_drv_twis_t const *const | p_instance | ) |

Disable TWIS instance.

Disabling TWIS instance gives possibility to turn off the TWIS while holding configuration done by nrf_drv_twis_init

Parameters

  p_instance | Pointer to the driver instance structure.

void nrf_drv_twis_enable | ( | nrf_drv_twis_t const *const | p_instance | ) |

Enable TWIS instance.

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

Parameters

  p_instance | Pointer to the driver instance structure.

uint32_t nrf_drv_twis_error_get_and_clear | ( | nrf_drv_twis_t const *const | p_instance | ) |

Get and clear last error flags.

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

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Returns
  Error flags defined in nrf_drv_twis_error_t

Attention
  This function clears error state and flags.

ret_code_t nrf_drv_twis_init | ( | nrf_drv_twis_t const *const | p_instance,
|  | nrf_drv_twis_config_t const * | p_config,
|  | nrf_drv_twis_event_handler_t const | event_handler
| ) |  |

Function for initializing the TWIS driver instance.

Function initializes and enables TWIS driver.

Attention
  After driver initialization enable it by nrf_drv_twis_enable

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

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

Parameters

  [in] | p_config | Initial configuration.
  [in] | event_handler | Event handler provided by the user.

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_INVALID_STATE | If the driver is already initialized.
  NRF_ERROR_BUSY | If some other peripheral with the same instance ID is already in use. This is possible only if PERIPHERAL_RESOURCE_SHARING_ENABLED is set to a value other than zero.

bool nrf_drv_twis_is_busy | ( | nrf_drv_twis_t const *const | p_instance | ) |

Function checks if driver is busy right now.

Actual driver substate is tested. If 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 | Driver is in state other than ERROR or IDLE
  false | There is no transmission pending.

bool nrf_drv_twis_is_pending_rx | ( | nrf_drv_twis_t const *const | p_instance | ) |

Check if driver is receiving data.

If this function returns true, it means that there is ongoing input transmission.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Return values

  true | There is ongoing input transmission.
  false | Driver is in other state.

bool nrf_drv_twis_is_pending_tx | ( | nrf_drv_twis_t const *const | p_instance | ) |

Check if driver is sending data.

If this function returns true, it means that there is ongoing output transmission.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Return values

  true | There is ongoing output transmission.
  false | Driver is in other state.

bool nrf_drv_twis_is_waiting_rx_buff | ( | nrf_drv_twis_t const *const | p_instance | ) |

Function checks if driver is waiting for rx buffer.

If this function returns true, it means that driver is staled expecting of the nrf_drv_twis_rx_prepare function call.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Return values

  true | Driver waits for nrf_drv_twis_rx_prepare
  false | Driver is not in the state where it waits for preparing rx buffer.

bool nrf_drv_twis_is_waiting_tx_buff | ( | nrf_drv_twis_t const *const | p_instance | ) |

Function checks if driver is waiting for tx buffer.

If this function returns true, it means that driver is stalled expecting of the nrf_drv_twis_tx_prepare function call.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Return values

  true | Driver waits for nrf_drv_twis_tx_prepare
  false | Driver is not in the state where it waits for preparing tx buffer.

size_t nrf_drv_twis_rx_amount | ( | nrf_drv_twis_t const *const | p_instance | ) |

Get number of received bytes.

Function returns number of bytes received. This function may be called after TWIS_EVT_WRITE_DONE or TWIS_EVT_WRITE_ERROR events.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Returns
  Number of bytes received.

ret_code_t nrf_drv_twis_rx_prepare | ( | nrf_drv_twis_t const *const | p_instance,
|  | void *const | p_buf,
|  | size_t | size
| ) |  |

Prepare data for receiving.

This function should be used in response for TWIS_EVT_WRITE_REQ event.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | p_buf | Buffer that would be filled with received data

Attention
  Receiving buffer has to be placed in RAM.

Parameters

  size | Size of the buffer (maximum amount of data to receive)

Return values

  NRF_SUCCESS | Preparation finished properly
  NRF_ERROR_INVALID_ADDR | Given p_buf is not placed inside the RAM
  NRF_ERROR_INVALID_LENGTH | Wrong value in size parameter
  NRF_ERROR_INVALID_STATE | Module not initialized or not enabled

size_t nrf_drv_twis_tx_amount | ( | nrf_drv_twis_t const *const | p_instance | ) |

Get number of transmitted bytes.

Function returns number of bytes sent. This function may be called after TWIS_EVT_READ_DONE or TWIS_EVT_READ_ERROR events.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Returns
  Number of bytes sent.

ret_code_t nrf_drv_twis_tx_prepare | ( | nrf_drv_twis_t const *const | p_instance,
|  | void const *const | p_buf,
|  | size_t | size
| ) |  |

Prepare data for sending.

This function should be used in response for TWIS_EVT_READ_REQ event.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | p_buf | Transmission buffer

Attention
  Transmission buffer has to be placed in RAM.

Parameters

  size | Maximum number of bytes that master may read from buffer given.

Return values

  NRF_SUCCESS | Preparation finished properly
  NRF_ERROR_INVALID_ADDR | Given p_buf is not placed inside the RAM
  NRF_ERROR_INVALID_LENGTH | Wrong value in size parameter
  NRF_ERROR_INVALID_STATE | Module not initialized or not enabled

void nrf_drv_twis_uninit | ( | nrf_drv_twis_t const *const | p_instance | ) |

Function for uninitializing the TWIS driver instance.

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

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Note
  It is safe to call nrf_drv_twis_uninit even before initialization. Actually nrf_drv_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, selected pins would not be reset to default configuration.