Test Suite for Smart Home with Matter is a developer platform to support 3rd-party partners build products using the Matter technology, which integrates with the Google Nest ecosystem.
To support partners in testing and certifying their products, Test Suite for Smart Home with Matter provides the tools and services to allow partners to comprehensively test their Matter products against the Google ecosystem in a scalable way.
Local Agent, one of the major components of Smart Home Partner Test Suite, is a Python-based application which can be installed in the host machines at partners' laboratory. The local agent is required for running automated test suite. It is used to command and control the devices under test (hereinafter called DUT) and perform Matter protocol operations at the testing site. Note that partners won't need to use local agent if they only aim to run Manual test suites.
In order to use local agent, partners will have to enable the Matter testability of their DUTs, please contact your Google Developer Support.
Note that this is not an officially supported Google product.
Make sure your machine meets the following prerequisites before setting up the local agent.
The device control library we're using in local agent is GDM, also known as Gazoo Device Manager, which is also a python package for interacting with Matter devices.
To allow local agent to talk to your Matter devices, you must build and add your own Matter device controllers to GDM. Please follow the extension Matter controller codelab in GDM to build and install.
Note that you'll have to install your extension packages under the same virtual environment that you create for setting up the local agent. Please contact your Google Developer Support if you are not sure how to implement your extension packages.
Clone the repository (at a desired place):
$ git clone https://testsuite-smarthome-matter.googlesource.com/local-agent
Create a dedicated virtual environment for developing local agent if you don't have one:
$ python3 -m venv <venv-name>
Important: Make sure you're running a python version >= 3.7, otherwise some packages are not supported.
Activate the virtual environment:
$ source <venv-name>/bin/activate
Install the local agent package in your virtual environment:
$ cd /path/to/{repo-base}/local-agent
$ pip install .
For development, we might want to use
pip install -e .. (See documentation of the “-e” option here)
local_agent_config.ini under ~/.config/google/.local_agent_config.ini.Matter extension packages section) in local_agent_config.ini. See example_config.ini for references.You should be running the Smart Home testsuite from the frontend web app to link and use the local agent.
On the web app's Test Plan page, you should see a Local Agent Setup button. Click on it, and if you haven’t linked your local agent before, you should see a linking code. Copy the linking code.
On your host machine, activate the virtual environment where you installed the local agent, and start the local agent by simply running $ local-agent.
Once you’ve started your local agent, you should see a prompt that asks you for the linking code. Paste the linking code you copied from the web app. The local agent should start the linking process, and it will also start the device detection process, which should detect your DUTs that are connected to your host machine.
A successful linking result will look like this:
$ local-agent
20211207 14:39:39.785 I local_agent.py:444 Start the linking process
Linking Code:1d8eb371
20211207 14:41:10.240 I local_agent.py:149 Local Agent is linked successfully.
20211207 14:41:10.241 I local_agent.py:224 Reporting status to AMS.
20211207 14:41:10.242 I local_agent.py:258 Polling JSON-RPC requests from AMS.
Moving config files to the backup directory /usr/local/google/home/chingtzuchen/gazoo/gdm/conf/backup/backup-20211207-064110
##### Step 1/3: Detecting potential new communication addresses. #####
detecting potential AdbComms communication addresses
detecting potential DockerComms communication addresses
detecting potential JlinkSerialComms communication addresses
detecting potential PigweedSerialComms communication addresses
detecting potential PtyProcessComms communication addresses
detecting potential SshComms communication addresses
detecting potential SerialComms communication addresses
No read/write permission for these serial address(es): ['/dev/bus/usb/001/001', '/dev/bus/usb/001/005', '/dev/bus/usb/002/001']
detecting potential UsbComms communication addresses
detecting potential YepkitComms communication addresses
'ykushcmd' is not installed. Cannot get Yepkit serials.
Found 1 possible pigweedserialcomms connections:
/dev/serial/by-id/usb-Silicon_Labs_J-Link_Pro_OB_000440186694-if00
Found 2 possible serialcomms connections:
/dev/bus/usb/001/002
/dev/bus/usb/001/003
Found 1 possible usbcomms connections:
000440186694
##### Step 2/3 Identify Device Type of Connections. #####
Identifying pigweedserialcomms devices..
_dev_serial_by-id_usb-Silicon_Labs_J-Link_Pro_OB_000440186694-if00_detect.txt logging to file /tmp/_dev_serial_by-id_usb-Silicon_Labs_J-Link_Pro_OB_000440186694-if00_detect.txt
_dev_serial_by-id_usb-Silicon_Labs_J-Link_Pro_OB_000440186694-if00_detect.txt closing switchboard processes
20211207 14:41:11.263 I local_agent.py:258 Polling JSON-RPC requests from AMS.
/dev/serial/by-id/usb-Silicon_Labs_J-Link_Pro_OB_000440186694-if00 is a efr32matterlighting.
pigweedserialcomms device_type detection complete.
Identifying serialcomms devices..
20211207 14:41:12.281 I local_agent.py:258 Polling JSON-RPC requests from AMS.
/dev/bus/usb/001/002 responses did not match a known device type.
/dev/bus/usb/001/003 responses did not match a known device type.
serialcomms device_type detection complete.
Identifying usbcomms devices..
000440186694 responses did not match a known device type.
usbcomms device_type detection complete.
##### Step 3/3: Extract Persistent Info from Detected Devices. #####
Getting info from communication port /dev/serial/by-id/usb-Silicon_Labs_J-Link_Pro_OB_000440186694-if00 for efr32matterlighting
efr32matterlighting_detect checking device readiness: attempt 1 of 1
efr32matterlighting_detect starting GazooDeviceBase.check_device_ready
Power cycling properties not yet detected.
efr32matterlighting_detect health check 1/3 succeeded: Check power cycling ready.
efr32matterlighting_detect waiting up to 3s for device to be connected.
efr32matterlighting_detect health check 2/3 succeeded: Check device connected.
efr32matterlighting_detect logging to file /tmp/_dev_serial_by-id_usb-Silicon_Labs_J-Link_Pro_OB_000440186694-if00_detect.txt
20211207 14:41:13.302 I local_agent.py:258 Polling JSON-RPC requests from AMS.
efr32matterlighting_detect health check 3/3 succeeded: Check create switchboard.
efr32matterlighting_detect GazooDeviceBase.check_device_ready successful. It took 0s.
efr32matterlighting_detect starting Efr32MatterDevice.get_detection_info
efr32matterlighting_detect Efr32MatterDevice.get_detection_info successful. It took 0s.
efr32matterlighting_detect closing switchboard processes
20211207 14:41:14.320 I local_agent.py:258 Polling JSON-RPC requests from AMS.
##### Detection Summary #####
1 new devices detected:
efr32matterlighting-6694
3 connections found but not detected:
/dev/bus/usb/001/002
/dev/bus/usb/001/003
000440186694
If a connection failed detection, check https://github.com/google/gazoo-device/blob/master/docs/device_setup for tips
Device Alias Type Model Connected
------------------------------ --------------- ------------------------ -------------------- ----------
efr32matterlighting-6694 <undefined> efr32matterlighting PROTO connected
Other Devices Alias Type Model Available
------------------------------ --------------- ------------------------ -------------------- ----------
1 total Gazoo device(s) available.
20211207 14:41:15.339 I local_agent.py:258 Polling JSON-RPC requests from AMS.
20211207 14:41:16.362 I local_agent.py:258 Polling JSON-RPC requests from AMS.
20211207 14:41:20.455 W local_agent.py:269 The local agent is unlinked.
20211207 14:41:20.456 I local_agent.py:285 Stopped polling RPC because stop event is set.
20211207 14:41:20.456 I local_agent.py:249 Stopped reporting info because stop event is set.
You won‘t be able to run Local Agent if it’s outdated (the current version is below the minimal required version showed on the web app). Check the version of your Local Agent:
$ local-agent -v
or
$ local-agent -version
If your Local Agent is outdated, you'll need to update the package manually:
Go to the directory where you installed the local agent:
$ cd /path/to/{repo-base}/local-agent
Fetch and rebase to get the latest commit:
$ git fetch origin $ git rebase origin/master
Enable the virtual environment and install the latest Local Agent:
$ source <venv-name>/bin/activate
$ cd /path/to/{repo-base}/local-agent
$ pip install .
Make sure you're using Ubuntu LTS on your host and python version is >= 3.7.
Make sure your local agent is talking to the correct backend service: The local agent will use the official backend configuration if the AMS_HOST, AMS_PORT and AMS_SCHEME are not provided in local_agent_config.ini, so for the external users, you should just simply leave these fields blank. For the internal users who deploy the backend by themselves, should probably check the backend configurations in local_agent_config.ini.
Local Agent uses Pigweed RPC debug interface for communicating with Matter devices, make sure your Matter device implements the Pigweed RPC endpoint and your Matter device class is already registered in GDM (step 5 in the Setup section). You can also try detecting the devices via GDM directly by following the GDM instructions.
If the device gets shutdown or rebooted during test execution, GDM may crash and you'll need to close the Local Agent and restart it again after the test execution. Local agent does not need to be re-linked..
Local agent will be closed forcely and you'll need to restart it. Local agent does not need to be re-linked.
Please contact your Google Developer Support or smarthome-testsuite-contrib@google.com if you encounter any unexpected problems.