Maui

Maui is device to streamline DUT debugging by combining ADB, CCD, and power delivery functionalities. This repo would be used for: MCU Firmware: - based on Zephyr RTOS - control of on-board ICs: PDC, signal muxing, etc. - host interface Host Software: - Linux-based tools - Integration with standard Google debugging tools (adb, fastboot, servod), - Provide maintenance tools: all system components firmware updates, managing in fleet - General host interface for additional features: remote DUT disconnection, etc.

Quick Start

Get the code and update your Maui device to the latest stable firmware:

# 1. Clone the repository
git clone https://chromium.googlesource.com/chromiumos/platform/hwtools/maui
cd maui

# 2. Update all firmware components (MCU & PDC) to the latest stable version

./tools/scripts/maui-flash all

# Note: You may need to provide your device serial number if multiple devices are connected.
./tools/scripts/maui-flash all --serial <SERIAL>

# 3. Verify device status / FW version
./tools/scripts/maui-ctl status

For detailed usage of the host tools, see tools/README.md.

Getting started

Create a directory to checkout the Maui source:

mkdir maui_source
cd maui_source

Get the source code:

git clone https://chromium.googlesource.com/chromiumos/platform/hwtools/maui
cd maui

This repository uses pre-commit hooks to enforce code style. Please make sure you have them installed by running:

pip install pre-commit --break-system-packages
pre-commit install

To upload your changes to gerrit you can use:

git push origin HEAD:refs/for/main

Supported Hardware Targets

Maui supports three prototype MCU hardware variants:

• maui_proto_3507 (Default):
  • MCU: TI MSPM0G3507
  • Features: Prototype board relying on an external FTDI USB-to-UART bridge. The shell/console operates over physical UART, and flashing uses UART BSL mode.
• maui_proto_5117:
  • MCU: TI MSPM0G5117
  • Features: Uses the native on-chip USB hardware controller with Zephyr USB Next stack. The shell/console operates directly over USB CDC ACM (/dev/ttyACM*), and flashing uses native USB DFU mode (--usb).
• maui_v1p2_it82002:
  • MCU: ITE IT82002AW (RISC-V), 1 MB flash
  • Features: Three-stage boot chain (RO bootloader -> RW bootloader -> App) with hardware flash write-protection of both bootloaders. Shell over native USB CDC ACM, firmware updates via MCUboot serial recovery (smpmgr).
  • See firmware/boards/maui_v1p2_it82002/README.md for the boot flow, flash layout, memory protection and flashing procedures.

Build firmware using Docker

While in the maui root directory of this repository:

1. Building for maui_proto_3507 (Default)

Build the Docker builder image for maui_proto_3507:

docker build -t maui-builder -f dockerfiles/Dockerfile.fw_builder .

Compile the maui_proto_3507 firmware:

docker run --rm -v $(pwd):/repo maui-builder:latest

2. Building for maui_proto_5117

Build the Docker builder image for maui_proto_5117:

docker build -t maui-builder-5117 --build-arg BOARD=maui_proto_5117 -f dockerfiles/Dockerfile.fw_builder .

Compile the maui_proto_5117 firmware:

docker run --rm -v $(pwd):/repo maui-builder-5117:latest -b maui_proto_5117 -p

This will generate a text-format firmware file in: firmware/build_docker/zephyr/zephyr.txt This file can be used to flash Maui using BSL or DFU.

3. Building for maui_v1p2_it82002

Build the Docker builder image for maui_v1p2_it82002:

docker build -t maui-builder-it82002 --build-arg BOARD=it82002 -f dockerfiles/Dockerfile.fw_builder .

Compile the maui_v1p2_it82002 firmware (RO bootloader, RW bootloader, application, and the combined 1 MB flash image):

docker run --rm -v "$(pwd)":/repo -w /repo/firmware \
  --entrypoint bash maui-builder-it82002 \
  -c './bootloader/mcuboot/build_bootloaders.sh'

Note that --entrypoint bash is required: the image's default entrypoint builds only the standalone single-image application and does not produce the bootloaders or the combined image.

See firmware/boards/maui_v1p2_it82002/README.md for the resulting artifacts and how to flash them.

Unit Testing

The project uses the Zephyr Twister framework for unit testing application code. Tests are executed inside the maui-builder Docker container to ensure a consistent environment.

Running Tests

First, ensure the builder image is built (if not already):

docker build -t maui-builder -f dockerfiles/Dockerfile.fw_builder .

To run all unit tests:

docker run --rm -v $(pwd):/repo --entrypoint /firmware_test.sh maui-builder

To run a specific test suite (e.g., utils.basic):

docker run --rm -v $(pwd):/repo --entrypoint /firmware_test.sh maui-builder -s utils.basic -v

Writing New Tests

1. Create a new directory under firmware/tests/unit/<component_name>_test.
2. Add a testcase.yaml defining the test scenarios. Ensure platform_allow and integration_platforms are set to native_sim.
3. Add a prj.conf (usually CONFIG_ZTEST=y is sufficient).
4. Add a CMakeLists.txt to include the test source and the application source files you are testing.
5. Add your test code in <component_name>_test/src/main.c using the Ztest API (ZTEST, zassert_equal, etc.).

Host Tools & Firmware Update

The project includes host-side tools for managing the device and updating firmware. These tools are distributed via a Docker container (maui-utils) which is automatically fetched or built by the wrapper scripts.

See tools/README.md for full documentation.

Common Commands

• Update Everything (Stable): ./tools/scripts/maui-flash all
• Check Status: ./tools/scripts/maui-ctl status