This page is a
translated version of the page
JS Guide and the translation is 100% complete.
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
});
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.
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
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:
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
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
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
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:
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».