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

Other languages:

Содержание

1 JavaScript API iRidium
2 Basics
3 Access to Interface Objects
4 Access to Drivers
5 Access to Tokens
6 Access to Sounds
7 Access to Server Databases
8 Library of Animation
9 iDate Object
10 iRidium Modules
- 10.1 Code Standard for iRidium Modules
11 Books and Web Sites on Java Script

JavaScript API iRidium

Guide for developers
Handbook » Examples »

iRidium API is a set of JavaScript functions enabling control of iRidium visualization projects. To add JavaScript in your project follow the guide.

The guide is meant for developers acquainted with JavaScript programming and the object-oriented paradigm of development. The guide describes the basic definitions used in API and methods for performing typical tasks to control iRidiumprojects.

Updated: 14.9.2023
Source language: JavaScript
Language version: 1.5
Specification: ECMAScript Edition 3
The JS version that we use is not the latest
one and it does not support new constructions,
but its functions are enough for panel projects
in 99% of all cases. To satisfy the remaining
one per cent converters of the https://babeljs.io
type can be used and of course experience
and developer's skills help.
Report an error

All available API objects are described in detail in the handbook on program interfaces.

Come to free iRidium webinars:

iRidium Script Part 1: Enhanced capabilities of control interfaces

iRidium Script Part 2: Work with iRidium drivers

Animated Items in iRidium Interfaces

Basics

iRidium JavaScript API is a set of iRidium API and JavaScript 1.5 functions and events. They are meant to control the visual part and drivers in iRidium projects. iRidium API communicates with i3 pro which interprets and executes JavaScript files. The iRidium API functions refer to the IR object. They are available only in the original application which version corresponds to the API version.

Use of API

To use JavaScript, add the JavaScript file (*.js) in your iRidium project (*.irpz) created in iRidium Studio.

The file is stored in the iRidium project and is uploaded together with the project in i3 pro. The script execution starts at project launch in the i3 pro application.

Create a JavaScript file in iRidium Studio:

Open iRidium Script Editor
Click "New Script"
Input the file name and click ОК

The file can be exported from the iRidium project in the *.js format and use again.

Connect the ready JavaScript file in iRidium Studio

Open iRidium Script Editor
Click "Add Script from file"
Select the *.js file - it will be added in the list of JavaScript files

Executing Scripts

JavaScript files can contain a set of iRidium API functions and events. Functions are executed in case of activation of an iRidium API event. It can be the application launch, pressings on graphic items, receiving data from equipment, etc.

JavaScript file - it is a *.js file attached to the project
Event - it is a process forwarded in scripts. It has an identifier for monitoring
Listener - it is a function which is executed in case of activation of the event assigned to it
IR - it is a global object containing all functions and constants of iRidium API

The code is allocated in the files. Listeners are allocated in the files. The events, objects and functions are sent to the listeners.

Listening function IR.AddListener()

The scripts can be activated on an event in the system. For example, when on receiving data from equipment or on pressing on an item. You can monitor different events which are activated during project work. Activation of the event monitored by the listener calls the unnamed function and can transfer parameters which are changed during the event to it.

An event - a process forwarded to scripts with an identifier for monitoring.

A listener - it is a function which is executed if the event set for it is activated

Add a listener using the method IR.AddListener

IR.AddListener(event, input, action);

event - the identifier of the event monitored by the listener
input - the input parameter required for creating the listener. If there is not such parameter indicate 0
action - the unnamed function or the link to the named function in which the actions are performed

Example 1 (without context):

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

Besides the three main parameters of the listener (Event, Input, Action), there is also the Pointer parameter. It enables transfer of the pointer which serves the external function from the listener to the function.

Example of use: call an unnamed function with the help of the listener and transfer the reference to the interface object to it as to context of function execution. You can refer to the context with the help of the this operator. The context can change during program work.

Example 2 (with the reference to the context):

var page =  IR.GetItem("Page 1")
for(var i = 0; i < page.ItemsCount; i++)
{
   //  page.GetItem(i) as a reference to the function ShowName
   IR.AddListener(IR.EVENT_ITEM_PRESS, page.GetItem(i), ShowName, page.GetItem(i));
} 
function ShowName()
{
   // using 'this' as a reference to the object  page.GetItem(i)
   IR.Log(this.Name);
}

See more information about the use of the IR.AddListener method in Handbook.

IR.SetGlobalListener()

The global listener is executed in case of activation of the event indicated for it. It can work with two events only: IR.EVENT_GLOBAL_TAG_CHANGE (it is activated on change of any tag in iRidium).

Unlike IR.AddListener, the global listener can be called only once. When calling it the second time, only the last listener created by the interpreter at the script launch will work.

For the listener to work on the tag change in iRidium project, you need to subscribe to the change with the IR.SubscribeTagChange method.

Example:

// 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() Command

The script can be called with the ScriptCall() command assigned to the graphic item. You can send only the pointer to the function without the input parameters to the command - and it will enable execution of any script in any moment on pressing the button without creating a separate listener:

In the drop-down list of the ScriptCall() command functions are displayed without input parameters. You cannot send function parameters with the help of this command.

Rules for Executing Scripts

The code is executed asynchronously. When iRidium refers to a device it does not disturb the interface work but receives data in a separate stream, as if you refer to a remote web site from your browser.

But when executing a big number of operation, for example, cycles, the GUI interface gets interrupted, waits for the end of the operation and only then continues its work.

Standard listeners can be called can be called several times. The global ones - only once.

The script files work in one name space at the project launch - do not use variables and functions with the same names in different script files.

Do not delete graphic items until they execute all operations connected to them. It will lead to errors of command execution.

Name Space

JavaScript files in iRidium projects are executed in one name space. The initialization of files is performed in a sequential order, from top downwards. Consider it when selecting function names and determining the scope. If different JS files determine a variable or a function with the same identifier (name), then during execution the function which was allocated in the memory last (i.e. in the file which is down in the list) will be used.

It does not refer to listeners. If in the project there are listeners for similar events, both will be executed.

JavaScript Editor

The JavaScript editor serves for creating and allocating JavaScript files in iRidium projects.

The editor interface:

1 Script tree.

Right-click on a script file to open the menu:

Open - open a file,
Open in an external editor - open a file in an external editor,
Rename - rename a file,
Save - save a script,
Save as - save a script as a separate file,
Active - activate a script,
Disable - disable a script,
Set password - set a password for a script file,
Delete - delete a script file.

2 Work area.

Right-click on a script name to open the menu:

Save - save a script,
Save as - save a script as a separate file,
Set password - set a password for a script file,
Close - close a script,
Close all - close all script files.

3 Help info on IR methods and events..

4 Toolbar:

	Show a script tree.
	Add: New script; Add script from file; New script folder.
	Delete the script file selected in the list.
	Set a password to view and edit a script file (for the password to come in effect, save the project and open it again).
	Move a file up/down.
	Apply changes made in the script.
	Save in *.js file
	Open in an external editor.
	Cancel/return the change.
	Enter color value in the editor.
	Show/hide help info on IR methods and events.
	Search by word or line (Ctrl+F).

IntellHelp

To fasten the process of script writing in there is a system of IntellHelp built in iRidium Studio.

It helps to form correct chains of commands
It determines which function you write at the moment and offers the available set of functions, methods and objects for it. It helps to decrease the number of syntax errors and fasten the input
It outputs the list of local resources as a list of audio files in the project

Ctrl + Space - to activate IntellHelp when it does not appear automatically

Debugging

Debugging of the written code in iRidium is performed with the help of the built-in debugging tool - the output console iRidium Log. The iRidium Log console serves for:

output of data to debug script work
automatic search for errors with indication of the number of the string where the error is found
saving logging results in a file

The iRidium Log window can be opened only in Windows. In iOS and Android you can use the system of remote debugging - the logging data are sent to remote Sysylog Server.

i3 pro for Windows (unlike for iOS, Android and Mac) allows you to see the system log directly in the application (Local logging). You can also send the log file to a remote PC (Remote logging)

Local logging

You can open the log of the i3 pro client application for Windows by clicking F4 in the application window (or in Emulator).
To enable display of required data in the log:

1. Indicate the logging depth for iRidium systems and subsystems in iRidium Studio. The setting up is performed in the Debug tab in the panel project settings window. The logging depth: from EMERGENCY (errors only) to DEBUG (full information)

2. Indicate the logging depth for each driver added in the project

3. If you use JavaScript in your project, use the IR.Log("text") method to output messages

3. Start the i3 pro application or Emulator on Windows, then click F4 to open the log.

Remote logging

The log of i3 pro can be sent to a remote PC. The log is sent with the help of software generally called Syslog Server. Here is an example of such a program: www.winsyslog.com

[Install] and set up the server:

1. enter the UDP-port for launching the service: 514, the same as in the i3 pro system settings

2. start Syslog Server

Set i3 pro to connect to Syslog Server:

1. Turn on Remote Debugging option in the Debug tag of the settings windows of a panel project, enter the Host - IP address of a PC where Syslog Server is launched. Logging port - 514. Enter the depth of logging of iRidium systems and subsystems in iRidium Studio. There are several levels of logging depth from EMERGENCY (only errors) to DEBUG (detailed information).

2. Set the depth of logging for each driver added to a project.

3. Remote logging of i3 pro can be set not only in a project on a PC, but also in the system menu of i3 pro using one of the following ways. Click the right mouse button on the panel in iRidium Transfer and open the menu with the help of Show System Menu, long press on the empy area of workspace or a swipe from left to right.

Activtae remote logging Enable in the Remove debug tab and enter the Host - IP- address of a PC with Syslog Server, port (514) and logging level.

Output data in the log:

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

Object Hierarchy

To get access to an interface object (page, popup, item, item property), driver (connection, command, tag), system parameters, sounds, etc. it is required to form access to them as a chain. Each item of the chain must refer to the result of the previous referring. At that is is required to adhere the object hierarchy:

IR is a global object containing all iRidium API functions and constants. It is the highest level of the hierarchy. You can see the list of objects in IntellHelp of Script Editor. The level of nesting depends on the object you wan to refer to and its level in the hierarchy.

Examples of hierarchical structures:

IR.GetPage("Page 1").GetItem("Item 1").Width = 100; // reference to the graphic item width

IR.AddListener(IR.EVENT_START,0,test); // creation of the listener

IR.CreateDevice(IR.DEVICE_CUSTOM_HTTP_TCP, "Driver", "myhost.com" 80); // creation of the HTTP driver

IR.GetDevice("Driver").Send(['string\r\n']); // sending the command

Access to Interface Objects

Interface objects are pages, popups and graphic items of iRidium projects.

Creation of Objects

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

IR.ITEM_BUTTON - the type of the item we create
"Button" - the item name
30, 40, 800, 150 - the basic (required) set of item properties: Х coordinate, Y coordinate, width, height

Item types:

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

To create an item it is enough to have the basic set of properties. But each item type has a set of specific properties:

Page

pages do not have specific properties but they can process gestures

Popup

LifeTime - it is set up in milliseconds. It defines the time after which the popup will be closed after it is opened.
Effects - it sets up effects of popup opening and closing.
Drags - it gives an opportunity to drag the popup in any place during application work

Button

Active - active/does not react on pressings
Hit - the type of event processing
Password Number - the password for activating actions

Trigger Button

Active - active/does not react on pressings
Hit - the type of event processing
Trigger Value 1 - the value for activation of state 1
Trigger Value 2 - the value for activation of state 2

Multistate Button

Active - active/does not react on pressings
Loop - the cyclic repetition
TimeUp - the time for playing animation forward
TimeDown - the time for playing animation backwards
Hit - the type of event processing
Password Number - the password for activating actions

Up/Down Button

Active - active/does not react on pressings
Up/Down Value - the value on which the current value decreases/increases
Max/Min Value - the maximum/minimum value
Hit - the type of event processing

Level

Min - the minimum value
Max - the maximum value
Range Type - the type of values
Direction - the level direction
Focus Look Receive - the possibility to get focus
Hit - the type of event processing
Invert - the values are inverted
Slider - the graphic representation of the slider
Slider Color - the slider color

Multistate Level

Min - the minimum value
Max - the maximum value
Direction - the level direction
Focus Look Receive - the possibility to get focus
Hit - the type of event processing
Invert - the values are inverted

EditBox

Active - active/does not react on pressings

Virtual Key

Active - active/does not react on pressings
Key Type - the key type
Key Action - the action the key will perform

Joystick

Range Type - the type of values
Active - active/does not react on pressings
Focus Look Receive - the possibility to get focus
Hit - the type of event processing
MinX - the minimum X value
MinY - the minimum Y value
InvertX - the inversion by the X axes
InvertY - the inversion by the Y axes
Cursor - the graphic representation of the cursor. It can be set from the script
Cursor Color - the cursor color

Referring to Objects

Access to objects of graphic interfaces is performed in accordance with their hierarchy. You can get access to an interface object:

By drag'n'droping this item to the JS editor window:

By indicating the item of the highest level:

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

GetPage("Page 1") - the page
GetItem("Item 1") - the item on the page
GetState(0) - the item state, beginning with zero
FillColor - the state property

By indicating the page:

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

GetPage("Page 1") - the page
GetItem("Item 1") - the item on the page
Value - the item property

By indicating the popup:

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

GetPopup("Popup 1") - the popup
GetItem("Item 1") - the item on the popup

By referring to the item on the current page:

IR.CurrentPage.GetItem("Item 1")

IR.CurrentPage - the current page
GetItem("Item 1") - the item on the current page

By indicating the variable which stores the reference to the object:

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

var item - the variable to which we assign the item
IR.GetPage("Page 1") - the page
GetItem("Item 1") - the item on the page

IR.AddListener(IR.EVENT_START,0,function()
{
   IR.GetItem("Page 1").GetItem("Item 1").Width = 100; // referring by GetItem("Item_Name")
   IR.GetPage("Page 1").GetItem("Item 1").Height = 50; // referring by GetPage("Page_Name")
   IR.GetPopup("Popup 1").GetItem("Item 1").Text = "This is text"; // referring by GetPopup("Popup_Name")
   IR.CurrentPage.GetItem("Item_Name").Text = "This is item on current page"; //referring to the current page
   var item = IR.GetPage("Page_Name") // writing the object identifier in the variable
   item.X = 20; // referring to the object property vi the variable
});

An item can have several states. And each state has its own properties.

That is why it is recommended to refer to state properties using the instruction GetState(State_Number) where State_Number - the state number, beginning with zero:

IR.AddListener(IR.EVENT_START,0,function() 
{
     // assign text to the second item state. The numeration starts with zero, State 2 = GetState(1) 
     IR.GetItem("Page 1").GetItem("Item 1").GetState(1).text = 'state 2';
});

Interface Events

Listeners of events are used to monitor user actions and interface changes.

The specific feature of interface listeners is absence of the "interface change" global event. Pressings on buttons must be processed by separate listeners. This feature has to be considered if you monitor a big number of items.

The number of any listeners in a project must not exceed 1024.

Examples of events: a pressing on an item, activation of the keyboard, device turn.

// the event is activated when pressing on Item 1 on Page 1
IR.AddListener(IR.EVENT_ITEM_PRESS, IR.GetItem("Page 1").GetItem("Item 1"), function ()
{
    IR.HidePopup("Popup 1"); // closing the popup by its name
});

IR.EVENT_ITEM_PRESS - the event activated by the listener. The list of events:

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

You cannot use events of the mouse on devices which do not have the mouse, for example, tablets or smart phones. The TOUCH event works only on devices with the sensor screen

Access to Drivers

Drivers are used for communication with automation equipment, remote servers and other actions demanding creation of TCP, UDP, HTTP(s), RS232 connection. With the help of iRidiumScript you can:

create a driver
change driver settings
connect/disconnect
send commands
receive and process data

Creation of Drivers

You can create a driver with the AV & Custom Systems type on the basis of TCP, HTTP or UDP transport with custom settings. There is also a possibility to create TCP and UDP servers on the basis of AV & Custom Systems. Drivers of this type can process random data and send random commands. On the basis of AV & Custom Systems you can create drivers which are not initially supported by iRidium.

The AMX, KNX, BAOS, Global Cache, Crestron drivers can also be created via scripts but you cannot send random data to them. Commands to these drivers are formed according to rules listed in the description of the Set command: IR.GetDevice("driver").Set("name", "data")

To refer to the drivers which cannot be created from the script, create drivers and commands in iRidium Studio > Project Device Panel (the standard way described in iRidium instructions for your equipment).

The command for driver creation:

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 - the driver type from the list of available ones
"AV Device (TCP)" - the driver name, string
"192.168.0.100" - the address to which the driver has to connect
8080 - the connection port

Each driver has a set of specific connection properties. See more information about it in the handbook.

Driver types (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

The driver connects to the indicated address right after its creation. If you do not want for the driver to connect to equipment, leave the field of connection address ("host") empty.

Referring to Drivers

When the driver is created you can refer to it to change settings, send commands and process data received from the driver.

To refer to the driver drag'n'drop it to the JS editor window or enter the name of the driver / network in the command manually as in the example below:

IR.GetDevice("driver_name");

Reference to an object - driver - can be assigned to the variable:

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

Control of Drivers

You can apply commands for connection/disconnection and change of work parameters to the created driver.

var driver = IR.GetDevice("driver_name");
driver.Disconnect(); // disconnect from  equipment 
driver.SetParameters({Host: "192.168.0.21", Port: "9090"}); // change the connection settings 
driver.Connect(); // connect to equipment

When changing the connection settings the driver disconnects from the equipment and reconnects to it with new settings. You do not have to disconnect manually when executing the SetParameters command.

Sending Commands

Depending on the driver type you can use different methods of command sending. There are two methods for that: Set and Send. They operate differently.

Send:

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

- it can be used only with the driver on the basis of AV & Custom Systems. The method enables sending of random strings or numbers (DEC, HEX, ASCII) to equipment. Strings are formed using the documentation of the equipment you want to control. The Send method works only with AV & Custom Systems!

Data for sending are formed directly in the script and are not connected to commands from iRidium Studio > Project Device Panel, created in a standard way.

The Send method for drivers with several transports:

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

transport_id - the number from 0 to n, means the number of transport whre you want to send the command. 0 - send to all, 1...n - send to a particular ID

- Global Cache is one of the drivers with several drivers as it uses ports 4998, 4999, 5000. AV & Custom Systems TCP Server and UDP Server also use several transports as they be connected by several clients each of which uses opens its own socket to which you can refer.

Set:

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

"command_name" - the command name in Project Device Panel
100 - the number you need to send to the command with the indicated name. You can also send a string

The Set method allows you to send a value to the previously created driver. To add a template drag'n'drop a command to the JS editor window and replace "0" to the value to send to a command:

IR.GetDevice("Driver_Name").Set("Subdevice_name:Command_name", 100);

Driver_Name - name of the driver;
Subdevice_name - name of the subdevice (if the driver is Network);
Сommand_name - name of the command;
100 - number to send to a command (you can also send a string).

- it can be used with any iRidium driver you created in iRidium Studio > Project Device Panel. Commands must be created and set up in the project tree in advance. Then you can activate them at any time and send any value to them. If you want to activate a command without sending values, the syntax is as follows: IR.GetDevice("Device_Name").Set(["command_name", ""]);

Receiving and Parsing Data

The AV & Custom Systems driver created in scripts or in Project Device Panel can receive any data as it is not known in advance to which equipment it connects. All the rest iRidium drivers receive data in the particular format known to iRidium.

Therefore there are two ways of parsing received data:

the method for random data of AV & Custom Systems
the method for data received in the preset Feedbacks in the project tree (Project Device Panel)

Processing is performed with the help of the listener which reacts on the event of data receipt (for AV & Custom Systems) and on changes of the feedback channel (for the rest drivers).

IR.EVENT_RECEIVE_TEXT & IR.EVENT_RECEIVE_DATA

var driver = IR.GetDevice("AV Control") // indicate the driver name 
// the listener reacts on data receipt 
IR.AddListener(IR.EVENT_RECEIVE_TEXT, driver, function(text) 
{  
    IR.Log(text) // output the received data in the log 
    // the data can be processed inside the listener
});

IR.EVENT_RECEIVE_TEXT - it defines in which format the received information will be displayed

IR.EVENT_RECEIVE_TEXT - the text format
IR.EVENT_RECEIVE_DATA - the byte format

these methods work only with эти AV & Custom Systems drivers. They cannot be used with other drivers! The methods return a string or a bit sequence received by the driver.

IR.EVENT_TAG_CHANGE

// indicate the driver name 
// the event is activated on changing tags set up in the project, the tab Feedbacks
IR.AddListener(IR.EVENT_TAG_CHANGE, IR.GetDevice("driver_name"), function(name, value) 
{  
    IR.Log(name+" : "+value) // output the tag name and its new value in the log 
});

This method works with any driver besides AV & Custom Systems. The method returns the name of the channel which is changed and it new value. The channel has to be created in the project tree in a standard way (in the Feedback tab of the driver).

Access to Tokens

Token - it is a variable not connected with commands to automation equipment. Tokens store data about iRidium work to which you can refer. There are three types of tokens:

Project Tokens

Project Tokens are named variables which can be created in iRidium. You can write a string, number, data array in the variable and refer to the data with the help of relations of graphic items or via iRidium API. Information in variables can be stored between launches of the iRidium application on the control panel.

they are stored in the device tree of the project - Project Device Panel
they can be created with iRidium API commands during application work
you can write a number, string or array (DEC, ASCII)
you can create, remove, copy, sort and group in folders
data can be stored in variables after closing the iRidium application
you can write data with the command from the item or from iRidium Script

Creation of tokens, writing values

Use the IR.SetVariable function to write values in Project Tokens.

If there is no token where the value is written in the project, it will be created automatically by calling IR.SetVariable

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

Tokens. - the pointer to the referring to the project token. You can also use the referring Global.
TokenName - the token name in Project Tokens in Project Device Panel
value - any value (number, string, array of numbers, array of strings)

Example:

IR.AddListener(IR.EVENT_START, 0, function()
{
    // create the test token (there is no such token in Project Device Panel) and write to it 23
    IR.SetVariable("Tokens.test", 23); 
    // output the data from the token in the console 
    IR.Log(IR.GetVariable("Tokens.test")); // 23
});

See how to write arrays in Projects Token and extract them in eamples of using JavaScript API

Reading values

Use the IR.GetVariable function to read values in Project Tokens.

If the token did not exist before, it returns undefined. If the token was created in Project Device Panel, but did not have a value written in it, it returns undefined

IR.GetVariable("Tokens.TokenName")

Tokens. - the pointer to the referring to the project token. You can also use the referring Global.
TokenName - the name of any token in the Project Tokens in Project Device Panel

Example:

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

download:
example of array writing and extracting from Project Token

System Tokens

System Token - it returns the value of system parameters of the control panel: time, date, battery charge, GPS coordinates, etc. The token can be assigned to any graphic item and it will output received information on the item.

You cannot write values in the system tokens. Data is input in by the control panel OS.

Referring to tokens

Use the IR.GetVariable command to get data from the system token:

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

System. - the pointer to the type of the variable you need to receive: the system variable
Time.Seconds - the name of the system variable, the same as in Project Device Panel

example:

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

You can see the full list of System Tokens in the handbook.

Driver Tokens

Driver variables are available for reading only. The set of variables is the same for any driver.

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
});

Access to Sounds

iRidium can play audio files in several streams - slots. Via iRidium API you can:

start and stop playing of audio files
stop playing of one slot or all slots
cycle sounds
control volume

To play an audio file you need to add it in Project Gallery in advance, the Sound tab.

You can see descriptions of all functions to control sounds in the handbook.

Access to Server Databases

The SQL database is formed in iRidium Server together with the server project. It enables storing the state of server variables to build graphs and create logs. There are two types of databases:

System database - writing in it is performed only through settings of server variables in iRidium Studio. It can be read with the help of JavaScript but cannot be edited or removed
User database - work with it is performed only via JavaScript. You can write, read, edit and remove data with the help of special JavaScript methods.

download:

example of forming the user database

See all methods of working with databases in DataBase API.

System Database

The system database is available for reading only. Writing in it is performed by the server.

The database consists of the following tables:

FLOAT_TAG_HISTORY - the tags where decimal numbers were written
INTEGER_TAG_HISTORY - the tags where whole numbers were written
PROJECTS -the projects uploaded on the server
QUALITY_LIST - [reserved]
STRING_TAG_HISTORY - the tags where strings are written
TAG_STATUSES - [reserved]
TAG_TYPES_LIST - [reserved]
TAGS_PASSPORT- all types of tags (string, integer, float)
VERSION - [reserved]

Referring to the system database. See all methods of working with databases in DataBase API.

// assign properties of the system database to the sql variable
var sql = IR.GetDatabase(); 
// create a request to the database
// assign the Request property of the sql database to the examp variable. The request body is in single quotes
var examp = sql.Request('SELECT ...'); 
IR.Log(examp.Columns); // the number of fields (columns) in the request
IR.Log(examp.Rows); // the number of records  (lines) in the request
IR.Log(examp.GetRowValue(0,1)); // the value of the box in line 1 and column 2
IR.Log(examp.GetColumnName(0)); // the name of the field which index corresponds to the number in brackets

Example: to select the information about the tags with value < 1500 in the database

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++) // organize the cycle to output values 
   for (j=0;j<examp.Rows;j++)
   {
      IR.Log(examp.GetRowValue(i,j)); // output  the fields values in the log 
   };  
});

User Databases

You can create a database and add/update/delete its tables/fields/values. Properties of the database must be written in the JavaScript variable. After that you get access to the properties. Referring to the database is performed with the help of SQL requests.

See all methods of working with databases in DataBase API.

Create a database, new SQL() - the definition of the database in iRidium JavaScript API

var mybase = new SQL();

Create a database file with which you will work

mybase.Open('Example.db');

.Open - to open the database file. If there is no such file, it will be created in the folder of software documents. For example, C:\Users\UserName\Documents\iRidium mobile 3\Settings\ Server\Database\Example.db - the database name with the suffix.

Use logic commands for fast and correct writing

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

.Execute - the function of executing an action with the database
"BEGIN" - the start of writing in the database
"COMMIT" - the end of writing in the database
.Close() - to close the database

You created an empty database. To create a table in the database, use the function

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

CREATE TABLE - the function for creating the table named Info
ID, Value, Name - the names of the table fields which will contain such values as int, double, string. You can change the names of the fields but you must indicate the field type.

To write in the database, use the structure:

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

INSERT INTO makes a record in the Info table, namely in the fields ID, Value, Name. VALUES - the parameters which will be written in the fields. So number 1 will be written in the ID field, number 2.5 will be written in the Value field, the text "sunny day" will be written in Name.

There have to be the same number of parameters in the brackets after VALUE as the number of fields in the brackets after

INSERT INTO()</code>.


Special features of writing values in table fields

Write the text in double quotes:
VALUES("iRidium", "Mobile");
Numbers are written without quotes, decimal numbers - using the point:
VALUES( 1, 2.5, 36.788);
Variables must be called in advance and included in single quotes. Also add pluses before and after the variable name:
// var CV; 
// var V;
...
VALUES( '+CV+', '+V+' );




Creating Requests to Databases
To create requests to databases, get acquainted with the SQL language. Requests are required when you have particular conditions for selecting data in the database. See all methods of work with databases in DataBase API.


Example: find the day, time and minute when the temperature was > 10 degrees in the database with weather information:
// create a variable and assign the sql.Request object to it, indicate the request body in brackets 
var RecordSet = sql.Request("select * from TEST WHERE grades>10");
function inquiry()       
{    
    sql.Open('weather.db'); // open the database "weather.db"
    sql.Execute("BEGIN");    
    var RecordSet = sql.Request("select * from TEST WHERE grades>10");       
    // output fields 1-3 in the log 
    IR.Log(RecordSet.GetColumnName(0) +'\t'+ RecordSet.GetColumnName(1) +'\t'+ RecordSet.GetColumnName(2));
    for (i=0;i<RecordSet.Rows;i++)   // the cycle will output data in strings 
    IR.Log(RecordSet.GetRowValue(0,i)+'\t'+RecordSet.GetRowValue(1,i)+'\t' + RecordSet.GetRowValue(2,i));   
    sql.Execute("COMMIT"); // the end of work with the database           
    sql.Close();    
};      
IR.SetInterval(60000, inquiry); // call the function every minute




Library of Animation
 see the free webinar


Animation library is a ready JavaScript file which contains a set of functions and methods for animation of items in your project.
Standard methods are based on use of frame animation and change of item states. iRidium animation library enables creation of complex effects for separate items and groups. 
The recent version of the library and instructions


iDate Object
iDate  - it is a representation of a date as 64 bit number with floating point. It can operate dates and time in the range from January 1, 100 to December 31, 9999. 
The whole part means the number of days since December 30, 1899, i.e. number 2 means January 1, 1900. To indicate dates until December 30, 1899, use negative numbers, for example,  -1 means January 29, 1899. 
The fraction part defines the time. To increase the time by 1 hour, add 1/24; to add a minute: 1/1440. The disadvantage of working with the object - low accuracy when working with milliseconds, the margin of error is +/-150 ms. 


iDate without arguments
When creating an object without arguments, the object is initiated with the current date and time.
var date = new iDate();
IR.Log("Date " + date.year + "." + date.month + "." + date.day);
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 with 1 argument
The argument is value - the number with floating point, meaning integrated representation of date and time.
When creating an object with floating point, you can receive date and time from the object.
// create an iDate object giving a whole positive number to it.
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
*/
// create an iDate object giving a whole negative number to it.
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 with more than 1 argument
Arguments:
 year 
 month 
 date 
 hours 
 minutes 
 seconds 
 ms


When creating an object, year, month, hours, minutes and ms are filled in separately. If some parameters are not filled in, they are filled in with the current value.
// creation of an iDate object with the current values of date and time.
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
*/
// creation of an iDate object with indication of year, month and date 
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
*/
// creation of an iDate object with indication of year, month, date, hour and minute 
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
*/
// creation of an iDate object with indication of year, month, date, hour, minute and millisecond
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 Modules
iRidium modules are ready iRidium projects with JavaScript files created by iRidium mobile or third-party developers. They can be merged with your iRidium project to use their additional functions without any programming from your side. 
Depending on the use (clock, weather, calendar, audio-video control, etc.) modules can require on not require iRidium licenses. Information about that is indicted in the module description. 


 Any module using the AV & Custom Systems driver or some other driver requires a license. Modules using the listeners IR.EVENT_RECEIVE_TEXT and IR.EVENT_RECEIVE_DATA require "Pro" licenses.


User instructions are not available for all modules. General steps for using:
 download the module (the *.irpz project file)
 open the module in iRidium Studio
 open the project where you want to add the module in iRidium Studio
 drag the module in your project in the Project Overview window - they will merge
 use the module pages and popups as a part of your project



video:

merge of iRidium projects



Code Standard for iRidium Modules
Agreement on naming:


0. Highlighting of words  - change of character case (camel case), Tabulation - 3 symbols, not blank spaces.


1. Names of constructor functions working with the "new" operator start with  capital letters
function AbstractDriver () {
};
var Driver_1 = new AbstractDriver ();


2. Names of functions and public method functions start with lowercase letters
function updateRequest () {
};
function AbstractDriver () {
    this.getData () {
    };
};
var Driver_1 = new AbstractDriver ();
Driver_1.getData ();


3. Names of public but temporary functions and object method functions start with the underscore and lowercase letters 
function AbstractDriver () {
    this._getPassword () {
    };
    _prepare = function () {
    }
    _prepare (); // private method
};
var Driver_1 = new AbstractDriver ();
Driver_1._getPassword (); // temporary API method


4. Names of properties start with lowercase letters
var lastIndex = 0;


5. Names of constants are written in capital letters with the underscore between words 
var EVENT_GENERATED_END = 0;


6. Names of incoming parameters start with the prefix in_, the first syllable starts with lowercase letters
function resizeProject (in_width, in_height) {
};


7. Names of outgoing parameters of functions start with the prefix out_, the first syllable starts with lowercase letters
function checkConnection () {
    return out_status;
};


8. The name space, all symbols are written in the upper case 
KNX = {};


9. Blank spaces: after key words, before opening brackets, before curly brackets, after commas
function name (in_arg1, in_arg_2) {
    return out_arg;
};


10. Semicolons: in the end of the string, after the closing curly brackets


11. Documenting of methods, constructors
/**
* 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;
};




Books and Web Sites on Java Script
If you have not worked with the Java Script language before and do not know anything about the object-oriented paradigm of development, we recommend you to visit some information web sites and read books on the subject. Here we present the web sites selected by us. But you can always find the resource which is more convenient for you.


Web sites:
 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)


Books:
"Eloquent JavaScript"

Knowledge level: beginner, language: ENG, author: Marijn Haverbeke.

Introductory book on JavaScript and programming on the whole.


"Learning Javascript Design Patterns"
 
Knowledge level: beginner, language: ENG, author: Addy Osmani
 
This book examines conventional and contemporary patterns of programming in JavaScript.


"jQuery Fundamentals"

Knowledge level: beginner, language: ENG, author: Rebecca Murphey

The book on JavaScript and jQuery.



"Javascript Enlightenment" 

Knowledge level: intermediate, language: ENG, author: Cody Lindley
 
Detailed review of JavaScript outlook through analysis of integrated objects and nuances.


"Smooth CoffeeScript"

Knowledge level: intermediate, language: ENG, author: E. Hoigaard
 
Introduction to CoffeScript with focus on clarity, abstraction and verification.


"Building A JavaScript Framework"

Knowledge level: advanced, language: ENG, author: Alex Young, 


Selected articles from the cyclus «Let’s Make a Framework».