Elgato Key Light

Английский | Немецкий

Отказ от ответственности

Все названия продуктов и компаний, логотипы и товарные знаки, упомянутые в этом проекте, принадлежат их соответствующим владельцам. Их использование осуществляется исключительно в целях идентификации и не подразумевает какой-либо связи, спонсорства или одобрения со стороны этих владельцев или связанных с ними компаний. Это частный, некоммерческий проект, разработанный в развлекательных целях. Elgato является товарным знаком компании Corsair GmbH.

Сообщения об ошибках в системе Sentry

Этот адаптер использует интеграцию Sentry, предоставляемую ioBroker, для автоматического сообщения разработчикам о неожиданных исключениях и ошибках в коде. Функция сообщения об ошибках доступна через js-controller начиная с версии 3.0 и помогает выявлять и устранять дефекты, которые в противном случае могли бы остаться незамеченными.

Подробную информацию о передаваемых данных и инструкции по отключению сообщений об ошибках см. в официальной документации ioBroker Sentry .

Управляйте поддерживаемыми Wi-Fi-светильниками Elgato локально из ioBroker, без учетной записи в облаке Elgato. Адаптер обнаруживает светильники через Bonjour/mDNS или подключается к вручную настроенному частному IP-адресу или локальному имени хоста. Он предоставляет доступ к управлению устройством и информации о его состоянии в том виде, в котором это указано в ioBroker, а также удобную панель управления в административном интерфейсе.

Для чего нужен адаптер?

Этот адаптер подключает светильники Elgato к ioBroker, позволяя использовать их из административной панели, скриптов, сцен, визуализаций и других адаптеров ioBroker. Типичные варианты использования:

• Совместное использование студийного освещения с потоковой передачей или записью;
• регулировка яркости и цветовой температуры в зависимости от времени суток;
• Управление светодиодной лентой Elgato с помощью цветов RGB/HSV;
• отслеживание доступности источника света и времени его следующего опроса;
• Отображение состояния батареи и уровня заряда Key Light Mini;
• Управление освещением вручную с помощью специальной панели Elgato Lights.

Связь осуществляется в локальной сети. Адаптер опрашивает каждое настроенное устройство, публикует его текущее состояние и отправляет изменения, внесенные пользователем, обратно на устройство. В случае неудачных запросов используется стратегия ограниченного количества повторных попыток/задержек, чтобы отключенный светильник не перегружал сеть.

Поддерживаемые устройства и возможности

Элементы управления создаются на основе фактического ответа API, а не на основе жестко заданного имени продукта. Это позволяет совместимому программному обеспечению и соответствующим моделям Elgato Light предоставлять доступ ко всем сообщаемым ими возможностям.

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

Требования

• Node.js 22.18 или более поздняя версия
• js-controller 7.2.2 или новее
• Администратор 7.8.23 или более поздняя версия
• Сетевой доступ от хоста ioBroker к светильникам обычно осуществляется через TCP-порт 9123.
• Порт UDP Bonjour/mDNS 5353 при использовании автоматического обнаружения.

Устройство Elgato Light и хост ioBroker обычно должны находиться в одной локальной сети. Для обнаружения устройств в разных VLAN может потребоваться mDNS-рефлектор; при недоступности обнаружения многоадресных устройств можно использовать ручную настройку.

Установка и настройка

1. Установите адаптер и создайте экземпляр.
2. Откройте конфигурацию экземпляра.
3. Выберите «Сканировать сеть» , чтобы найти_elg._tcp.local. затем добавьте необходимые результаты для служб. В качестве альтернативы введите частный IP-адрес или.local Имя хоста и порт указываются вручную. Порт API Elgato по умолчанию:9123 .
4. Используйте функцию «Тест» , чтобы проверить адрес, указанный вручную, перед его добавлением.
5. Включите настроенные устройства и сохраните конфигурацию.
6. Для управления в режиме реального времени откройте вкладку Elgato Key Light на боковой панели администратора.

При сканировании сети отображаются только доступные устройства. Добавьте необходимые результаты сканирования явно, чтобы устройства оставались привязанными к нужному экземпляру адаптера.

Параметры выполнения

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

Использование панели управления

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

• Кнопка питания включает и выключает свет.
• Регулировка яркости позволяет устанавливать выходную мощность от 0 до 100 процентов.
• При наличии соответствующей поддержки, можно регулировать цветовую температуру белого цвета в диапазоне от 2900 K до 7000 K.
• Цвет открывает палитру цветов в браузере для устройств, поддерживающих RGB.
• Режим Studio управляет отключением питания на Key Light Mini, когда его прошивка сообщает об этом параметре.
• Функция Identify позволяет выбранному устройству идентифицировать себя.
• Функция Reconnect немедленно повторно считывает данные с устройства.

На карте также отображается статус онлайн/офлайн, задержка ответа, версия прошивки, информация о батарее (если доступна) и обратный отсчет до следующего опроса. Кнопки «Включить все» и «Выключить все» управляют всеми доступными индикаторами в текущем экземпляре адаптера. Кнопка «Обновить» перезагружает данные панели управления, а кнопка «Диагностика» отображает информацию о времени работы и устройстве, полезную для устранения неполадок.

Изменение цвета светодиодной ленты сохраняет её отдельную настройку яркости.hex иrgb Значения состояния представляют собой текущий излучаемый цвет и, следовательно, включают текущую яркость. Например, один и тот же оттенок синего может отображаться как#000080 при 50% яркости и#0000FF при 100% яркости.

Управление устройствами с помощью состояний ioBroker

Каждое успешно подключенное устройство получает корневой объект на основе своего серийного номера:

elgato-key-light.<instance>.<serial>

Большинство устройств содержат один источник света.light.lights.0 Создаются только те состояния, которые поддерживаются устройством.

Дополнительная информация только для чтенияinfo При передаче соответствующих данных могут быть созданы состояния Wi-Fi, напряжения/тока батареи и настроек устройства.

Примеры скриптов

Замените номер экземпляра и серийный номер идентификаторами из дерева объектов ioBroker. Запись в состояния, доступные для записи, должна производиться с использованиемack = false Таким образом, адаптер распознает их как команды.

const light = 'elgato-key-light.0.EW40K1A09882.light.lights.0';

// Switch on and set brightness to 65%.
setState(`${light}.on`, true, false);
setState(`${light}.brightness`, 65, false);

// Set a warm white color temperature.
setState(`${light}.temperature`, 3200, false);

// Set an RGB-capable light to blue without changing its brightness.
setState(`${light}.hex`, '#0000FF', false);

Одни и те же состояния для записи можно использовать из Blockly, Scenes, VIS и других компонентов ioBroker. Быстрая запись ползунка объединяется для каждого устройства; побеждает последнее значение.

Множественные экземпляры и удаление устройств

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

Удаление устройства, отмеченного значком корзины, удаляет его из работающего экземпляра, из сохраненной конфигурации экземпляра и из дерева объектов устройств этого экземпляра. Сохранение страницы администрирования после внесения изменений в конфигурацию по-прежнему рекомендуется. Устройства, назначенные другому экземпляру, не затрагиваются.

Поиск неисправностей

Устройство не найдено

• Убедитесь, что ioBroker и индикатор уровня сигнала могут взаимодействовать друг с другом в локальной сети.
• Для обнаружения проверьте многоадресный DNS/UDP-пакет 5353 и_elg._tcp.local. Пересылка.
• Добавьте частный IP-адрес или.local Если обнаружение не удается осуществить через VLAN, имя хоста задается вручную.
• Убедитесь, что TCP-порт 9123 доступен и устройство не изолировано политикой гостевой сети Wi-Fi.

На панели управления отображается сообщение «Устройство отключено».

На карточке отображается последняя ошибка и обратный отсчет до следующей попытки. Используйте функцию «Переподключиться» для немедленного считывания данных. Проверьте.health.lastError ,health.consecutiveFailures иhealth.nextPoll для автоматизации или мониторинга.

Элементы управления отсутствуют

Адаптер формирует элементы управления на основе полей, возвращаемых устройством. При необходимости обновите прошивку устройства, подключите его обратно и проверьте работу.info.capabilities или диагностику панели управления. Отсутствие элемента управления обычно означает, что API не сообщил о наличии такой возможности.

Сбор диагностических данных

Диалоговое окно диагностики панели управления включает в себя информацию о версии адаптера/среды выполнения и текущем состоянии устройства. Значения SSID опущены, но серийные номера устройств и адреса локальных сетей могут присутствовать, поскольку они полезны для диагностики. Перед публикацией результатов следует проверить их.

Разработчики и специалисты по тестированию оборудования могут использовать зонд, работающий только с GET-запросами:

npm run elgato:probe -- 192.168.1.50 9123

Зонд скрывает серийный номер, MAC-адрес и SSID. Подробная информация о протоколе приведена в файле docs/ELGATO_API.md .

Сеть и конфиденциальность

Для связи между устройствами используется локальный неаутентифицированный HTTP API Elgato. Проверка хоста принимает только частные/локальные адреса и локальные имена хостов; схемы URL, встроенные учетные данные, пути и публичные IP-адреса отклоняются. Адаптер не требует учетной записи в облаке Elgato и не добавляет телеметрию.

Поскольку локальный API устройства не предусматривает аутентификацию, размещайте осветительные приборы и хост ioBroker в доверенной сети и не открывайте TCP-порт 9123 для доступа из интернета.

Обновление с более старой версии.

Корневые каталоги устройств с серийными номерами и установленные пути для записи, указанные ниже.<serial>.light.lights.0 Сохранены. Информацию об исправлениях метаданных, миграции конфигурации и откате см. в файле docs/MIGRATION.md. Перед крупным обновлением создайте резервную копию ioBroker.

Разработка

npm run install:all
npm run lint
npm run typecheck
npm test
npm run test:integration
npm run build

Аппаратные тесты являются необязательными, по умолчанию выполняются только с помощью GET-запросов и не должны запускаться в CI.

Changelog

WORK IN PROGRESS

2.0.0 (2026-08-16)

• (xXBJXx) Reworked the backend with a validated HTTP client, capability detection, resilient polling and bounded Bonjour/mDNS discovery.
• (xXBJXx) Added reliable controls for supported lights, including RGB, temperature, battery and studio mode, with strict instance isolation and clean device removal.
• (xXBJXx) Modernized the configuration and dashboard UIs with responsive device cards, health data, diagnostics and device/API details.
• (xXBJXx) Addressed repository checker findings for managed timers and repository metadata.
• (xXBJXx) Requires Node.js >= 22.18, js-controller >= 7.2.2 and Admin >= 7.8.23.
• (xXBJXx) Fixes issues #116, #117, #130, #152 and #159; supersedes PRs #39, #129, #181, #185, #186, #209 and #250.

Older entries: CHANGELOG_OLD.md

License

Created by xXBJXx and maintained by ioBroker Community Adapters. Elgato is a trademark of Corsair GmbH; this project is not affiliated with or endorsed by Elgato/Corsair.

Copyright (c) 2024-2026 iobroker-community-adapters mcm57@gmx.at
Copyright (c) 2023 xXBJXx issi.dev.iobroker@gmail.com

Released under the MIT License. See LICENSE.