Эта страница является переводом страницы JS Guide. Перевод выполнен на 100%.

Other languages:

Содержание

1 JavaScript API iRidium
2 Общие положения
3 Доступ к объектам интерфейса
4 Доступ к драйверам
5 Доступ к токенам
6 Доступ к звукам
7 Доступ к базам данных Сервера
8 Библиотека анимации
9 Объект iDate
10 Готовые модули iRidium
- 10.1 Кодовый стандарт готовых модулей
11 Книги и сайты по Java Script

JavaScript API iRidium

Руководство разработчика
Справочник » Примеры »

API iRidium - это набор JavaScript функций, позволяющий управлять проектом визуализации iRidium. Чтобы добавить JavaScript в свой проект, следуйте руководству.

Руководство рассчитано на разработчиков, знакомых с программированием на JavaScript и объектно-ориентированной парадигмой разработки. В руководстве описаны основные понятия, используемые в API и методы решения типовых задач управления проектом iRidium.

Обновлено: 30.8.2018
Язык предок: JavaScript
Версия языка: 1.5
Спецификация: ECMAScript Edition 3
Сообщить об ошибке

Все доступные объекты API подробно описаны в справочнике по программному интерфейсу.

Посетите бесплатные обучающие вебинары:

iRidium Script Часть 1: Расширение возможностей управляющего интерфейса

iRidium Script Часть 2: Работа с драйверами iRidium

Создание анимированных элементов в интерфейсах iRidium

Общие положения

JavaScript API iRidium - это набор функций и событий API iRidium и JavaScript 1.5, предназначенных для управления визуальной частью и драйверами в проекте iRidium. API iRidium взаимодействует с приложением i3 pro, которое интерпретирует и выполняет JavaScript файлы. Функции API iRidium ссылаются на объект IR, они доступны только в оригинальном приложении, версия которого соответствует версии API.

Использование API

Чтобы использовать JavaScript, нужно добавить JavaScript файл (*.js) в проект iRidium (*.irpz), разработанный с помощью приложения iRidium Studio.

Файл хранится внутри проекта iRidium и загружается вместе с проектом в приложение i3 pro. Выполнение скрипта начинается при запуске проекта в приложении i3 pro.

Создать JavaScript файл в iRidium Studio:

Откройте iRidium Script Editor
Нажмите "New Script"
Введите имя файла и нажмите ОК

Файл можно экспортировать из проекта iRidium в формате *.js и использовать повторно.

Подключить готовый JavaScript файл в iRidium Studio

Откройте iRidium Script Editor
Нажмите "Add Script from file"
Выберите файл с расширением *.js - он добавится в список JavaScript файлов

Выполнение скрипта

JavaScript файл может содержать необходимый набор функций и событий API iRidium. Функция выполняется в случае срабатывания одного из событий API iRidium. Таким событием может быть запуск приложения, нажатие на графический элемент, получение данных от оборудования и др.

JavaScript файл - это файл с расширением *.js, который прикреплен к проекту
Событие - процесс, проброшенный в скрипты и имеющий идентификатор для отслеживания
Слушатель - это функция, которая выполняется в случае срабатывания указанного ей события
IR - глобальный объект, содержащий в себе все функции и константы API iRidium

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

Слушатель IR.AddListener()

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

Событие - процесс, проброшенный в скрипты и имеющий идентификатор для отслеживания.

Слушатель - это функция, которая выполняется в случае срабатывания указанного ей события

Добавьте слушатель с помощью метода IR.AddListener

IR.AddListener(event, input, action);

event - идентификатор события, за которым следит слушатель
input - входной параметр, необходимый для создания слушателя. Если параметра нет, укажите 0
action - не именованная функция или ссылка на объявленную функцию, внутри которой выполняются действия
pointer - указатель на контекст вызова слушателя (не обязательный). Обратиться к контексту можно с помощью оператора this. Контекст может меняться во время работы программы

Пример 1 (без указания на контекст):

IR.AddListener(IR.EVENT_START, 0, function()
{
    IR.Log("Hello World!")
});

Помимо трех основных параметров слушателя (event, input, action), существует параметр pointer, который позволяет передать из слушателя во внешнюю для него функцию указатель на объект, обслуживающий эту внешнюю функцию.

Пример использования: вызовем с помощью слушателя именованную функцию и передадим в нее ссылку на объект интерфеса, как на контекст выполнения функции. Обратиться к контексту можно с помощью оператора this. Контекст может меняться во время работы программы.

Пример 2 (с указанием на контекст):

var page =  IR.GetItem("Page 1")
for(var i = 0; i < page.ItemsCount; i++)
{
   //  page.GetItem(i) будет контекстом выполнения функции ShowName
   IR.AddListener(IR.EVENT_ITEM_PRESS, page.GetItem(i), ShowName, page.GetItem(i));
} 
function ShowName()
{
   // оператор this позволяет обратиться к контексту: объекту page.GetItem(i)
   IR.Log(this.Name);
}

Подробно об использовании метода IR.AddListener см. в Справочнике.

Глобальный слушатель IR.SetGlobalListener()

Глобальный слушатель выполняется в случае срабатывания указанного ему события. Может работать только с двумя событиями: IR.EVENT_GLOBAL_TAG_CHANGE (срабатывает при изменении любого тега в iRidium) и IR.EVENT_GLOBAL_GUI_CHANGE (срабатывает при любом событии интерфейса).

В отличие от IR.AddListener, глобальный слушатель можно объявить только 1 раз. При повторном объявлении, работать будет только последний слушатель, созданный интерпретатором при запуске скрипта.

Чтобы слушатель сработал при изменении тега в проекте iRidium, на это изменение нужно подписаться методом IR.SubscribeTagChange.

Пример:

// Set global listener
IR.SetGlobalListener(IR.EVENT_GLOBAL_TAG_CHANGE, function(name, value)
{
     IR.Log("Active Global Listener: " + name + "\tValue: " + value);
});
// Subscribe 
IR.SubscribeTagChange("Drivers.KNX IP Router.Address 1"); 
IR.SubscribeTagChange("Drivers.AV & Custom Systems (TCP).Online"); 
IR.SubscribeTagChange("UI.Page 1.Item 1.Text"); 
IR.SubscribeTagChange("System.Time.24");

Команда ScriptCall()

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

В выпадающем списке команды ScriptCall() отображаются функции без входных параметров. С помощью этой команды нельзя передать функции параметры.

Правила выполнения скрипта

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

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

Обычные слушатели можно объявлять несколько раз. Глобальные - только один раз.

Файлы скриптов при запуске проекта работают в одном пространстве имен - не используйте переменные и функции с одинаковыми именами в разных файлах скрипта.

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

Пространство имен

JavaScript файлы в проекте iRidium выполняются в одном пространстве имен, инициализация файлов производится последовательно, сверху вниз. Учитывайте это при выборе имен функций и определении областей видимости. Если в разных JS файлах определена переменная или функция с одинаковым идентификатором (именем), то во время выполнения будет использоваться функция которая была размещена в памяти последняя, т.е. в файле, который находился ниже.

Это не относится к слушателям. Если в проекте определенны слушатели на одинаковые события, выполняются оба.

Редактор JavaScript

Редактор JavaScript служит для создания и размещения JavaScript файлов в проекте iRidium.

Интерфейс редактора:

	Показать дерево скриптов
	новый файл скрипта: создать файл скрипта открыть файл скрипта (*.js)
	удалить выбранный в списке файл скрипта
	переместить вверх/переместить вниз
	установить пароль на просмотр и редактирование файла скрипта (для вступления пароля в силу, необходимо сохранение и повторное открытие проекта)
	применить внесенные в скрипт изменения
	сохранить в файл *.js
	открыть во внешнем редакторе зашифрованные скрипты нельзя открыть во внешнем редакторе
	отменить/вернуть изменение
	Вставить значение цвета в редакторе
	показать/скрыть справку по методам и событиям IR.
	поиск по слову или строке (Ctrl+F)
	включение скрипта в работе клиента
	выключение скрипта в работе клиента (отключенные скрипты помечены серой иконкой)
	ввод пароля
	сброс пароля (для удаления оставьте поле "Set new password" пустым)

Интеллектуальные подсказки

Для ускорения процесса написания скриптов в iRidium Studio встроена система интеллектуальных подсказок, она

Помогает строить правильные цепочки команд
Определяет какую функцию вы сейчас пишете и предлагает доступный для нее набор функций, методов и объектов, что уменьшает количество синтаксических ошибок и ускоряет ввод
Выводит список локальных ресурсов, как список аудио-файлов в проекте

Ctrl + Space - вызвать подсказку, когда она не появляется автоматически

Отладка

Отладка написанного кода в iRidium происходит при помощи встроенного инструмента отладки - консоли вывода iRidium Log. Консоль iRidium Log служит для:

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

Окно iRidium Log можно открыть только на Windows. На iOS и Android работает система удаленной отладки - данные логирования отправляются на удаленный Sysylog Server.

i3 pro для Windows (в отличие от iOS, Android и Mac) позволяет увидеть системный лог прямо в приложении (локальное логирование), а также поддерживает передачу лога на удаленный ПК (удаленное логирование).

Локальное логирование

Лог приложения-клиента i3 pro для Windows вы можете открыть по нажатию F4 в окне приложения (или в Эмуляторе).
Чтобы обеспечить отображение в логе необходимых данных:

1. Укажите глубину логирования систем и подсистем iRidium в iRidium Studio. Настройка производится во вкладке Debug в окне настроек панельного проекта. Глубина логирования подразделяется на уровни от EMERGENCY (только ошибки) до DEBUG (подробная информация);

2. Укажите глубину логирования каждого драйвера, добавленного в проект;

3. Если в вашем проекте есть JavaScript, используйте метод IR.Log("text") для вывода сообщений.

3. Запустите приложение i3 pro или Эмулятор на Windows и нажмите F4, чтобы открыть лог.

Удаленное логирование

Лог i3 pro можно передать на удаленный ПК. Передача производится с помощью программ регистрации системного журнала, обобщенно называемых Syslog Server. Пример такой программы: www.winsyslog.com

Установите и настройте сервер:

1. укажите UDP-порт запуска сервиса: 514, такой же, как в системных настройках i3 pro

2. запустите Syslog Server

Настройте i3 pro для подключения к Syslog Server:

1. На вкладке Debug в окне настроек панельного проекта включите опцию Remote Debugging, укажите Host - IP адрес ПК, где запущен Syslog Server. Порт логирования - 514. Укажите глубину логирования систем и подсистем iRidium в iRidium Studio. Глубина логирования подразделяется на уровни от EMERGENCY (только ошибки) до DEBUG (подробная информация).

2. Укажите глубину логирования каждого драйвера, добавленного в проект.

3. Удаленное логирование i3 pro можно настроить не только в проекте на ПК, но и через системное меню i3 pro. Откройте меню командой Show System Menu по нажатию правой кнопки на панель в iRidium Transfer, длительным нажатием по нерабочей области проекта или свайпом от левого края экрана. Во вкладке Remove debug активируйте удаленное логирование Enable и укажите Host - IP адрес ПК с Syslog Server, порт (514) и уровень логирования.

Выведем данные в лог:

IR.AddListener(IR.EVENT_START, 0, function()
{
      var test = 10;
      IR.Log(test); // 10
});

Иерархия объектов

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

IR - глобальный объект, содержащий в себе все функции и константы API iRidium, верхний уровень иерархии. Список объектов можно увидеть в интеллектуальной подсказке Script Editor. Степень вложенности зависит от объекта, к которому вы хотите обратиться и его уровня в иерархии.

Примеры иерархической структуры:

IR.GetPage("Page 1").GetItem("Item 1").Width = 100; // ссылка на ширину графического элемента

IR.AddListener(IR.EVENT_START,0,test); // создание слушателя

IR.CreateDevice(IR.DEVICE_CUSTOM_HTTP_TCP, "Driver", "myhost.com" 80); // создание HTTP драйвера

IR.GetDevice("Driver").Send(['string\r\n']); // отправка команды

Доступ к объектам интерфейса

Объекты интерфейса - это страницы, попапы и графические элементы проекта iRidium.

Создание объекта

IR.CreateItem(IR.ITEM_BUTTON,"Button", 30, 40, 800, 150);

IR.ITEM_BUTTON - тип_элемента, который создаем
"Button" - имя элемента
30, 40, 800, 150 - базовый (обязательный) набор свойств элемента: Координата_Х, Координата_Y, Ширина, Высота

Типы элементов:

IR.ITEM_BUTTON
IR.ITEM_LEVEL
IR.ITEM_MULTI_STATE_BUTTON
IR.ITEM_MULTI_STATE_LEVEL
IR.ITEM_JOYSTICK
IR.ITEM_EDIT_BOX
IR.ITEM_UPDOWN_BUTTON
IR.ITEM_TRIGGER_BUTTON
IR.ITEM_VIRTUAL_KEY_BUTTON
IR.ITEM_PAGE
IR.ITEM_POPUP
IR.ITEM_LISTBOX
IR.ITEM_STATIC_LISTBOX

Для создания элемента достаточно базового набора параметров. Но у каждого типа элемента есть специфический набор свойств:

Page

страница не имеет специфичных свойств, но может обрабатывать жесты

Popup

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

Button

Active - активен / не принимает нажатие
Hit - тип обработки событий
Password Number - Пароль для активации действий

Trigger Button

Active - активен / не принимает нажатие
Hit - тип обработки событий
Trigger Value 1 - Значение для активации 1-го состояния
Trigger Value 2 - Значение для активации 2-го состояния

Multistate Button

Active - активен / не принимает нажатие
Loop - Цикличное повторение
TimeUp - Время проигрывания анимации вперед
TimeDown - Время проигрывания анимации назад
Hit - тип обработки событий
Password Number - Пароль для активации действий

Up/Down Button

Active - активен / не принимает нажатие
Up/Down Value - Значение на которое увеличивается или уменьшается текущее значение
Max/Min Value - максимальное или минимальное значение
Hit - тип обработки событий

Level

Min - минимальное значение уровня
Max - максимальное значение уровня
Range Type - тип значений
Direction - направление уровня
Focus Look Receive - возможность получения фокуса
Hit - тип обработки событий
Invert - Инверсия, значения наоборот
Slider - графическое представление слайдера
Slider Color - цвет слайдера

Multistate Level

Min - минимальное значение
Max - максимальное значение
Direction - направление уровня
Focus Look Receive - возможность получения фокуса
Hit - тип обработки событий
Invert - Инверсия, значения наоборот

EditBox

Active - активен / не принимает нажатие

Virtual Key

Active - активен / не принимает нажатие
Key Type - тип ключа
Key Action - действие которое будет выполнять ключ

Joystick

Range Type - тип значений
Active - активен / не принимает нажатие
Focus Look Receive - возможность получения фокуса
Hit - тип обработки событий
MinX - минимальное значение X
MinY - минимальное значение Y
InvertX - инверсия по оси X
InvertY - инверсия по оси Y
Cursor - графическое изображение курсора, можно задать из-под скрипта
Cursor Color - цвет курсора

Обращение к объекту

Доступ к объектам графического интерфейса производится в соответствии с их иерархией. Получить доступ к объекту интерфейса можно:

Через указание элемента верхнего уровня:

IR.GetItem("Page 1").GetItem("Item 1").GetState(0).FillColor

GetPage("Page 1") - страница
GetItem("Item 1") - элемент на странице
GetState(0) - состояние элемента, отсчет с нуля
FillColor - свойство состояния

Через указание страницы:

IR.GetPage("Page 1").GetItem("Item 1").Value

GetPage("Page 1") - страница
GetItem("Item 1") - элемент на этой странице
Value - свойство элемента

Через указание попапа:

IR.GetPopup("Popup 1").GetItem("Item 1")

GetPopup("Popup 1") - попап
GetItem("Item 1") - элемент на этом попапе

Через обращение к элементу на текущей странице:

IR.CurrentPage.GetItem("Item 1")

IR.CurrentPage - текущая страница
GetItem("Item 1") - элемент на текущей странице

Через переменную, которая хранит ссылку на объект:

var item = IR.GetPage("Page 1").GetItem("Item 1")

var item - переменная которой мы присваиваем элемент
IR.GetPage("Page 1") - страница
GetItem("Item 1") - элемент на странице

IR.AddListener(IR.EVENT_START,0,function()
{
   IR.GetItem("Page 1").GetItem("Item 1").Width = 100; // обращение через GetItem("Item_Name")
   IR.GetPage("Page 1").GetItem("Item 1").Height = 50; // обращение через GetPage("Page_Name")
   IR.GetPopup("Popup 1").GetItem("Item 1").Text = "This is text"; // обращение через GetPopup("Popup_Name")
   IR.CurrentPage.GetItem("Item_Name").Text = "This is item on current page"; //Обращение к текущей странице
   var item = IR.GetPage("Page_Name") // запись идентификатора объекта в переменную
   item.X = 20; // обращение к свойству объекта через переменную
});

У элемента может быть несколько состояний, и у каждого состояния есть свои свойства.

Поэтому, для обращения к свойству состояния следует использовать инструкцию GetState(State_Number), где State_Number - это номер стейта, нумерация начинается с нуля:

IR.AddListener(IR.EVENT_START,0,function() 
{
     // присвоить текст второму состоянию элемента. Нумерация начинается в нуля, State 2 = GetState(1) 
     IR.GetItem("Page 1").GetItem("Item 1").GetState(1).text = 'state 2';
});

События интерфейса

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

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

Число любых слушателей в проекте не должно превышать 1024.

Примеры событий: нажатие на элемент, появление клавиатуры, поворот устройства.

// событие сработает при нажатии на элемент Item 1, который расположен на странице Page 1
IR.AddListener(IR.EVENT_ITEM_PRESS, IR.GetItem("Page 1").GetItem("Item 1"), function ()
{
    IR.HidePopup("Popup 1"); // закрытие попапа по имени
});

IR.EVENT_ITEM_PRESS - событие, которое активирует слушатель. список событий:

IR.EVENT_ITEM_PRESS
IR.EVENT_ITEM_RELEASE
IR.EVENT_ITEM_SELECT
IR.EVENT_ITEM_CHANGE
IR.EVENT_ITEM_HOLD
IR.EVENT_ITEM_SHOW
IR.EVENT_ITEM_HIDE
IR.EVENT_MOUSE_DOWN
IR.EVENT_MOUSE_UP
IR.EVENT_MOUSE_MOVE
IR.EVENT_TOUCH_DOWN
IR.EVENT_TOUCH_UP
IR.EVENT_TOUCH_MOVE
IR.EVENT_GESTURE_BEGIN
IR.EVENT_KEYBOARD_SHOW
IR.EVENT_ORIENTATION
IR.EVENT_APP_ENTER_BACKGROUND
IR.EVENT_APP_ENTER_FOREGROUND
IR.EVENT_APP_WILL_TERMINATE
IR.EVENT_RECIEVE_NOTIFY
IR.EVENT_RECIEVE_QR_CODE
IR.EVENT_RECIEVE_SCHEME
IR.ANDROID_MENU_PRESS
IR.ANDROID_BACK_PRESS
IR.BACKGROUND_OFF
IR.BACKGROUND_ON

События мыши нельзя использовать на устройствах, у которых нет мыши , например, на планшетах или смартфонах. Событие TOUCH работает только на устройствах, оснащенных сенсорным экраном

Доступ к драйверам

Драйверы используются для взаимодействия с оборудованием автоматизации, удаленными серверами и др. действий, требующих создания TCP, UDP, HTTP(s), RS232 соединения. С помощью iRidiumScript вы можете:

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

Создание драйвера

Создать можно драйвер с типом AV & Custom Systems на базе транспорта TCP, HTTP или UDP со свободной настройкой. Также есть возможность создания TCP и UDP сервера на базе AV & Custom Systems. Драйверы этого типа могут обрабатывать произвольные данные и отправлять произвольные команды. На основе AV & Custom Systems делают драйверы для управления оборудованием, которое не поддерживается iRidium изначально.

Драйверы AMX, KNX, BAOS, Global Cache, Crestron - тоже можно создать через скрипт, но им нельзя отправить произвольные данные. Команды этим драйверам формируются по строгим правилам, которые перечислены в описании команды Set: IR.GetDevice("driver").Set("name", "data")

Для обращения к драйверам, которые нельзя создать из скрипта, создайте драйвер и команды в iRidium Studio > Project Device Panel (обычным способом, описанным в инструкции iRidium для вашего оборудования).

Команда создания драйвера:

var driver = IR.CreateDevice(IR.DEVICE_CUSTOM_TCP, "AV Device (TCP)",	
			{Host: "192.168.0.47",
			Port: 80
			});
IR.Log(driver);

IR.DEVICE_CUSTOM_TCP - тип драйвера из списка доступных
"AV Device (TCP)" - имя драйвера, строка
"192.168.0.100" - адрес, к которому должен подключиться драйвер
8080 - порт подключения

У каждого драйвера набор параметров подключения специфичен. См. подробное описание в справочнике.

Типы драйверов (Device Type):

IR.DEVICE_CUSTOM_TCP
IR.DEVICE_CUSTOM_UDP
IR.DEVICE_CUSTOM_HTTP_TCP
IR.DEVICE_CUSTOM_SERVER_TCP
IR.DEVICE_CUSTOM_SERVER_UDP
IR.DEVICE_AMX
IR.DEVICE_EIB_UDP
IR.DEVICE_BAOS_1
IR.DEVICE_BAOS_2
IR.DEVICE_CRESTRON
IR.DEVICE_GLOBAL_CACHE
IR.DEVICE_UPNP_CONTROL

Драйвер подключается к указанному адресу сразу после создания. Если вы не хотите, чтобы драйвер подключался к оборудованию, оставьте адрес подключения ("host") пустым.

Обращение к драйверу

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

IR.GetDevice("driver_name");

Ссылку на объект - драйвер, можно присвоить переменной:

var driver = IR.GetDevice("driver_name");
driver.Disconnect();

Управление драйвером

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

var driver = IR.GetDevice("driver_name");
driver.Disconnect(); // отключиться от оборудования
driver.SetParameters({Host: "192.168.0.21", Port: "9090"}); // изменить настройки подключения
driver.Connect(); // подключиться к оборудованию

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

Отправка команд

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

Метод Send:

IR.GetDevice("Device_Name").Send(['send string\r\n']);

- можно использовать только с драйвером на базе AV & Custom Systems. Метод позволяет отправить оборудованию произвольную строку или число (DEC, HEX, ASCII). Строка формируется с использованием документации к оборудованию, которым вы хотите управлять. Метод Send работает только с AV & Custom Systems!

Данные для отправки формируются прямо в скрипте и не связаны с командами из iRidium Studio > Project Device Panel, созданными обычным методом.

Метод Send для драйверов с несколькими транспортами:

IR.GetDevice("Device_Name").Send(['send string\r\n'], transport_id);

transport_id - число от 0 до n, означает номер транспорта, в который нужно отправить команду. 0 - отправить всем, 1...n - отправить конкретному ID

- к драйверам с несколькими транспортами относится Global Cache, т.к. он использует порты 4998, 4999, 5000. Также несколько транспортов использует AV & Custom Systems TCP Server и UDP Server, т.к. к ним может подключиться несколько клиентов, каждый из которых открывает свой сокет, к которому можно обратиться.

Метод Set:

IR.GetDevice("Device_Name").Set("command_name", 100);

"command_name" - имя команды в Project Device Panel
100 - число, которое нужно передать команде с указанным именем. Так же можно передать строку

- можно использовать с любым драйвером iRidium, который вы создали в iRidium Studio > Project Device Panel. Команды нужно заранее создать и настроить в дереве проекта, затем их можно вызвать в любой момент и передать им любое значение. Если команду нужно просто активировать без передачи значения, синтаксис будет: IR.GetDevice("Device_Name").Set(["command_name", ""]);

Получение и разбор данных

Драйверу AV & Custom Systems, созданному в скриптах или в Project Device Panel, могут прийти любые данные, т.к. заранее не определено, к какому оборудованию он подключается. Всем остальным драйверам iRidium приходят данные в определенном формате, о котором iRidium уже знает.

Отсюда возникает два метода разбора полученных данных:

метод для произвольных данных AV & Custom Systems
метод для данных, которые пришли в заранее настроенные Feedbacks в дереве проекта (Project Device Panel)

Обработка производится с помощью слушателя, который реагирует на событие получения данных (для AV & Custom Systems) и на изменение канала обратной связи (для всех остальных драйверов).

IR.EVENT_RECEIVE_TEXT и IR.EVENT_RECEIVE_DATA

var driver = IR.GetDevice("AV Control") // указываем имя драйвера
// слушатель реагирует на получение данных
IR.AddListener(IR.EVENT_RECEIVE_TEXT, driver, function(text) 
{  
    IR.Log(text) // выводим полученные данные в лог
    // данные можно обработать внутри этого слушателя
});

IR.EVENT_RECEIVE_TEXT - определяет, в каком виде будет отображаться полученная информация

IR.EVENT_RECEIVE_TEXT - текстовый формат
IR.EVENT_RECEIVE_DATA - битовый формат

эти методы работают только с драйверами AV & Custom Systems. Их нельзя использовать с другими драйверами! Методы возвращают строку или битовую последовательность, полученную драйвером.

IR.EVENT_TAG_CHANGE

// указываем имя драйвера
// событие срабатывает при изменении тегов настроенных в проекте, вкладка Feedbacks
IR.AddListener(IR.EVENT_TAG_CHANGE, IR.GetDevice("driver_name"), function(name, value) 
{  
    IR.Log(name+" : "+value) // в лог выводим имя тега и его новое значение
});

Этот метод работает с любым драйвером, кроме AV & Custom Systems. Метод возвращает имя канала, который изменился, и его новое значение. Канал должен быть создан в дереве проекта обычным методом (во вкладке Feedback драйвера).

Доступ к токенам

Токен - переменная, не связанная с командами оборудованию автоматизации. Токен хранит данные о работе iRidium, к которым можно обратиться. Различают токены трех видов:

Токены проекта

Project Tokens - именованные переменные, которые можно создать в iRidium. В переменную можно записать строку, число, массив данных и обратиться к этим данным с помощью Relations (связей) графических элементов или через API iRidium. Информацию в переменных можно сохранять между запусками приложения iRidium на панели управления.

хранятся в Дереве устройств проекта - Project Device Panel
можно создать командой API iRidium в процессе работы приложения
можно записать число или строку, массив (DEC, ASCII).
можно создавать, удалять, делать копии, сортировать между собой и группировать по папкам
данные в переменных можно сохранять после закрытия приложения iRidium
записать данные можно командой с элемента или из iRidium Script

Создание токена, запись значений

Используйте функцию IR.SetVariable для записи значений в Project Tokens.

Если токена, в который записывается значение, нет в проекте, он будет автоматически создан вызовом IR.SetVariable

IR.SetVariable("Tokens.TokenName", value)

Tokens. - указатель на обращение к токену проекта. Можно также использовать обращение Global.
TokenName - имя токена в Project Tokens на панели Project Device Panel
value - любое значение (число, строка, массив чисел, массив строк)

Пример:

IR.AddListener(IR.EVENT_START, 0, function()
{
    // создадим токен test (его нет в Project Device Panel) и запишем в него число 23
    IR.SetVariable("Tokens.test", 23); 
    // выведем данные из токена в консоль
    IR.Log(IR.GetVariable("Tokens.test")); // 23
});

Запись массивов в Projects Token и их извлечение см. в примерах использования JavaScript API

Чтение значений

Используйте функцию IR.GetVariable для чтения значений в Project Tokens.

Если токен ранее не существовал, он вернет undefined. Если токен был создан в Project Device Panel, но значение в него не было записано, он вернет undefined

IR.GetVariable("Tokens.TokenName")

Tokens. - указатель на обращение к токену проекта. Можно также использовать обращение Global.
TokenName - имя любого токена находящегося в папке Project Tokens в панели Project Device Panel

Пример:

IR.AddListener(IR.EVENT_START, 0, function()
{
IR.SetVariable("Tokens.test", 23); 
var gTest = IR.GetVariable("Tokens.test");
IR.Log(gTest); // 23
});

загрузить:
пример записи и извлечения массива из Project Token

Системные токены

System Token - возвращает значение системных параметров панели управления: время, дата, заряд батареи, координаты GPS и др. Токен можно привязать к любому графическому элементу, и он будет выводить в него полученную информацию.

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

Обращение к токену

Используйте команду IR.GetVariable чтобы получить данные из системного токена:

IR.GetVariable("System.Time.Seconds")

System. - указатель на тип переменной, которую нужно получить: системная переменная
Time.Seconds - название системной переменной, такое же, как в Project Device Panel

пример:

IR.AddListener(IR.EVENT_START, 0, function()
{
var time = IR.GetVariable("System.Time.Seconds");
IR.Log(time);
});

Полный список системных токенов см. в справочнике.

Токены драйвера

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

IR.AddListener(IR.EVENT_START, 0, function()
{
// Driver Tokens
    var tag1 = IR.GetVariable("Drivers.AV & Custom Systems.Online");  // Online..Offline = 1..0
    var tag2 = IR.GetVariable("Drivers.AV & Custom Systems.Status");  // Offline..Connecting..Online..Waiting = 0..1..2..3
    var tag3 = IR.GetVariable("Drivers.AV & Custom Systems.Host");  // domain name of remote equipment
    var tag4 = IR.GetVariable("Drivers.AV & Custom Systems.HostPort");  // port of remote device
    var tag5 = IR.GetVariable("Drivers.AV & Custom Systems.IP");  // IP address of Control Panel
    var tag6 = IR.GetVariable("Drivers.AV & Custom Systems.HostIP");  // IP address of remote equipment
    var tag7 = IR.GetVariable("Drivers.AV & Custom Systems.Port");  // local port on Control Panel
});

Доступ к звукам

iRidium может воспроизводить аудио-файлы в нескольких потоках - слотах. Через API iRidium доступен:

запуск и остановка воспроизведения аудио-файла
остановка звук в слоте и во всех слотах
зацикливание звука
управление громкостью

Чтобы воспроизвести аудио-файл, нужно заранее добавить его в Галерею проекта, вкладка Sound.

Подробное описание всех функций управления звуком см. в справочнике.

Доступ к базам данных Сервера

База данных SQL формируется в iRidium Server вместе с серверным проектом. Она позволяет сохранить состояние перемененных Сервера для построения графиков и создания логов. Существует два вида базы:

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

скачать:

пример формирования пользовательской базы данных

Все методы работы с базами см. в DataBase API.

Системная база данных

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

База состоит из таблиц:

FLOAT_TAG_HISTORY - теги, в которые было записано десятичное число
INTEGER_TAG_HISTORY - теги, в которые было записано целое число
PROJECTS - какие проекты загружены на сервер
QUALITY_LIST - [reserved]
STRING_TAG_HISTORY - теги, в которые записана строка
TAG_STATUSES - [reserved]
TAG_TYPES_LIST - [reserved]
TAGS_PASSPORT- все типы тегов (string, integer, float)
VERSION - [reserved]

Обращение к системной базе данных. Все методы работы с базами см. в DataBase API.

// присвоили переменной sql свойства системной базы
var sql = IR.GetDatabase(); 
// создадим запрос по базе
// присвоим переменной examp свойство Request базы sql. В кавычках тело запроса
var examp = sql.Request('SELECT ...'); 
IR.Log(examp.Columns); // количество полей (столбцов) в запросе
IR.Log(examp.Rows); // количество записей (строк) в запросе
IR.Log(examp.GetRowValue(0,1)); // значение ячейки в строке 1 и столбце 2
IR.Log(examp.GetColumnName(0)); // имя поля, у которого индекс соответствует числу в скобках

Пример: выбрать из базы информацию о тегах, которые содержат значение < 1500

var i;
var j;
IR.AddListener(IR.EVENT_START,0,function()
{
var sql = IR.GetDatabase();
var examp = sql.Request('SELECT DISTINCT(ID), VALUE, TAG_ID FROM FLOAT_TAG_HISTORY WHERE VALUE<1500'); 
for (i=0;i<examp.Columns;i++) // организовали цикл для вывода значений
   for (j=0;j<examp.Rows;j++)
   {
      IR.Log(examp.GetRowValue(i,j)); // выводим в лог значения полей
   };  
});

Пользовательская база данных

Можно создать базу данных и добавить/обновить/удалить её таблицы/поля/значения. Свойства базы данных необходимо записать в переменную JavaScript, после чего вы получите доступ к ее свойствам. Обращение к базе производится с помощью SQL запросов.

Все методы работы с базами см. в DataBase API.

Cоздадим базу данных, new SQL() - определение базы в JavaScript API iRidium

var mybase = new SQL();

Cоздадим файл базы, с которым будем в дальнейшем работать

mybase.Open('Example.db');

.Open - открыть файл базы. Если такого файла нет, то он будет создан в папке документов программы. Например C:\Users\UserName\Documents\iRidium mobile 3\Settings\ Server\Database\Example.db - имя базы с расширением.

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

mybase.Execute("BEGIN");
...
// actions with DataBase
...
mybase.Execute("COMMIT");
mybase.Close();

.Execute - функция выполнения действия с базой
"BEGIN" - начало записи в базу
"COMMIT" - конец записи в базу
.Close() - закрытие базы

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

mybase.Execute('CREATE TABLE Info(ID int, Value double, Name string)');

CREATE TABLE - функция создания таблицы с именем Info
ID, Value, Name - имена полей таблицы, которые будут содержать значения типа int, double, string соответственно. Вы можете менять имена полей, но должны обязательно указывать тип поля.

Чтобы произвести запись в базу, воспользуйтесь структурой:

mybase.Execute('INSERT INTO Info(ID, Value, Name) VALUES(1,2.5,"sunny day")');

INSERT INTO осуществляет запись в таблицу Info, а именно в поля ID, Value, Name. VALUES - параметры, которые будут записаны в поля. Соответственно в поле ID будет записано число 1, в поле Value будет записано число 2.5, в поле Name текст "sunny day".

Параметров в скобках после VALUE должно быть столько же, сколько и объявленных полей в скобках после INSERT INTO <Имя таблицы>().

Особенности записи значений в поля таблицы

Текст пишите в двойных кавычках:

VALUES("iRidium", "Mobile");

Число пишите без кавычек, десятичное число - через точку:

VALUES( 1, 2.5, 36.788);

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

// var CV; 
// var V;
...
VALUES( '+CV+', '+V+' );

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

Для создания запросов к базе ознакомьтесь с языком SQL. Запросы необходимы, когда есть определённые условия отбора данных из базы. Все методы работы с базами см. в DataBase API.

Например: из базы с информацией о погоде возьмем день, час и минуту, когда температура была > 10 градусов:

// создали переменную и присвоили ей объект sql.Request, в скобках указали тело запроса
var RecordSet = sql.Request("select * from TEST WHERE grades>10");
function inquiry()       
{    
    sql.Open('weather.db'); // открыть базу данных "weather.db"
    sql.Execute("BEGIN");    
    var RecordSet = sql.Request("select * from TEST WHERE grades>10");       
    // вывод в лог имена полей с 1 по 3
    IR.Log(RecordSet.GetColumnName(0) +'\t'+ RecordSet.GetColumnName(1) +'\t'+ RecordSet.GetColumnName(2));
    for (i=0;i<RecordSet.Rows;i++)   // цикл будет выводить данные по строкам
    IR.Log(RecordSet.GetRowValue(0,i)+'\t'+RecordSet.GetRowValue(1,i)+'\t' + RecordSet.GetRowValue(2,i));   
    sql.Execute("COMMIT"); // конец работы с базой          
    sql.Close();    
};      
IR.SetInterval(60000, inquiry); // вызов функции каждую минуту

Библиотека анимации

посетить бесплатный обучающий вебинар

Библиотека анимации - это готовый JavaScript файл, который содержит набор функций и методов для анимации элементов в вашем проекте.

Стандартные методы основаны на использовании по кадровой анимации и смены состояний элемента. Библиотека анимации iRidium позволяет создать сложные эффекты для отдельных элементов и групп.

Актуальная версия библиотеки и инструкции

Объект iDate

iDate - это представление даты в виде 64 битного числа с плавающей запятой. Может оперировать датами и временем в диапазоне от 1 января 100 года до 31 декабря 9999 года.

Целая часть означает количество дней с 30 декабря 1899 года, т.е. число 2 будет означать 1 января 1900 года. Чтобы указать даты до 30 декабря 1899 года, используйте отрицательное число, например -1 будет обозначать 29 января 1899 года.

Дробная часть определяет время. Чтобы увеличить время на 1 час нужно прибавить 1/24, чтобы прибавить 1 минуту: 1/1440. Недостатком объекта является низкая точность при работе с миллисекундами, погрешность составляет +/-150 миллисекунд.

iDate без аргументов

При создании без аргументов, создается объект, который инициализируемый текущей датой и временем.

var date = new iDate();
IR.Log("Date " + date.year + "." + date.month + "." + date.days);
IR.Log("Time " + date.hours + ":" + date.minutes + ":" + date.seconds + "." + date.ms);
IR.Log("Value " + date.value);
/*
   result:
   Date 2014.11.29
   Time 20:49:20.778
   Value 41972.86760159722
*/

iDate c 1 аргументом

Аргументом является value - число с плавающей запятой, обозначающее совмещенное представление даты и времени.

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

// создадим объект iDate, передав ему целое положительное число.
var d1 = new iDate(16384);
IR.Log("Date 1 " + d1.year + "." + d1.month + "." + d1.date);
IR.Log("Time 1 " + d1.hours + ":" + d1.minutes + ":" + d1.seconds + "." + d1.ms);
IR.Log("Value 1" + d1.value);
/* 
   result:
   Date 1 1944.11.8
   Time 1 0:0:0.0
   Value 1 16384
*/
// создадим объект iDate, передав ему целое отрицательное число.
var d2 = new iDate(-16384);
IR.Log("Date 2" + d2.year + "." + d2.month + "." + d2.date);
IR.Log("Time 2" + d2.hours + ":" + d2.minutes + ":" + d2.seconds + "." + d2.ms);
IR.Log("Value 2" + d2.value);
/* 
   result:
   Date 2 1855.2.20
   Time 2 0:0:0.0
   Value 2 -16384
*/

iDate более чем с 1 аргументом

Аргументы:

year - год
month - месяц
date - день
hours - часы
minutes - минуты
seconds - секунды
ms - миллисекунды

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

// создание  объекта iDate, с текущими значениями даты и времени.
var cur = new iDate();
IR.Log("Cur Date " + cur.year + "." + cur.month + "." + cur.date);
IR.Log("Cur Time " + cur.hours + ":" + cur.minutes + ":" + cur.seconds + "." + cur.ms);
IR.Log("Cur Value" + cur.value);
/* 
   result:
   Cur Date 2014.11.29
   Cur Time 21:6:45.128
   Cur Value41972.879688981484
*/
// создание  объекта iDate, с указанием года, месяца и числа
var date2 = new iDate(1999, 1, 21);
IR.Log("Date 2 " + date2.year + "." + date2.month + "." + date2.date);
IR.Log("Time 2 " + date2.hours + ":" + date2.minutes + ":" + date2.seconds + "." + date2.ms);
IR.Log("Value 2 " + date2.value);
/* 
   result:
   Date 2 1999.1.21
   Time 2 21:6:45.133
   Value 2 36181.87968903935
*/
// создание объекта iDate, с указанием года, месяца, числа, часа и минуты
var date4 = new iDate(1999, 1, 21, 4, 16);
IR.Log("Date 4 " + date4.year + "." + date4.month + "." + date4.date);
IR.Log("Time 4 " + date4.hours + ":" + date4.minutes + ":" + date4.seconds + "." + date4.ms);
IR.Log("Value 4 " + date4.value);
/* 
   result:
   Date 4 1999.1.21
   Time 4 4:16:45.138
   Value 4 36181.17830020833
*/
// создание  объекта iDate, с указанием года, месяца, числа, часа, минуты, секунды и миллисекунды
var date6 = new iDate(1999, 1, 21, 4, 16, 12, 400);
IR.Log("Date 6 " + date6.year + "." + date6.month + "." + date6.date);
IR.Log("Time 6 " + date6.hours + ":" + date6.minutes + ":" + date6.seconds + "." + date6.ms);
IR.Log("Value 6 " + date6.value);
/* 
   result:
   Date 6 1999.1.21
   Time 6 4:16:12.400
   Value 6 36181.177921296294
*/

Готовые модули iRidium

Модули iRidium - это готовые проекты iRidium с JavaScript файлами, которые созданы iRidium Mobile или сторонними разработчиками. Их можно объединять со своим проектом iRidium для использования дополнительного функционала без самостоятельного программирования.

В зависимости от назначения (часы, отображение погоды, календарь, управление аудио-видео и др.) модуль может требовать или не требовать лицензии iRidium. Информация об этом обычно указана в описании модуля.

Любой модуль, использующий драйвер AV & Custom Systems, или другой драйвер, требует лицензии. Модуль, использующий в работе слушатели IR.EVENT_RECEIVE_TEXT и IR.EVENT_RECEIVE_DATA требует лицензии с суффиксом "Pro" в названии.

Инструкции по использованию доступны не для всех модулей. Общий порядок использования:

скачайте модуль (файл проекта с расширением *.irpz)
откройте модуль в iRidium Studio
откройте в iRidium Studio проект, куда нужно добавить модуль
в окне Project Overview перетяните модуль в свой проект - они объединятся
используйте страницы и окна модуля как часть своего проекта

видео:
объединение проектов iRidium

Кодовый стандарт готовых модулей

Соглашение по именованию:

0. Выделение слов - смена регистра символов (camel case), Табуляция - 3 знака, не пробелы.

1. Функции - конструкторы, работающие с оператором new именуются с большой буквы

function AbstractDriver () {
};
var Driver_1 = new AbstractDriver ();

2. Функции, и публичне функции - методы объекта с маленькой буквы

function updateRequest () {
};
function AbstractDriver () {
    this.getData () {
    };
};
var Driver_1 = new AbstractDriver ();
Driver_1.getData ();

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

function AbstractDriver () {
    this._getPassword () {
    };
    _prepare = function () {
    }
    _prepare (); // private method
};
var Driver_1 = new AbstractDriver ();
Driver_1._getPassword (); // temporary API method

4. Имена свойств с маленькой буквы

var lastIndex = 0;

5. Константы - все знаки в верхнем регистре, выделение слов знаком нижнего подчеркивания

var EVENT_GENERATED_END = 0;

6. Входящие параметры функций, префикс in_, первый слог с маленькой буквы

function resizeProject (in_width, in_height) {
};

7. Выходящие параметры функций, префикс out_, первый слог с маленькой буквы

function checkConnection () {
    return out_status;
};

8. Пространство имен, все знаки в верхнем регистре

KNX = {};

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

function name (in_arg1, in_arg_2) {
    return out_arg;
};

10. Точка запятой: в конце строки, после закрывающей фигурной скобки

11. Документирование методов, конструкторов

/**
* Purpose of the function - the method appointment
*
* @namespace Name of the namespace - name of space
* @method / @onstructor Name of the function - name of method or constructor
* @param  {Type} Description - input data
* @return {Type} Description - output data
*/
/**
* Create the data base of the app
*
* HDL
* @method createDataBase
* @param  {String} Path of the file
* @return {Boolean} Success of the action
*/
function createDataBase (in_path) {
    return out_result;
};

Книги и сайты по Java Script

Если вы еще не сталкивались с языком Java Script и не имеете представления об объектно-ориентированной парадигме разработки, рекомендуем посещение информационных сайтов и изучение литературы. Здесь перечислены сайты, которые нравятся нам, вы всегда можете найти для себя более подходящий ресурс.

Сайты:

http://learn.javascript.ru/ (RUS)
http://www.codecademy.com/ (RUS/ENG)
http://www.w3schools.com/js/default.asp (ENG)
http://help.dottoro.com/ljsdaoxj.php (ENG)
http://mas-html.narod.ru/js01.htm (RUS)

Книги: "Eloquent JavaScript"
Уровень знаний: начальный, язык: ENG, автор: Marijn Haverbeke.
Вводная книга по JavaScript и программирование в целом.

"Learning Javascript Design Patterns"
Уровень знаний: начальный, язык: ENG, автор: Addy Osmani
В книге рассматриваются классические и современные патерны программирования на JavaScript

"jQuery Fundamentals"
Уровень знаний: начальный, язык: ENG, автор: Rebecca Murphey
Создаваемая сообществом книга по JavaScript и jQuery.

"Javascript Enlightenment"
Уровень знаний: средний, язык: ENG, автор: Cody Lindley
Тщательный обзор мировоззрения JavaScript через разбор встроенных объектов и нюансов.

"Smooth CoffeeScript"
Уровень знаний: средний, язык: ENG, автор: E. Hoigaard
Введение в CoffeScript с акцентом на ясность, абстракции и верификации.

"Building A JavaScript Framework"
Уровень знаний: продвинутый, язык: ENG, автор: Alex Young,

Избранные статьи из цикла «Let’s Make a Framework».