Quick Start Guide for the TWIM driver

This is the quick start guide for the TWIM - Two-Wire Master Interface, with step-by-step instructions on how to configure and use the driver for a specific use case.The code examples can be copied into e.g the main application loop or any other function that will need to control the TWIM module.

Use cases

• TWIM basic usage

TWIM basic usage

This use case will demonstrate how to initialize the TWIM module.

Setup steps

Prerequisites

This module requires the following service

• Clock Management (Sysclock)

twim_basic_setup_workflow

1. Setup TWIM options, including TWIM clock frequency, the desired TWI bus speed, the target chip slave address (optional) and being in SMBus mode or not.

• struct twim_config twim_conf;
  twim_conf.twim_clk = sysclk_get_cpu_hz();
  twim_conf.speed = DESIRED_TWI_BUS_SPEED;
  twim_conf.smbus = false;
  twim_conf.hsmode_speed = 0;
  twim_conf.data_setup_cycles = 0;
  twim_conf.hsmode_data_setup_cycles = 0;
  twim_set_config(TWIM0, &twim_conf);

  • Note

    The TWIM driver supports I2C standard speed, fast speed, fast speed plus and high speed.

1. The default callback function must be set before calling read/write functions.

   • twim_set_callback(TWIM0, 0, twim_default_callback, 1);

   • Note

     The read/write functions will enable and disable the corresponding interrupt sources.

Usage steps

twim_basic_usage_code

We can send data to the target slave device. Firstly, the data package should be prepared. In one data package, several items should be set, the target slave address, the internal address (if needed), the length of the internal address (if needed), the data buffer to be written and the length of the data buffer.

twi_package_t packet_tx;
packet_tx.chip = TARGET_SLAVE_ADDRESS;
packet_tx.addr[0] = (INTERNAL_ADDRESS >> 16) & 0xFF;
packet_tx.addr[1] = (INTERNAL_ADDRESS >> 8) & 0xFF;
packet_tx.addr_length = INTERNAL_ADDRESS_LENGTH;
packet_tx.buffer = (void *) data_buf_tx;
packet_tx.length = DATA_BUF_TX_LENGTH;

• Note

  The TWIM driver supports 1-3 bytes of internal address.

  After the data package is ready, we can call twi_master_write() to send the package to the slave address. The callback set before will be handled in ISR.

  twi_master_write(TWIM1, &packet_tx);

• Note

  If the function returns STATUS_OK, the package has been sent to the target slave device successfully. Otherwise, the transmission fails.

  We can receive data from the target slave device. Firstly, the data package should be prepared. In one data package, several items should be set, the target slave address, the internal address (if needed), the length of the internal address (if needed), the data buffer used to store received data and the length of the data to be received.

  twi_package_t packet_rx;
  packet_rx.chip = TARGET_SLAVE_ADDRESS;
  packet_rx.addr[0] = (INTERNAL_ADDRESS >> 16) & 0xFF;
  packet_rx.addr[1] = (INTERNAL_ADDRESS >> 8) & 0xFF;
  packet_rx.addr_length = INTERNAL_ADDRESS_LENGTH;
  packet_rx.buffer = (void *) data_buf_rx;
  packet_rx.length = DATA_BUF_RX_LENGTH;

• Note

  The TWIM driver supports 1-3 bytes of internal address.

  After the data package is ready, we can call twi_master_read() to receive the data package from the slave device. The callback set before will be handled in ISR.

  twi_master_read(TWIM1, &packet_rx);

• Note

  If the function returns STATUS_OK, the package has been received from the target slave device and the data has been stored in the data buffer successfully. Otherwise, the transmission failed.