Фундамент безопасности заложен и теперь пришло время узнать о профессиональном подходе к разработке сценариев управления умным домом с помощью правил на языке JavaScript.
О том, что из себя представляет движок правил wb-rules, можно прочесть в статье компании Wirenboard:
Существует множество способов ввода правил. Например, через веб-интерфейс или прямой доступ к каталогам посредством удалённого подключения. В большинстве случаев, их будет достаточно.
Предполагается, что дорогой читатель уже успел ознакомиться с официальными обучающими видео:
Мы же пойдём по более сложному пути. Так получится меньше нагрузки на внутреннюю память контроллера и удастся по достоинству оценить всю красоту и мощь программирования - ведь часть инструментов предполагает интенсивную работу с файловой системой и тянет из интернета сотни мегабайт вспомогательного кода, который используется только на этапе разработки.
Создадим проект на своём компьютере, а для работы с кодами используем популярный редактор Visual Studio Code (VS Code). Синхронизацию с контроллером будем выполнять специальной утилитой командной строки, которая переносит на целевое устройство только отличающиеся фрагменты файлов.
Постепенно усложним задачу: добавим типизацию TypeScript и подсказки конструкций wb-rules. Познакомимся со средствами автоматического форматирования кода и освоим работу с системой контроля версий для возможности командной работы: научимся вести историю изменений, как это реализовано в больших компаниях.
Разумеется, весь рассказ не поместится в одной-единственной статье, поэтому подписывайтесь, чтобы не пропустить выход продолжения!
ℹ️ Примечание: в примерах упоминается учётная запись username. Вместо этого слова нужно подставлять имя пользователя со своего контроллера. То же самое справедливо и по отношению к IP-адресу 10.200.200.1 - при подготовке материалов статьи, подключение выполнялось через отладочный порт.
Все этапы статьи последовательно выполнялись на контроллере Wirenboard 8.5, а для подключений, как и прежде, использовался стандартный Терминал Windows.
Подготовка к работе
Многие утилиты командной строки требуют наличия на компьютере установленной Node.js. Для загрузки следует выбрать версию LTS, как наиболее стабильную и предсказуемую в поведении:
Инструменты собираются разработчиками в так называемые пакеты и хранятся в публичных репозиториях. Для работы с ними будем использовать Yarn, как более продвинутую систему управления зависимостями, по сравнению с NPM. После установки Node.js, в терминале или командной строке нужно выполнить команду
npm install -g yarn
Комфортный и гибко настраиваемый редактор кода - это уже половина успеха. Дистрибутив Visual Studio Code доступен для Windows, Linux и macOS. Загрузить можно с официального сайта:
При первом запуске появится вот такое окно:
Переключить язык интерфейса на русский можно путём вызова палитры команд, через сочетание Ctrl + Shift + P и ввод команды Configure Display Language.
Однако лучше остаться на английском. Дело в том, что большинство инструкций и примеров в сети создаются мировым сообществом и ориентированы именно на этот язык, в дальнейшем будет сложно проводить параллели.
Создание проекта
Откроем Проводник Windows и выберем расположение для будущего проекта. Обычно такие вещи размещают на отдельном диске - чем короче путь, тем проще его набирать в различных командах. Остановимся на варианте
D:\repos\wirenboard
Здесь repos - каталог, который будет содержать все наши проекты. Название является сокращением от repositories. В терминологии систем контроля версий, репозиториями называют папки, изменения в которых отслеживаются независимо друг от друга. Ведя несколько разных проектов, в любом из них можно посмотреть, что было раньше, вернуться к одному из прошлых состояний или скопировать старый код. Но об этом позже.
В качестве первого репозитория, создадим папку для проекта под названием wirenboard. Перейдём внутрь неё и, удерживая зажатой клавишу Shift, кликнем правой кнопкой мышки. В появившемся меню выберем строчку «Открыть с помощью Code».
Если опция по каким-то причинам отсутствует в списке, запустим Code вручную и в меню «File» кликнем пункт «Open Folder» (либо последовательно прожмём комбинации клавиш Ctrl + K, Ctrl + O), после чего выберем целью созданную папку wirenboard.
ℹ️ Примечание: обратите внимание на строчку меню «Открыть окно PowerShell здесь». Она нам ещё не раз пригодится - избавляет от необходимости пользоваться командой cd для перемещения по каталогам.
При открытии нового расположения, редактор спросит, доверяем ли мы авторам файлов в этой папке? Ответим утвердительно.
Экран разделится на две части - в левой обнаружим панель инструментов и пока что пустую область со списком файлов и каталогов проекта, Explorer (открывается по сочетанию клавиш Ctrl + Shift + E).
Щёлкнув правой кнопкой мышки в незанятой части Explorer, добавим в проект папку .vscode и внутрь поместим файл settings.json, в котором обяжем редактор использовать способ обозначения конца строки типа LF, используемый в Linux:
{
"files.eol": "\n"
}
Теперь все новые файлы в проекте будут создаваться с применением данной установки.
Внутренняя структура
В корень проекта будем складывать различные файлы настроек. И первый, самый главный из них - package.json, содержащий сведения о самом проекте, перечень всех используемых инструментов и их версий, а также заранее подготовленные команды для терминала.
Содержимое файла заполним таким образом:
{
"name": "wirenboard",
"version": "1.0.0",
"private": true,
"scripts": {
}
}
С name всё понятно, version установим в значение «1.0.0», а обязательный для нас атрибут private - в true.
Наибольший интерес представляет секция scripts, позже сюда запишем команду для синхронизации состояния контроллера Wirenboard. Команда длинная, помнить и набирать её каждый раз в консоли быстро надоест.
Установка утилиты синхронизации
Репозиторий на рабочем компьютере всегда выступает «источником истины» и местом хранения актуальных кодов, поэтому за исключением первичной инициализации проекта, изменения в файлах будем передавать строго в одну сторону - из компьютера в контроллер. Такой процесс в профессиональных кругах называют деплоем (от англ. deploy - размещение, развёртывание).
ℹ️ Совет из мемов: никогда не деплойте по пятницам и перед праздниками.
Для осуществления задумки понадобится утилита rsync. Но вот незадача - она доступна только в UNIX-подобных системах. Работая в Windows, будем вызывать её через подсистему Windows для Linux, о которой рассказывалось ранее:
Откроем терминал WSL и установим rsync, выполнив следующие команды
sudo apt-get update
sudo apt-get install rsync
При работе с контроллером, rsync устанавливает соединение по SSH. А это плавно подводит нас к следующей теме - правильной настройке подключения.
Особенности подключения к контроллеру
В одной из прошлых статей мы рассмотрели, как закрыть root-доступ по SSH и создать на контроллере учётную запись обычного пользователя с возможностью запроса повышенных привилегий:
Если ваше подключение надёжно защищено при помощи ключевого носителя, то чтобы rsync могла обращаться к контроллеру, потребуется монтировать токен в подсистему WSL (подробнее о процессе).
При этом токен будет невидим для Windows, а без него станет невозможным прямое подключение к контроллеру. Работая в Терминале Windows, можно обхитрить систему и в профиле подключения добавить перед вызовом ssh словечко wsl:
wsl ssh -I /usr/lib/librtpkcs11ecp.so username@10.200.200.1
Теперь соединение устанавливается не из Windows, а из подсистемы Windows для Linux, поэтому и путь к библиотеке для работы с токеном внутренний, «линуксовый».
ℹ️ Примечание: чтобы ключевой носитель не отсоединялся от WSL в процессе работы, терминал подсистемы должен оставаться открытым в отдельном окне.
Первичная инициализация проекта
Вполне возможно, что на вашем контроллере уже имеются какие-то наработки в правилах wb-rules.
🟥 Критически важно! Чтобы на следующих этапах не уничтожить свои шедевры первым же деплоем, воспользуемся утилитой rsync и загрузим их с контроллера к себе в проект. При деплое всё, что не соответствует состоянию проекта на компьютере, будет автоматически удаляться из расположения сценариев и модулей.
➡️ На заметку: если перед запуском сомневаетесь в том, что сделает rsync, не играйте с огнём, добавьте два ключа:
--dry-run --itemize-changes
Таким образом вы убедитесь, что по крайней мере, не собираетесь снести половину файловой системы на контроллере или рабочем компьютере.
Ключ --dry-run переводит rsync в режим имитации процесса и не производит никаких реальных операций с файлами и директориями, а --itemize-changes выполняет перечисление запланированных действий.
Даже если контроллер только из коробки и на нём нет никаких правил, всё равно выполните все шаги, чтобы воссоздать структуру проекта и проверить функционирование утилиты.
Откроем PowerShell и перейдём в каталог проекта:
cd D:\repos\wirenboard
затем выполним следующую команду (вариант для случая, когда доступ к SSH осуществляется по паролю):
wsl rsync -rlptzv --progress --exclude='alarms.conf' 'username@10.200.200.1:/mnt/data/etc/wb-rules*' "`$(wslpath -a '$PWD')/src"
ℹ️ Примечание: если для подключения применяется ключевой носитель, понадобится добавить ещё один параметр, задействующий библиотеку PKCS#11:
wsl rsync -e 'ssh -I /usr/lib/librtpkcs11ecp.so' -rlptzv --progress --exclude='alarms.conf' 'username@10.200.200.1:/mnt/data/etc/wb-rules*' "`$(wslpath -a '$PWD')/src"
Файлик alarms.conf не относится к процессам разработки, поэтому его мы всячески игнорируем и аккуратно обходим утилитой синхронизации. Хочется верить, что однажды создатели контроллера переместят его в более подходящее место.
После выполнения команды заглянем в проект, открытый в VS Code. Содержимое Explorer дополнится каталогом src, в котором появятся папки wb-rules и wb-rules-modules, а в них будут все файлы, которые обнаружились на контроллере.
🟥 Осторожно! Если файлы не появились, значит что-то пошло не так. Чтобы сохранить существующие правила, не переходите к следующим этапам, пока не разберётесь в причинах.
Все дальнейшие разработки будем вести в этих двух каталогах проекта - wb-rules и wb-rules-modules.
ℹ️ На заметку: распробовав возможности утилиты rsync, можно приспособить её и для других дел. Например, создавать резервные копии конфигураций и восстанавливать их при необходимости.
Настройка прав доступа в контроллере
Если прежде проводился тюнинг безопасности и теперь подключения по SSH к контроллеру происходят от имени обычного пользователя, понадобится выполнить ещё несколько настроек.
Дело в том, что изначально каталоги wb-rules и wb-rules-modules принадлежат пользователю root и его группе root, что не позволит записывать в них «посторонним». Первая же попытка деплоя завершится ошибкой.
Чтобы это исправить, подключимся к контроллеру и создадим группу developers:
sudo groupadd developers
Затем в созданную группу добавим нашего пользователя:
sudo usermod -aG developers username
Наконец, последовательно выполним несколько команд, позволяя разработчикам редактировать содержимое каталогов с правилами и модулями:
sudo find /mnt/data/etc/wb-rules* -not -path '*/alarms.conf' -exec chgrp developers {} +
sudo find /mnt/data/etc/wb-rules* -not -path '*/alarms.conf' -exec chmod g+rw {} +
🟥 Важно! При копировании этих команд не потеряйте фигурные скобки и плюсики в конце строки. Скобки используются утилитой find для подстановки найденных соответствий, а плюсик осуществляет поочерёдное выполнение указанного в -exec действия для каждого результата в отдельности. Такая уж она, консольная магия.
Добавление команды синхронизации
Вернёмся к редактированию проекта в VS Code. В созданном ранее файле package.json найдём секцию scripts и добавим туда команду с названием deploy, заключённую в кавычки (не забудьте поменять username и IP-адрес на те, что используются вашим оборудованием):
"deploy": "wsl rsync -rltzvgO --progress --delete --exclude='alarms.conf' --groupmap=*:developers src/* 'username@10.200.200.1:/mnt/data/etc/'"
Рассмотрим команду подробнее: через wsl вызывается команда rsync, которой передаётся набор флагов -rltzvgO (о них можно прочитать в руководстве к утилите rsync).
Остальные параметры:
--progress отображает в консоли результат выполнения;
--delete очищает целевое расположение от файлов, которые были удалены в репозитории;
--exclude защищает от уничтожения файл с настройками тревожных уведомлений alarms.conf (он остаётся на сервере и не имеет отношения к разработке),
--groupmap устанавливает переданным на контроллер файлам и папкам группу developers.
ℹ️ Примечание: если работа ведётся с использованием ключевого носителя, понадобится добавить ещё один параметр, задействующий библиотеку PKCS#11:
"deploy": "wsl rsync -e 'ssh -I /usr/lib/librtpkcs11ecp.so' -rltzvgO --progress --delete --exclude='alarms.conf' --groupmap=*:developers src/* 'username@10.200.200.1:/mnt/data/etc/'"
Теперь изменения в проекте можно передавать на контроллер, вызывая прямо в терминале VS Code короткую строчку
yarn deploy
Удобно, не правда ли?
Послесловие
Сегодня мы настроили источником синхронизации папку src, однако в дальнейшем, после начала работы с транспайлером, разделим код на исходный и итоговый, готовый к переносу на контроллер. Читать продолжение: