Пример разработки конфигуратора с json-editor

Список страниц по JSON-editor

Описание

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

Анализ функциональности

Что должен делать скрипт wb-rules:
- скрипт должен включать и выключать зуммер в зависимости от настроек, которые задал пользователь.
Какие параметры будут заданы пользователем, а какие будут неизменяемыми:
- будем давать пользователю включать и выключать зуммер;
- не будем давать пользователю настраивать конкретные MQTT топики в которые мы пишем - это будет внутренней скрытой частью от пользователя.
Какой внешний вид будут иметь настраиваемые параметры на странице WEBUI:
- включение и отключение зуммера сделаем с помощью галочки (checkbox).
Какие значения по умолчанию должны быть у параметров:
- галочка должна быть убрана в начале работы, чтобы зуммер внезапно не заработал.

Создание файла JSON схемы для описания формы в WEBUI

Создадим файл в каталоге /usr/share/wb-mqtt-confed/schemas/usr-buzzer.schema.json.

В данном файле содержится только описание внешнего вида формы, которую будет заполнять пользователь в веб-интерфейсе. В нем нет логики работы скрипта и данный файл не знает каким скриптом wb-rules он будет использоваться.

{
  "type": "object",
  "title": "Buzzer configuration",
  "description": "This config may enable or disable buzzer",
  "configFile": {
    "path": "/etc/usr-buzzerConfig.conf",
    "service": "wb-rules"
  },
  "properties": {
    "buzzerStatus": {
      "type": "boolean",
      "title": "status_title",
      "default": false,
      "_format": "checkbox",
      "propertyOrder": 1
    }
  },
  "required": [
    "buzzerStatus"
  ],
  "translations": {
    "en": {
      "status_title": "Turn on the buzzer"
    },
    "ru": {
      "status_title": "Включить зуммер"
    }
  }
}

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

Создание JSON-конфиг файла вручную

Создадим файл в каталоге /etc/usr-buzzerConfig.conf:

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

В первый раз вам нужно вручную создать структуру JSON-файла, которая может выглядеть так:

{
    "buzzerStatus": false
}

Проверка корректности запуска конфига в WEBUI

На данном этапе важно добиться чтобы:

мы увидели новую добавленную конфигурацию на странице "Конфигурационные файлы";
после нажатия на конфиг мы увидели в браузере форму описанную JSON-схемой;
все поля, описания полей и другие элементы отображались корректно;
проверки регулярных выражений, минимальных длин и др. должны отрабатываться корректно и не сохранять конфиг при ошибке;
после настройки параметров мы должны иметь возможность их сохранить;
сохраненные настройки должны корректно записаться в файл конфига.

Конфигуратор «Buzzer configuration» в меню

Откройте Настройки → Конфигурационные файлы.

Наличие созданного конфигуратора «Buzzer configuration» означает, что:

файл схемы существует, иначе конфигуратор бы отсутствовал в списке;
файл схемы корректно прочитан, иначе не прочитался бы title и не смог подставиться в список.

Внешний вид конфигуратора «Buzzer configuration»

Текущий конфиг будет выглядеть следующим образом:

То, что мы видим данную форму означает, что:

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

Сохраняем конфиг с несколькими настроенными объектами

В нашем случае этот шаг не нужен, так как у нас только один параметр:

нет массивов;
нет вариативности включаемых объектов по их структуре.

Создание файла скрипта wb-rules

Затем, нужно написать скрипт wb-rules, который будет читать этот конфиг и в зависимости от значения buzzerEnabled включать или выключать зуммер, используя его контрол MQTT "buzzer/enabled".

Файл расположен в каталоге /etc/wb-rules/usr-buzzer.js:

/**
 * @file Скрипт для управления зуммером на основе конфигурации через json-editor
 * @overview Этот скрипт:
 *             - Читает конфигурацию для зуммера из файла
 *             - Применяет настройки зуммера согласно конфигурации
 * @author Your Name <your.email@example.com>
 * @link Комментарии в формате JSDoc <https://jsdoc.app/>
 */

/**
 * Путь к JSON-конфигурационному файлу
 * @type {string}
 */
var CONFIG_PATH = "/etc/usr-buzzerConfig.conf";

/**
 * Читает конфигурационный файл и возвращает объект конфигурации.
 * @param {string} configPath Путь к конфигурационному файлу.
 * @returns {Object|null} Возвращает:
 *                          - Объект конфигурации, если файл успешно прочитан
 *                          - null, в случае ошибки
 */
function readAndValidateConfig(configPath) {
  log.debug("Input config path: " + configPath);
  var config = readConfig(configPath);

  if (!config) {
    log.error("Error: Could not read config from " + configPath);
    return null;
  }
  log.debug("Input config contain: " + JSON.stringify(config));

  // Проверяем существование поля и его корректность
  if (!config.hasOwnProperty('buzzerStatus') || typeof config.buzzerStatus !== 'boolean') {
    log.error("Error: 'buzzerStatus' does not exist or is not a boolean in the configuration.");
    return null;
  }
  
  // Если конфигурация валидна, возвращаем её
  log.debug("Config valid with buzzerStatus: " + config.buzzerStatus);
  return config;
}

/**
 * Обновляет состояние зуммера на основе переданного конфига
 * @param {Object} config Объект конфигурации, содержащий параметры управления зуммером
 */
function updateBuzzer(config) {
  if (!config) {
    log.error("No valid configuration provided.");
    return;
  }

  // Проверяем значение buzzerStatus и управляем зуммером
  if (config.buzzerStatus) {
    // Включаем зуммер
    dev["buzzer/enabled"] = true;
  } else {
    // Выключаем зуммер
    dev["buzzer/enabled"] = false;
  }
}

function main() {
  var buzzerConfig = readAndValidateConfig(CONFIG_PATH);
  if (!buzzerConfig) return;

  updateBuzzer(buzzerConfig);
}

main();

Тестирование совместной работы конфига и нашего скрипта

Заходим в WEBUI контроллера и проверяем работу конфига следующим образом:

при первом входе на страницу конфигуратора галочка Включить зуммер будет отсутствовать - значит зуммер отключен;
поставьте галочку и нажмите Записать, если зуммер включился, то все работает как надо;
для выключения зуммера снимите галочку и нажмите Записать.

Наблюдение за процессом работы скрипта в логах

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

Результат

Мы создали свой собственный конфигуратор скрипта «Buzzer configuration» в браузере!

Navigation menu