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

1. Введение

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

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

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

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

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

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

Мы будем использовать ранее настроенный контейнер Docker на хост-компьютере Linux. Этот контейнер включает в себя все необходимые зависимости для создания и запуска виртуального устройства Matter.

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

Компьютеры Windows и MacOS в настоящее время не поддерживаются этой установкой Docker. Вы можете вручную установить и собрать Matter на MacOS или Windows.

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

Настроить докер

  1. Установите Docker Engine (не используйте Docker Desktop).
  2. Загрузите образ Docker из Docker Hub. В окне терминала запустите:
    user@host> docker pull us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest
    Выполнение этой операции может занять несколько минут.
  3. Запустите контейнер Docker:
    user@host> xhost local:1000
user@host> docker run -it --ipc=host --net=host -e DISPLAY --name matter-container us-docker.pkg.dev/nest-matter/docker-repo/virtual-device-image:latest

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

Environment looks good, you are ready to go!
$

Давайте разберемся с командой 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), а не как фоновый процесс.

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

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

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

Всякий раз, когда вы запускаете команду 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

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

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

Первоначальная настройка Материи

Когда ваш терминал откроется, он уже будет в клонированном репозитории Matter по адресу ~/connectedhomeip . Никаких дополнительных шагов по настройке Matter не требуется.

Делитесь файлами между хостом и контейнером

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

Запустите свой контейнер с дополнительным аргументом --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. На странице «Управление проектами» нажмите «Создать проект» .
    Центр разработчиков Google Home
  2. На странице «Начало работы» нажмите «Создать проект» .

  1. Введите уникальное имя проекта и нажмите «Создать новый проект» .Диалог создания нового проекта
  2. Нажмите + Добавить интеграцию , чтобы перейти на экран «Ресурсы Matter», где вы можете просмотреть документацию по разработке Matter и прочитать о некоторых инструментах.
  3. Когда вы будете готовы продолжить, нажмите «Далее: разработка» , чтобы отобразить страницу контрольного списка Matter .
  4. Нажмите Далее: Настройка
  5. На странице «Настройка» введите название продукта .
  6. Щелкните Выбрать тип устройства и выберите тип устройства в раскрывающемся меню (в данном случае Light ).
  7. В Vendor ID (VID) выберите Test VID и выберите 0xFFF1 в раскрывающемся меню Test VID. В поле Product ID (PID) введите 0x8000 и нажмите «Сохранить и продолжить» , а затем нажмите «Сохранить» на следующей странице.
    Настройка проекта
  8. Теперь вы увидите одно устройство Matter в разделе интеграции с Matter. Интеграция материи
  9. Перезагрузите свой концентратор, чтобы убедиться, что он получает самую последнюю конфигурацию проекта интеграции 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. Контроллер виртуального устройства

Контроллер виртуальных устройств — это автономное приложение, которое предоставляет графический пользовательский интерфейс для управления и отображения состояний ваших виртуальных устройств Matter. Он использует клиент RPC для связи с устройствами Matter, подключенными к вашей среде разработки.

Контроллер виртуального устройства

Контроллер виртуального устройства обеспечивает визуальное представление вашего виртуального устройства.

Вы можете взаимодействовать с виртуальным устройством через графический интерфейс пользователя (GUI) Virtual Device Controller. Ваши изменения в графическом интерфейсе влияют на базовую модель данных. В настоящее время контроллер виртуального устройства поддерживает тип устройства с регулируемой яркостью света.

Установите контроллер виртуального устройства

Контроллер виртуальных устройств предустановлен в контейнере Docker Ubuntu LTS 20.04.

Запустите контроллер виртуального устройства

Создайте второй экземпляр сеанса терминала:

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

Запустите Virtual Device Controller, указав сетевой сокет, который будет использоваться для связи с виртуальным устройством:

  $ cd ~/matter-virtual-device-gui/
  $ electron main.js --s=localhost:33000 --no-sandbox

Если вы запустите контроллер без каких-либо аргументов, по умолчанию он будет использовать параметр сетевого сокета с использованием локального порта 33000. Как только контроллер сможет подключиться к виртуальному устройству, он отобразит экран, показывающий состояние вашего устройства:

Графический пользовательский интерфейс виртуального устройства

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

Приложение Virtual Device Controller также можно использовать для извлечения QR-кода в процессе ввода устройства в эксплуатацию. Щелкните значок QR-кода рядом с изображением устройства, чтобы отобразить QR-код для этого устройства:

QR код

Вы можете использовать этот QR-код для ввода устройства в эксплуатацию.

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

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

Гнездо Хаб

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

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

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

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

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

Для процесса ввода в эксплуатацию требуется информация о подключении Matter, предоставляемая с помощью QR-кода. Вы можете получить QR-код для своего виртуального устройства в Virtual Device Controller.

Выполнить комиссионную операцию

  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 и что у вас нет других проектов, использующих такую ​​же комбинацию VID/PID.

Сбой ввода в эксплуатацию после «Сканирования устройства» в течение длительного периода

7. Управляйте устройством

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

  • Использование Google Ассистента.
  • С помощью приложения Google Home.
  • Использование графического интерфейса виртуального устройства.

Google Ассистент

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

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

Приложение Google Главная

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

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

Графический интерфейс виртуального устройства

Вы можете взаимодействовать с графическим интерфейсом виртуального устройства, чтобы изменить состояние устройства. Независимо от того, управляете ли вы виртуальным устройством с помощью контроллера виртуального устройства, приложения Google Home на своем телефоне или с помощью концентратора, все эти интерфейсы будут отражать текущее состояние виртуального устройства.

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

Вы успешно создали свое первое устройство Matter. Потрясающий!

В этой лаборатории кода вы узнали, как:

  • Установите среду разработки Matter, используя предварительно упакованный образ Docker.
  • Создайте и запустите виртуальное устройство Matter.
  • Ввод в эксплуатацию и управление вашим виртуальным устройством из Google Home.

Чтобы узнать больше о Материи, изучите эти ссылки: