XML-RPC Server

OI Runtime provides an XML-RPC server which allows other programs to get information about the OI terminal and to view or modify tag values.

The writeTag method is only allowed if the communication adapter is set to permit these functions in OIB.

Warning

Allowing XML-RPC server to modify tag data can present hazardous situations. We recommend creating a separate adapter which includes only the tags you want to allow external access to.

Testing Using CLI

OI includes a sample PHP script to allow testing the XML-RPC functionality by using the command line interface.

Log into the OI through SSH, then run:

cd /var/oi/www/php_cli
./tag_cli.php --help
./tag_cli.php --readTagValue --tag someTag
./tag_cli.php --writeTagValue --tag someTag --value valueToWrite

The tag_cli.php script prints output json formatted.

OI XML-RPC server methods API

XML-RPC returns 'error' property if request failed and there is no tags to return. Its value has textual description what was wrong.

XML-RPC returns 'ok' property if request was fully or partially successful.

On full success 'ok' property value is 'success'.

On partial success 'ok' property value contains textual description what was wrong.

getInfo

XML-RPC input parameters: none

XML-RPC response converted into php using function xmlrpc_decode:

array (
  0 => array (
    'property' => 'ok',
    'value' => 'success',
  ),
  1 => array (
    'property' => 'info',
    'value' => array (
      0 => array (
        'property' => 'oi_version',
        'value' => '1.9',
      ),
      1 => array (
        'property' => 'build',
        'value' => 'Apr 16 2015  14:40:33 UTC',
      ),
      2 => array (
        'property' => 'up_time_sec',
        'value' => 346105,
      ),
      3 => array (
        'property' => 'timestamp',
        'value' => '33250316',
      ),
      4 => array (
        'property' => 'date_time',
        'value' => '2015-04-20 17:02:09',
      ),
      5 => array (
        'property' => 'mode',
        'value' => 'master',
      ),
      6 => array (
        'property' => 'application',
        'value' => array (
          0 => array (
            'property' => 'name',
            'value' => 'unnamed',
          ),
          1 => array (
            'property' => 'desc',
            'value' => '',
          ),
          2 => array (
            'property' => 'file',
            'value' => '/oi/gestamp_alarmtest.oi',
          ),
          3 => array (
            'property' => 'current_screen',
            'value' => 3,
          ),
        ),
      ),
    ),
  ),
)

getTagList

XML-RPC input parameters: none

XML-RPC response converted into php using function xmlrpc_decode:

array (
  0 => array (
    'property' => 'ok',
    'value' => 'success',
  ),
  1 => array (
    'property' => 'info',
    'value' =>
    array (
            /*  ... the same object as returned by getInfo method ...  */
    )
  ),
  2 => array (
    'property' => 'drivers',
    'value' => array (  /*  list of all drivers  */
      0 => /* 1st driver */
      array (
        0 =>
        array (
          'property' => 'driver_name',
          'value' => 'dummy',
        ),
        1 =>
        array (
          'property' => 'driver_type',
          'value' => 'Internal Memory',
        ),
        2 =>
        array (
          'property' => 'tags',
          'value' => array (  /*  list of all driver tags  */
            0 => /* 1st tag */
            array (
              0 =>
              array (
                'property' => 'name',
                'value' => 'alarmLoopTrigger',
              ),
              1 =>
              array (
                'property' => 'description',
                'value' => '',
              ),
              2 =>
              array (
                'property' => 'data_type',
                'value' => 4,
              ),
              3 =>
              array (
                'property' => 'address',
                'value' => 'N0:0/0',
              ),
            ),
            1 => /* 2nd tag */
            array (
              0 =>
              array (
                'property' => 'name',
                'value' => 'hideAlarms',
              ),
              1 =>
              array (
                'property' => 'description',
                'value' => '',
              ),
              2 =>
              array (
                'property' => 'data_type',
                'value' => 1,
              ),
              3 =>
              array (
                'property' => 'address',
                'value' => 'N0:2/0',
              ),
            ),
...

Meaning of data_type property:

data_type	Data Type	Description
0	Undefined	undefined type (undefined value)
1	Bit	bit
2	BitA	bit array
3	Bcd4	bcd4 (0000-9999)
4	UInt	16bit unsigned integer
5	Int	16bit signed integer
6	CharA	character array
7	Real	32bit IEEE float
8	DInt	32bit signed integer
9	DUInt	32bit unsigned integer

readTagValue

XML-RPC input parameters: at least 1 parameter, each parameter is name of tag to read (string type) PHP code:

$xml_rpc_params = array();

// name of OI tag we want to read
$xml_rpc_params[] = 'tag1';

XML-RPC response converted into php using function xmlrpc_decode:

array (
  0 =>
  array (
    'property' => 'ok',
    'value' => 'success',
  ),
  1 =>
  array (
    'property' => 'info',
    'value' => array (
            /*  ... the same object as returned by getInfo method ...  */
    ),
  ),
  2 =>
  array (
    'property' => 'tags',
    'value' => array (  /* list of all tags and values */
      0 => /* 1st tag */
      array (
        0 =>
        array (
          'property' => 'name',
          'value' => 'tag_0',
        ),
        1 =>
        array (
          'property' => 'value',
          'value' => '0',
        ),
      ),
      1 => /* 2nd tag */
      array (
        0 =>
        array (
          'property' => 'name',
          'value' => 'tag_1',
        ),
        1 =>
        array (
          'property' => 'value',
          'value' => '0',
        ),
      )
...

writeTagValue

XML-RPC input parameters: at least 1 parameter, each parameter is struct type.

Struct:

member 'name': tag name (string)
member 'value': value to write (string)

$xml_rpc_params = array();

// name of OI tag and value we want to write into
$xml_rpc_params[] = array('name'=>'tag1', 'value'=>'1');

XML-RPC response converted into php using function xmlrpc_decode:

array (
  0 =>
  array (
    'property' => 'ok',
    'value' => 'success',
  ),
  1 =>
  array (
    'property' => 'info',
    'value' => array (
            /*  ... the same object as returned by getInfo method ...  */
    ),
  ),
  2 =>
  array (
    'property' => 'tags',
    'value' => array (  /* list of all tags and values */
      0 => /* 1st tag */
      array (
        0 =>
        array (
          'property' => 'name',
          'value' => 'tag_0',
        ),
        1 =>
        array (
          'property' => 'write_value',
          'value' => '10',
        ),
        array (
          'property' => 'read_back_value',
          'value' => '10',  /* this is ok - read value == write value */
        ),
      ),
      1 => /* 2nd tag */
      array (
        0 =>
        array (
          'property' => 'name',
          'value' => 'tag_1',
        ),
        1 =>
        array (
          'property' => 'write_value',
          'value' => '10',
        ),
        array (
          'property' => 'read_back_value',
          'value' => '0',   /* this indicates error - read value != write value */
        ),
      )
...