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.