Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/wb-mirta/core

🚀 Unleash the power of wb-rules with Mirta Framework
https://github.com/wb-mirta/core

home-automation iot mqtt smart-home wb-rules wirenboard

Last synced: 4 months ago
JSON representation

🚀 Unleash the power of wb-rules with Mirta Framework

Awesome Lists containing this project

README 

          
# Mirta Core



[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/wb-mirta/core/build.yml?branch=latest&logo=github&style=flat-square)](https://github.com/wb-mirta/core/actions/workflows/build.yml)

[![GitHub Repo Stars](https://img.shields.io/github/stars/wb-mirta/core?color=594ae2&style=flat-square&logo=github)](https://github.com/wb-mirta/core/stargazers)

[![GitHub Last Commit](https://img.shields.io/github/last-commit/wb-mirta/core?color=594ae2&style=flat-square&logo=github)](https://github.com/wb-mirta/core)

[![NPM Downloads](https://img.shields.io/npm/dm/mirta?style=flat-square&logo=npm)](https://npmjs.com/package/mirta)

[![pkg.pr.new](https://pkg.pr.new/badge/wb-mirta/core?style=flat-square&color=555)](https://pkg.pr.new/~/wb-mirta/core)



Создавайте автоматизации без лишних сложностей — с подсказками, автодополнением, юнит-тестами и современным синтаксисом. Здесь можно запрограммировать умный дом на JavaScript и TypeScript.



Перед началом ознакомьтесь с [основами правил wb-rules](https://github.com/wirenboard/wb-rules#readme).



**Оглавление**

- [Что такое Мирта?](#что-такое-мирта)

- [Ключевые возможности](#ключевые-возможности)

- [Перед началом](#перед-началом)

- [Быстрый старт](#быстрый-старт)

- [Работа с JS и TS](#работа-с-javascript-и-typescript)

- [Миграция на TypeScript](#миграция-на-typescript)

- [Подготовка рабочего пространства](#подготовка-рабочего-пространства)

- [Современный синтаксис](#современный-синтаксис)

- [Поддержка проекта](#поддержка-проекта)

- [Исходный код фреймворка](#исходный-код-фреймворка)

- [История создания](#история-создания)

- [Полезные ссылки](#полезные-ссылки)



## Что такое Мирта?



**Мирта** — это **готовая среда разработки** для создания сценариев автоматизации на контроллерах [компании Wiren Board](https://wirenboard.com/) с использованием правил `wb-rules`.



Система позволяет стандартизировать разработку, снизить сложность и сэкономить ресурсы.



> Вы пишете [те же правила](https://github.com/wirenboard/wb-rules#readme), что и раньше.  

> Только теперь — с комфортом и полным контролем над кодом.



Цель данного фреймворка — **не добавить ещё один слой для изучения**, а **убрать всю рутину**:

- Настройка TypeScript, ESLint, Rollup — уже сделана

- Подсветка конструкций wb-rules, автодополнение, проверка ошибок — работают «из коробки» *

- Юнит-тесты и имитация контроллера — доступны сразу *



Вы можете начать с JavaScript и постепенно переходить на TypeScript.  



Здесь поддерживаются `let` и `const`, а также функции-стрелки — это когда пишут `let sum = (a, b) => a + b`.



\* При установке рекомендованных системой плагинов ESLint и Vitest для VSCode.



## Ключевые возможности



- **Мастер настройки** — задаёт вопросы и формирует проект по вашим предпочтениям

- **Гибридный режим JS/TS** — поддержка `.js` и `.ts` в одном проекте

- **ESNext → ES5** — пишите на современном JavaScript / TypeScript, получайте совместимый код

- **Tree-shaking** — незадействованный код удаляется после сборки и не попадает на контроллер

- **Переменные окружения** — отделяйте чувствительную информацию от кода

- **Пользовательские события** — гибкая связь между различными частями кода

- **Хранилище состояний** — современная альтернатива `module.static` и `global`

- **Юнит-тесты и моки** — проверяйте логику без контроллера

- **Поддержка NPM** — быстро и легко подключайте модули wb-rules к проекту, публикуйте собственные

- **Готовые CI-воркфлоу для GitHub** — тесты и сборка запускаются автоматически при коммите



## Перед началом



Ваш проект автоматизации умного дома разрабатывается и тестируется на локальном компьютере, с использованием любого подходящего редактора кода (рекомендуется [Visual Studio Code](https://code.visualstudio.com/download)).



Работа с Миртой возможна на Windows, Linux и macOS.



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

- [Node.js](https://nodejs.org/en/download) в варианте LTS (не ниже 24.12.0),

- менеджер пакетов `pnpm`



Подробная инструкция по установке вышеперечисленного представлена [в статье](https://dzen.ru/a/aIiGBETD13y-r0V0) на Дзене.



Контроллер Wiren Board подключается на финальном этапе, для отправки на него готового кода из папки `dist/es5`.  

Благодаря тому, что код пишется в соответствии с самым современным стандартом ESNext, в будущем возможен бесшовный переход на обновлённый движок, работающий на чистом NodeJs.



## Быстрый старт



Принцип создания проекта подробно показан [в обучающем видео](https://dzen.ru/video/watch/68896f973774640db979065b).



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



```bash

pnpm create mirta

```

Мастер задаст несколько вопросов и создаст проект с нужной конфигурацией.



Если нужна определённая версия Мирты, укажите её явным образом:

```bash

pnpm create mirta@latest # Актуальная

pnpm create mirta@0.4.11 # Фиксированная

```



Откройте проект:

```bash

code ./wb-rules-mirta # Замените на название вашего проекта

```



Запустите сборку из терминала VSCode:

```bash

pnpm build

```



Проверьте, что произойдёт при первом деплое:

```bash

pnpm wb:deploy --dry-run

```



Если всё в порядке, отправьте изменения на контроллер:

```bash

pnpm wb:deploy

```



## Работа с JavaScript и TypeScript



Мирта поддерживает гибридный режим: файлы `.js` и `.ts` обрабатываются одинаково:

- Современный синтаксис ESNext

- Переменные окружения

- Tree-Shaking

- Юнит-тесты



> 💡 Подсказки и автодополнение работают даже в .js-файлах — благодаря JSDoc и типам из `@mirta/globals`.



## Миграция на TypeScript



Постепенно переводите код JavaScript на TypeScript:



- Меняйте расширение файлов с `.js` на `.ts` или создавайте рядом одноимённый файл с расширением `.ts`.

- Пользуйтесь преимуществами строгих типов и улучшенной типизацией, а также всеми возможностями Мирты.



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



Наглядный пример доступен в формате [видеоруководства](https://dzen.ru/video/watch/68b39c150c5cde33febb375c).



## Подготовка рабочего пространства



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



```

/mnt/data/etc/wb-rules         → src/wb-rules

/mnt/data/etc/wb-rules-modules → src/wb-rules-modules

```



При передаче готового кода на контроллер выполняется очистка целевых директорий.  

Подробнее — [в статье о деплое](https://dzen.ru/a/aWzbtighulUT7AQA)



## Современный синтаксис



Фреймворк Мирта поддерживает только современный синтаксис ESNext.  

Во время сборки система автоматически преобразует ваш код в формат ES5, совместимый с контроллерами Wiren Board.



Зачем нужен переход на ESNext?



- Современные стандарты: повышают качество и читаемость кода

- Поддержка статического анализа: помогает выявить ошибки на раннем этапе

- Tree-Shaking: удаляет неиспользуемый код, оптимизируя итоговую сборку



Прежде вы использовали классический синтаксис CommonJS (импорт через `require` и экспорт через объект `exports`). Необходимо пересмотреть свой код и заменить эти конструкции на современные аналоги:



- Используйте `import` вместо `require`

- Используйте `export` вместо `exports`



Корректный экспорт в файле модуля:



```js

// src/wb-rules-modules/my-module.js

export function hello(text) {

  log('Hello from module, {}', text)

}



export const answer = 42

```

Импорт в файле сценария, куда подключается модуль:



```js

// src/wb-rules/my-script.js

import { hello, answer } from '#wbm/my-module'



hello('world')

log('The answer is {}', answer)

```

⚠️ **Внимание!** Используйте исключительно именованный экспорт — в настоящее время контроллеры Wiren Board не поддерживают код, генерируемый экспортом по умолчанию (`export default`):



```js

// В файле модуля: НЕ поддерживается!

export default function(text) {

  log('Hello from module, {}', text)

}



// В файле сценария: НЕ сработает!

import hello from '#wbm/my-module'

```



## Поддержка проекта



Мирта — это **открытый проект**, распространяемый по лицензии [Unlicense](https://github.com/wb-mirta/core?tab=Unlicense-1-ov-file).  

Фреймворк существует благодаря энтузиазму автора и поддержке сообщества.



Ваша помощь — это не просто донат. Это **вклад в развитие инструмента**, которым пользуются многие разработчики.



🔹 **Платные подписчики** получают доступ к закрытому чату **Mirta Guild** в Telegram — месту, где обсуждают сложные сценарии, делятся идеями и помогают друг другу.  

🔹 **Каждый донат** позволяет автору осредоточиться на улучшениях, новых возможностях, проработке интеграций и документации.



Вместе мы делаем автоматизации проще — для всех.



[![Поддержать через Boosty](https://img.shields.io/badge/%D0%9F%D0%BE%D0%B4%D0%B4%D0%B5%D1%80%D0%B6%D0%B0%D1%82%D1%8C-Boosty-F15F2C?style=for-the-badge

)](https://boosty.to/wihome)



Также сказать «Спасибо» можно через сервис для приёма безналичных чаевых от Т‑Банка и CloudPayments:



[![Поддержать через CloudTips](https://img.shields.io/badge/%D0%9F%D0%BE%D0%B4%D0%B4%D0%B5%D1%80%D0%B6%D0%B0%D1%82%D1%8C-Cloud_Tips-blue?style=for-the-badge

)](https://pay.cloudtips.ru/p/58512cca)



## Исходный код фреймворка



Чтобы создавать проекты с использованием фреймворка, не требуется вникать в его исходные коды. Однако, все они здесь - проект структурирован по принципу монорепозитория, с разделением на пакеты (см. каталог `packages`). Всё открыто для ваших идей и предложений.



Пакеты Мирты можно условно разделить на два типа (соответственно секциям файла `package.json`):

- `dependencies` - код с возможностью использования на контроллере,

- `devDependencies` - инструменты этапа разработки, которые остаются на локальном компьютере.



К первому типу относятся различные готовые функции (например, реализация debounce и throttle).

При импорте таких конструкций, сборщик Rollup автоматически создаст соответствующий файл в следующем расположении:



```

dist/es5/wb-rules-modules/packages/package-name

```

Ко второму - наборы конфигураций по умолчанию, определения типов для подсветки кода, инструменты вроде Rollup, ESLint, Vitest и т.п.



Если же вы стремитесь понять глубинные принципы проекта, существует [серия статей](https://dzen.ru/suite/5a7ecf61-ac80-4d7d-abe2-ecebd73b6ef4), где его ранний прототип собирается без разделения на пакеты, вручную и с подробным объяснением каждой строки.



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



## История создания



Идея [шаблона для быстрого старта](https://github.com/wihome-dev/wb-rules-typescript) разработки правил на TypeScript начала активно развиваться и стало понятно, что формат репозитория «всё в одном» слишком сложен для восприятия, а его модернизация без версионирования приводит к значительным изменениям.



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



## Полезные ссылки



- [wb-rules 2.0](https://github.com/wirenboard/wb-rules) — движок правил

- [Блог на Boosty](https://boosty.to/wihome) — разработка Мирты, ранний доступ

- [Канал на Дзене](https://dzen.ru/wihome) — видео и статьи про автоматизации