node-red-contrib-osyshome 0.2.6

Node-RED nodes for osysHome: catalog, get/set properties, call methods, property events (Socket.IO + REST)

npm install node-red-contrib-osyshome

node-red-contrib-osyshome — руководство (RU)

Интеграция Node-RED с osysHome: одна общая настройка сервера (URL + API-ключ), каталог объектов/свойств/методов в редакторе и в flow, чтение/запись свойств, вызов методов, события изменений.

Версия пакета: 0.2.6

Что нужно заранее

В osysHome установлен wsServer не ниже 1.6 (авторизация Socket.IO по API-ключу).
У пользователя задан API-ключ: свойство Users.<имя>.apikey.
Из машины/контейнера Node-RED доступны HTTP API и WebSocket osysHome (/api/... и /socket.io/).

Установка (npm)

npm install --prefix ~/.node-red node-red-contrib-osyshome

Или в редакторе: Manage palette → Install → node-red-contrib-osyshome.

Для мейнтейнеров: отдельный репозиторий Anisan/node-red-contrib-osyshome, публикация в npm — DEPLOY.md (тег v* + секрет NPM_TOKEN).

Локальная разработка (клон репо или путь к этой папке):

cd ~/.node-red
npm install /путь/к/node-red-contrib-osyshome

Перезапустите Node-RED. В палитре появится категория osysHome.

Пример flow

Базовый smoke-test: examples/osyshome-test-flow.json

Реальные сценарии:

Example	Смысл
`osyshome-motion-light-flow.json`	Движение → вкл/выкл свет + мониторинг лампы + эмуляция датчика
`osyshome-night-light-flow.json`	Ночной свет: движение только ночью, выключение через 60 с (trigger extend)

Импорт: ☰ → Import → файл / Examples → node-red-contrib-osyshome.

В сценариях по умолчанию стоят имена MotionSensor.occupancy и HallLamp.state — замените на свои через Refresh в нодах.

Перед тестом: Server → Base URL + API key → Test API → Deploy.

Как задать настройки сервера в Node-RED

Адрес osysHome и API-ключ задаются один раз в конфиг-ноде osys-config.
На рабочих нодах (get / set / call / events / list) URL и ключ не вводятся — там только выбирается уже созданный Server.

Шаг 0. Получить API-ключ в osysHome

Откройте веб-интерфейс osysHome под пользователем, от имени которого будет ходить Node-RED.
Найдите объект пользователя класса Users (например Users.admin или ваш логин).
Откройте свойство apikey.
Если ключа нет — сгенерируйте/задайте строку (достаточно длинный случайный токен) и сохраните.
Скопируйте значение apikey — оно понадобится в Node-RED.

Проверка ключа в браузере или curl (подставьте свой URL и ключ):

http://192.168.0.10:5000/api/object/list?apikey=ВАШ_КЛЮЧ

Должен вернуться JSON вида { "success": true, "result": { ... } }.

Также убедитесь, что плагин wsServer версии ≥ 1.6 установлен и osysHome перезапущен после его обновления.

Шаг 1. Открыть диалог конфига в Node-RED

Есть два одинаковых способа:

Способ A (удобнее)

В палитре слева найдите категорию osysHome.
Перетащите на лист любую ноду, например get property или list / catalog.
Дважды кликните по ноде.
В поле Server нажмите карандаш (✎) или выберите Add new osys-config… → карандаш.

Способ B
Меню Node-RED (☰) → Configuration nodes → найти/создать osys-config.

Откроется окно настроек сервера.

Шаг 2. Заполнить поля

Поле	Что писать	Пример	Важно
Name	Любое имя для себя	`Дом`, `osys-prod`	Так конфиг будет подписан в списке Server у всех нод
Base URL	Корень сайта osysHome	`http://192.168.0.10:5000`	Без `/` в конце. Не добавляйте `/api` и не `/admin`
API key	Значение `Users.*.apikey`	`a1b2c3…`	Один и тот же ключ для REST (каталог) и Socket.IO (get/set/call/events)

Какой Base URL выбрать

Где крутится Node-RED	Где крутится osysHome	Типичный Base URL
На том же ПК	Локально, порт 5000	`http://127.0.0.1:5000`
На другом ПК в LAN	ПК с IP `192.168.0.10`	`http://192.168.0.10:5000`
В Docker (Docker Desktop)	На хосте Windows/Mac	`http://host.docker.internal:5000`
В Docker в той же compose-сети	Сервис `osyshome`	`http://osyshome:5000`
За nginx с HTTPS	Домен	`https://osys.example.com`

Неверно: http://192.168.0.10:5000/api, http://192.168.0.10:5000/ (лишний / лучше убрать), URL только WebSocket без схемы.

Если osys за reverse-proxy, прокси должен пропускать и /api/…, и апгрейд WebSocket на /socket.io/.

Шаг 3. Проверить связь — кнопка Test API

В том же окне нажмите Test API.
Успех: сообщение вроде OK — N objects (N — число объектов).
Ошибка: проверьте Base URL, ключ, что osysHome запущен, файрвол, что из контейнера Node-RED этот хост реально пингуется.

Test API дергает REST: GET {Base URL}/api/object/list?apikey=….
Socket.IO проверяется позже, когда задеплоите ноду get/set/events (статус ноды: green connected).

Шаг 4. Сохранить конфиг и задеплоить

В окне config нажмите Add / Update.
В окне рабочей ноды в Server должен появиться ваш конфиг (по Name или URL) — выберите его.
Нажмите Done.
Красная кнопка Deploy (правый верхний угол редактора) — обязательно.

Пока не сделан Deploy, runtime ещё не знает URL/ключ; каталог в редакторе может подтягиваться через query, но для стабильной работы всегда деплойте после смены настроек.

Если нет карандаша у Server (поле простое красное)

Тип osys-config не загрузился. Часто пакет только скопировали, но не сделали npm install — нет socket.io-client, раньше из‑за этого падала регистрация config-ноды.

# хост
cd ~/.node-red
npm install /путь/к/integrations/node-red-contrib-osyshome

# Docker
docker exec -it <node-red> sh -c "cd /data && npm install /data/nodes/node-red-contrib-osyshome"
docker restart <node-red>

Затем Ctrl+F5 в редакторе. У Server должны появиться список и карандаш ✎ / «Add new osys-config…».

Шаг 5. Привязать Server на остальных нодах

На каждой ноде osysHome:

Откройте ноду.
В Server выберите тот же osys-config (не создавайте второй с тем же URL без нужды).
Нажмите Refresh у списков Object/Property/Method — должны появиться объекты из osys.
Deploy.

Один дом / один osys → один config.
Два сервера (например test и prod) → два config с разными Name / URL / ключами, на нодах выбираете нужный Server.

Как потом изменить URL или ключ

Меню ☰ → Configuration nodes → клик по вашему osys-config.
Либо откройте любую ноду → Server → карандаш.
Поменяйте Base URL и/или API key.
Снова Test API.
Update → Done → Deploy.

Все ноды, ссылающиеся на этот Server, сразу начнут ходить на новый адрес (после Deploy).

Два сервера в одном flow

Пример: osys-config с Name=prod и второй с Name=lab.
На ноде events выберите Server=prod, на list — Server=lab.
Ключи и URL у каждого config свои.

Если настройки «не видятся»

Симптом	Действие
В Server пусто / только Add new	Создайте config через карандаш, сохраните, Deploy
Test API OK, а списки объектов пустые	Выберите Server на ноде, нажмите Refresh, Deploy config
Нода красная `no config`	Не выбран Server или config удалён
Нода `unauthorized` / connect error	wsServer ≥ 1.6; ключ тот же, что в Test API; Base URL доступен из runtime
API key «пропал» после импорта flow	Ключ в credentials не всегда едет в JSON — введите ключ снова в config

Общая настройка: краткая шпаргалка `osys-config`

Поле	Пример
Name	`Дом`
Base URL	`http://192.168.0.10:5000`
API key	значение `Users.*.apikey`

Каталог в редакторе (автозаполнение)

В нодах get / set / call / events / list:

Выберите Server (ваш osys-config).
Нажмите кнопку обновления (Refresh).
Выберите Object, затем Property или Method.

Для events:

Add — добавить Object.property в список подписок;
Add all props — все свойства выбранного объекта;
* — подписаться на все свойства системы (нагрузка!);
Clear — очистить список.

Списки берутся из REST:

объекты — /api/object/list
свойства — /api/property/list/<object>
методы — /api/method/list/<object>
объект целиком — /api/object/<name>

Ноды по одной

list / catalog (`osys-list`)

По каждому входному сообщению запрашивает каталог (REST).

Mode	Что возвращает в `msg.payload`
`objects`	словарь имён объектов → описание
`details`	объекты со свойствами и методами
`object`	один объект (нужен Object)
`properties`	свойства объекта
`methods`	методы объекта

Переопределение из flow: msg.mode, msg.object.

Типичный сценарий: inject → osys-list → debug, чтобы изучить имена перед автоматикой.

get property

Читает текущее значение через wsServer.

В редакторе: Object + Property из каталога.
В runtime: msg.object + msg.property, либо полный путь в msg.property / msg.topic.
Выход: msg.payload = значение, msg.topic = Object.property, msg.osys = полный ответ.

set property

Пишет msg.payload в выбранное свойство. Источник на стороне osys: NodeRed.

Ждёт подтверждения propertyChanged. Ошибка валидации/прав приходит как ошибка ноды.

call method

Вызывает метод объекта. При включённом Wait result ждёт resultCallMethod, результат кладётся в msg.payload.

events

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

Каждое событие → отдельное сообщение:

msg.topic — Object.property
msg.payload — новое значение
msg.osys.source — кто изменил (api, WS, NodeRed, …)

Опция Ignore own отбрасывает события с source === "NodeRed", чтобы не зациклить flow «событие → set → снова событие».

Поля сообщений (шпаргалка)

Поле	Когда
`msg.payload`	значение / результат метода / каталог
`msg.topic`	квалифицированное имя или тема каталога
`msg.object`	имя объекта
`msg.property`	имя свойства или `Object.property`
`msg.method`	имя метода или `Object.method`
`msg.mode`	режим list
`msg.waitResult`	ждать ли результат call
`msg.osys`	сырой/структурированный ответ сервера

Примеры сценариев

Датчик → лампа

osys events — подписка MotionSensor.occupancy
switch — payload is true
change — payload = true (если нужно именно включить, а не передать occupancy)
osys set property — HallLamp.state

Обзор системы

inject (timestamp)
osys list, mode = details
debug (complete message object)

По кнопке вызвать метод

inject
osys call method — выбрать Object и Method, Wait result = on
debug

Частые проблемы

Симптом	Что проверить
Test API красный	URL, ключ, osys запущен, порт
Пустые выпадающие списки	Deploy config, Refresh, тот же ключ что в Test
connect / unauthorized	wsServer ≥ 1.6, ключ в config
Нет событий	список подписок, wsServer, Ignore own
set timeout	есть ли свойство, права, валидация значения
В браузере ок, в Docker нет	Base URL «глазами» контейнера; прокси WebSocket

Архитектура (кратко)

Node-RED editor  --HTTP-->  Node-RED runtime admin proxy  --REST-->  osys /api/object|property|method
Node-RED nodes   --Socket.IO + apikey-->  wsServer  --set/call/subscribe-->  ObjectManager

Один osys-config = один Base URL + один API key + одно общее Socket.IO-соединение на все ноды, которые на него ссылаются.

Node Info

Version: 0.2.6

Updated 1 day ago

License: MIT

Rating: not yet rated

View on npm

View on GitHub

View Scorecard 12

Actions

Downloads

0 in the last week

Nodes

osys-config
osys-list
osys-get-property
osys-set-property
osys-call-method
osys-events

Keywords

node-red
osyshome
smart-home
socket.io
websocket

Maintainers

anisan

node-red-contrib-osyshome 0.2.6

node-red-contrib-osyshome — руководство (RU)

Что нужно заранее

Установка (npm)

Пример flow

Как задать настройки сервера в Node-RED

Шаг 0. Получить API-ключ в osysHome

Шаг 1. Открыть диалог конфига в Node-RED

Шаг 2. Заполнить поля

Какой Base URL выбрать

Шаг 3. Проверить связь — кнопка Test API

Шаг 4. Сохранить конфиг и задеплоить

Если нет карандаша у Server (поле простое красное)

Шаг 5. Привязать Server на остальных нодах

Как потом изменить URL или ключ

Два сервера в одном flow

Если настройки «не видятся»

Общая настройка: краткая шпаргалка `osys-config`

Каталог в редакторе (автозаполнение)

Ноды по одной

list / catalog (`osys-list`)

get property

set property

call method

events

Поля сообщений (шпаргалка)

Примеры сценариев

Датчик → лампа

Обзор системы

По кнопке вызвать метод

Частые проблемы

Архитектура (кратко)

Node Info

Categories

Actions

Downloads

Nodes

Keywords

Maintainers

Report this module

node-red-contrib-osyshome 0.2.6

node-red-contrib-osyshome — руководство (RU)

Что нужно заранее

Установка (npm)

Пример flow

Как задать настройки сервера в Node-RED

Шаг 0. Получить API-ключ в osysHome

Шаг 1. Открыть диалог конфига в Node-RED

Шаг 2. Заполнить поля

Какой Base URL выбрать

Шаг 3. Проверить связь — кнопка Test API

Шаг 4. Сохранить конфиг и задеплоить

Если нет карандаша у Server (поле простое красное)

Шаг 5. Привязать Server на остальных нодах

Как потом изменить URL или ключ

Два сервера в одном flow

Если настройки «не видятся»

Общая настройка: краткая шпаргалка osys-config

Каталог в редакторе (автозаполнение)

Ноды по одной

list / catalog (osys-list)

get property

set property

call method

events

Поля сообщений (шпаргалка)

Примеры сценариев

Датчик → лампа

Обзор системы

По кнопке вызвать метод

Частые проблемы

Архитектура (кратко)

Node Info

Categories

Actions

Downloads

Nodes

Keywords

Maintainers

Report this module

Общая настройка: краткая шпаргалка `osys-config`

list / catalog (`osys-list`)