@gregory-gost/node-red-contrib-gost-yandex-alice 0.1.2

Палитра управления устройствами Yandex Alice для Node-RED

npm install @gregory-gost/node-red-contrib-gost-yandex-alice

GOST Yandex Virtual for Node-RED

RU · EN

RU

Сайт проекта

@gregory-gost/node-red-contrib-gost-yandex-alice добавляет в Node-RED ноды для создания виртуальных устройств и управления ими голосом через Алису или через приложение "Умный дом"

Требования

• Node-RED 4 или новее.
• Node.js 24 или новее.
• Учетная запись в Яндексе

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

1. В главном меню (☰) выберите «Управление палитрой» (Manage palette), затем вкладку «Установить» (Install). Найдите @gregory-gost/node-red-contrib-gost-yandex-alice и установите модуль.
2. Добавьте на рабочую область нужную *-input или *-output-ноду и откройте её настройки.
3. В поле конфигурации создайте ноду соответствующей возможности или свойства: On/Off, Range, Mode, Color, Video Stream или Property.
4. В настройках этой ноды создайте device-node, выберите тип устройства и заполните его сведения.
5. В настройках устройства создайте nr-service-node, пройдите авторизацию OAuth и сохраните его.
6. Сохраните связанные ноды, добавьте при необходимости парную *-input или *-output-ноду, разверните поток и передайте начальное состояние на *-input.

Концепция

nr-service-node
└── device-node
    └── config-нода возможности или свойства
        ├── *-output → ваш поток
        └── *-input  ← состояние или ответ вашего потока

Роли нод

• Сервис (nr-service-node) хранит авторизацию и связывает устройства потока с сервисом.
• Устройство (device-node) представляет один объект в Умном доме: например, лампу, розетку или датчик. Здесь задаются его тип, имя и другие сведения.
• Возможность (config-нода) описывает то, чем можно управлять: On/Off, Toggle, Range, Mode, Color или Video Stream.
• Свойство (config-нода Property) передаёт показания и события — например, температуру, влажность или открытие двери. Свойства не принимают команды.
• *-output отправляет в ваш поток команды и запросы состояния.
• *-input принимает из вашего потока состояние устройства и ответы на команды или запросы.

Несколько input- и output-нод

К одной config-ноде можно подключить несколько одинаковых *-input и *-output-нод. *-output не выбирает одну из веток: каждую команду и запрос состояния, который требуется передать в поток, модуль отправляет во все подключённые output-ноды.

При строгом завершении команды её итог определяет первый обработанный коррелированный ответ; последующие ответы уже не влияют на результат команды. Обычные сообщения из всех *-input-нод обновляют общий кэш состояния, поэтому сохранённым станет значение, поступившее последним. Запрос состояния, отправленный в поток, также должен получить только один ответ.

Используйте несколько output-нод только для намеренного широковещания, например для наблюдения или согласованных действий. Для одного физического устройства лучше оставить один рабочий *-output и один *-input: ветвите поток после output-ноды, а значения и ответы сводите перед input-нодой. Так независимые задержки веток не приведут к устаревшему состоянию или непредсказуемому результату команды.

Возможности(Capability) устройства

• On/Off — включает и выключает устройство.
• Toggle — переключает отдельную функцию: подсветку, паузу, блокировку управления, поддержание тепла, отключение звука или вращение.
• Range — задаёт числовое значение: яркость, громкость, температуру, влажность, степень открытия или канал.
• Mode — выбирает режим из заданного списка: например, программу работы, нагрев или скорость вентилятора.
• Color — меняет цвет освещения: RGB/HSV, цветовую температуру или готовую сцену.
• Video Stream — передаёт для камеры ссылку на HLS-видеопоток.

Свойства(Property) устройства

• Float — передаёт числовое показание с единицей измерения: температуру, влажность, освещённость, давление, мощность, заряд или показание счётчика.
• Event — сообщает о событии или состоянии: открытии, движении, нажатии кнопки, дыме, утечке воды и других событиях датчика.

Свойства только передают информацию о состоянии и не принимают команды.

Выбор типа устройства и сочетание возможностей

Строгой таблицы соответствия между типом устройства и его функциями нет. Выберите в device-node наиболее близкий тип и добавляйте только те возможности и свойства, которые действительно есть у устройства: от этого зависят элементы управления в приложении и голосовые команды.

• Лампа, светильник, лента — On/Off; для диммирования добавьте Range с яркостью, для цветного света — Color.
• Розетка, выключатель, реле — On/Off; при наличии измерений добавьте Float: мощность, напряжение или показание счётчика электроэнергии.
• Термостат, кондиционер, увлажнитель, вентилятор — On/Off, Range для температуры или влажности, Mode для режима работы, Toggle для дополнительных функций и Float для показаний датчиков.
• Шторы, жалюзи, клапан — Range с параметром открытия.
• Камера — Video Stream.
• Датчик или счётчик — Float и Event: например, температура и влажность, движение, открытие, протечка или расход ресурса.
• Бытовая техника — обычно On/Off вместе с Mode для программы работы и Toggle для паузы, блокировки или поддержания тепла.

К одному устройству можно добавить несколько возможностей и свойств. Не дублируйте одну и ту же функцию: On/Off, Color и Video Stream добавляются по одному; несколько Toggle, Range и Mode допустимы, если они управляют разными параметрами. Свойства также должны описывать разные измерения или события.

On/Off — исключение: у одного устройства может быть только один. Если двухклавишный выключатель управляет двумя независимыми линиями, создайте два device-node с отдельными On/Off-нодами, например «Свет — клавиша 1» и «Свет — клавиша 2», и подключите их к одному nr-service-node.

Возможность(Capability) или свойство(Property) становятся доступными в Умном доме, когда к его config-ноде добавлен хотя бы один *-input или *-output.

Состояния и ответы

Обычное сообщение на *-input обновляет состояние. Передайте значение в msg.payload:

msg.payload = true
return msg

На запрос или команду *-output добавляет к сообщению msg.broker. Верните это же сообщение через соответствующую *-input-ноду, меняя только msg.payload. Не создавайте и не изменяйте msg.broker вручную.

if (msg.broker?.kind === 'query-reply') {
  msg.payload = true
}
return msg

Настройки возможностей и свойств

• Запрос состояния (retrievable) разрешает платформе запросить текущее значение.

• Публикация состояния (reportable) передаёт изменение состояния в сервис уведомлений.

• Отвечать последним известным состоянием включено по умолчанию. Запрос получает валидное значение из кэша без запуска потока. Если выключить эту опцию, запрос выйдет через *-output; поток должен вернуть актуальное значение через *-input.

• Считать команду выполненной после отправки включено по умолчанию. Если выключить опцию, модуль ждёт коррелированный ответ потока: верните через *-input запрошенное корректное значение до установленного срока. Как только оно получено, команда считается успешно выполненной (результат DONE).

  Для относительной команды Range, например «увеличить значение на 10», модуль также сообщит об успехе, но не изменит сохранённое последнее значение. Когда новое значение станет известно, передайте его обычным сообщением в *-input.

• Срок ответа задаётся отдельно для каждого запроса. Для команды он находится в msg.broker.deadline_at, для запроса состояния — в msg.payload.deadline_at. Верните состояние или подтверждение через *-input до этой отметки времени в UTC: общего фиксированного тайм-аута у модуля нет, а поздний ответ не принимается.

• Раздельные команды (split) доступны только для On/Off при выключенном retrievable и отправляют включение и выключение отдельными командами.

Свойства не поддерживают действий. Для Video Stream *-output передаёт get_stream; верните через *-input абсолютный URL HLS в msg.payload, сохранив msg.broker.

Документация Yandex Smart Home

• Типы устройств
• Умения устройств
• Свойства устройств

Независимость проекта

Это независимый проект: он не является продуктом Яндекса и не связан с компанией. Названия «Яндекс» и «Алиса» используются только чтобы пояснить совместимость модуля с сервисами Яндекса.

Лицензия

MIT © GregoryGost

EN

Project website

@gregory-gost/node-red-contrib-gost-yandex-alice adds nodes to Node-RED for creating virtual devices and controlling them by voice through Alice or through the Smart Home app.

Requirements

• Node-RED 4 or later.
• Node.js 24 or later.
• A Yandex account.

Quick start

1. In the main menu (☰), select “Manage palette”, then open the “Install” tab. Search for @gregory-gost/node-red-contrib-gost-yandex-alice and install the module.
2. Add the required *-input or *-output node to the workspace and open its settings.
3. In the configuration field, create the node for the appropriate capability or property: On/Off, Range, Mode, Color, Video Stream, or Property.
4. In that node's settings, create a device-node, select the device type, and enter its details.
5. In the device settings, create an nr-service-node, complete OAuth authorization, and save it.
6. Save the connected nodes, add the paired *-input or *-output node if needed, deploy the flow, and send the initial state to *-input.

Concept

nr-service-node
└── device-node
    └── capability or property config node
        ├── *-output → your flow
        └── *-input  ← state or reply from your flow

Node roles

• Service (nr-service-node) stores authorization and connects the flow's devices to the service.
• Device (device-node) represents one Smart Home object, such as a light, outlet, or sensor. Its type, name, and other details are configured here.
• Capability (config node) describes what can be controlled: On/Off, Toggle, Range, Mode, Color, or Video Stream.
• Property (Property config node) provides readings and events, such as temperature, humidity, or a door opening. Properties do not accept commands.
• *-output sends commands and state requests to your flow.
• *-input receives device state and replies to commands or requests from your flow.

Multiple input and output nodes

Several *-input and *-output nodes of the same type can be connected to one config node. An *-output node does not select one branch: the module sends every command and every state query that must enter the flow to all connected output nodes.

For a command with strict completion, the first processed correlated reply determines the command result; later replies no longer affect it. Ordinary messages from all *-input nodes update the shared state cache, so the value that arrives last becomes the stored value. A state query sent to the flow must also receive only one reply.

Use multiple output nodes only for intentional broadcasting, such as observation or coordinated actions. For one physical device, it is best to keep one working *-output and one *-input: branch the flow after the output node, and merge values and replies before the input node. This prevents independent branch delays from producing stale state or an unpredictable command result.

Device capabilities

• On/Off — turns the device on and off.
• Toggle — switches an individual function, such as backlight, pause, control lock, keep-warm, mute, or rotation.
• Range — sets a numeric value: brightness, volume, temperature, humidity, opening level, or channel.
• Mode — selects a mode from a predefined list, such as a program, heating mode, or fan speed.
• Color — changes the lighting color: RGB/HSV, color temperature, or a predefined scene.
• Video Stream — provides an HLS video stream URL for a camera.

Device properties

• Float — provides a numeric reading with a unit of measurement: temperature, humidity, illuminance, pressure, power, charge level, or a meter reading.
• Event — reports an event or state: opening, motion, a button press, smoke, water leak, or another sensor event.

Properties only provide state information and do not accept commands.

Choosing a device type and combining capabilities

There is no strict mapping between a device type and its functions. Choose the closest type in device-node and add only the capabilities and properties the device actually has: these determine the controls in the app and available voice commands.

• Lamp, light fixture, or strip — On/Off; add a Range for brightness control and Color for colored light.
• Outlet, switch, or relay — On/Off; when measurements are available, add Float for power, voltage, or an electricity-meter reading.
• Thermostat, air conditioner, humidifier, or fan — On/Off, a Range for temperature or humidity, Mode for operating mode, Toggle for extra functions, and Float for sensor readings.
• Curtains, blinds, or valve — Range with the opening parameter.
• Camera — Video Stream.
• Sensor or meter — Float and Event; for example, temperature and humidity, motion, opening, water leak, or resource consumption.
• Home appliance — usually On/Off together with Mode for the operating program and Toggle for pause, control lock, or keep-warm.

One device can have several capabilities and properties. Do not duplicate the same function: On/Off, Color, and Video Stream can be added once each; multiple Toggle, Range, and Mode nodes are allowed when they control different parameters. Properties must likewise describe different measurements or events.

On/Off is an exception: a device can have only one. If a two-gang switch controls two independent circuits, create two device-node nodes with separate On/Off nodes, for example “Light — switch 1” and “Light — switch 2”, and connect them to one nr-service-node.

A capability or property becomes available in Smart Home when at least one *-input or *-output node is attached to its config node.

State and replies

An ordinary message sent to *-input updates the state. Put the value in msg.payload:

msg.payload = true
return msg

For a request or command, *-output adds msg.broker to the message. Return the same message through the corresponding *-input node, changing only msg.payload. Do not create or modify msg.broker manually.

if (msg.broker?.kind === 'query-reply') {
  msg.payload = true
}
return msg

Capability and property settings

• State query (retrievable) lets the platform request the current value.

• State reporting (reportable) sends state changes to the notification service.

• Reply with the last known state is enabled by default. A request receives a valid cached value without starting the flow. If this option is disabled, the request is sent through *-output; the flow must return the current value through *-input.

• Treat the command as complete after sending is enabled by default. If disabled, the module waits for a correlated flow reply: return the requested valid value through *-input before the deadline. Once received, the command is marked successful (the result is DONE).

  For a relative Range command, such as “increase the value by 10”, the module also reports success, but does not change the stored last value. When the new value is known, send it as an ordinary message to *-input.

• Response deadline is set separately for each request. For a command, it is in msg.broker.deadline_at; for a state query, it is in msg.payload.deadline_at. Return the state or confirmation through *-input before this UTC timestamp: the module has no single fixed timeout, and a late reply is not accepted.

• Split commands (split) are available only for On/Off when retrievable is disabled and send switching on and off as separate commands.

Properties do not support actions. For Video Stream, *-output sends get_stream; return an absolute HLS URL in msg.payload through *-input, preserving msg.broker.

Yandex Smart Home documentation

• Device types
• Device capabilities
• Device properties

Independent project

This is an independent project: it is not a Yandex product and is not affiliated with the company. The names “Yandex” and “Alice” are used only to explain the module's compatibility with Yandex services.

License

MIT © GregoryGost