xLights: программируем световое шоу в Minecraft

Ранее мы рассказывали про историю протоколов управления световым оборудованием. Настало время сделать свое шоу.

Для создания собственного светового шоу требуются «умные» источники света и пульт управления. Наиболее доступное решение — использование адресных светодиодных лент на базе WS2818b и микроконтроллера с Wi-Fi. Подробную инструкцию по работе с адресной светодиодной лентой можно найти в блоге AlexGyver, а программную часть взять у проекта WLED.

В современных домашних инсталляциях для управления светом удобнее всего использовать Wi-Fi и протокол E1.31, а в качестве программы для создания шоу — xLights. Мы решили пойти дальше и разработать собственное E1.31-совместимое устройство и запрограммировать с его помощью небольшое светопреставление. Выбор пал на Minecraft.

Энтузиасты проводят в этой популярной «песочнице» разные мероприятия, в том числе квартирники, спектакли и вебинары. Во всех случаях игра выполняет роль самостоятельной и независимой виртуальной площадки. В нашем случае «сценическое оборудование» находится внутри игры, а пульт управления — снаружи. Эту проблему решает плагин для сервера Minecraft.

Все описанное в статье применимо к любому проекту, где возможно подключение к интернету и есть контролируемые осветительные приборы.

Протокол E1.31

Хотя Art-Net проще, мы выбрали стандартизированный sACN (E1.31). В интернете можно найти реализацию для языков C, C#, Python. Java — не лучший язык для обработки байтового потока, но другого не надо. Необходимая нам функциональность — получение пакетов E1.31 и извлечение необходимых данных, поэтому мы напишем свой приемник. Пакеты sACN отправляются по UDP и состоят из трех слоев. Структура пакета в нотации языка С, взятая из libe131:

/* E1.31 Packet Type */
/* All packet contents shall be transmitted in network byte order (big endian) */
typedef union {
  PACK(struct {
    PACK(struct { /* ACN Root Layer: 38 bytes */
      uint16_t preamble_size;    /* Preamble Size */
      uint16_t postamble_size;   /* Post-amble Size */
      uint8_t  acn_pid[12];      /* ACN Packet Identifier */
      uint16_t flength;          /* Flags (high 4 bits) & Length (low 12 bits) */
      uint32_t vector;           /* Layer Vector */
      uint8_t  cid[16];          /* Component Identifier (UUID) */
    }) root;

    PACK(struct { /* Framing Layer: 77 bytes */
      uint16_t flength;          /* Flags (high 4 bits) & Length (low 12 bits) */
      uint32_t vector;           /* Layer Vector */
      uint8_t  source_name[64];  /* User Assigned Name of Source (UTF-8) */
      uint8_t  priority;         /* Packet Priority (0-200, default 100) */
      uint16_t reserved;         /* Reserved (should be always 0) */
      uint8_t  seq_number;       /* Sequence Number (detect duplicates or out of order packets) */
      uint8_t  options;          /* Options Flags (bit 7: preview data, bit 6: stream terminated) */
      uint16_t universe;         /* DMX Universe Number */
    }) frame;

    PACK(struct { /* Device Management Protocol (DMP) Layer: 523 bytes */
      uint16_t flength;          /* Flags (high 4 bits) / Length (low 12 bits) */
      uint8_t  vector;           /* Layer Vector */
      uint8_t  type;             /* Address Type & Data Type */
      uint16_t first_addr;       /* First Property Address */
      uint16_t addr_inc;         /* Address Increment */
      uint16_t prop_val_cnt;     /* Property Value Count (1 + number of slots) */
      uint8_t  prop_val[513];    /* Property Values (DMX start code + slots data) */
    }) dmp;
  });

  uint8_t raw[638]; /* raw buffer view: 638 bytes */
} e131_packet_t;

Нам интересны следующие поля:

• номер последовательности — seq_number;
• номер DMX Universe — universe;
• количество байт DMX-информации в данном пакете — prop_val_cnt;
• байты DMX-информации — prop_val;

Так как данные отправляются с большой частотой и по ненадежному UDP, то перепутать пакеты местами достаточно просто. Значение seq_number обозначает номер последовательности и фактически обозначает номер «кадра» в световом шоу, позволяя отбрасывать пакеты с номером меньше актуального. Значение universe помогает упорядочивать пакеты внутри кадра.

Обратите внимание, что один E1.31-пакет может содержать не больше 511 байт полезной информации. Согласно стандарту DMX, нулевой байт, называющийся стартовым кодом, зарезервирован и должен быть равен нулю.

При наличии более одной DMX-области полученные пакеты необходимо упорядочить и объединить DMX-данные, удалив нулевой байт из каждой DMX-области. Полученные DMX-данные можно использовать для управления освещением.

Настраиваем xLights

xLights — свободно распространяемое программное обеспечение для управления DMX-контроллерами. Данная программа поддерживает Windows, Linux и macOS. На момент написания статьи на странице загрузки актуальная версия — 2020.56.

Сперва необходимо подключить все доступные контроллеры. Контроллер — это устройство, которое принимает пакеты E1.31, извлекает из них данные и отправляет подключенным DMX-устройствам. В нашем случае контроллер один — сервер Minecraft. Однако если вы используете светодиодные ленты, то скорее всего у каждой ленты будет свой контроллер.

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

Мы используем E1.31, поэтому выбираем «Add Ethernet» и в правой половине указываем необходимые для подключения данные: IP-адрес, протокол E131, номер начальной DMX-области и количество областей.

Количество областей напрямую зависит от количества каналов. Так, при использовании светодиодной ленты WS2812B каждый светодиод требует три канала. Таким образом, одна DMX-область может управлять только 170 светодиодами. Если светодиодов больше, то данному устройству нужно выделить больше DMX-областей.

После указания всех необходимых данных нажимаем на кнопку «Save», которая окрашивается в красный цвет при наличии несохраненных изменений. Мы указали две DMX-области по 510 каналов (511 вместе со стартовым кодом). Число 510 выбрано неслучайно, оно кратно трем, а все RGB-устройства имеют количество каналов, кратное трем.

Обратите внимание, что настройки контроллеров и композиции сохраняются в каталог, который указан как каталог шоу (Show Directory).

После настройки контроллеров можно переходить к настройке композиции.

Организация композиции

Переходим на вкладку Layout в xLights. На данной вкладке можно видеть три области:

• список моделей (левая верхняя четверть);
• настройки выделенной модели (левая нижняя четверть);
• внешний вид инсталляции (правая половина).

При первом открытии ни одна модель не выделена, а в настройках доступны параметры композиции. В параметре Background Image можно указать изображение, например, фотографию дома, квартиры или любого места, которое планируется для организации шоу.

Для добавления устройства в композицию необходимо выбрать его тип, а затем «нарисовать» его в окне композиции. По умолчанию xLights предоставляет базовые элементы и несколько «сложных» фигур. Тем не менее, предусмотрена возможность создания собственных моделей и отправки «сырых» DMX-данных.

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

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

После изменения параметров модели необходимо нажать кнопку Save, иначе изменения будут сброшены!

Моделей, которые предоставляет xLights, достаточно для создания первых композиций. В меню добавления моделей есть кнопка с иконкой скачивания. Это позволяет загрузить готовые модели из разных источников. Тем не менее, иногда возникает необходимость в собственных моделях. Для этого случая есть два вида решения:

• Custom (иконка с мордашкой);
• DMX (иконка с цветным текстом DMX).

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

Модель типа Custom позволяет создавать трехмерные модели с различной адресацией источников света в модели. Создание собственной модели представляет собой заполнение номеров управляющего канала в таблицах. Обращаем внимание, что данный редактор подразумевает использование однородных элементов в модели. Иными словами, все светильники в модели должны использовать одинаковое количество каналов. По умолчанию используются RGB-светильники, которые используют по три канала. Так мы разметили девять источников света, но модель потребляет 27 каналов.

В случае, когда тип Custom не способен решить проблему, например, используется DMX-совместимое не световое оборудование, на помощь приходит модель типа DMX. xLights имеет некоторое представление о не световых DMX-устройствах и предлагает выбрать тип устройства из списка. Если используемое устройство не присутствует в списке, то стоит выбрать General и указать количество используемых каналов и их названия в настройках модели в параметре Strand/Node Names. Мы использовали генератор огня, который принимает значения «высота огня в блоках» и «продолжительность огня».

После создания композиции можно приступать к программированию шоу.

Создание шоу

Создание шоу — наиболее времязатратное действие. Переходим на вкладку Sequencer. Большинство элементов интерфейса будут неактивны, так как последовательность не создана. Последовательность создается через File → New Sequence или комбинацией клавиш Ctrl+N.

В первую очередь xLights задаст вопрос о типе последовательности. Это может быть музыкальное шоу (Musical Sequence) или анимация (Animation). Первый тип требует указать музыкальный файл, который будет использоваться в светопреставлении. Вне зависимости от выбранного типа необходимо указать кадровую частоту для шоу. По умолчанию предлагаются значения 20 или 40 кадров в секунду. Данная настройка напрямую зависит от способности оборудования работать с требуемой скоростью. Мы рекомендуем начинать с 20 кадров в секунду.

Последним вопросом при создании шоу будет выбор моделей.

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

Рассмотрим панели, расположенные над вкладками. Нижняя вкладка с мелкими иконками — панель эффектов. В отличие от моделей эффекты перетаскиваются на временную шкалу, а не устанавливаются кликом. Верхняя панель делится на блоки, слева направо:

• операции с композицией (создание, сохранение и т.д.);
• выравнивание эффектов по времени или по клеткам шкалы времени;
• операции с последовательностью (запуск, пауза, остановка, перемотка, зацикливание);
• включение или отключение отображения окон во вкладке Sequencer;
• увеличение и уменьшение масштаба временной шкалы и настройки последовательности;
• трансляция последовательности на контроллеры (справка, остановить, погасить все лампы, включить отображение на контроллеры).

На вкладке Sequence есть несколько окон:

• Model Preview;
• House Preview;
• Color;
• View;
• Effect Settings;
• Layer Blending;
• Layer Settings.

Нам интересны только первые пять. Окно Model Preview позволяет увидеть, как выделенная на шкале времени модель отображает эффект, а House Preview позволяет увидеть все модели в контексте композиции.

С помощью окна Color можно задать разрешенные для модели цвета. По умолчанию xLights предполагает, что используются RGB-светильники, и разрешает использовать все цвета. Если вы хотите запретить какие-то цвета, необходимо снять отметки и нажать кнопку Update.

Окна View и Effect Settings позволяют указать время воспроизведения эффекта и задать его параметры. Мы не будем рассказывать про каждый эффект и его настройки, оставим это зоной для ваших экспериментов. Если эффект нравится в предпросмотре xLights, его можно вывести на контроллеры и посмотреть результат вживую.

В окне Effect Settings также присутствует кнопка Update. Ее следует нажимать, если модель, которая воспроизводит эффект, изменилась, иначе может быть некорректное отображение эффектов.

Ранее мы упоминали про DMX-совместимые устройства, которые не являются световым оборудованием, но могут управляться через xLights. В нашем случае это генератор огня, требующий два канала. Если каналы устройства были подписаны при создании композиции, то они отобразятся в настройках эффекта DMX.

Обращаем внимание, что xLights позволяет задавать эффекты не только всему устройству, но и каждой линии (strand) или каждой ячейке (node) сложного устройства. Для этого достаточно дважды кликнуть по устройству на временной шкале.

Демонстрация результатов

Для демонстрации мы взяли фрагмент композиции «RADIO TAPOK — Потрошитель». Хотя возможности Minecraft по отображению световых эффектов весьма ограниченны, а автор — любитель в этой области, постановка получилась достаточно интересной.

Плагин для Minecraft все еще в разработке, но его исходный код уже доступен в репозитории на github.com.

Заключение

Мы кратко рассмотрели процесс создания светового шоу в xLights. Если вас заинтересовала данная тема, то рекомендуем к ознакомлению сайт xlights.org. Там можно найти инструкции и людей, которые могут ответить на вопрос как на форуме, так и в Zoom.