API сценариев wb-rules

API управления девайсами и контролами

Наравне с доступом к контролам через специальную переменную dev есть также API, позволяющий получить возможности, которые недоступны при использовании dev. Например, можно сначала определить виртуальное устройство без контролов и после этого вызывая метод addControl() добавлять динамически к нему необходимые контролы.

Приведённый ниже код при изменении положения переключателя создаст новый контрол, если его в данный момент нет на девайсе и удалит, если он присутствует:

var ctrlID = "myCtrlID";
defineRule({
  whenChanged: ["spawner/spawn"],
  then: function(newValue) {
    if (getDevice("spawner").isControlExists(ctrlID)) {
      getDevice("spawner").removeControl(ctrlID);
    } else {
      var newControl = {type: "text", value: "test-text", readonly: false};
      getDevice("spawner").addControl(ctrlID, newControl);
    }
  }
});

defineVirtualDevice("spawner", {
  title: "spawner",
  cells: {
    "spawn": {
      type: "switch",
      value: false,
    },
  },
});

Здесь использованы методы getDevice() для получения объекта девайса, для этого объекта вызывается метод isControlExists() для проверки на существование контрола с указанным ID. addControl() и removeControl() добавляет и удаляет контрол соответсвенно.

Для получения объекта девайса также можно использовать возврат функции defineVirtualDevice(). Пример выше можно переписать с использованием этого метода следующим образом:

var spawnerDevice;

spawnerDevice = defineVirtualDevice("spawner", {
  title: "spawner",
  cells: {
    "spawn": {
      type: "switch",
      value: false,
    },
  },
});

defineRule({
  whenChanged: ["spawner/spawn"],
  then: function(newValue) {
    if (spawnerDevice.isControlExists(ctrlID)) {
      spawnerDevice.removeControl(ctrlID);
    } else {
      var newControl = {type: "text", value: "test-text", readonly: false};
      spawnerDevice.addControl(ctrlID, newControl);
    }
  }
});

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

Например, чтобы получить доступ по всем контролам девайса "some-device" и вывести их ID и значение ошибки можно использовать такой код:

getDevice("some-device").controlsList().forEach(function (ctrl) {
  log("ctrlID: {}, error: {}".format(ctrl.getId(), ctrl.getError()))
})

Здесь используются методы объекта контрола getId(), который возвращает строковое значения id контрола и getError(), который возвращает строку, содержащуюю текст ошибки или пустую строку при её отсутствии.

У контролов также есть методы-сеттеры, с помощью которых можно устанавливать различные опции. Например, если необходимо при нештатной ситуации установить ошибку на контролле, который не может отобразить данные можно использовать такой код:

runShellCommand("cat /sys/bus/w1/devices/xx-xxxxxxxxxxxx/w1_slave", {
  captureOutput: true,
  exitCallback: function (exitCode, capturedOutput) {
    if (exitCode != 0) {
      getDevice("Temperature").getControl("term1").setError("sensor unreachable");
      return;
    }
    ...
  }
});

Полный список доступных методов для девайсов:

getDeviceId() - возвращает id девайса
getCellId() - возвращает строку "device_id/ctrl_id" для использования с dev[]
addControl() - создаёт новый контрол на девайсе
getControl() - возвращает контрол по id
isControlExists() - возвращает true, если контрол с указанным id существует, иначе - false
removeControl() - удаляет контрол с указанным id
controlsList() - возвращает массив всех контролов на девайсе

Полный список доступных методов для контролов:

getId() - возвращает строку, содержащую id контрола
[get|set]Description() - возвращает/устанавливает строку description
[get|set]Type() - возвращает/устанавливает строку type
[get|set]setUnits() - возвращает/устанавливает строку units
[get|set]Readonly() - возвращает/устанавливает булево значение readonly
[get|set]Max() - возвращает/устанавливает число поля max
[get|set]Error() - возвращает/устанавливает строку поля error
[get|set]Order() - возвращает/устанавливает число поля order