Quickstart guide for Common service TWIHS

This is the quickstart guide for the Common service TWIHS, with step-by-step instructions on how to configure and use the driver in a selection of use cases.

The use cases contain several code fragments. The code fragments in the steps for setup can be copied into a custom initialization function, while the steps for usage can be copied into, e.g., the main application function.

Basic use case

In the most basic use case, the TWIHS module is configured for

• Master operation
• addressing one slave device of the bus at address 0x50
• TWIHS clock of 400kHz
• polled read/write handling

Setup steps

Example code

Add to your application C-file, for example in SAM series chip:

void twihs_init(void)
{
  twihs_master_options_t opt = {
      .speed = 400000,
      .chip  = 0x50
  };

  twihs_master_setup(&TWIM0, &opt);
}

Workflow

1. Ensure that board_init() has configured selected I/Os for TWIHS function.
2. Ensure that conf_twim.h is present for the driver.

   • Note

     This file is only for the driver and should not be included by the user.

3. Define and initialize config structs for TWIHS module in your TWIHS initialization function, for example in SAM series chip:

   • twihs_master_options_t opt = {
       .speed = 400000,
       .chip  = 0x50
     }; 

   • field speed sets the baudrate of the TWIHS bus
   • field chip sets the address of the slave device you want to communicate with
4. Call twihs_master_setup and optionally check its return code

   • Note

     The config structs can be reused for other TWIHS modules after this step. Simply reconfigure and write to others modules.

Usage steps

Example code : Writing to a slave device

Use in application C-file, for example in SAM series chip:

const uint8_t test_pattern[] = {0x55,0xA5,0x5A,0x77,0x99};

twihs_package_t packet_write = {
  .addr         = EEPROM_MEM_ADDR,      // TWIHS slave memory address data
  .addr_length  = sizeof (uint16_t),    // TWIHS slave memory address data size
  .chip         = EEPROM_BUS_ADDR,      // TWIHS slave bus address
  .buffer       = (void *)test_pattern, // transfer data source buffer
  .length       = sizeof(test_pattern)  // transfer data size (bytes)
};

while (twihs_master_write(&TWIM0, &packet_write) != TWI_SUCCESS);

Workflow

1. Prepare the data you want to send to the slave device:

   • const uint8_t test_pattern[] = {0x55,0xA5,0x5A,0x77,0x99}; 

2. Prepare a twihs_package_t structure

   twihs_package_t packet_write; 

   Fill all the fields of the structure :
   • addr is the address in the slave device
   • addr_length is the size of the address in the slave (support for large TWI memory devices)
   • chip sets the 7 bit address of the slave device you want to communicate with
   • buffer is a pointer on the data to write to slave
   • length is the number of data to write
3. Finally, call twihs_master_write

   twihs_master_write(&TWIM0, &packet_write); 

   and optionally check its return value for TWI_SUCCESS.

Example code : Reading from a slave device

Use in application C-file, for example in SAM series chip:

uint8_t data_received[10];

twihs_package_t packet_read = {
  .addr         = EEPROM_MEM_ADDR,      // TWIHS slave memory address data
  .addr_length  = sizeof (uint16_t),    // TWIHS slave memory address data size
  .chip         = EEPROM_BUS_ADDR,      // TWIHS slave bus address
  .buffer       = data_received,        // transfer data destination buffer
  .length       = 10                    // transfer data size (bytes)
};
// Perform a multi-byte read access then check the result.
if(twihs_master_read(&TWIM0, &packet_read) == TWI_SUCCESS){
  //Check read content
  if(data_received[0]==0x55)
    do_something();
}

Workflow

1. Prepare a data buffer that will receive the data from the slave device:

   uint8_t data_received[10]; 

2. Prepare a twihs_package_t structure

   twihs_package_t packet_read; 

   Fill all the fields of the structure :
   • addr is the address in the slave device
   • addr_length is the size of the address in the slave (support for large TWI memory devices)
   • chip sets the 7 bit address of the slave device you want to communicate with
   • buffer is a pointer on the data buffer that will receive the data from the slave device
   • length is the number of data to read
3. Finally, call twihs_master_read

   twihs_master_read(&TWIM0, &packet_read); 

   and optionally check its return value for TWI_SUCCESS. the data read from the device are now in data_received.