Interoperability Debugging Tool

Overview

The “Interoperability Debugging Tool” (IDT) is a python-based tool that supports a variety of commands that are useful in the context of interoperability testing of Matter devices and app controllers.

Discovery

While in discovery mode, the tool displays all Matter devices that are in commission and/or operational mode. This is useful to have a clear understanding of all Matter devices currently “active” in the testing environment.

See section “4.3. Discovery” of the Matter spec for official documentation.

When run interactively, discovery functions in one of two modes: BLE and DNS-SD.

Capture

While in capture mode, the tool starts capturing all data of interest (e.g. video recording of interactions with the mobile app, logs from all components involved, network packets capture, etc.) while a test is being conducted manually. It also provides feedback to the user on test setup and execution.

When the test completes, capture mode is stopped and all captured data is zipped in a file that can then be sent to all parties involved in investigating any issue uncovered via the manual test. Each ecosystem may implement an analysis that analyzes capture data, displays info to the user, probes the local environment and generates additional artifacts.

Getting started

Raspberry Pi installation

Environment overview

The execution environment of IDT when using Raspberry Pi is shown in the figure below.

[TODO] add figure.

The Raspberry Pi is where “discovery” and “capture” are executed.

The “admin” computer is the machine used to connect to and control the RPi, and to fetch artifacts which were created during capture from the RPi.

This directory contains tools for use on both the admin computer and the RPi.

Environment details

1. idt will be used on both the admin computer and the RPi.
2. scripts only points to one installation location at a time. It is ideal to maintain a single idt directory on each (admin and RPi) system accordingly.
3. The expected install location on the RPi is the home directory of the user specified in idt/scripts/vars.sh, which will be generated by running a script in the next section.
4. Helper scripts may be used on admin computers that support zsh and bash (Linux and macOS).
5. Windows may be used as the admin computer via tools like PowerShell, MobaXterm and FileZilla.
6. This setup is intended to work with the admin computer and RPi connected to the same Wi-Fi network, which is also the Wi-Fi network used for testing.
7. Corporate networks are not expected to be used as test networks.

Prepare the RPi

1. A >= 128 GB SD card is recommended.
2. Flash the RPi SD with the debian based distribution of your choice.
3. Plug the SD into the RPi.
4. Ensure the RPi is connected to your network, either via ethernet or with Wi-Fi configured in the disk image.
5. Boot the RPi.

Configure admin computer and push to the RPi

Linux and macOS admin computers

1. On your admin computer, source the alias script from the parent directory of idt to get idt commands in your current shell.

    source idt/scripts/alias.sh
   

   • To avoid having to repeat this step for each session, optionally configure automatic aliases permanently.
   • NOTE: Once run, idt commands will be globally and automatically available. If you need to remove the installation, edit the .rc files mentioned in setup_shell.

   source idt/scripts/setup_shell.sh
   

2. Run idt_create_vars and follow the prompts to set IDs for the target RPi.
3. Send idt to the RPi:

   idt_push
   

4. ssh to the RPi:
   • NOTE: You may need to wait a few minutes after boot for the ssh server to be available on the RPi. Retry if needed!

   idt_connect
   

Windows admin computers

1. Open PowerShell, cd to the directory containing idt and send idt to the RPi:

   scp -r ./idt/* $PIUSER@$PIHOST:/home/$PIUSER/idt
   

2. ssh to the RPi, e.g. with MobaXterm
   • NOTE: You may need to wait a few minutes after boot for the ssh server to be available on the RPi. Retry if needed!
   • Use $PIUSER@$PIHOST or $PIUSER@$ip where $ip is the RPi's IP found in your router admin panel.

Configure the RPi

1. Configure passwords or ssh keys.
2. Configure Wi-Fi networks if needed.
3. Set up idt:

   cd ~                               # Go to idt parent dir
   source idt/scripts/setup_shell.sh  # Setup atuo aliases
   source idt/scripts/alias.sh        # Get aliases now
   idt_bootstrap                      # Initial configuration
   idt_build                          # Build the container image
   

Install updates

SCP may not overwrite all files. To clear the idt dir off of the RPi safely between pushes, exit the container and:

idt_clean

NOTE the idt artifacts directory is contained in idt, so running this will delete any artifacts ([TODO] change).

Then from the admin computer:

idt_push

Single host installation (no Raspberry Pi)

Follow the steps below to execute capture and discovery without a Raspberry Pi.

Linux installation

Requirements

• This package should work on most Debian (/based) systems.
• idt is currently tested on Python 3.11.
• adb and tcpdump are required.
• The machine running idt should be connected to the same Wi-Fi network used for testing.

Setup

• From the parent directory of idt, run source idt/scripts/alias.sh.
• Optionally, run source idt/scripts/setup_shell.sh to install aliases permanently.

You may use idt in a Python virtual environment OR using a container from the idt image.

Python virtual environment

• After idt aliases are available in your environment, calling any idt command will automatically create a new virtual environment and install dependencies.

Docker

• Run idt_build and idt_activate to enter the idt container.

[TODO] Podman

macOS installation

Most features other than BLE should work on macOS.

Follow the Linux installation steps above, but do not use Docker.

[TODO] macOS BLE support

User guide

IMPORTANT
idt_ commands are shell aliases helpful for administrative commands.
idt invokes the idt python package.

RPi users, as needed:

• For users with Windows admin computers, reconnect e.g., using MobaXterm
• Other users reconnect ssh to the RPi (from your admin computer):

  idt_connect
  

• Run the idt container (from the RPi):

  idt_activate
  

Capture

idt capture -h

usage: idt capture [-h] [--platform {Android}]
                   [--ecosystem {PlayServices,PlayServicesUser,ALL}]
                   [--pcap {t,f}]
                   [--interface {wlp0s20f3,docker0,lo}]
                   [--additional {t,f}]

options:
  -h, --help            show this help message and exit
  --platform {Android}, -p {Android}
                        Run capture for a particular platform
                        (default Android)
  --ecosystem {PlayServices,PlayServicesUser,ALL}, -e {PlayServices,PlayServicesUser,ALL}
                        Run capture for a particular ecosystem or ALL
                        ecosystems (default ALL)
  --pcap {t,f}, -c {t,f}
                        Run packet capture (default t)
  --interface {wlp0s20f3,docker0,lo}, -i {wlp0s20f3,docker0,lo}
                        Run packet capture against a specified
                        interface (default wlp0s20f3)
  --additional {t,f}, -a {t,f}
                        Run ble and mdns scanners in the background
                        while capturing (default t)

Artifacts

Each ecosystem and platform involved in the capture will have their own subdirectory in the root artifact dir.

To download your artifacts, run these commands from your admin computer:

idt_fetch_artifacts

On windows admin computers, you may use FileZilla to pull the archive listed at the end of output.

Discovery

idt discover -h

usage: idt discover [-h] --type {ble,b,dnssd,d}

options:
  -h, --help            show this help message and exit
  --type {ble,b,dnssd,d}, -t {ble,b,dnssd,d}
                        Specify the type of discovery to execute

ble

idt discover -t b

mDNS

idt discover -t d

Artifacts

There is a per device log for ble scanning in ble subdirectory of the root artifact dir.

[TODO] dnssd per device log

Extending functionality

Ecosystem and Platform implementations are dynamically loaded.

For each package in capture/ecosystem, the ecosystem loader expects a module name matching the package name.
This module must contain a single class which is a subclass of capture.base.EcosystemCapture.

/capture/ecosystem/play_services_user contains a minimal example implementation.

As another example, link /res/plugin_demo/ecosystem/demo_ext_ecosystem.

$ idt_go && ln -s $PWD/idt/res/plugin_demo/ecosystem/demo_ext_ecosystem/ idt/capture/ecosystem
$ idt capture -h
usage: idt capture [-h] [--platform {Android}] [--ecosystem {DemoExtEcosystem...

The platform loader functions the same as capture/ecosystem.

For each package in capture/platform, the platform loader expects a module name matching the package name.
This module must contain a single class which is a subclass of capture.base.PlatformLogStreamer.

Note the following runtime expectations of platforms:

• Start should be able to be called repeatedly without restarting streaming.
• Stop should not cause an error even if the stream is not running.