Создайте виртуальное устройство Matter

1. Введение

Matter — это протокол связи, открывающий захватывающие возможности для разработки интеллектуальных устройств. В этом практическом занятии вы создадите своё первое устройство на основе Matter, используя ресурсы из Matter SDK.

Чтобы узнать больше о технологии Matter, посетите Центр разработчиков Google Home или веб-сайт Альянса стандартов подключения .

Что вы узнаете

  • Как настроить среду сборки Matter
  • Как создать виртуальное устройство Материи, работающее на вашем компьютере
  • Как ввести в эксплуатацию и управлять виртуальным устройством Matter с помощью Google Home

Что вам понадобится

  • Центр управления — это любое устройство Google Nest, поддерживающее Matter , например, Nest Hub (2-го поколения).
  • Компьютер под управлением Linux с оконной системой X11.
  • Docker.
  • Гит.
  • Базовые знания Linux.
    • Обратите внимание, что для всех команд в этом практическом занятии предполагается использование оболочки BASH.

2. Настройте свою среду.

Проверьте ваше оборудование.

Данная установка Docker не поддерживается компьютерами под управлением Windows и macOS. Вы можете установить и собрать Matter вручную на macOS.

Кроме того, эти инструкции предполагают, что на вашем компьютере с Linux установлена ​​оконная система X11. Если на вашем компьютере с Linux установлен Wayland, убедитесь, что X.Org также установлен.

Настройка среды разработки

  1. Установите Docker Engine (не используйте Docker Desktop).
  2. Клонируйте SDK Matter, обратите внимание на коммит, который мы используем в следующем примере. 
    git clone https://github.com/project-chip/connectedhomeip.git
cd connectedhomeip
git show
commit f2f3d0eb03ba5bea32b22f19982c402a8c1c9063
  3. Запустите контейнер сборки, используя общедоступные образы CI SDK, и выполните только что созданное виртуальное устройство из этого контейнера. Найдите образ, соответствующий вашей версии SDK, следующим образом:
    buildimage=$(grep chip-build .github/workflows/chef.yaml | head -n 1 | awk '{print $2}')
echo $buildimage
    Если вы используете тот же коммит, вы должны увидеть ghcr.io/project-chip/chip-build:66 Сначала перенаправим порты xhost, чтобы позже можно было использовать приложения с пользовательским интерфейсом:
    xhost local:1000
    Далее запустите контейнер с соответствующими ресурсами, перенаправленными с хоста (наш загруженный SDK, сетевые ресурсы и ресурсы отображения/связи). 
    docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind   --workdir="/workspace" $buildimage /bin/bash

Давайте разберемся в команде docker и параметрах, которые мы ей передали:

  • xhost local:1000 позволяет системе X Window принимать соединения с локального хоста через порт 1000, что обеспечивает возможность использования графического пользовательского интерфейса.
  • docker run … image запускает указанный образ, при необходимости загружая его из реестра Docker.
  • --ipc=host позволяет Docker использовать пространство имен межпроцессного взаимодействия совместно с вашей хост-машиной.
  • --net=host позволяет Docker использовать сетевой стек хоста внутри контейнера, что необходимо для передачи mDNS-трафика с хоста в контейнер и для совместного использования дисплея X11 хоста.
  • -e DISPLAY экспортирует $DISPLAY на хост, предоставляя доступ к графическому интерфейсу вашей системы. Это необходимо для запуска инструмента ZAP при редактировании кластеров Matter.
  • -it запускает Docker с интерактивным терминалом (tty), а не в фоновом режиме.
  • --mount монтирует ранее загруженный нами SDK в контейнер.
  • --workdir устанавливает в качестве рабочего каталога при запуске смонтированный каталог SDK.

При желании вы можете запустить второй экземпляр терминальной сессии:

user@host> docker exec -it matter-container /bin/bash
$

Остановите и запустите контейнер Docker Matter.

При каждом запуске команды docker run вы создадите новый контейнер с указанным образом. При этом ваши старые данные, сохраненные в предыдущем экземпляре контейнера, будут потеряны. Иногда это именно то, что вам нужно, поскольку это позволяет начать с чистой установки. Но бывают ситуации, когда вы предпочитаете сохранять свою работу и конфигурацию среды между сессиями.

Поэтому после создания контейнера вы можете его остановить, чтобы предотвратить потерю вашей работы.

user@host> docker stop matter-container

Когда будете готовы снова запустить контейнер, запустите его и откройте окно терминала:

user@host> docker start matter-container
user@host> docker exec -it matter-container /bin/bash

Вы можете открыть дополнительные терминальные сессии для вашего контейнера с помощью команды:

user@host> docker exec -it matter-container /bin/bash

Или запустите сеанс с правами root, используя:

user@host> docker exec -u 0 -it matter-container /bin/bash

Начальная подготовка материала

Инициализируйте SDK.

Инициализируйте SDK Matter. Эта операция займет несколько минут. 

source scripts/bootstrap.sh
python3 scripts/checkout_submodules.py --shallow --platform linux

Ваш SDK Matter инициализирован. Для быстрой повторной инициализации среды в будущем выполните следующую команду: 

sudo docker exec -it  matter-container /bin/bash
source ./scripts/activate.sh

Обмен файлами между хостом и контейнером.

Ранее мы получали доступ к файлам на вашей хост-машине изнутри контейнера, используя привязку монтирования. Вы также можете записывать файлы в смонтированный каталог изнутри контейнера для доступа с хоста.

Как правило, для монтирования контейнера с помощью bind mount используйте дополнительный аргумент --mount source=$(pwd),target=/workspace,type=bind чтобы смонтировать текущий рабочий каталог в контейнер по адресу /workspace . 

user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container --mount source=$(pwd),target=/workspace,type=bind us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

Права доступа пользователя контейнера к смонтированному каталогу должны управляться на хосте.

Получите идентификатор группы пользователя контейнера изнутри контейнера. 

$ id
uid=1000(matter) gid=1000(matter) groups=1000(matter)

Откройте еще одну терминальную сессию на хосте контейнера и установите рабочий каталог в каталог, смонтированный контейнером.

Рекурсивно установите группу для файлов в смонтированном каталоге в группу пользователя контейнера. 

user@host> sudo chgrp -R 1000 .

Предоставьте группе необходимые права доступа к каталогу. В этом примере группе пользователей контейнера предоставляются права на чтение, запись и выполнение всех файлов в смонтированном каталоге. 

user@host> sudo chmod -R g+rwx .

Обратите внимание, что эти команды не влияют на права доступа к новым файлам, созданным пользователем хоста. Не забудьте при необходимости обновить права доступа к новым файлам, созданным на хосте.

Вы можете добавить своего пользователя хоста в группу пользователя контейнера, чтобы он унаследовал права доступа к файлам, созданным пользователем контейнера. 

user@host> currentuser=$(whoami)
user@host> sudo usermod -a -G 1000 $currentuser

3. Консоль разработчика Google Home

Консоль разработчика Google Home — это веб-приложение, в котором вы управляете интеграцией Matter с Google Home.

Любое устройство Matter, прошедшее сертификацию Connectivity Standards Alliance (Alliance) Matter, работает в экосистеме Google Home. Устройства, находящиеся в разработке и не прошедшие сертификацию, могут быть включены в экосистему Google Home при определенных условиях — см. раздел «Ограничения сопряжения» для получения дополнительной информации.

Создайте проект для разработчиков.

Для начала перейдите в консоль разработчика Google Home:

  1. Нажмите «Создать проект» .
  2. Введите уникальное название проекта, а затем нажмите «Создать проект» .Диалоговое окно «Создать новый проект»
  3. Нажмите кнопку «Добавить интеграцию» , и вы перейдете на экран ресурсов Matter , где сможете просмотреть документацию по разработке Matter и ознакомиться с некоторыми инструментами.
  4. Когда будете готовы продолжить, нажмите «Далее: Разработка» , после чего откроется страница контрольного списка «Вопрос» .
  5. Нажмите «Далее: Настройка»
  6. На странице «Настройка» введите название вашего продукта .
  7. Нажмите «Выбрать тип устройства» и выберите тип устройства из выпадающего меню (в данном случае, Light »).
  8. В поле «Идентификатор поставщика (VID)» выберите «Тестовый VID» и выберите 0xFFF1 из выпадающего меню «Тестовый VID». В поле «Идентификатор продукта (PID)» введите 0x8000, нажмите «Сохранить и продолжить» , а затем нажмите «Сохранить» на следующей странице. Используйте именно эти значения VID/PID, поскольку дальнейшие шаги в практическом задании зависят от них.
    Создание проекта
  9. Теперь вы увидите свою интеграцию в разделе «Интеграции Matter» .
  10. Перезагрузите хаб, чтобы убедиться, что он получил самую последнюю конфигурацию проекта интеграции Matter. Если вам потребуется изменить VID или PID позже, вам также потребуется перезагрузить устройство после сохранения проекта, чтобы изменения вступили в силу. Пошаговые инструкции по перезагрузке см. в разделе «Перезапуск устройств Google Nest или Google Wifi» .

4. Создайте устройство.

Все примеры использования Matter находятся в папке examples в репозитории Github . Доступно несколько примеров, но в этом практическом занятии мы сосредоточимся на Chef .

Шеф-повар — это и то, и другое:

  • Пример приложения, предоставляющего терминальный интерфейс и использующего функции, также присутствующие в приложении examples/shell .
  • Скрипт, использующий принцип «соглашение важнее конфигурации», позволяет реализовать ряд распространенных задач, необходимых для разработки устройства, поддерживающего технологию Matter.

Перейдите в папку с примерами Chef и выполните свою первую сборку Matter: 

$ cd examples/chef
$ ./chef.py -zbr -d rootnode_dimmablelight_bCwGYSDpoe -t linux

У Chef есть несколько параметров, которые можно просмотреть, запустив chef.py -h . В данном случае мы используем следующие параметры:

  • -d : определяет тип используемого устройства. В данном случае мы создаём приложение для управления освещением с функциями включения/выключения и регулировки уровня.
  • -z : запускает инструмент ZAP для генерации исходных файлов, реализующих тип устройства. То есть, в зависимости от выбранного вами типа освещения, ZAP автоматически создаст код, который будет включен в сборку и определяет тип освещения (модель данных) и то, как оно взаимодействует с другими устройствами (модель взаимодействия).
  • -b : сборки.
  • -r : [необязательно] включает RPC-сервер на виртуальном устройстве Matter, чтобы другие компоненты (например, графический интерфейс пользователя) могли взаимодействовать с устройством для установки и получения атрибутов модели данных.
  • -t linux : целевая платформа. Поддерживаемые платформы: linux , nrfconnect и esp32 . Вы можете запустить ./chef.py -h , чтобы увидеть все доступные команды и поддерживаемые целевые платформы. linux используется для виртуальных устройств Matter.

Запустите устройство

Matter использует TCP/UDP-порт 5540 , поэтому, если на вашем компьютере запущен брандмауэр, либо отключите его, либо разрешите входящие TCP/UDP-соединения через порт 5540.

Запустите виртуальное устройство в контейнере с помощью следующей команды: 

$ ./linux/out/rootnode_dimmablelight_bCwGYSDpoe
   [1648589956496] [14264:16538181] CHIP: [DL] _Init]
...
[1648562026.946882][433632:433632] CHIP:SVR: SetupQRCode: [MT:Y3.13Y2N00KA0648G00]
[1648562026.946893][433632:433632] CHIP:SVR: Copy/paste the below URL in a browser to see the QR Code:
[1648562026.946901][433632:433632] CHIP:SVR: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AY3.13Y2N00KA0648G00
[1648562026.946915][433632:433632] CHIP:SVR: Manual pairing code: [34970112332]

Оставьте устройство включенным. Теперь перейдем к приложению Google Home, чтобы подключить ваше устройство к системе Google Home.

Остановите устройство

Если вам нужно остановить устройство, вы можете выйти из программы с помощью CTRL+C. Если приложение не закрывается, вам также может потребоваться использовать CTRL+\.

Учетные данные для вашего виртуального устройства хранятся в каталоге /tmp/ , в файлах, начинающихся с префикса chip .

Если вы хотите повторить весь процесс ввода в эксплуатацию с самого начала, вам придётся удалить эти файлы, выполнив следующую команду: 

$ rm /tmp/chip*

5. Введите устройство в эксплуатацию.

Примечание : Этот шаг будет успешно выполнен только в том случае, если вы уже настроили свой проект в консоли разработчика Google Home.

Nest Hub

Для подключения вашего устройства к сети Matter Fabric необходим хаб. Это устройство Google Nest, например, Nest Hub (2-го поколения), поддерживающее Matter и выступающее в качестве пограничного маршрутизатора для устройств с поддержкой Thread, а также в качестве локального пути обработки запросов Smart Home.

Обратитесь к этому списку , чтобы узнать, какие хабы поддерживают Matter.

Перед началом процесса ввода в эксплуатацию убедитесь в следующем:

  • Ваш хаб сопряжен с той же учетной записью Google, которую вы использовали для входа в консоль Google Home.
  • Ваш центральный узел подключен к той же сети Wi-Fi, что и компьютер, который вы используете для запуска устройства Virtual Matter.
  • Ваш центральный узел находится в той же структуре, которую вы используете в приложении Google Home. (На графике Google Home «дом» обозначает вашу структуру).

Получите QR-код

Для процесса ввода в эксплуатацию необходима информация о подключении к Matter, предоставленная в виде QR-кода. Изучите вывод консоли приложения Matter, который будет содержать ссылку на QR-код, необходимый для ввода в эксплуатацию.

Выполните операцию ввода в эксплуатацию.

  1. Откройте приложение Google Home.
  2. Нажмите на значок «+» в верхнем левом углу.
  3. Нажмите «Настроить устройство» .
  4. Нажмите «Новое устройство» .
  5. Выберите свой дом и нажмите «Далее» .
  6. Приложение Google Home выполнит поиск вашего устройства. Если появится сообщение «Устройство Matter найдено...», нажмите «Да». В противном случае нажмите «Настроить другое устройство» , затем выберите устройство Matter из списка устройств.
  7. Наведите камеру на QR-код вашего устройства или на QR-код, сгенерированный на веб-сайте.
  8. Продолжите процесс сопряжения, как указано в инструкции к приложению Google Home.

После выполнения этих шагов виртуальное устройство Matter должно быть успешно введено в эксплуатацию и отобразиться в виде нового значка в приложении Google Home.

Парная лампочка в приложении Google Home

Поиск неисправностей

Процесс ввода в эксплуатацию завершается с ошибкой "Проблема с подключением" или "Не удалось связаться с Google".

  • Убедитесь, что вы создали проект с правильной комбинацией VID/PID в консоли Google Home и что у вас нет других проектов, использующих ту же комбинацию VID/PID.

Процесс ввода в эксплуатацию завершается с ошибкой после длительного периода сканирования устройства.

6. Управление устройством

После того как ваше устройство с поддержкой Matter будет успешно введено в эксплуатацию и отобразится в приложении Google Home как лампочка, вы можете проверить управление устройством различными способами:

  • Используя Google Ассистент.
  • Используя приложение Google Home.

Google Ассистент

Используйте Google Ассистент на своем телефоне или хабе, чтобы переключать состояние устройства с помощью голосовых команд, например, скажите: «Привет, Google, включи свет».

Дополнительные примеры команд можно найти в разделе « Управление устройствами умного дома с помощью голосовых команд» в приложении Google Home .

Приложение Google Home

Вы можете нажать на кнопки «Вкл. » и «Выкл. » рядом со значком лампочки в приложении Google Home.

Дополнительную информацию см. в разделе « Управление устройствами умного дома, добавленными в приложение Google Home» в статье «Управление устройствами умного дома, добавленными в приложение Google Home» .

7. Поздравляем!

Вы успешно создали своё первое устройство Matter. Замечательно!

В этом практическом занятии вы научились:

  • Установите среду разработки Matter.
  • Создайте и запустите виртуальное устройство Matter.
  • Настраивайте и управляйте своим виртуальным устройством из Google Home.

Чтобы узнать больше о материи, изучите следующие источники: