Эта страница является переводом страницы IRidium studio 2019 Custom Systems. Перевод выполнен на 100%.

---

iRidium studio 2019

Tools to create your own drivers

Tools to create your own drivers

A group of "AV & Custom Systems" drivers allows to set connection with an external resource (TCP, UDP, HTTP, Serial), on the basis of which you can realize a protocol of data exchange that you did not find in the list of iRidium ready soluitons.

A driver in iRidium realizes a protocol (rules) to exchange data with equipment on the basis of transport - a definite means to exchange data (TCP, UDP, HTTP, Serial).

But if your system does not have a realized protocol, you can create it yourself. To do it a driver is required that realizes only the transport part of the data exchange process, as for the protocol part (forming requests and processing answers), it is formed by you with the help of JavaScript.

Several driver-transports can be created in iRidium pro. Let's have a close look at their features and use:

Selecting AV & Custom Systems Driver

Add AV & Custom Systems driver for your task:

• TCP, UDP, Serial (RS232) to connect to a remote resource via TCP, UDP or RS232 protocol.:
  • "AV & Custom Systems" driver in i3 pro or iRidium server
  • Select in the "Protocol" parameter of the driver settings a type of transport: TCP, UDP or Serial (RS232)
• HTTP to connect to c remote resource via HTTP, HTTPs protocol:
  • Драйвер "AV & Custom Systems (HTTP)" in i3 pro or iRidium server
• TCP server to accept connections from remote resources via TCP protocol:
  • JavaScript realization of TCP server, a driver is not added to the device tree
• General transport. For several logic devices to work via one TCP/UDP, using different data in the script and different address to commands and feedback channels
  • "AV & Custom TCP/UDP Network" driver in i3 pro or iRidium server
  • "AV & Custom HTTP Network" driver in i3 pro or iRidium server

Connection Settings

When a driver is added, enter its connection parameters:

AV & Custom Systems, TCP

AV & Custom Systems driver, Protocol: TCP. Connection parameters:

• Host - IP-адрес or domain name
• Port - TCP connection port
• Mode - connection mode:
  • Always Connected - it is always connected
  • Connect when Sending - it is connected only at the moment commands are sent. Feedback is not received in this mode, but commands can be sent without occupying connection al the time
• SSL - turn on /off SSL encrypting
• Script Mode - a mode of forwarding commands to script:
  • Direct and Script - send a command to equipment at once and copy it to the script
  • Script Only - send a command only to script (when a button is pressed, a command, assigned to it, is processed in iRidium script, and is not sent to equipment, as it usually happens)
• Disable Queue - turn off a queue of commands in iRidium. The queue "stores" commands that were not sent for some reason and sends them when connection is restored
• Send Command Attempts - the number of attempts to send a command from a queue that was not successfully sent for the first time. 0 - do not repeat sending
• Wait for Connection (ms) – time to wait for connection (otherwise another connection attempt is made)
• Wait for Data (ms) – time to wait for and answer from equipment (otherwise a command is repeated and connection is checked). Put 0, if you don't want your driver to disconnect from equipment, if there is no data exchange

AV & Custom Systems, UDP

AV & Custom Systems driver, Protocol: UDP. Conenction parameters:

• Host - IP-address or domain name
• Port - UDP connection port
• Script Mode - mode to forward commands to script:
  • Direct and Script - send a command directly to equipment and copy it in the script
  • Script Only - send a command only to the script (when a button is pressed, a command, assigned to it, is processed in iRidium script and is not sent to equipment, as it usually happens)
• Local Port - UDP port that is open on iRidium side: data from equipment come here. It can be different from a port open on the equipment side
• Multicast - use a mode of multicast connection
  • Group - multicast group, for example, например 224.0.0.1

AV & Custom Systems, Serial (RS232)

AV & Custom Systems Driver, Protocol: Serial (RS232). Connection parameters:

• Host - number of СОМ-port, to which a controlled device is connected. For example,: \\.\COM1
• Baud Rate - speed of data exchange
• Data Bits - number of data bits in a shot
• Parity - parity control
• Stop Bits - stop bit in a shot
• Script Mode - mode to forward commands to script:
  • Direct and Script - send a command directly to equipment and copy it to script
  • Script Only - send a command only to script (when a button is pressed, a command, assigned to it, is processed in iRidium script, it is not sent to equipment, as it usually happens)

AV & Custom Systems (HTTP), HTTP

AV & Custom Systems driver (HTTP). Connection parameters:

• Host - IP address or domain name
• Port - TCP connectin port (usually 80)
• Login, Password - login and password of protected connection
• SSL - turn on/off SSL encrypting
• User Agent - user name used by iRidium to address a remote system
• Script Mode - mode to forward commands to script:
  • Direct and Script - send a command directly to equipment and copy it to script
  • Script Only - send a command only to script (when a button is pressed, a command, assigned to it, is processed in iRidium script, but is not sent to equipment, as it usually happens)
• Disable Queue - turn off a queue of commands to iRidium. A queue "stores" commands, that were not sent for some reason,and sends them when connection is restored
• Send Command Attempts - number of attempts to send a command from a queue that could not be sent once. 0 - do not repeat sending
• Wait for Connection (ms) – time to wait for connection (otherwise another connection attempt is made)
• Wait for Data (ms) – period of time to wait for an answer from equipment (otherwise a command is repeated and connection is checked). Enter 0, if you do not want a driver to disconnect from equipment when there is no data exchange

Examples of Forming Commands

Strings, simbols, numerals and their sequences for TCP, UDP, Serial

To send equipment some data sequence via TCP, UDP, or via COM-port, it is required: to create a Command in "AV & Custom Systems" driver with a corresponding transport and enter data in the Data field of the created command.

When a command with any value is called, entered data are sent to equipment

During iRidium work the contents of a command written this way can't be changed (it's a constant). Variable values must be formed in script (see .Set и .Send methods).

Rules to form data :

• STRING use 'single quotes', use single quotes for several strigns and separate them with commas. See below CR or LF line break
• Шестнадцатеричные (HEX) символы разделите запятыми, перед каждым символом поставьте значок $ или 0x (другие не поддерживаются)
• Десятичные (DEC) числа разделите запятыми
• В конце данных добавьте, согласно указаниям вашего API, один из символов конца строки (или оба символа):
  • ,13 - возврат каретки (CR, carriage return). Этот же символ в iRidium можно записать как ,$0D или ,0x0D
  • ,10 - подача строки (LF, line feed). Этот же символ в iRidium можно записать как ,$0A или ,0x0A
  • некоторые устройства принимают только CR, некоторые CR+LF, а некоторые и вовсе не нуждаются в указании на конец строки, но указание чаще требуется; опирайтесь на ваш API и не пренебрегайте этой надстройкой!

Examples:

• Sequence of hexadecimal simbols + end of line
  0x16,0x8A,0xFF,0x81,13 or
  0x16,0x8A,0xFF,0x81,0x0D
• Sequence of decimal numbers + end of line
  01,255,255,15,13
• Line + end of line
  'PWR 01',13
• Mixed data + end of line
  0,255,'PWR 01',0x00,0xFF,13

How to understand that data are formed correctly:

• The lower part of the window in the window mode of data review shows a command in the HEX format (as a driver sends it). If you see no simbols in the lower part of the window, or if the number of simbols above and below is evidently different, it means you made a mistake in forming data. Check commasm interted commas and HEX simbols.
• If the first part of data is formed correctly, and the second is not, the second part is ignored,, that's why check that the number of simbols in the upper and lower part of the window is the same.

GET, POST, PUT requests over HTTP

To send HTTP-request to equipment create a Command in "AV & Custom Systems (HTTP)" driver and enter data in the URI field of a created command. POST and PUT requests allow to send additional data in the Data field.

When a command with any value is called, you send a formed request to equipment

During iRidium work the contents of a request written this way can't be changed (it's a constant). Variable values must be formed in script (see .SendEx method).

Rules for GET-requests:

A request consists of URI body - it's data written in the HTTP-request after IP-address or domain. Data must be copied to the URI field starting with / (slash) simbol without inverted commas:

• example 1: http://iridi.com/support
  • /support - it's a body of a request that must be placed in the URI field.
  • iridi.com - send address is entered in the Host fiels of a driver settings
  • default port (80) is entered in driver settings
• example 2: httр://192.168.0.100:81/do?cmd=ir_code=B748BF00
  • /do?cmd=ir_code=B748BF00 - it's a body of a request that must be placed in the URI field.
  • 192.168.0.100 - send address is entered in the Host fiels of a driver settings
  • 81 - port, entered in driver settigns
• You can use .SendEx script method to form requests, data, headings and to process answers received to these requests

Rules of POST and PUT-requests:
A request consists of a URI body - it's data written in HTTP-request after IP-address or a domain name, that are written in the Data fiels. URI is written without inverted commas, Data are writtem as a line array in inverted commas (see rules for TCP, UDP, Serial lines).

Example:

POST /YamahaRemoteControl/ctrl HTTP/1.1
 
Accept: */*
Referer: http://192.168.10.102/
Content-Type: text/xml; charset=UTF-8
Host: 192.168.10.100
Content-Length: 105
Cache-Control: no-cache
 
<YAMAHA_AV cmd="PUT"><System><Power>Standby</Power></System></YAMAHA_AV>

• /YamahaRemoteControl/ctrl - (without HTTP 1.1) it's the body of a request that must be placed in the URI field
• '<YAMAHA_AV cmd="PUT"><System><Power>Standby</Power></System></YAMAHA_AV>' - these are additional data, that must be placed in inverted commas and placed in the Data field
• The remaining data are headings that a driver forms automatically
• You can use .SendEx script method to form requests, data, headings and to process answers received to these requests

Examples of Processing Incoming Data

Incoming data are always processed in the script.

You can subscribe to IR.EVENT_RECEIVE_TEXT or IR.EVENT_RECEIVE_DATA event with the help of any transport and process data received from a driver.

In case withHTTP the most suitable method to process data is .SendEx – it allows to form and send a request, to wait for an answer and to process at once the answer that came to this very request. This way you will not have to identify what this or that answer refers to, in contrast to working with the event system of a driver.

Example of TCP-server with processing incoming data.

Example of using SendEx:

function Login() {
   IR.GetDevice("Server REST").SendEx({ 
      Type: "POST",                                                                    
      Url:  "/html/login",
      Data: ["Password=2007&name=auth&Login=admin"],
      Headers: {"Content-Type": "application/x-www-form-urlencoded"}, 
 
      cbReceiveKey: function(key,value) 
      {             
         if (key == "set-cookie")
         {   
            cookie = value.match(/=.+;/);
            if (cookie) {
                IR.Log("ir-session-id" + cookie);
                Volume80();
            }
         }
      }
   });
}
 
function Volume80() {
   IR.GetDevice("Server REST").SendEx({ 
      Type: "GET",                                                                    
      Url:  "/json/ok/server/channel/set?name=Sender%20Hotel.FM%20Volume?value=80",
      Headers: {"Cookie":"ir-session-id" + cookie},
 
       cbReceiveText: function(text, code, headers) {
           IR.Log("cbReceiveText code: " + code); IR.Log("cbReceiveText text: " + text);
       }
   });
}
 
IR.AddListener(IR.EVENT_START, 0, function() {
    Login();
});

Example of TCP-server

Example: TCP-server for i3 pro