Драйвер Javascript

Fork me on GitHub

Описание

Драйвер JavaScript является главным местом для автоматизации. Он позволяет совершать различные действия при реакции на события.

Информация

 

Актуальная версия
Необходимые условия
Разработчик Bluefox
Ключевые слова
скрипы, правила
Github icon_link Ссылка
Платформа Javascript/Node.js
Лицензия MIT

Установка

Установка осуществляется на вкладке Драйвера странички администрирования системы. В группе драйверов Скрипты и логика находим строчку с названием Javascript/Coffescript Script Engine и нажимаем кнопку со значком плюса в этой строке справа. На экране появится всплывающее окно установки драйвера, в конце установки оно автоматически закроется. Если все прошло удачно, на вкладке Настройка драйверов появится строка javascript.0 с установленным экземпляром драйвера.

Изображение

Создание скриптов

Переходим на вкладку Скрипты:
Изображение

Нажимаем на значок добавления нового скрипта:
Изображение
Даём название скрипту и пишем код скрипта нажимаем “Сохранить” и запустить.

javascript5

Глобальные функции

Вы можете определить глобальные сценарии в “глобальной”(global)  папке. Все глобальные сценарии являются доступными во всех скриптах. Если глобальный сценарий отключен, он не будет использоваться. Глобальный сценарий будет просто вставлен в обычный сценарий и скомпилирован, поэтому вы не сможете обмениваться данными между сценариями c помощью глобального сценария. Используйте для этого состояния (статусы).

Рекомендации:

Создайте два экземпляра адаптера javascript: один “тестовый” и один “рабочий”. После тестирования сценария в экземпляре “тестовый”, он может быть перемещен в “рабочий”. Таким образом вы можете перезапустить “тестовый” экземпляр так, как вы хотите.

В сценарии могут быть использованы следующие функции

require – загрузить какой-либо модуль

Предварительно загружены следующие модули: fs, crypto, wake_on_lan, request, suncalc, util, path, os, net, events, dns.

Для использования других модулей, перейдите в настройки драйвера javascript в админ и введите в поле “Дополнительные NPM Модули” названия пакетов через запятую. После успешного окончания установки, он может быть использован в обработчике сценариев.

Буфер

Буфер – Buffer в Node.js, читайте здесь http://nodejs.org/api/buffer.html

log – Выводит сообщение в журнал

Сообщение является строкой, а параметр критичности одним из: ‘debug’, ‘info’, ‘warn’, ‘error’. По умолчанию критичность – ‘info’

exec – выполнить некоторые команды ОС как например “cp file1 file2”

Выполняет вызов системной команды и возвращает результат.

on – Подписаться на изменения или обновления какого-либо состояния

Функция обратного вызова вернет объект как параметр со следующим содержанием:

Примечание: ранее вместо state был newState. Данная функция еще работает.

Пример:

Вы можете использовать следующие параметры для указания триггера:

параметр тип/значение описание
logic string (строка) логика “and” или “or” для комбинирования условий (по умолчанию: “and”)
id string (строка) имя равнозначно указанному
RegExp имя соответствует регулярному выражению
name string (строка) имя равнозначно указанному
RegExp имя соответствует регулярному выражению
change string (строка) “eq”, “ne”, “gt”, “ge”, “lt”, “le”, “any”
“eq” (равнозначно) Новое значение должно быть равнозначно старому (state.val == oldState.val)
“ne” (неравнозначно) Новое значение должно быть неравнозначно старому (state.val != oldState.val) Если шаблоном является строка id, тогда это значение используется по умолчанию
“gt” (больше) Новое значение должно быть больше, чем старое (state.val > oldState.val)
“ge” (больше или равнозначно) Новое значение должно быть больше или равнозначно старому (state.val >= oldState.val)
“lt” (меньше) Новое значение должно быть меньше старого (state.val < oldState.val)
“le” (меньше или равнозначно) Новое значение должно быть меньше или равнозначно старому (state.val <= oldState.val)
“any” Триггер будет поднят в случае появления любого нового значения
val mixed(оба типа) Новое значение должно быть равнозначно указанному
valNe mixed(оба типа) Новое значение не должно быть равнозначно указанному
valGt mixed(оба типа) Новое значение должно быть больше указанного
valGe mixed(оба типа) Новое значение должно быть больше или равнозначно указанному
valLt mixed(оба типа) Новое значение должно быть меньше указанного
valLe mixed(оба типа) Новое значение должно быть меньше или равнозначно указанному
ack boolean(логический) Подтвержденное состояние нового значения равнозначно указанному
oldVal mixed(оба типа) Предыдущее значение должно быть равнозначно указанному
oldValNe mixed(оба типа) Предыдущее значение не должно быть равнозначно указанному
oldValGt mixed(оба типа) Предыдущее значение должно быть больше указанного
oldValGe mixed(оба типа) Предыдущее значение должно быть больше или равнозначно указанному
oldValLt mixed(оба типа) Предыдущее значение должно быть меньше указанного
oldValLe mixed(оба типа) Предыдущее значение должно быть меньше или равнозначно указанному
oldAck bool(логический) Подтвержденное состояние предыдущего значения равнозначно указанному
ts string (строка) Новая метка времени значения должна быть равнозначна указанной (state.ts == ts)
tsGt string (строка) Новая метка времени значения не должна быть равнозначна указанной (state.ts != ts)
tsGe string (строка) Новая метка времени значения должна быть больше указанного значения (state.ts > ts)
tsLt string (строка) Новая метка времени значения должна быть больше или равнозначна указанной (state.ts >= ts)
tsLe string (строка) Новая метка времени значения должна быть меньше указанной (state.ts < ts)
oldTs string (строка) Предыдущая метка времени должна быть равнозначна указанной (oldState.ts == ts)
oldTsGt string (строка) Предыдущая метка времени не должна быть равнозначна указанной (oldState.ts != ts)
oldTsGe string (строка) Предыдущая метка времени должна быть больше указанной (oldState.ts > ts)
oldTsLt string (строка) Предыдущая метка времени должна быть больше или равнозначна указанной (oldState.ts >= ts)
oldTsLe string (строка) Предыдущая метка времени должна быть меньше указанной (oldState.ts < ts)
lc string (строка) Метка времени последнего изменения должна быть равнозначна указанной (state.lc == lc)
lcGt string (строка) Метка времени последнего изменения не должна быть равнозначна указанной (state.lc != lc)
lcGe string (строка) Метка времени последнего изменения должна быть больше указанного значения (state.lc > lc)
lcLt string (строка) Метка времени последнего изменения должна быть больше или равнозначна указанной (state.lc >= lc)
lcLe string (строка) Метка времени последнего изменения должна быть меньше указанной (state.lc < lc)
oldLc string (строка) Предыдущая метка времени последнего изменения должна быть равнозначна указанной (oldState.lc == lc)
oldLcGt string (строка) Предыдущая метка времени последнего изменения не должна быть равнозначна указанной (oldState.lc != lc)
oldLcGe string (строка) Предыдущая метка времени последнего изменения должна быть больше указанного значения (oldState.lc > lc)
oldLcLt string (строка) Предыдущая метка времени последнего изменения должна быть больше или равнозначна указанной (oldState.lc >= lc)
oldLcLe string (строка) Предыдущая метка времени последнего изменения должна быть меньше указанной (oldState.lc < lc)
channelId string (строка) Код канала должен быть равнозначен указанному
RegExp Код канала соответствует регулярному выражению
channelName string (строка) Имя канала должно быть равнозначно указанному
RegExp Имя канала соответствует регулярному выражению
deviceId string (строка) Код устройства должен быть равнозначен указанному
RegExp Код устройства соответствует регулярному выражению
deviceName string (строка) Имя устройства должно быть равнозначно указанному
RegExp Имя устройства соответствует регулярному выражению
enumId string (строка) Состояние принадлежит указанному перечислению
RegExp Код одного перечисления состояния удовлетворяет указанное регулярное выражение
enumName string (строка) Состояние принадлежит указанному перечислению
RegExp Имя одного перечисления состояния удовлетворяет указанное регулярное выражение
from string (строка) Новое значение из определенного адаптера
fromNe string (строка) Новое значение не из определенного адаптера
oldFrom string (строка) Старое значение из определенного адаптера
oldFromNe string (строка) Старое значение не из определенного адаптера

Примеры: Триггеры по всем состояниям с именем ‘*.STATE’ если они подтверждены(ack=true) и имеют новое значение “true”.

Примечание: вы можете непосредственно использовать RegExp:

Для того, чтобы просто соединить два состояния друг с другом, напишите:

Все изменения stateId1 будут прописаны в stateId2.

Пожалуйста, обратите внимание, что по умолчанию, “change” равняется “any” за исключением случаев, когда код задан как строка (наподобие on("id", function (){});). В последнем случае “change” будет равняться “ne”.

Функция “on” возвращает указатель на обработчик. Этот указатель может быть использован при отмене подписки.

subscribe (подписаться) – то же, что и on

unsubscribe (отменить подписку)

Удалить все подписки для указанного ID объекта или для указанного указателя.

getSubscriptions

Получить список подписок

Пример результата:

schedule (расписание)

Планировщик времени с астро-функцией.

Time schedule (Расписание)

Шаблон может быть строкой с Cron-Syntax, например:

Шаблон может быть объектом, он используется преимущественно в тех случаях, когда требуется указать секунды:

Шаблон может быть объектом данных Javascript (какой-то определенный момент времени) – только в этом случае он может быть активирован/инициирован только один раз.

Примечание: функция расписания поддерживает также и секунды, таким образом вы можете указать:

для активации его каждые две секунды.

Astro- function (Астро-функция)

Астро-функция может быть использована посредством использования аттрибута “astro”:

Атрибут “shift” является смещением в минутах. Он также может быть отрицательным, для определения момента времени перед астро событием.

Следующие значения могут использоваться в качестве атрибута в астро-функции:

  • sunrise: рассвет (верхняя граница солнца появляется на горизонте)
  • sunriseEnd: рассвет заканчивается (нижняя часть солнца касается горизонта)
  • goldenHourEnd: золотой час утра (мягкий свет, лучшее время для фотографии) заканчивается
  • solarNoon: солнечный полдень (солнце находится в своей самой высокой позиции)
  • goldenHour: начинается золотой час вечера
  • sunsetStart: начинается закат (нижняя граница солнца касается горизонта)
  • sunset: закат (солнце скрывается за горизонтом, начинаются вечерние гражданские сумерки)
  • dusk: сумрак (начинаются вечерние навигационные сумерки)
  • nauticalDusk: навигационный сумрак (начинаются вечерние астрономические сумерки)
  • night: начинается ночь (достаточно темно для астрономических наблюдений)
  • nightEnd: ночь заканчивается (начинаются утренние астрономические сумерки)
  • nauticalDawn: навигационная заря (начинаются утренние навигационные сумерки)
  • dawn: заря (заканчиваются утренние навигационные сумерки, начинаются утренние гражданские сумерки)
  • nadir: надир (самый темный момент ночи, когда солнце расположено в своей самой низкой позиции)

Примечание: для использования функции “astro”, в настройках адаптера javascript должны быть определены “latitude”(широта) и “longitude” (долгота).

Примечание: вы можете использовать функцию “on” для расписания с небольшой модификацией:

clearSchedule

Если не используется функция “astro”, вы можете позже отменить расписание. Чтобы это сделать, необходимо сохранить как-нибудь возвращаемый объект:

getAstroDate

Возвращает объект данных javascript к указанному шаблону. Для просмотра допустимых значений шаблонов, пройдите в раздел Astro в функции расписание.

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

isAstroDay

Возвращает значение “истина”, если текущее время находится между астрономическими рассветом и закатом.

compareTime

Сравнивает указанное время с границами.

Если не указано время для сравнения, тогда будет использовано фактическое время.

Возможны следующие операции:

  • > – если указанное время больше значения startTime
  • >= – если указанное время больше или равнозначно startTime
  • < – если указанное время меньше startTime
  • <= – если указанное время меньше или равнозначно startTime
  • == – если указанное время равнозначно startTime
  • <> – если указанное время неравнозначно startTime
  • between – если указанное время между startTime и endTime
  • not between – если указанное время не между startTime и endTime

Время может быть объектом даты или датой со временем, или просто временем.

setState

Пожалуйста, перейдите по ссылке https://github.com/ioBroker/ioBroker/wiki/Adapter-Development-Documentation#commands-and-statuses для объяснения использования “ack”. Вкратце:

  • ack = false : Сценарий хочет отправить команду для того, чтобы её выполнило целевое устройство/адаптер
  • ack = true : Команда была успешно выполнена и состояние обновлено в качестве положительного результата

setStateDelayed

То же, что и setState, но с задержкой в миллисекундах. Вы можете отменить задержку выполнения для данного ID (по умолчанию). Пример:

Эта функция возвращает обработчик таймера и данный таймер может быть остановлен в индивидуальном порядке посредством clearStateDelayed

clearStateDelayed

Удаляет все отложенные задания для заданного ID или некоего заданного отложенного задания.

getState

Вовзращает состояние кода в форме {val: value, ack: true/false, ts: timestamp, lc: lastchanged, from: origin} .

Если состояние не существует, последует возврат следующего объекта: {val: null, notExist: true}

getObject

Получите описание объекта в том виде, как он хранится в системе. Вы можете задать имя перечисления (enum): Если оно задано, тогда два дополнительных атрибута будут добавлены к результату: enumIds и enumNames. Эти массивы имеют все перечисления, членом которых является этот ID. Пример:

getObject ('adapter.N.objectName', 'rooms')

возвращает в enumIds все комнаты, в которых числится запрошенный объект. Вы можете задать enumName как true, чтобы получить обратно все перечисления в которые входит этот ID.

setObject

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

Используйте их подобным образом:

extendObject

Это практически то же самое, что и setObject, но вначале он читает объект и пытается объединить вместе все настройки.

Используйте подобным образом:

getIdByName

возвращает код объекта с указанным именем. При существовании более, чем одного объекта с этим именем, результатом будет массив. Если установлен флажок alwaysArray, результатом всегда будет массив при нахождении ID.

getEnums

Получить список существующих перечислений с такими элементами, как:

createState

Создает состояние и объект в пространстве имён javascript, но только если он не существует, пример “javascript.0.mystate”.

Параметры:

  • name: имя состояния без пространства имен, пример “mystate”
  • initialValue: после создания переменная может быть инициализирована. Значение “undefined” означает, что инициализации значения не проводится.
  • forceCreation: создайте состояние независимо от того, существует ли уже оно или нет.
  • common: общее описание объекта, смотрите описание здесь
  • native: личное описание объекта. Любая конкретная информация.
  • callback: вызов происходит после того, как состояние создано и инициализировано.

Возможно короткое написание createState:

  • createState(‘myVariable’) – просто создается переменная, если она не существует
  • createState(‘myVariable’, 1) – создается переменная, если она не существует, и инициализируется со значением 1
  • createState(‘myVariable’, {name: ‘My own variable’, unit: ‘°C’}, function () {log(‘created’);});
  • createState(‘myVariable’, 1, {name: ‘My own variable’, unit: ‘°C’}) – создается переменная, если она не существует, с заданным именем и единицами

deleteState

deleteState('myVariable')_ - просто удаляется переменная, если она существует

sendTo:

setInterval

То же, что и setInterval  в javascript.

clearInterval

То же, что и clearInterval в javascript.

setTimeout

То же, что и setTimeout в javascript.

clearTimeout

То же, что и clearTimeout в javascript.

formatDate

Параметры:

  • date: количество миллисекунд из state.ts или state.lc (Количество миллисекунд от 1970.01.01 00:00:00) или объект new Date() в javascript или количество миллисекунд от (new Date().getTime())
  • format: Может быть “null”, таким образом будет использован временной формат системы:
    • YYYY, JJJJ, ГГГГ – год полностью, например 2015
    • YY, JJ, ГГ – год сокращенно, например 15
    • MM, ММ(кириллицей) – месяц полностью, например 01
    • M, М(кириллицей) – месяц сокращенно, например 1
    • DD, TT, ДД – день полностью, например 02
    • D, T, Д – день сокращенно, например 2
    • hh, SS, чч – часы полностью, например 03
    • h, S, ч – часы сокращенно, например 3
    • mm, мм(кириллицей) – минуты полностью, например 04
    • m, м(кириллицей) – минуты сокращенно, например 4
    • ss, сс(кириллицей) – секунды полностью, например 05
    • s, с(кириллицей) – секунды сокращенно, например 5
    • sss, ссс(кириллицей) – миллисекунды
    • WW, НН(кириллицей) – день недели полностью текстом
    • W, Н(кириллицей) – день недели сокращенно текстом
    • OO, ОО(кириллицей) – месяц полностью текстом
    • O, О(кириллицей) – месяц сокращенно текстом

Примеры

formatDate(new Date(), "YYYY-MM-DD") => Дата "2015-02-24"

formatDate(new Date(), "hh:mm") => Часы и минуты "17:41"

formatDate(state.ts) => "24.02.2015"

formatDate(state.ts, "JJJJ.MM.TT SS:mm:ss.sss) => "2015.02.15 17:41:98.123"

formatDate(new Date(), "WW") => День недели "Вторник"

formatDate(new Date(), "W") => День недели "Вт"

 

getDateObject

Конвертирует строку или число в объект даты. Если указаны только часы, тогда будет добавлена текущая дата и будет совершена попытка конвертации.

getDateObject(“20:00”) => “Вт Авг 09 2016 20:00:00 GMT+0200”

formatValue

Форматирует любое значение (в том числе и строки) в числа. Заменяет точку запятой, если установлено в системных настройках. Decimals означают количество цифр после запятой. Заданное значение по умолчанию 2. Формат по выбору:

  • ‘.,’: 1234.567 => 1.234,56
  • ‘,.’: 1234.567 => 1,234.56
  • ‘ .’: 1234.567 => 1 234.56

adapterSubscribe

Отправляет сообщение “subscribe” адаптеру для информирования адаптера. Если на адаптере установлен общий флажок “subscribable” в случае функции “subscribe”, данная функция будет вызыватся автоматически.

adapterUnsubscribe

Отправляет сообщение “unsubscribe” адаптеру, чтобы сообщить даптеру не проводить опрос значений.

$ – Selector (селектор)

Формат селектора: ”’name[commonAttr=something1](enumName=something2){nativeName=something3}[id=idfilter][state.id=idfilter]”’

имя может быть: состояние, канал или устройство “idfilter” могут иметь знаки подстановки ‘*’

Префиксы (не внедрено – требует обсуждения) : # – принимаются по имени, а не по коду. – фильтруются по роли § – фильтруются по комнате

Пример:

  • $(‘state[id=.STATE]’) или $(‘state[state.id=.STATE]’) or $(‘*.STATE’) – выберите все состояния, в которых код заканчивается на “.STATE”.
  • $(‘state[id=’hm-rpc.0.]’) или $(‘hm-rpc.0.‘) – вовзращает все состояния экзмепляра адаптера hm-rpc.0
  • $(‘channel(rooms=Зал)’) – все состояния в комнате “Living room(зал)”
  • $(‘channel{TYPE=BLIND}[state.id=*.LEVEL]’) – Получите все границы Homematic
  • $(‘channel[role=switch](rooms=Living room)[state.id=*.STATE]’).setState(false) – Переключите все состояния каналов с .STATE с ролью “переключить” в “Зал” к неправильной позиции
  • $(‘channel[state.id=*.STATE](functions=Windows)’).each(function (id, i) {log(id);}); – напечатайте все состояния перечисления “windows (окна)” в журнале
  • $(‘.switch §”Living room”) – Примите состояния со всеми переключателями в ‘Зал’ (не внедрено – требует обсуждения)
  • $(‘channel .switch §”Living room”) – Примите состояния со всеми переключателями в ‘Зал’ (не внедрено – требует обсуждения)

Объяснение

Давайте взглянем на:

Этот код ищет в каналах. Найти все каналы с common.role=”switch” и принадлежащие к enum.rooms.Зал. Найти все состояния, где код заканчивается на “.STATE и подписаться на все эти состояния. Если некоторые из этих состояний изменяются, то обратный вызов будет осуществлятся как для функции “on”.

Возможны следующие функции, setValue, getValue (only from first), on, each

Вы можете прервать цикл “each” путем возвращения false, например:

readFile

Читает файл из папки “javascript”. Результат будет предоставлен в функции обратного вызова.

writeFile

Выборочный код ошибки будет указан в обратном вызове. fileName является именем файла. Все файлы хранятся в папке “javascript”. Если вы хотите записать в другие папки, например в “/vis.0/”, используйте для этого setFile.

Файл, выглядящий как ‘/subfolder/file.txt’ будет храниться под именем “/javascript/subfolder/file.txt” и будет доступен через веб-сервер http://ip:8082/javascript/subfolder/file.txt

delFile

Удалить файл или директорию.  fileName это имя файла или директории в базе данных.

Эта функция является псевдонимом для unlink.

onStop

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

timeout по умолчанию составляет 1000 миллисекунд.

getHistory

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

Возможные параметры вы можете найти здесь.

Дополнительно к этим параметрам вы должны указать “ID” и вы должны указать время ожидания (по умолчанию: 20000 миллисекунд).

Еще один пример:

Примечание:  разумеется, история должна быть сначала включена для выбранного ID в admin.

runScript

Запускает или останавливает другие сценарии (и себя тоже) по имени. Есть также второй параметр

startScript

То же, что и

stopScript

То же, что и runScript('scriptName', false);

Если stopScript вызывается без аргументов, тогда он сам себя остановит:

isScriptActive

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

name

Это не функция. Это переменная с именем сценария, которая является видимой в области сценария.

instance

Это не функция. Это переменная с экземпляром javascript, которая является видимой в области сценария.

Опция – “Не подписываться на все состояния в начале”

Существует два режима подписки на состояния:

  • Адаптер подписывается на все изменения в начале и получает все изменения всех состояний (легче использовать getStates(id), но требуется больше CPU и RAM):

  • Адаптер подписывается каждый раз на указанный ID, если происходит вызов “on/subscribe”.  В этом режиме адаптер получает только обновления для желаемых состояний. Это более продуктивно и эффективно для RAM, но вы не сможете получить доступ к состояниям напрямую через getState. Вы должны будете использовать функцию обратного вызова для получения результата состояния:

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

Scripts activity / Активность сценариев

Существует возможность включать и отключать сценарии посредством состояний. Для каждого сценария состояние будет создано с именем javascript.INSTANCE.scriptEnabled.SCRIPT_NAME. Сценарии могут быть активированы и деактивированы посредством контроля этого состояния с помощью ack=false.

Примечание

Если в сценарии некоторые модули или функции используются совместно с функциями обратного вызова или циклическими вызовами, за исключением setTimeout/setInterval, тогда они будут вызываться снова и снова даже при условии, что существует новая версия сценария или же он был удален. К примеру, следующий сценарий:

был удален пользователем до того, как вернулся результат. Обратный вызов в любом случае будет выполнен. Для исправления данного свойства, перезапустите драйвер javascript.

Вы можете использовать функцию “cb” для переноса вашего результата, как указано ниже

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