# OI Scripting

OI Scripts can be used to provide advanced custom features to an OI application. Examples include:

read several tag values, prepare the results in a file, and FTP the file to a remote computer
provide custom database functionality beyond that available in OI

WARNING

OI-Windows and OI-Embedded support different methods of executing scripts. OI-Embedded uses HTTP Script and Shell Script components, similar functionality can be accomplished using the Generic Run component for OI-Windows. Generic run does not provide mechanisms to pass tag values to and from OI-Windows.

This manual page discusses OI-Embedded scripting.

Information on the HTTP and Shell script components can be found in the Nonvisual Component documentation.

# Passing Values To Scripts

# Direct Tags

Tag values can be passed using the inputTags property. By just using the tag name, these values are passed to the script in variables of the same name:

Example: tag1 ; tag2 ; tag3
Tag names are passed into script unchanged, i.e. “tag1”, “tag2”, and “tag3” are passed into script.
Current OI tag values at the time of trigger are passed into script

# Tags Mapped By Name

Tag values can be passed using the inputTags property and mapped to different names in the script:

Example: oi_tag1 > php_tag1 ; oi_tag2 > php_tag2; oi_tag3 > php_tag3
OI tag name is mapped to specific name into script, i.e. “php_tag1”, “php_tag2” and “php_tag3” are passed into script.
Current oi tag values at the time of trigger are passed into script

# Constants

Constant values can also be passed into the script.

Example: “some text” > php_tag1 ; “4” > php_tag2
Specific value is passed together with specific name into script.
Constant syntax is the same as in TagCopy component, i.e. constant value is quoted. Inner quotes can be escaped by another quote. For example “This is ”“quoted”” string”

# inputTags Example

All options can be combined:

tag1; tag2 > php_tag2; "static value" > php_tag3

//Script will receive inputs tag1, php_tag2, and php_tag3.

# XML-RPC

Scripts can fetch values directly by using the XML-RPC facility provided by OI. For more information, see the XML-RPC page.

# Getting Values From Scripts

# Return Values

Scripts can return no value (empty string) or a JSON formatted string with output tags values and an optional error message (the red error banner will appear if error_string is defined and non-empty/non-null).

{
  "vars" : [
     {"name" : "tag1" , "value" : '0'},
     {"name" : "tag2" , "value" : '0'},
      ...
  ],
  "error_string" : "Some error message"
}

TIP

OI expects HTTP return values to be 200. Any other return value is treated as an error.

# Direct tags

The script can return tags mapped directly to tag names listed in the outputTags property.

Example: tag1 ; tag2 ; tag3
Tag names are passed from script under their names as defined by script, i.e. “tag1”, “tag2” and “tag3” is passed from the script.
Values from the script are written into OI tags.

# Mapped Return Values

The return values from the script can be mapped to tags in OI.

Example: oi_tag1 < php_tag1 ; oi_tag2 < php_tag2; oi_tag3 < php_tag3
Specific name from the script is mapped to oi tag name, i.e. “php_tag1” from the script is mapped to oi tag oi_tag1, etc.
Values from the script are written into OI tags.

# outputTag Example

All options can be combined:

tag1; tag2 < php_tag2

//OI will set the values of tags tag1 and tag2

# XML-RPC

Scripts can communicate with the OI application to fetch current tag values by using the XML-RPC server included in OI. The XML RPC page describes the service further. See examples in the Tutorials for example scripts.

# Script Packaging

Scripts are packaged with an application using subdirectories for HTTP scripts and Shell scripts:

Location	Description
applicationName___httpscripts	directory where all http scripts and all the accompanying files are located
applicationName___shellscripts	directory where all shell scripts and all the accompanying files are located

# OIB Behavior

OIB creates an empty directory 'applicationName___httpscripts' at the moment application with at least one HTTP script component is saved. Any files can be copied into the directories and they will be distributed with the application. The contents of the directory is saved together with the OI app on Save As and Save to FTP commands.

The same applies to 'applicationName___shellscripts' directory and Shell script component.

# OI Runtime Behavior

There are two run-time directories where the scripts will be copied before application starts.

Location	Description
/tmp/app/httpscripts	for HTTP Script Component. Content of 'applicationName___httpscripts' is copied here
/tmp/app/shellscripts	for Shell Script Component. Content of 'applicationName___shellscripts' is copied here

Note

The whole directory /tmp/app is always cleared by 'rm -r *' when the application is selected or screen rebooted so there can't be any clashes between different scripts of different applications. Simply exiting to the Config screen and then returning to Run mode will not reload the scripts directory.

Note

These directories are in RAM disk (volatile storage) and their content is lost at TS reboot. If scripts need to store their data then they have to place them to non-volatile location such as the data card or hard disk.

# Debugging

Script Log Example

Example of logging information contained for script execution.

Debug output from each component is written into file: /var/log/oiscript_N_CompName where

N … screen number where script component is placed
CompName …. name of script component. If there are multiple components with the same name on the same screen then suffix _1, _2, etc. is appended.

The log file is rotated if its size exceeds 2 MB. Total number of log files in the rotation is 2.

# Debugging HTTP Scripts

HTTP Scripts can be debugged using a browser to visit the script page. See Web Server for more information.

# Debugging Shell Scripts

Shell scripts can be executed directly using the command line. You can access the command line by starting XTerm (on the OI terminal, go to OIB, minimize the window, click once on XTerm). This can be performed remotely using VNC.

You can also use SSH to access command line and debug shell scripts directly.

# Sample PHP HTTP Script

This script accepts int1 and string1 variables from OI, and adds 1 to int1 and modifies string1.

<?php
require 'init_defaults.php';
header('Content-type: application/json');
chdir(__DIR__);
ini_set("error_reporting",E_ALL);  // error reporting level
ini_set('display_errors', true);   // print errors into output ?
ini_set("log_errors",true);        // log errors into log ?
//ini_set("error_log","/var/log/php.log");  // log into given file instead of web server's log

// is set to true if the script is executed on application start
$_STARTUP_ = false;

// all input variables passed to the script are stored into $input_vars array
$input_vars = array();

// this list of all output variables is converted to json and echoed to output at the end of this script
$output_vars = array();

// this string will be displayed by OI in top red message box window
$output_error_string = '';

// ***********************************************************
// fill $input_vars array
// ***********************************************************
foreach($_POST as $varName=>$varValue) {
  if ($varName=="_STARTUP_") {
    $_STARTUP_ = true;
    continue;
  }
  $input_vars[$varName] = $varValue;
}

// ***********************************************************
// convert $output_vars to json and put to output
// ***********************************************************
function echoJSON() {
    global $output_vars;
    global $output_error_string;
    $ret = array();
    $vars = array();
    foreach($output_vars as $varName=>$varValue) {
        $var = array();
        $var["name"] = $varName;
        $var["value"] = $varValue;
        $vars[] = $var;
    }
    $ret["vars"] = $vars;
    $ret["error_string"] = $output_error_string;
    if (version_compare(PHP_VERSION, '5.4.0') >= 0)
        $retJSON = json_encode($ret, JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES);
    else
        $retJSON = json_encode($ret);
    echo $retJSON . "\n";
}

// ***********************************************************
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
// main script starts here
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
// ***********************************************************

// sanity check of input variables
if ( !array_key_exists("int1",$input_vars) ) $input_vars["int1"] = 0;
if ( !array_key_exists("string1",$input_vars) ) $input_vars["string1"] = "empty string";
if ( !array_key_exists("string2",$input_vars) ) $input_vars["string2"] = "";

// calculate output tags
if ($_STARTUP_) {
  $output_vars["int1"] = 999;
  $output_vars["string1"] = "OI app has just started !";
} else {
  $output_vars["int1"] = $input_vars["int1"] + 1;
  $output_vars["string1"] = $input_vars["int1"] + 1 . " " . $input_vars["string1"] . $input_vars["string2"];
  //$output_error_string = "Oops this should not happen !";
}

// echo json output
echoJSON();

# PHP Shell Script Example

#!/usr/bin/php
<?php
require 'init_defaults.php';

// is set to true if the script is executed on application start
$_STARTUP_ = false;

// all input variables passed to the script are stored into $input_vars array
$input_vars = array();

// this list of all output variables is converted to json and echoed to output at the end of this script
$output_vars = array();

// this string will be displayed by OI in top red message box window
$output_error_string = '';

// ***********************************************************
// fill $input_vars array
// ***********************************************************
foreach($argv as $param) {
  if ($param=="-_STARTUP_=1") {
    $_STARTUP_ = true;
    continue;
  }
  if (strpos($param,"-var:")===0) {
    $param = substr($param, 5);
    $a = explode("=", $param);
    if (count($a)==2) {
      $varName = str_replace('\"', '"', $a[0]);  // unescape quotes
      $varValue = str_replace('\"', '"', $a[1]); // unescape quotes
      $input_vars[$varName] = $varValue;
    }
  }
}

// ***********************************************************
// convert $output_vars to json and put to output
// ***********************************************************
function echoJSON() {
    global $output_vars;
    global $output_error_string;
    $ret = array();
    $vars = array();
    foreach($output_vars as $varName=>$varValue) {
        $var = array();
        $var["name"] = $varName;
        $var["value"] = $varValue;
        $vars[] = $var;
    }
    $ret["vars"] = $vars;
    $ret["error_string"] = $output_error_string;
    if (version_compare(PHP_VERSION, '5.4.0') >= 0)
        $retJSON = json_encode($ret, JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES);
    else
        $retJSON = json_encode($ret);
    echo $retJSON . "\n";
}

// ***********************************************************
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
// main script starts here
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
// ***********************************************************

// sanity check of input variables
if ( !array_key_exists("int1",$input_vars) ) $input_vars["int1"] = 0;
if ( !array_key_exists("string1",$input_vars) ) $input_vars["string1"] = "empty string";
if ( !array_key_exists("string2",$input_vars) ) $input_vars["string2"] = "";

// calculate output tags
if ($_STARTUP_) {
  $output_vars["int1"] = 999;
  $output_vars["string1"] = "OI app has just started !";
} else {
  $output_vars["int1"] = $input_vars["int1"] + 1;
  $output_vars["string1"] = $input_vars["int1"] + 1 . " " . $input_vars["string1"] . $input_vars["string2"];
  //$output_error_string = "Oops this should not happen !";
}

// echo json output
echoJSON();
?>

← Screens Storage →