Материал из for iRidium developers
Перейти к: навигация, поиск
Эта страница является переводом страницы JS Guide. Перевод выполнен на 100%.

Other languages:
English • ‎русский

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: 20.7.2017
Source language: JavaScript
Language version: 1.5
Specification: ECMAScript Edition 3
Report an error

All available API objects are described in detail in the handbook on the software interface.


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:

  1. Open iRidium Script Editor
  2. Click "New Script"
  3. Input the file name and click ОК


JS addNewFile.png

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


Connect the ready JavaScript file in iRidium Studio

  1. Open iRidium Script Editor
  2. Click "Add Script from file"
  3. 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) and IR.EVENT_GLOBAL_GUI_CHANGE (it is activated on any interface event).

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:

JSguide helloFunction.png

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:

Editor window JS Editor.png


JSnew.png a new script file:
  • create a script file
  • open the script file (*.js)
  • create a folder
JSdel.png delete the script file selected in the list
JSupdown.png move up/down
JSpass.png set the password for viewing and editing the script file
JSrename.png rename the script file
JSsavefile.png save the *.js file
JShelp.png show/hide information about the IR methods and events
JSapply.png apply the changes made in the script
JSserch.png search by a word/string (Ctrl+F)
JSundoredo.png cancel/undo the change
Icon Emulator.png launch Emulator
JSfunctions.png search by function names in the JS file



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.

Logging is a tool required in the process of debugging iRidium projects. In particular, it is important if you use JavaScript in your project.
i3 pro for Windows (unlike for iOS, Android and Mac) allows you to see the system log directly in the application (Local debugging). You can also send the log file to a remote PC (Remote debugging)


Local debugging

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 Properties tab. 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
ServerLogSettings-1.png
ServerLogSettings-2.png
3. Start the i3 pro application or Emulator on Windows, then click F4 to open the log.
Log window.png
to open the log window together with Emulator in iRidium Studio automatically, activate the function:
Tools > Options > Show Log At Emulator start


Remote debugging

The i3 pro log can be sent to a remote PC. The sending of the log is performed with the help of special programs for registration of the system log which are called Syslog Server. Example of such program: Ipswitch Syslog Server.


Install and set up Syslog Server:

1. indicate the UDP-port for launching the service: 514
2. start Syslog Server as a service


Set up i3 pro for connection to Syslog Server:

1. Indicate the logging depth as it is shown in the settings of Local debugging
2.1. Activate the Remote Debugging option in the properties of the panel project, indicate Host - the IP-address of the PC with running Syslog Server. Leave the default logging port (514).
2.2. Remote debugging of i3 pro can be set up not only in the project on PC but also via the i3 pro system menu. Open the menu by clicking F8, the password: 2007.
In the Info tab tick "Remote Debugging" and indicate Host - the IP-address of the PC with running Syslog Server
3. Save the changes and close the application. At the next launch the log will be sent to the server.
ServerLogSettings-7.png
IOSApp Settings8.png


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 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; // обращение через 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.

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


- 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 bit 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.

Tokens 1.png
  • 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

AddSysTokenToItem.png

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

Receiving of driver tokens (Host, Port, ...) is not available.



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

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()". 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.days);
IR.Log("Time " + date.hours + ":" + date.minutes + ":" + date.seconds + "." + date.ms);
IR.Log("Value " + date.value);
/*
   result:
   Date 2014.11.29
   Time 20:49:20.778
   Value 41972.86760159722
*/


iDate 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:

  1. download the module (the *.irpz project file)
  2. open the module in iRidium Studio
  3. open the project where you want to add the module in iRidium Studio
  4. drag the module in your project in the Project Overview window - they will merge
  5. 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

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:


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».