XMOS I2C Library

https://github.com/xmos/lib_i2c
Admin
A software library providing I2C communication capabilities for XMOS devices.
Tokens:15,573
Snippets:65
Trust Score:9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Build and Run Commands for AN00156 I2C Master Example

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00156_i2c_master_example/doc/rst/AN00156.rst

Provides the necessary bash commands to configure, build, and run the AN00156 I2C master example on XMOS hardware using the XTC tools and xmake.

```bash
cd examples
cd AN00156_i2c_master_example
cmake -G "Unix Makefiles" -B build
xmake -C build
```

```bash
xrun --xscope bin/xs2/AN00156_i2c_master_example.xe
```

--------------------------------

### XMOS lib_i2c Example Configuration

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/CMakeLists.txt

Configures the build environment for XMOS lib_i2c examples by including common modules and adding subdirectories for various master and slave configurations.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(lib_i2c_examples)

add_subdirectory(AN00156_i2c_master_example)
add_subdirectory(AN00157_i2c_slave_example)
add_subdirectory(app_simple_asynchronous_master)
add_subdirectory(app_simple_repeated_start_master)
add_subdirectory(app_simple_single_port_master)
add_subdirectory(app_simple_slave)
add_subdirectory(app_simple_synchronous_master)
```

--------------------------------

### XMOS lib_i2c CMake Project Configuration

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/CMakeLists.txt

Configures the CMake build system for the AN00157 i2c slave example project on XMOS hardware. It sets the minimum CMake version, includes common XMOS build utilities, defines project name and target hardware, and specifies compiler flags.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(AN00157_i2c_slave_example)

set(APP_HW_TARGET XK-EVK-XU316)

set(APP_COMPILER_FLAGS -O2 -g -DDEBUG_PRINT_ENABLE=1 -report)

include(${CMAKE_CURRENT_LIST_DIR}/../deps.cmake)

set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../../)

XMOS_REGISTER_APP()
```

--------------------------------

### Main Application Task Setup

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00156_i2c_master_example/doc/rst/AN00156.rst

Sets up the main application tasks, including declaring the I2C master interface. This demonstrates how to initialize and manage concurrent tasks in xC.

```c
int main(void)
{
    /* Declare the I2C master interface */
    i2c_master_ifc i2c[1];

    /* Start tasks in parallel */
    par
    {
        /* Initialize and run the I2C master task */
        i2c_master_init(i2c, &p_scl, &p_sda, I2C_MASTER_SPEED_400KB);

        /* Run the accelerometer task */
        accelerometer(i2c[0]);
    }

    return 0;
}
```

--------------------------------

### I²C Slave Task Diagram and Instantiation

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Illustrates the architecture of an I²C slave task and provides an example of instantiating an I²C slave and connecting to it within an XMOS application.

```xc
port p_scl;
// ... other declarations ...
void my_application
```

--------------------------------

### Instantiate Asynchronous I2C Master

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Shows the setup for an asynchronous I2C master component, similar to the synchronous setup. This allows operations to be offloaded to another task for non-blocking behavior.

```xcore
port p_scl

// Setting up an asynchronous I2C master component is done in the same manner as the synchronous component.
// The asynchronous API offloads operations to another task. Calls are provided to initiate reads and writes.
// Notifications are provided when the operation completes. This API requires more management in the application but can provide much more efficient operation.
// It is particularly suitable for applications where the I2C bus is being used for continuous data transfer.
```

--------------------------------

### XC Code Snippet: I2C Master and Application Start

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00156_i2c_master_example/doc/rst/AN00156.rst

This snippet demonstrates the initialization of an I2C master and the application using the xC 'par' construct. It highlights how distributable components are managed across logical cores.

```xc
par
  // Code to start the I2C master and application
  // ... (actual code omitted as per literalinclude directive)
```

--------------------------------

### Repeated Start Bit Transaction Example

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Demonstrates the library's support for repeated start bits in I2C transactions. The example shows how to perform a read operation without sending a stop bit, enabling a subsequent transaction to begin with a repeated start bit.

```xcore
void my_application(client i2c_master_if i2c, uint8_t target_device_addr) {
  // The library supports repeated start bits.
  // The read and write functions allow the application to specify whether to send a stop bit at the end of the transaction.
  // If this is set to 0 then no stop bit is sent and the next transaction will begin with a repeated start bit e.g.
  // Note that if no stop bit is sent then no other client using the bus can perform a transaction.
}
```

--------------------------------

### Start Application Tasks

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Initiates all application tasks concurrently using the xC 'par' construct. This includes the I2C slave, register file, slave application, I2C master, and master application.

```xcore
par
    {
        // I2C slave task
        i2c_slave_task(i_i2c, i_spi, i_regfile, i_clk);

        // Register file task
        regfile_task(i_regfile, i_i2c);

        // Slave application task
        slave_app_task(i_i2c, i_regfile);

        // I2C master task
        i2c_master_task(i2c, i_spi, i_clk);

        // Master application task
        master_app_task(i2c, i_regfile);
    }
```

--------------------------------

### XMOS lib_i2c CMake Configuration

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00156_i2c_master_example/CMakeLists.txt

Configures the build environment for the AN00156 i2c master example project using CMake. It sets the target hardware, compiler flags, and includes necessary dependencies and modules for the project.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(AN00156_i2c_master_example)

set(APP_HW_TARGET XCORE-200-EXPLORER)

set(APP_COMPILER_FLAGS -O2 -g -DDEBUG_PRINT_ENABLE=1 -report)

include(${CMAKE_CURRENT_LIST_DIR}/../deps.cmake)

set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../../)

XMOS_REGISTER_APP()
```

--------------------------------

### Instantiate Synchronous I2C Master

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Example code demonstrating the instantiation of an I2C master component for synchronous operation in an XMOS application. It shows how to define and connect the master interface using specific port definitions.

```xcore
port p_scl

// Instantiate an I2C master component
// The master component is instantiated as a parallel task
// The application can connect via an interface connection using the i2c_master_if interface type
// The connection is an array of interfaces, so several tasks can connect to the same master.
// For example, the following code instantiates an I2C master and connects to it
// The master component does not use any logical cores of its own. It is a distributed task which means it will perform its function on the logical core of the application task connected to it (provided the application task is on the same tile as the I2C ports).
```

--------------------------------

### I²C Slave Callback Implementation

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Example code showing how an I²C slave application responds to requests from the bus master by implementing a callback interface.

```xc
void my_application(server i2c_slave_callback_if i2c) {
  // end
```

--------------------------------

### Slave Application Logic

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

An example implementation of a slave application that uses the register file. It inverts data written to the register file and logs these operations.

```xc
void slave_application
```

--------------------------------

### lib_i2c CMake Build Setup

Source: https://github.com/xmos/lib_i2c/blob/develop/tests/i2c_test_repeated_start/CMakeLists.txt

This CMake script configures the build environment for the lib_i2c project. It sets up the minimum required CMake version, includes common XMOS scripts, defines application hardware targets (XK-EVK-XU316, XCORE-200-EXPLORER), and specifies compiler flags for different architectures (xs2, xs3). It registers the application using XMOS_REGISTER_APP.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)

set(APP_PCA_ENABLE ON)
set(XMOS_SANDBOX_DIR    ${CMAKE_CURRENT_LIST_DIR}/../../..)
include(${CMAKE_CURRENT_LIST_DIR}/../../examples/deps.cmake)

set(ARCH xs2 xs3)

foreach(arch ${ARCH})
    if(arch STREQUAL "xs3")
        set(target "XK-EVK-XU316")
    elseif(arch STREQUAL "xs2")
        set(target "XCORE-200-EXPLORER")
    endif()

    project(i2c_test_repeated_start)
    set(APP_HW_TARGET   ${target})

    set(APP_COMPILER_FLAGS_${arch}
                    -O2
                    -g
                    -DDEBUG_PRINT_ENABLE=1
                    -report)

    XMOS_REGISTER_APP()
    unset(APP_COMPILER_FLAGS_${arch})
endforeach()
```

--------------------------------

### XMOS lib_i2c Project Setup with CMake

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/app_simple_single_port_master/CMakeLists.txt

This CMakeLists.txt file defines the build configuration for an XMOS application. It sets the minimum CMake version, includes common XMOS modules, defines the project name, target hardware, and compiler flags, and registers the application.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(app_simple_single_port_master)

set(APP_HW_TARGET XK-EVK-XU316)

set(APP_COMPILER_FLAGS -O2 -g -DDEBUG_PRINT_ENABLE=1 -report)

include(${CMAKE_CURRENT_LIST_DIR}/../deps.cmake)

set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../../)

XMOS_REGISTER_APP()
```

--------------------------------

### CMake Project Setup for lib_i2c

Source: https://github.com/xmos/lib_i2c/blob/develop/tests/i2c_master_reg_test/CMakeLists.txt

Configures the CMake build system for the lib_i2c project, including setting minimum version, including common scripts, defining hardware targets, and specifying compiler flags for different XMOS architectures.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)

set(APP_PCA_ENABLE ON)
set(XMOS_SANDBOX_DIR    ${CMAKE_CURRENT_LIST_DIR}/../../..)
include(${CMAKE_CURRENT_LIST_DIR}/../../examples/deps.cmake)

set(ARCH xs2 xs3)

foreach(arch ${ARCH})
    if(arch STREQUAL "xs3")
        set(target "XK-EVK-XU316")
    elseif(arch STREQUAL "xs2")
        set(target "XCORE-200-EXPLORER")
    endif()

    project(i2c_master_reg_test)
    set(APP_HW_TARGET   ${target})


    set(APP_COMPILER_FLAGS_${arch}
                    -O2
                    -g
                    -DDEBUG_PRINT_ENABLE=1
                    -report)

    XMOS_REGISTER_APP()
    unset(APP_COMPILER_FLAGS_${arch})
endforeach()
```

--------------------------------

### Python Development Dependencies

Source: https://github.com/xmos/lib_i2c/blob/develop/tests/requirements.txt

Lists the Python packages required for development and testing of the lib_i2c project. These are typically installed using pip. The specific versions ensure compatibility and a stable development environment.

```python
pytest==8.3.3
```

```python
pytest-xdist==3.6.1
```

```python
-e ./../../test_support
```

--------------------------------

### Asynchronous I2C Master Client Operations

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Example code illustrating the use of the asynchronous API for I2C master operations. It shows how to offload bus operations to the I2C master, allowing other tasks to perform calculations concurrently.

```xcore
void my_application(client i2c_master_async_if i2c, uint8_t target_device_addr) {
  // Here the calculation of my_application_fill_buffer will overlap with the sending of data by the other task.
  // The application can then use the asynchronous API to offload bus operations to the I2C master.
  // For example, the following code repeatedly calculates BUFFER_BYTES bytes to send over the bus.
}

void my_application_handle_bus_error
```

--------------------------------

### Launch Demo Application with xsim

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Launches the built demo application using the xsim simulator. Includes options for tracing and port configuration.

```bash
xsim --trace-to trace.txt --plugin LoopbackPort.so
  "-pullup -port tile[0] XS1_PORT_1E 1 0 -port tile[0] XS1_PORT_1G 1 0
   -pullup -port tile[0] XS1_PORT_1F 1 0 -port tile[0] XS1_PORT_1H 1 0"
   bin/AN00157_i2c_slave_example.xe
```

--------------------------------

### Build Application Binaries

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Builds the application binaries using the 'xmake' command after the build system has been configured with CMake.

```bash
xmake -C build
```

--------------------------------

### I2C Transaction Termination

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Handles the end of an I2C transaction by clearing the current register number state, ensuring the next transaction starts with a clean slate.

```xc
case i2c.stop_bit
  // select
```

--------------------------------

### Include System and Library Headers

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00156_i2c_master_example/doc/rst/AN00156.rst

Includes necessary headers for xCORE specific definitions and the I2C and logging libraries. These are essential for hardware interaction and debugging.

```c
#include <xs1.h>
#include "i2c.h"
#include "debug_print.h"
```

--------------------------------

### Include System and Library Headers in xC

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Shows the necessary system and library header files to include for an xC application using the I2C slave library. It includes core system headers and specific library headers for I2C and logging.

```c
include <xs1.h>
...
include <syscall.h>
```

```c
include "i2c.h"
...
include "debug_print.h"
```

--------------------------------

### Enable VCD Tracing for Waveforms

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Adds options to the xsim command to enable VCD (Value Change Dump) tracing for detailed waveform analysis. The output can be viewed with tools like GTKWave.

```bash
--vcd-tracing "-o trace.vcd -tile tile[0] -ports"
```

--------------------------------

### Configure Build with CMake

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Configures the build system using CMake for the project. This command generates build files for Unix Makefiles.

```bash
cd examples
cd AN00157_i2c_slave_example
cmake -G "Unix Makefiles" -B build
```

--------------------------------

### Configure lib_i2c Tests Build

Source: https://github.com/xmos/lib_i2c/blob/develop/tests/CMakeLists.txt

This CMakeLists.txt file sets up the build environment for the lib_i2c test suite. It specifies the minimum required CMake version, includes common XMOS build modules, defines the project name, and adds subdirectories for various I2C master and slave testing configurations.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(lib_i2c_tests)

add_subdirectory(i2c_master_async_test)
add_subdirectory(i2c_master_reg_test)
add_subdirectory(i2c_master_test)
add_subdirectory(i2c_slave_test)
add_subdirectory(i2c_sp_test)
add_subdirectory(i2c_test_locks)
add_subdirectory(i2c_test_repeated_start)
```

--------------------------------

### CMake Configuration for XMOS App

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/app_simple_asynchronous_master/CMakeLists.txt

This CMakeLists.txt file sets up the build environment for an XMOS application. It specifies the minimum CMake version, includes common XMOS modules, defines the project name, target hardware, compiler flags, and registers the application.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(app_simple_asynchronous_master)

set(APP_HW_TARGET XK-EVK-XU316)

set(APP_COMPILER_FLAGS -O2 -g -DDEBUG_PRINT_ENABLE=1 -report)

include(${CMAKE_CURRENT_LIST_DIR}/../deps.cmake)

set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../../)

XMOS_REGISTER_APP()
```

--------------------------------

### CMake Configuration for lib_i2c Project

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/app_simple_slave/CMakeLists.txt

This snippet shows the CMakeLists.txt file used to configure the lib_i2c project. It sets the minimum CMake version, includes common XMOS modules, defines project specifics like the hardware target and compiler flags, and registers the application.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(app_simple_slave)

set(APP_HW_TARGET XK-EVK-XU316)

set(APP_COMPILER_FLAGS -O2 -g -DDEBUG_PRINT_ENABLE=1 -report)

include(${CMAKE_CURRENT_LIST_DIR}/../deps.cmake)

set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../../)

XMOS_REGISTER_APP()
```

--------------------------------

### Configure and Enable Accelerometer

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00156_i2c_master_example/doc/rst/AN00156.rst

Initializes the accelerometer by writing configuration values to its registers. This function sets up the device for operation.

```c
void accelerometer(i2c_master_ifc i2c)
{
    unsigned char data[2];
    int ret;
    int accel_x, accel_y, accel_z;

    /* Configure the accelerometer */
    data[0] = 0x00; /* Control Register 1 */
    data[1] = 0x01; /* Active mode, 100Hz output data rate */
    ret = i2c.write_reg(FXOS8700CQ_I2C_ADDR, data[0], data + 1, 1);
    if (ret != 1)
        debug_printf("Error writing to accelerometer control register\n");

    /* ... rest of the accelerometer logic ... */
}
```

--------------------------------

### CMakeLists.txt Configuration

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00156_i2c_master_example/doc/rst/AN00156.rst

Configures the project's dependent modules and compiler flags. It specifies 'lib_i2c' and 'lib_logging' as dependencies and enables debug printing via a compiler flag.

```cmake
set(APP_DEPENDENT_MODULES "lib_i2c"
                            "lib_logging")

set(APP_COMPILER_FLAGS ... -DDEBUG_PRINT_ENABLE=1 ...)
```

--------------------------------

### I²C Slave API Functions

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Provides documentation for core I²C slave functions, including the creation of slave instances.

```APIDOC
i2c_slave
  Creates an I²C slave instance.
```

--------------------------------

### lib_i2c CMake Configuration

Source: https://github.com/xmos/lib_i2c/blob/develop/tests/i2c_test_locks/CMakeLists.txt

Configures the build for the lib_i2c project, including target hardware selection (XS2, XS3), compiler flags, and application registration. It sets up the project for different architectures and includes common XMOS build utilities.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)

set(APP_PCA_ENABLE ON)
set(XMOS_SANDBOX_DIR    ${CMAKE_CURRENT_LIST_DIR}/../../..)
include(${CMAKE_CURRENT_LIST_DIR}/../../examples/deps.cmake)

set(ARCH xs2 xs3)

foreach(arch ${ARCH})
    if(arch STREQUAL "xs3")
        set(target "XK-EVK-XU316")
    elseif(arch STREQUAL "xs2")
        set(target "XCORE-200-EXPLORER")
    endif()

    project(i2c_test_locks)
    set(APP_HW_TARGET   ${target})

    set(APP_COMPILER_FLAGS_${arch}
                    -O2
                    -g
                    -DDEBUG_PRINT_ENABLE=1
                    -report)

    XMOS_REGISTER_APP()
    unset(APP_COMPILER_FLAGS_${arch})
endforeach()
```

--------------------------------

### CMake Build Configuration

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/app_simple_repeated_start_master/CMakeLists.txt

This snippet outlines the CMake build system configuration for the XMOS lib_i2c project. It sets the minimum required CMake version, includes common XMOS modules, defines the project name, target hardware, compiler flags, and registers the application for building.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(app_simple_repeated_start_master)

set(APP_HW_TARGET XK-EVK-XU316)

set(APP_COMPILER_FLAGS -O2 -g -DDEBUG_PRINT_ENABLE=1 -report)

include(${CMAKE_CURRENT_LIST_DIR}/../deps.cmake)

set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../../)

XMOS_REGISTER_APP()
```

--------------------------------

### Configure CMake Dependencies for lib_i2c

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Specifies how to add the lib_i2c and lib_logging modules to the dependent modules list in the CMakeLists.txt file for an XMOS project. This is a prerequisite for using the I2C library.

```cmake
set(APP_DEPENDENT_MODULES "lib_i2c"
                            "lib_logging")
```

--------------------------------

### CMake Configuration for XMOS lib_i2c

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/app_simple_synchronous_master/CMakeLists.txt

Configures the build environment for the XMOS lib_i2c project using CMake. It sets the minimum CMake version, includes common XMOS modules, defines the target hardware, specifies compiler flags, includes dependencies, and registers the application.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)
project(app_simple_synchronous_master)


set(APP_HW_TARGET XK-EVK-XU316)

set(APP_COMPILER_FLAGS -O2 -g -DDEBUG_PRINT_ENABLE=1 -report)

include(${CMAKE_CURRENT_LIST_DIR}/../deps.cmake)

set(XMOS_SANDBOX_DIR ${CMAKE_CURRENT_LIST_DIR}/../../../)

XMOS_REGISTER_APP()
```

--------------------------------

### Master Application Logic

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Provides stimulus to test the I2C slave register file. It performs a single register write operation and verifies its successful completion.

```xc
void master_application
  // Read a single
```

--------------------------------

### CMake Configuration for I2C Master Test

Source: https://github.com/xmos/lib_i2c/blob/develop/tests/i2c_master_test/CMakeLists.txt

This script configures the build environment for the I2C master test application. It reads parameters from a JSON file, iterates through different hardware architectures and test conditions (direction, speed, stop bits), and sets appropriate compiler flags for each build configuration. It utilizes XMOS-specific CMake modules and commands to manage the build process.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)

# Get JSON lists
file(READ ${CMAKE_CURRENT_LIST_DIR}/test_params.json params_json)

# Get individual fields from params_json
string(JSON speed_list GET ${params_json} SPEEDS)
string(JSON stop_list GET ${params_json} STOPS)
string(JSON dir_list GET ${params_json} DIRECTION)

string(JSON speed_list_len LENGTH ${speed_list})
string(JSON stop_list_len LENGTH ${stop_list})
string(JSON dir_list_len LENGTH ${dir_list})

# Subtract one off each of the lengths because RANGE includes last element

math(EXPR speed_list_len "${speed_list_len} - 1")
math(EXPR stop_list_len "${stop_list_len} - 1")
math(EXPR dir_list_len "${dir_list_len} - 1")


set(APP_PCA_ENABLE ON)
set(XMOS_SANDBOX_DIR    ${CMAKE_CURRENT_LIST_DIR}/../../..)
include(${CMAKE_CURRENT_LIST_DIR}/../../examples/deps.cmake)

set(ARCH xs2 xs3)

set(stop_val 1)
set(no_stop_val 0)

foreach(arch ${ARCH})
    if(arch STREQUAL "xs3")
        set(target "XK-EVK-XU316")
    elseif(arch STREQUAL "xs2")
        set(target "XCORE-200-EXPLORER")
    endif()

    foreach(i RANGE 0 ${dir_list_len})
        string(JSON dir GET ${dir_list} ${i})

        foreach(j RANGE 0 ${speed_list_len})
            string(JSON speed GET ${speed_list} ${j})

            foreach(k RANGE 0 ${stop_list_len})
                string(JSON stop GET ${stop_list} ${k})
                set(config ${dir}_${speed}_${stop}_${arch})
                message(STATUS "building config ${config} => ${dir}_${speed}_${${stop}_val}_${arch}")

                if(dir STREQUAL "rx_tx")
                    set(rx_enable 1)
                    set(tx_enable 1)
                elseif(dir STREQUAL "tx_only")
                    set(rx_enable 0)
                    set(tx_enable 1)
                else()
                    set(rx_enable 1)
                    set(tx_enable 0)
                endif()

                project(i2c_master_test)
                set(APP_HW_TARGET  ${target})

                set(APP_COMPILER_FLAGS_${config}
                    -O2
                    -g
                    -DDEBUG_PRINT_ENABLE=1
                    -report
                    -DSPEED=${speed}
                    -DENABLE_TX=${tx_enable}
                    -DENABLE_RX=${rx_enable}
                    -DSTOP=${${stop}_val})

                XMOS_REGISTER_APP()
                unset(APP_COMPILER_FLAGS_${config})

            endforeach() # stop
        endforeach() # speed
    endforeach() # direction
endforeach() # arch

```

--------------------------------

### I²C Master API Functions

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Provides documentation for core I²C master functions, including creation of single-port and asynchronous master instances.

```APIDOC
i2c_master
  Creates an I²C master instance.

i2c_master_single_port
  Creates an I²C master instance for a single port.

i2c_master_async
  Creates an asynchronous I²C master instance.

i2c_master_async_comb
  Creates a combined asynchronous I²C master instance.
```

--------------------------------

### CMake Configuration for XMOS lib_i2c

Source: https://github.com/xmos/lib_i2c/blob/develop/tests/i2c_slave_test/CMakeLists.txt

This CMake script configures the build environment for the lib_i2c project. It sets up the minimum required CMake version, includes common XMOS modules, defines target architectures (XS2, XS3), and specifies compiler flags for debugging and optimization.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)


set(APP_PCA_ENABLE ON)
set(XMOS_SANDBOX_DIR    ${CMAKE_CURRENT_LIST_DIR}/../../..)
include(${CMAKE_CURRENT_LIST_DIR}/../../examples/deps.cmake)

set(ARCH xs2 xs3)

foreach(arch ${ARCH})
    if(arch STREQUAL "xs3")
        set(target "XK-EVK-XU316")
    elseif(arch STREQUAL "xs2")
        set(target "XCORE-200-EXPLORER")
    endif()

    project(i2c_slave_test)
    set(APP_HW_TARGET   ${target})

    set(APP_COMPILER_FLAGS_${arch}
                    -O2
                    -g
                    -DDEBUG_PRINT_ENABLE=1
                    -report)

    XMOS_REGISTER_APP()
    unset(APP_COMPILER_FLAGS_${arch})
endforeach()
```

--------------------------------

### XMOS lib_i2c Build Configuration

Source: https://github.com/xmos/lib_i2c/blob/develop/tests/i2c_sp_test/CMakeLists.txt

Configures the build process for the lib_i2c library on XMOS targets. It reads parameters from test_params.json, iterates through speed and stop bit combinations for different architectures (xs2, xs3), and sets compiler flags and hardware targets for each configuration.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)

# Get JSON lists
file(READ ${CMAKE_CURRENT_LIST_DIR}/test_params.json params_json)

# Get individual fields from params_json
string(JSON speed_list GET ${params_json} SPEEDS)
string(JSON stop_list GET ${params_json} STOPS)

string(JSON speed_list_len LENGTH ${speed_list})
string(JSON stop_list_len LENGTH ${stop_list})

# Subtract one off each of the lengths because RANGE includes last element

math(EXPR speed_list_len "${speed_list_len} - 1")
math(EXPR stop_list_len "${stop_list_len} - 1")

set(APP_PCA_ENABLE ON)
set(XMOS_SANDBOX_DIR    ${CMAKE_CURRENT_LIST_DIR}/../../..)
include(${CMAKE_CURRENT_LIST_DIR}/../../examples/deps.cmake)

set(ARCH xs2 xs3)

set(stop_val 1)
set(no_stop_val 0)

foreach(arch ${ARCH})
    if(arch STREQUAL "xs3")
        set(target "XK-EVK-XU316")
    elseif(arch STREQUAL "xs2")
        set(target "XCORE-200-EXPLORER")
    endif()
    foreach(j RANGE 0 ${speed_list_len})
        string(JSON speed GET ${speed_list} ${j})

        foreach(k RANGE 0 ${stop_list_len})
            string(JSON stop GET ${stop_list} ${k})
            set(config ${speed}_${stop}_${arch})
            message(STATUS "building config ${speed}_${stop}_${arch} => ${speed}_${${stop}_val}_${arch}")

            project(i2c_sp_test)
            set(APP_HW_TARGET   ${target})

            set(APP_COMPILER_FLAGS_${config}
                -O2
                -g
                -DDEBUG_PRINT_ENABLE=1
                -report
                -DSPEED=${speed}
                -DSTOP=${${stop}_val})

            XMOS_REGISTER_APP()
            unset(APP_COMPILER_FLAGS_${config})

        endforeach()
    endforeach()
endforeach()
```

--------------------------------

### I2C Register Write Function

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Demonstrates the usage of the I2C master interface to write data to a specific register on the slave device.

```xc
i2c.write_reg
```

--------------------------------

### I2C Slave Callback Implementations

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Implements the core I2C slave callback functions required for communication. This includes handling read/write request acknowledgments, data transmission, and transaction termination.

```xc
case i2c.ack_read_request
case i2c.master_sent_data
case i2c.master_requires_data
case i2c.stop_bit
```

--------------------------------

### Define Register File Interface for User Application

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Declares a custom interface for the register file, allowing a user application to interact with it. It includes functions for reading, writing, and notifying the application of changes.

```c
typedef interface register_if {
    [[in]] int read(unsigned reg);
    [[in]] void write(unsigned reg, int value);
    [[in]] void notification(void);
} register_if;

[[distributable]]
void register_file(chanend c_i2c, register_if app);
```

--------------------------------

### Application Interface Handler

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Handles function calls from the user application interface, specifically the 'set_register' operation. It validates the register number and performs the requested write operation.

```xc
case app.set_register
  // Handle I2C slave
```

--------------------------------

### Instantiate Single Port I2C Master

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Illustrates the top-level instantiation for a single multi-bit port version of an I2C master. This configuration is used when the I2C master utilizes a single multi-bit port for communication.

```xcore
port p_i2c

// For the single multi-bit port version of I2C the top level instantiation would look like
// Note that the connection is an array of interfaces, so several tasks can connect to the same master.
```

--------------------------------

### Enable Debug Logging in Compiler Flags

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Details how to enable debug printing functionality within the application by adding a specific define to the compiler flags. This allows verbose output for debugging purposes.

```cmake
set(APP_COMPILER_FLAGS ... -DDEBUG_PRINT_ENABLE=1 ...)
```

--------------------------------

### CMake Configuration for I2C Master Async Test

Source: https://github.com/xmos/lib_i2c/blob/develop/tests/i2c_master_async_test/CMakeLists.txt

This script configures build parameters for an I2C master asynchronous test application. It iterates through different architectures (XS2, XS3), speeds, and stop conditions defined in a JSON file. For each combination, it sets specific compiler flags and registers the application using XMOS-specific build system commands. It also includes a separate configuration block for interference testing.

```cmake
cmake_minimum_required(VERSION 3.21)
include($ENV{XMOS_CMAKE_PATH}/xcommon.cmake)

# Get JSON lists
file(READ ${CMAKE_CURRENT_LIST_DIR}/test_params.json params_json)

# Get individual fields from params_json
string(JSON speed_list GET ${params_json} SPEEDS)
string(JSON stop_list GET ${params_json} STOPS)
string(JSON comb_list GET ${params_json} COMBS)

string(JSON speed_list_len LENGTH ${speed_list})
string(JSON stop_list_len LENGTH ${stop_list})
string(JSON comb_list_len LENGTH ${comb_list})

# Subtract one off each of the lengths because RANGE includes last element

math(EXPR speed_list_len "${speed_list_len} - 1")
math(EXPR stop_list_len "${stop_list_len} - 1")
math(EXPR comb_list_len "${comb_list_len} - 1")


set(APP_PCA_ENABLE ON)
set(XMOS_SANDBOX_DIR    ${CMAKE_CURRENT_LIST_DIR}/../../..)
include(${CMAKE_CURRENT_LIST_DIR}/../../examples/deps.cmake)

set(ARCH xs2 xs3)

set(comb_val 1)
set(non_comb_val 0)
set(stop_val 1)
set(no_stop_val 0)

foreach(arch ${ARCH})
    if(arch STREQUAL "xs3")
        set(target "XK-EVK-XU316")
    elseif(arch STREQUAL "xs2")
        set(target "XCORE-200-EXPLORER")
    endif()

    foreach(i RANGE 0 ${comb_list_len})
        string(JSON comb GET ${comb_list} ${i})

        foreach(j RANGE 0 ${speed_list_len})
            string(JSON speed GET ${speed_list} ${j})

            foreach(k RANGE 0 ${stop_list_len})
                string(JSON stop GET ${stop_list} ${k})
                set(config ${comb}_${speed}_${arch}_${stop})
                message(STATUS "building config ${config} => ${${comb}_val}_${speed}_${arch}_${${stop}_val}")

                project(i2c_master_async_test)
                set(APP_HW_TARGET   ${target})

                set(APP_COMPILER_FLAGS_${config}
                    -O2
                    -g
                    -DDEBUG_PRINT_ENABLE=1
                    -report
                    -DSPEED=${speed}
                    -DCOMB=${${comb}_val}
                    -DSTOP=${${stop}_val})

                XMOS_REGISTER_APP()

                unset(APP_COMPILER_FLAGS_${config})

            endforeach() # stop
        endforeach() # speed
    endforeach() # comb

    foreach(k RANGE 0 ${stop_list_len})
        string(JSON stop GET ${stop_list} ${k})
        set(config interfere_${arch}_${stop})
        message(STATUS "building config ${config} => ${arch}_${${stop}_val}")

        project(i2c_master_async_test)
        set(APP_HW_TARGET   ${target})

        set(APP_COMPILER_FLAGS_${config}
            -O2
            -g
            -DDEBUG_PRINT_ENABLE=1
            -report
            -DSPEED=100
            -DCOMB=1
            -DSTOP=${${stop}_val}
            -DINTERFERE)

        XMOS_REGISTER_APP()
        unset(APP_COMPILER_FLAGS_${config})

    endforeach() # stop
endforeach() # arch

```

--------------------------------

### I2C Master Data Request Handling

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Handles requests from the I2C master for data. If a register has been selected, it reads the corresponding register's data; otherwise, it returns 0.

```xc
case i2c.master_requires_data
  // select
```

--------------------------------

### Declare Application Interfaces

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Declares interfaces for inter-task communication within the application. This includes interfaces for the I2C slave, the register file, and the I2C master.

```xcore
i2c_slave_callback_if i_i2c;
    i2c_master_if i2c[1];
```

--------------------------------

### I²C Slave Interface

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Documents the interface group for I²C slave callback operations, detailing the methods for responding to master requests.

```APIDOC
doxygengroup:: i2c_slave_callback_if
  Interface for I²C slave callback operations.
```

--------------------------------

### Accelerometer Device Defines

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00156_i2c_master_example/doc/rst/AN00156.rst

Defines constants for the FXOS8700CQ accelerometer, including its I2C address and key register addresses for data access.

```c
#define FXOS8700CQ_I2C_ADDR 0x1E
#define FXOS8700CQ_OUT_X_MSB 0x01
#define FXOS8700CQ_OUT_X_LSB 0x02
#define FXOS8700CQ_OUT_Y_MSB 0x03
#define FXOS8700CQ_OUT_Y_LSB 0x04
#define FXOS8700CQ_OUT_Z_MSB 0x05
#define FXOS8700CQ_OUT_Z_LSB 0x06
```

--------------------------------

### I²C Master Supporting Typedefs

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Lists and describes the typedefs used for I²C master operations, specifically for return types of operations.

```APIDOC
i2c_res_t
  Typedef for I²C operation results.

i2c_regop_res_t
  Typedef for I²C register operation results.
```

--------------------------------

### I2C Master Data Handling

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Processes data bytes received from the I2C master. The first byte is interpreted as a register number, and subsequent bytes are written to that register. It also notifies the application of changes.

```xc
case i2c.master_sent_data
  // select
```

--------------------------------

### Register File State Variables

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Defines local state variables for the I2C slave interface to track the currently accessed register number and any recently modified registers.

```xc
int current_regnum
int changed_regnum
```

--------------------------------

### Synchronous I2C Master Client Operations

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Demonstrates how an application task can use the client end of an I2C master interface connection to perform I2C bus operations. Operations like read and write will block until completion.

```xcore
void my_application(client i2c_master_if i2c, uint8_t target_device_addr) {
  // The application can use the client end of the interface connection to perform I2C bus operations e.g.
  // i2c.read will block until the operation is completed on the bus.
  // More information on interfaces and tasks can be found in the XMOS Programming Guide.
  // By default the I2C synchronous master mode component does not use any logical cores of its own.
  // It is a distributed task which means it will perform its function on the logical core of the application task connected to it (provided the application task is on the same tile as the I2C ports).
}
```

--------------------------------

### Declare I2C Hardware Ports in xC

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Defines the 1-bit ports required for the I2C interface, specifying pins for both the slave and master devices. Each requires a clock (SCL) and data (SDA) pin.

```c
port p_slave_scl;
port p_slave_sda;
port p_master_scl;
port p_master_sda;
```

--------------------------------

### Read I2C Register Value

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Reads the register value back from an I2C device and verifies the read operation's completion and data inversion.

```xcore
i2c.read_reg
```

--------------------------------

### Add lib_i2c to CMake

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

This snippet shows how to include the lib_i2c library in your XMOS application's CMake configuration by adding it to the APP_DEPENDENT_MODULES list. Applications should then include the i2c.h header file.

```cmake
set(APP_DEPENDENT_MODULES "lib_i2c")
```

--------------------------------

### I²C Master Synchronous Interface

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Documents the interface group for synchronous I²C master operations, detailing the available methods for controlling the I²C bus.

```APIDOC
doxygengroup:: i2c_master_if
  Interface for synchronous I²C master operations.
```

--------------------------------

### I²C Master Asynchronous Interface

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Documents the interface group for asynchronous I²C master operations, detailing the available methods for non-blocking control of the I²C bus.

```APIDOC
doxygengroup:: i2c_master_async_if
  Interface for asynchronous I²C master operations.
```

--------------------------------

### Include lib_i2c in CMakeLists.txt

Source: https://github.com/xmos/lib_i2c/blob/develop/doc/rst/lib_i2c.rst

Specifies how to include the lib_i2c library in your project's CMake build configuration by adding it to the APP_DEPENDENT_MODULES list.

```CMakeLists.txt
set(APP_DEPENDENT_MODULES "lib_i2c")
```

--------------------------------

### Declare I2C Slave Address

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Declares the 8-bit unsigned integer variable holding the address of the I2C slave device.

```xcore
uint8_t device_addr = 0x3c
```

--------------------------------

### Register File Storage Declaration

Source: https://github.com/xmos/lib_i2c/blob/develop/examples/AN00157_i2c_slave_example/doc/rst/AN00157.rst

Declares the storage for registers within the I2C register file. This array holds the actual data for each register, managed by the I2C interface.

```xc
uint8_t registers[NUM_REGISTERS]
```
Tokens:
Raw