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

1. Введение

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

Чтобы узнать о Matter, посетите Центр разработчиков Google Home или веб-сайт Connectivity Standards Alliance .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Гнездо Хаб

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

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

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

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

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

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

Провести комиссионную операцию

  1. Откройте приложение Google Home.
  2. Нажмите + в левом верхнем углу.
  3. Нажмите «Настроить устройство» .
  4. Нажмите «Новое устройство» .
  5. Выберите свой дом и нажмите «Далее» .
  6. Приложение Google Home выполняет поиск вашего устройства. При появлении сообщения «Обнаружено важное устройство...» нажмите «Да». В противном случае коснитесь «Настроить другое устройство» и выберите «Материальное устройство» из списка устройств.
  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 Assistant на своем телефоне или концентраторе, чтобы переключать состояние устройства с помощью голосовых команд, например «Окей, Google, включи мой свет».

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

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

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

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

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

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

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

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

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

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

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