Сигналы

Сигнал — это сообщение, которому вы дали имя и которое сохранили: OSC-сообщение, сырая датаграмма UDP, HTTP-запрос или публикация MQTT вместе с адресатом. Вы создаёте его один раз — на экране Сигналы или сохранив то, что только что отправили с другого экрана, — и отправляете снова, когда нужно, байт в байт так же.

Библиотека — это файл JSON, который можно читать, править вручную, копировать на другой компьютер или коммитить рядом с проектом. Экран Сигналы показывает её слева как дерево папок, а справа — поля выбранного сигнала.

Что может отправлять сигнал

Выберите вид в поле Транспорт. У каждого вида свои поля:

Транспорт	Поля	Что уходит
OSC	Цель host:port, OSC-адрес, Аргументы	Одно OSC-сообщение на один IP:port или host:port с нового порта UDP. Типы аргументов — на странице OSC.
UDP (сырой)	Цель host:port, Вид (Текст или Байты (hex)), Полезная нагрузка	Одна датаграмма ровно с этими байтами. Текст уходит как написан, без терминатора; hex — это пары цифр вроде de ad be ef (пробелы и префикс 0x допустимы).
HTTP	Метод, URL, Таймаут (мс), Заголовки, Аутентификация, Тело	Один HTTP-запрос. См. HTTP.
MQTT	Брокер host:port, Топик, QoS, retain, Полезная нагрузка	Одна публикация. См. MQTT.

У каждого сигнала есть и поля Имя, Папка и Заметка; в заметке можно записать, что сигнал должен вызвать и что должно совпасть на другом конце.

Адресаты OSC- и UDP-сигналов — это IP:port или host:port (например, 127.0.0.1:9000); имя хоста разрешается при каждой отправке сигнала. Брокер MQTT-сигнала — host:port; без порта это 1883.

Когда вы меняете вид сигнала, его сообщение начинается заново со значений по умолчанию для нового вида. Сохраняется только адресат, и только при переходе между OSC и UDP (сырой), где адресат значит одно и то же.

Отправка сигнала

Чтобы отправить сигнал с экрана Сигналы, сделайте любое из этого:

• Выберите его и нажмите Отправить.
• Нажмите Ctrl+Enter, пока работаете в его полях.
• Дважды щёлкните его в дереве.

Каждая отправка пишет в консоль строку: что и куда ушло, сколько байт, а для HTTP — статус и затраченное время. Ошибка (отказ в соединении, недоступный хост) — красная строка с причиной. Время последней отправки показано рядом с кнопками.

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

Как отправляется каждый вид:

Вид	Как уходит
OSC	Так же, как отправляет сообщение экран OSC.
UDP (сырой)	Одна датаграмма на адресата.
HTTP	Так же, как отправляет запрос экран HTTP, — с его банкой cookie, пока там включён параметр Хранить cookie. Отказ в соединении или тайм-аут считается ошибкой, а не статусом.
MQTT	Пока экран MQTT подключён к брокеру сигнала — по этому соединению, с его id клиента и учётными данными. Иначе — если соединения нет или оно с другим брокером — Signal Lab подключается к брокеру сигнала ради этой одной публикации, со своим id клиента, без имени пользователя и с чистой сессией, затем отключается.

Соединение считается соединением с брокером сигнала, когда хост тот же (без учёта регистра) и порт тот же, причём 1883 подразумевается для брокера, записанного без порта. Имена не разрешаются: localhost и 127.0.0.1 здесь — два разных брокера, поэтому сигнал, который называет один из них, не отправляется по соединению с другим.

TIP

MQTT-сигнал не хранит пароль. Чтобы публиковать на брокер, который его запрашивает, сначала подключитесь к этому брокеру на экране MQTT; сигнал пойдёт по этому соединению.

Отправка с любого экрана

Нажмите Ctrl+K на любом экране, чтобы открыть палитру, введите несколько букв имени сигнала, его папки, адресата или сообщения и нажмите Enter. Палитра закроется, сигнал будет отправлен, а вы останетесь на экране, за которым наблюдали.

Клавиша	Что делает
Ctrl+K	Открывает палитру или закрывает её.
↑ ↓	Перемещает выбор.
Enter	Отправляет выбранный сигнал.
Esc	Закрывает палитру без отправки.

Палитра показывает не больше 12 сигналов: пока вы ничего не набрали — первые 12 из библиотеки, затем первые 12 подходящих. Щелчок по строке отправляет сигнал; щелчок вне палитры закрывает её.

Создание сигналов

На экране сигналов

1. Выберите папку, в которой должен лежать сигнал (см. текущую папку).
2. Нажмите Новый сигнал. В этой папке появится новый OSC-сигнал на 127.0.0.1:9000 с адресом /hello, он будет выбран.
3. Измените Имя, Транспорт и поля сообщения.

Каждое изменение сохраняется само; кнопки сохранения на этом экране нет. Пока файл библиотеки нельзя прочитать, ничего не сохраняется, а поля доступны только для чтения (см. Файл библиотеки).

Кнопка Дублировать помещает копию сразу после выбранного сигнала, добавляя к его имени ·. Кнопка Удалить спрашивает ещё раз (Удалить?): второй щелчок удаляет сигнал из файла. Его папка остаётся, даже если теперь пуста.

С экранов HTTP, OSC и MQTT

Отправляющая часть трёх экранов — Запрос на экране HTTP, Отправитель на экране OSC, Отправка на экране MQTT — может сохранить то, что отправила бы, как сигнал.

1. Настройте сообщение и отправляйте, пока оно не станет делать то, что нужно.
2. Нажмите Сохранить… (или Ctrl+S в этой части экрана). Откроется диалог Сохранить в библиотеку.
3. Проверьте Имя: оно предлагается по тому, что отправляется.
4. Выберите или введите Папка. Подставляется папка, которой вы пользовались в прошлый раз; путь вроде Venue/Stage, которого ещё нет, будет создан.
5. Нажмите Сохранить.

С этого момента экран связан с этим сигналом. Плашка рядом с кнопками сообщает, где он лежит (❖ Folder / Name); щёлкните её, чтобы увидеть сигнал на экране Сигналы.

Что вы видите	Что это значит	Что можно сделать
✓ Сохранено (серым)	Библиотека хранит ровно то, что отправил бы экран.	Сохранять нечего.
Сохранить и изменено на плашке	Сообщение экрана отличается от сигнала.	Сохранить или Ctrl+S записывает сообщение экрана в этот сигнал; его имя, папка и заметка остаются.
Сохранить как…	—	Снова открывает диалог, заполненный именем и папкой сигнала, и сохраняет новый сигнал. Экран после этого связан с новым.

Сравнение смотрит на сообщение, а не на то, как оно записано: порядок ключей JSON и последние цифры OSC float сверх 32-битной точности изменением не считаются.

Экраны HTTP и OSC сохраняют связь при перезапуске Signal Lab; экран MQTT — до закрытия приложения.

WARNING

HTTP-сигнал хранит содержимое поля Аутентификация — имя пользователя и пароль или токен — в файле библиотеки открытым текстом. Кто может прочитать файл, тот может прочитать и их.

Открытие сигнала на его экране

У выбранного HTTP-, OSC- или MQTT-сигнала есть кнопка, которая открывает его на экране его протокола (HTTP, OSC или MQTT). Поля экрана заполняются из сигнала, и экран связывается с ним, как описано выше: правьте там, отправляйте, затем Сохранить. У сырого UDP-сигнала собственного экрана нет.

Из кадра или топика

• В Инспекторе выберите кадр и нажмите Сохранить как сигнал. Датаграмма становится сырым UDP-сигналом с точными байтами этого кадра; публикация MQTT — MQTT-сигналом с теми же брокером, топиком, QoS, флагом retain и содержимым. Другие кадры сохранить нельзя.
• На экране MQTT выберите топик и нажмите Сохранить как сигнал. Получится MQTT-сигнал, который публикует последнее значение топика, с его QoS и флагом retain, на брокер, к которому вы подключены.

Оба попадают в папку Захвачено и называются по тому, что было захвачено.

В эксперименте

Когда вы добавляете узел в эксперимент, меню Добавить нод показывает и ваши сигналы в группе Сохранённые сигналы. Выбрав один, вы добавляете узел OSC, HTTP, MQTT или UDP с тем же сообщением. Сырой UDP-сигнал с hex-содержимым не предлагается: UDP-узел отправляет текст. См. Узлы.

Папки

Папка — это путь из имён, соединённых через /: API/Auth — папка Auth внутри API. Поле Папка сигнала хранит путь к его папке; пустое значение означает верхний уровень (верхний уровень). Когда вы выходите из поля, имена обрезаются от пробелов, а пустые части отбрасываются, так что API / Auth/ превращается в API/Auth.

Папки сортируются по имени, числа — в числовом порядке (Cue 2 перед Cue 10); сигналы остаются в порядке файла. Каждая папка показывает, сколько сигналов она содержит, включая вложенные папки. Пустая папка сохраняется, пока вы её не удалите.

Текущая папка

Текущая папка — та, по которой вы щёлкнули последней, или папка выбранного сигнала: Новый сигнал и Новая папка создают новое в ней. Плашка над деревом называет её; щёлкните плашку, чтобы вернуться на верхний уровень.

Работа с папками

Чтобы	Сделайте так
Создать папку	Нажмите ＋ Новая папка. Она создаётся внутри текущей папки с именем Новая папка (с номером после него, если имя занято), и вы сразу же её переименовываете.
Открыть или закрыть папку	Щёлкните её или нажмите → / ←, пока она в фокусе. Signal Lab запоминает, какие папки закрыты.
Открыть или закрыть все	Кнопки ⊞ и ⊟ над деревом (Открыть все папки, Закрыть все папки).
Переименовать папку	Нажмите ✎ (Переименовать папку) или F2 на ней, введите имя, затем Enter; Esc отменяет.
Переместить сигнал или папку	Перетащите на папку или на пустое место дерева — на верхний уровень.
Переместить сигнал вводом	Измените его поле Папка.
Удалить папку	Нажмите × (Удалить папку), затем Удалить?, или дважды нажмите Delete на ней.

Переименование никогда не сливает две папки: имя с / внутри или имя, которое уже есть у соседней папки, отклоняется, о чём сообщает консоль. Папку нельзя перетащить в неё саму или в папку внутри неё. Если перетащить папку в папку, где уже есть папка с тем же именем, они сливаются.

Удаление папки удаляет только саму папку: её сигналы и вложенные папки поднимаются на один уровень. Ничто не удаляется.

Поиск сигнала

Введите текст в поле над деревом (Фильтр по имени, папке или цели). Он сопоставляется с именем, папкой, заметкой, адресатом и сообщением. Пока вы фильтруете, каждая папка с совпадением открыта, а остальные скрыты.

Стартовый набор

Когда Signal Lab в первый раз не находит файла библиотеки, он записывает девять примеров, каждый — про то, в чём легко ошибиться. Их имена и заметки пишутся на языке интерфейса в этот момент; дальше вы вольны их менять. Все они нацелены на этот компьютер.

Папка	Сигнал	Что отправляет
OSC	Значение фейдера	/fader/1 с float 0.75 на 127.0.0.1:9000
OSC	Все типы аргументов	/types с int -7, float 1.5, строкой hi, bool true, int64 4294967296, double 0.125 и nil
OSC	Идентификатор и значение	/tag со строками reader-1 и 04a1b2c3
OSC	Триггер без аргументов	/cue/go без аргументов
MQTT	Опубликовать значение	1 в lab/example/value на 127.0.0.1:1883, QoS 0
MQTT	Задать retained-значение	night в lab/example/config, QoS 1, retained
MQTT	Стереть retained-значение	Пустое retained-содержимое в lab/example/config, QoS 1
HTTP	Сервис работает?	GET http://127.0.0.1:8080/, тайм-аут 4000 мс
Сырые данные	Сырые байты UDP	Байты de ad be ef на 127.0.0.1:9000

Чтобы вернуть стартовый набор, переместите или переименуйте signals.json и нажмите Перечитать файл: если файла нет, он записывается заново.

Файл библиотеки

Библиотека — это signals.json в папке данных: Documents/SignalLab в вашей домашней папке на настольном компьютере или папка данных сервера (см. Файлы и папки). Наведите указатель на число сигналов под деревом, чтобы увидеть полный путь.

• Сохраняется само. Каждое изменение записывается через 0,7 с после последнего, сразу всем файлом, через временный файл в той же папке, который затем занимает место файла, — оборванная запись оставляет прежний файл. Пока запись ждёт, внизу дерева написано сохраняю…; затем — сохранено. Запись, которая ещё ждёт, выполняется до того, как обновление перезапустит приложение.
• Правка вручную. Signal Lab не замечает, что файл изменился у него под ногами. После правки или замены файлом с другого компьютера нажмите Перечитать файл. Перечитывание читает файл заново и отбрасывает изменение, которое ещё ждало записи.
• Сломанный файл никогда не заменяется. Если файл — не корректный JSON или не библиотека сигналов, дерево показывает ошибку с путём к файлу, строкой и столбцом, и консоль сообщает то же самое. Файл остаётся как есть, и ничто не записывает библиотеку, пока она снова не прочитается: Новый сигнал, переименование, перемещение и удаление сигналов и папок, перетаскивание, поля сигнала, Сохранить…, Сохранить и Сохранить как… на экранах HTTP, OSC и MQTT, а также Сохранить как сигнал в Инспекторе и на экране MQTT — всё это отключено, а подсказка объясняет, что не так. Исправьте файл или удалите его и нажмите Перечитать файл: как только он прочитается, всё снова заработает.
• Файл, который ломается во время работы приложения. Если вы превратили файл во что-то нечитаемое, а приложение затем сохраняет изменение, сохранение отклоняется с той же ошибкой, файл остаётся таким, каким вы его сделали, и приложение перестаёт записывать, пока вы не исправите файл и не нажмёте Перечитать файл. Файл, который вы правили и оставили корректным, при следующем сохранении заменяется списком приложения, как описано выше: сначала перечитайте.

Короткий пример файла:

{
  "version": 2,
  "signals": [
    {
      "id": "fader-value",
      "name": "Fader value",
      "group": "Venue/Stage",
      "note": "Main fader of desk A.",
      "body": {
        "transport": "osc",
        "target": "127.0.0.1:9000",
        "address": "/fader/1",
        "args": [{ "type": "float", "value": 0.75 }]
      }
    }
  ],
  "folders": ["Venue/Stage", "Venue/Empty for now"]
}

Ключ	Что это
version	2. Файл версии 1 (до папок) читается так же, но без пустых папок.
signals[].id	Составляется из имени при создании сигнала (fader-value, fader-value-2, …) и никогда не меняется при переименовании. По нему сигнал находит signallab fire.
signals[].group	Путь к папке; "" — верхний уровень.
signals[].body	Сообщение. transport — osc, udp, http или mqtt; остальные ключи — поля этого вида.
folders	Все папки, чтобы пустая сохранялась. Опускается, если папок нет. group, которого нет ни в одной записи, — тоже папка.

Из командной строки

signallab fire отправляет сигнал из библиотеки через те же команды, что и приложение:

signallab fire "Fader value"
signallab fire fader-value --library ./show/signals.json

Сначала он ищет сигнал по id, затем по имени без учёта регистра. Если у нескольких сигналов такое имя, он называет их id и ничего не отправляет. Без --library он читает собственный signals.json приложения; файл он никогда не записывает. См. Командная строка.

См. также

• Инспектор — смотреть, что отправляет сигнал, и сохранять захваченный кадр как сигнал.
• Сочетания клавиш
• Файлы и папки — где находится папка данных.