README.md

Zephyr Example Application for MEC1753 I3C

This repository contains a Zephyr sample application for Microchip's MEC1753 I3C peripheral. It is based on the Zephyr example application framework. Some of the features demonstrated in this example are:

• Basic Zephyr application skeleton
• Zephyr workspace applications
• Zephyr modules
• West T2 topology
• Custom boards
• Custom devicetree bindings
• Out-of-tree drivers
• Out-of-tree libraries
• Example CI configuration (using GitHub Actions)
• Custom west extension
• Doxygen and Sphinx documentation boilerplate

This repository is versioned together with the Microchip fork of the Zephyr main tree and hal_microchip.

Getting Started

Before getting started, make sure you have a proper Zephyr development environment. Follow the official Zephyr Getting Started Guide.

Initialization

The first step is to initialize the workspace folder (zws) where the mec5_i2c_app and all Zephyr modules will be cloned. Run the following command:

# initialize zws for the mec5_i3c_app (main branch)
mkdir ~/zws
# configure a python virtual environment in zws
python -m venv ~/zws/.venv
# enter the python virtual environment
source ~/zws/.venv/bin/activate
cd ~/zws
# install west and other python modules
pip install west
pip install unidiff
pip install compdb
# Download the mec5_i3c_app using https or GitHub tool (gh)
git clone https://github.com/MicrochipTech/mec5_i3c_app
# or using GitHub command line tools assuming you have authentication configured
gh repo clone MicrochipTech/mec5_i3c_app
# Intialize the local repo
west init -l mec5_i3c_app
# Update to pull down the Zephyr, Microchip HAL, and CMSIS HAL.
west update
west zephyr-export
# Download Pythom modules required by Zephyr
pip install -r ~/zws/zephyr/scripts/requirements.txt

Building and running

To build the application, run the following command:

cd mec5_i3c_app
west build -p always -b mec_assy6941_mec1753qsz app

One can define the environment variable BOARD=mec_assy6941_mec1753qsz and use $BOARD in commands

NOTE: mec5_i3c_app contains the 'custom_plank` board which is present only as a reference on how to implement an out-of-tree board. It is not meant to build with the I3C application.

A sample debug configuration is also provided. To apply it, run the following command:

west build -b $BOARD app -- -DEXTRA_CONF_FILE=debug.conf

Testing

To execute Twister integration tests, run the following command:

west twister -T tests --integration

Documentation

A minimal documentation setup is provided for Doxygen and Sphinx. To build the documentation first change to the doc folder:

cd doc

Before continuing, check if you have Doxygen installed. It is recommended to use the same Doxygen version used in CI. To install Sphinx, make sure you have a Python installation in place and run:

pip install -r requirements.txt

API documentation (Doxygen) can be built using the following command:

doxygen

The output will be stored in the _build_doxygen folder. Similarly, the Sphinx documentation (HTML) can be built using the following command:

make html

The output will be stored in the _build_sphinx folder. You may check for other output formats other than HTML by running make help.