AMX i!-ConnectLinx Instruction Manual

LICENSE GRANT. AMX grants to Licensee the non-exclusive right to use the AMX Software in the manner described in this License. The AMX Software is licensed, not sold. The AMX Software consists of generally available programming and development software, product documentation, sample applications, tools and utilities, and miscellaneous technical information. Please refer to the README.TXT file on the compact disc or download for further information regarding the components of the AMX Software. The AMX Software is subject to restrictions on distribution described in this License Agreement. YOU MAY NOT LICENSE, RENT, OR LEASE THE AMX SOFTWARE. You may not reverse engineer, decompile, or disassemble the AMX Software. INTELLECTUAL PROPERTY. The AMX Software is owned by AMX and is protected by United States copyright laws, patent laws, international treaty provisions, and/or state of Texas trade secret laws. Licensee may make copies of the AMX Software solely for backup or archival purposes. Licensee may not copy the written materials accompanying the AMX Software. TERMINATION. AMX RESERVES THE RIGHT, IN ITS SOLE DISCRETION, TO TERMINATE THIS LICENSE FOR ANY REASON AND UPON WRITTEN NOTICE TO LICENSEE. In the event that AMX terminates this License, the Licensee shall return or destroy all originals and copies of the AMX Software to AMX and certify in writing that all originals and copies have been returned or destroyed. PRE-RELEASE CODE. Portions of the AMX Software may, from time to time, as identified in the AMX Software, include PRE-RELEASE CODE and such code may not be at the level of performance, compatibility and functionality of the final code. The PRE-RELEASE CODE may not operate correctly and may be substantially modified prior to final release or certain features may not be generally released. AMX is not obligated to make or support any PRE-RELEASE CODE. ALL PRE-RELEASE CODE IS PROVIDED "AS IS" WITH NO WARRANTIES. LIMITED WARRANTY. AMX warrants that the AMX Software will perform substantially in accordance with the accompanying written materials for a period of ninety (90) days from the date of receipt. AMX DISCLAIMS ALL OTHER WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH REGARD TO THE AMX SOFTWARE. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. Any supplements or updates to the AMX SOFTWARE, including without limitation, any (if any) service packs or hot fixes provided to you after the expiration of the ninety (90) day Limited Warranty period are not covered by any warranty or condition, express, implied or statutory. LICENSEE REMEDIES. AMX's entire liability and your exclusive remedy shall be repair or replacement of the AMX Software that does not meet AMX's Limited Warranty and which is returned to AMX. This Limited Warranty is void if failure of the AMX Software has resulted from accident, abuse, or misapplication. Any replacement AMX Software will be warranted for the remainder of the original warranty period or thirty (30) days, whichever is longer. Outside the United States, these remedies may not available. NO LIABILITY FOR CONSEQUENTIAL DAMAGES. IN NO EVENT SHALL AMX BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THIS AMX SOFTWARE, EVEN IF AMX HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES/COUNTRIES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU. U.S. GOVERNMENT RESTRICTED RIGHTS. The AMX Software is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software Restricted Rights at 48 CFR 52.227-19, as applicable. This Agreement replaces and supercedes all previous AMX Software License Agreements and is governed by the laws of the State of Texas, and all disputes will be resolved in the courts in Collin County, Texas, USA. Should you have any questions concerning this Agreement, or if you desire to contact AMX for any reason, please write: AMX Corporation, 3000 Research Drive, Richardson, TX 75082.

i i!-ConnectLinx Table of Contents Introduction ...............................................................................................................1 Supported Operating Systems .......................................................................................... 1 Minimum PC Requirements .............................................................................................. 1 Installing i!-ConnectLinx .................................................................................................... 2 Using i!-ConnectLinx ...............................................................................................3 Standard Actions............................................................................................................... 4 Action Arguments.............................................................................................................. 6 Action Persistence and Distribution................................................................................... 7 International Issues / Localization ..................................................................................... 8 Programming..................................................................................................................... 8 Channels.................................................................................................................................. 8 Levels....................................................................................................................................... 8 Commands............................................................................................................................... 9 Strings.................................................................................................................................... 10 Module ................................................................................................................................... 11

world. i!-ConnectLinx allows a programmer to define and program actions that can be utilized by other user interfaces or processes outside the NetLinx Control System. For instance, i!-ConnectLinx can be programmed to expose source select functions and i!-ConnectLinx compatible technologies, such as MeetingManager and i!-MacroManager, can use this information to allow the source selects to be executed a scheduled event. i!-ConnectLinx also provides a mechanism to request actions to be executed on the NetLinx Control System. Once a process outside the NetLinx Control System has obtained the action list, the process can then make a request to i!-ConnectLinx to execute that action. i!-ConnectLinx handles this request and makes this request available to the NetLinx program for execution. i!-ConnectLinxEngineMod, is the main i!-ConnectLinx module that handles exposing and executing action requests, see the Module section on page 11. To support i!-ConnectLinx, you simply include this module in your program, define your actions and write programming to support those actions. The i!-ConnectLinxEngineMod module makes the list of actions available to other processes, executes their requests and provides your program with a push when an action needs to be executed. Supported Operating Systems z Windows 95®/98® (with at least 48 MB of installed memory) z Windows NT 4.0® Workstation or Server (service pack 6 B or greater, with at least 64 MB of installed memory) z Windows 2000® Professional or Server (running on a Pentium 233 MHz processor (minimum requirement); 300 MHz or faster recommended, with 96 MB of installed memory.) Minimum PC Requirements z Windows-compatible mouse (or other pointing device) z At least 5 MB of free disk space (150 MB recommended) z VGA monitor, with a minimum screen resolution of 800 x 600 z A Network adapter z A Web server such as Personal Web Server (PWS) or Internet Information Server (IIS) z Windows 95® and 98® use PWS. z Windows 2000® Professional or Server, and Windows NT 4.0® Server use IIS.

downloaded the i!-ConnectLinx install program. 2. After reading the License Agreement, select I Agree and Next to proceed. 3. The Welcome To i!-ConnectLinx Setup dialog appears, reminding you to close all Windows programs before going any further. Click Next to proceed. 4. In the Select i!-ConnectLinx Install Location dialog, use the Browse button to navigate to a directory other than the default install directory, if desired. Click Next. 5. In the i!-ConnectLinx Shortcut Creation dialog, select Install Shortcut Icons for the installed components on your desktop, if desired. 6. Click Next in the Start i!-ConnectLinx Installation dialog to install the selected components. 7. The program prompts you to restart your system to complete the installation.

implemented as a NetLinx module. Adding the module definition and all it’s parameters to your code is all that is required. In order to use i!-ConnectLinx, you need to program and define a series of actions in the NetLinx Control System. The key to the i!-ConnectLinx engine is the virtual device, vdvCLActions, see the Module section on page 11. Support the actions you want executed remotely using this virtual device. Think of the virtual device, vdvCLActions, as a touch panel. Normally, you write your NetLinx program to respond to certain push channel from a touch panel; i!-ConnectLinx is exactly the same. Let’s say you want the user to be able to allow the ability to play and stop a VCR. Imagine you have two touch panel buttons that do these functions; write code that responds to the pushes: BUTTON_EVENT[TP,1] (* VCR Play *) { PUSH: { PULSE[VCR,1] } } BUTTON_EVENT[TP,2] (* VCR Stop *) { PUSH: { PULSE{VCR,2] } } To expose these actions using i!-ConnectLinx, write the same code substituting the touch panel device for your i!-ConnectLinx virtual device: BUTTON_EVENT[vdvCLActions,1] (* VCR Play *) { PUSH: { PULSE[VCR,1] } } BUTTON_EVENT[vdvCLActions,2] (* VCR Stop *) { PUSH: { PULSE{VCR,2] } } When the i!-ConnectLinx engine gets a request to play the VCR, i!-ConnectLinx will "push" the button of the virtual device just like a user pushes a button on a touch panel. There is now only one thing left to do: Tell the user which actions are which. In order to expose an action for execution via i!-ConnectLinx, you need to support the programming for the action, as we have just seen, and you need to tell i!-ConnectLinx what that action is.

the name of a given channel code. To specify the names of the actions in the above example, you would add some code like this: DATA_EVENT[vdvCLActions] { ONLINE: { (* Setup actions *) (* VCR Play *) SEND_COMMAND vdvCLActions,"'ADD ACTION-1,VCR Play" (* VCR Stop *) SEND_COMMAND vdvCLActions,"'ADD ACTION-2,VCR Stop' " } Once i!-ConnectLinx receives these commands, it stores this information in an XML file that can be used by i!-ConnectLinx compatible technologies to browse available actions. In addition to specifying the name of an action, you can also supply a help string and a folder name. The help string helps a user understand the intent of the action more clearly. The folder name allows you to organize the actions in a tree view so that actions are more easily browsed. Standard Actions So far, i!-ConnectLinx has handled custom actions where each action is likely to be different from system to system. In the Using i!-ConnectLinx example, page 3, action 1 played the VCR. However, in another system, it is very unlikely that action 1 plays the VCR. i!-ConnectLinx uniquely identifies each action list. Once an i!-ConnectLinx compatible technology programs itself to execute an action on a system, it also stores a copy of the system identifier from the action list. This identifier is sent to i!-ConnectLinx along with this action execution request. If the action identifier does not match the i!-ConnectLinx system that received the request, the action is not executed. This eliminates the ambiguity that may exist, since each system’s action 1 may be different. i!-ConnectLinx supports standard actions. Standard actions are actions defined by AMX and supported natively by i!-ConnectLinx. When adding actions to i!-ConnectLinx, it is best to use the standard action if it is available. That way, the action can be executed regardless of which system the i!-ConnectLinx compatible technology was programmed to control. The list of standard actions are listed in the i!-ConnectLinxStdFunctionList.xls file. The standard actions ID are the same is the channel number used to execute the action. For instance, VCR Select has an ID of 1011 so the programming to support this standard action is: BUTTON_EVENT[vdvCLActions,1011] (* VCR Select *) { PUSH: { // Switch the projector and switcher to select the VCR } } To add a standard action, look up the action ID in the Standard Function List file, and send that in a send command to i!-ConnectLinx to tell it you want to support that action. To change the above example to standard action: 1. Lookup VCR Play and VCR Stop in the Standard Function List. Continued

3. Send the IDs to i!-ConnectLinx: DATA_EVENT[vdvCLActions] { ONLINE: { (* Setup actions *) (* VCR Play *) SEND_COMMAND vdvCLActions,"'ADD STD-1131'" (* VCR Stop *) SEND_COMMAND vdvCLActions,"'ADD STD-1132'" } Additionally, change the two BUTTON_EVENTs to trigger for channels 1131 and 1132 instead of 1 and 2. There are other syntax’s of the add standard action command that allow you add multiple actions at a time. The ‘&’ character can be used to signify "AND" and the ‘-‘ character can be used to signify "through". Since many of the standard actions are related, they can also be added by macros. A macro is a list of one or more standard actions. In the case of a VCR, the full set of transports are needed, not just Play and Stop. Also, if the VCR exists in the system then there is likely a way to select the VCR as the active source. Therefore, the "vcr" macro includes the VCR source select and the standard transports. To load a set of actions by macro, simply send a command to i!-ConnectLinx with the macro you want added. For example: DATA_EVENT[vdvCLActions] { ONLINE: { (* Setup actions *) (* VCR Select and Play-Record *) SEND_COMMAND vdvCLActions,"'ADD MACRO-vcr'" } For a complete list of macros, see the i!-ConnectLinxStdFunctionList.xls file. A common method for programming i!-ConnectLinx is to simply register standard actions and responding to the actions by "DO_PUSH"ing an existing button on the touch panel. For instance: BUTTON_EVENT[vdvCLActions,1011](* VCR Select *) { PUSH: DO_PUSH(dvTP,11) (* Button 11 on dvTP selects VCR *) } To make programming i!-ConnectLinx easier, the i!-ConnectLinxStdFunctionList.xls file includes an i!-ConnectLinx Code Generator page. On this page, you can enter the i!-ConnectLinx device, the Touch Panel device and the Touch Panel buttons for each standard action. The code generator will create an Include (AXI) file that contains the necessary code to register and respond to the selected actions. Optionally, the code generator can include the DEFINE_MODULE statement for i!-ConnectLinx. Once the Include file is created, you will need to include this file in your main program with an #INCLUDE statement and make sure the i!-ConnectLinx and Touch Panel devices are defined. See the i!-ConnectLinxStdFunctionList.xls file for more details.

instance, if you wanted to support an action to set the program volume, the user needs to supply a volume level. This is accomplished using arguments. Each action can support zero or more arguments. Each argument can be one of the following types: z Number – A single number from –32767 to 32767. You can define the minimum value, maximum value, desired step and a default value. The user is presented with a text box in which to enter this number. z Level – Similar to a Number argument, only the user is presented with a slider to enter the level. z String – A string. You can define the minimum length, maximum length and default value. The user is presented with a text box to enter this string. z Enumeration – A list or enumeration of values the user can choose from. The user is presented with a drop down list to choose and value from. Each argument is numbered in the order they are added. Arguments are added by using the 'ADD NARG', 'ADD LARG', 'ADD SARG' and 'ADD EARG' commands. When an i!-ConnectLinx compatible technology requests an action with arguments to be executed, the argument values are passed to i!-ConnectLinx. i!-ConnectLinx then posts the argument values as levels for number and level arguments and strings for string and enumeration arguments. These values can be retrieved by using LEVEL_EVENTs and DATA_EVENTs in your program and must be saved. Then, when an action request is triggered via a BUTTON_EVENT, you can retrieve these argument values and use them (as appropriate) for the action to be executed. Each argument is provided an ID at the time it is added. The ID’s start at one and are numbered sequentially to each argument as they are added. When i!-ConnectLinx posts the argument value, it supplies the ID number as well. For numbers and levels, this ID is the level number to which the argument is posted. For strings and enumerations, this ID is included in the string that posts the argument value. For an example, see the i!-ConnectLinxStandardFunctionShell.axi file.

i!-ConnectLinx stores the supported actions in a XML file called i!-ConnectLinx.xml located in the doc:\user\connectlinx directory. All action information is stored in this file. i!-ConnectLinx compatible technologies retrieve this file directly from the NetLinx Master. It may not always be practical to keep all the i!-ConnectLinx action list files on the NetLinx Master. For instance, in a corporate environment with 20 NetLinx Masters in various conference rooms, a user outside the company needs to have direct access to each NetLinx Master through the firewall in order to download the files. Additionally, each NetLinx Master needs it’s own DNS entry, so users do not have to remember an IP Address. To simplify action list management, i!-ConnectLinx compatibly technologies support an action list index file format. This index file lists the names of various files and a URL where the file can be retrieved. This allows you to move all the action list files from the NetLinx Masters to a web server for easy retrieval. Place this index file in a directory called connectlinx off the root directory of the web server and name it i!-ConnectLinx.xml. However, it can contain links to any URL with any file name in any folder. In the above example, the IT department might collect all the action list files and place them in the connectlinx directory of the company’s web server. Each file should be renamed to reflect the room that the action list is for. Then a web developer should edit the supplied i!-ConnectLinxList.xml file to reflect the names and URL’s of each of these files and rename it to i!-ConnectLinx. Now anyone can retrieve an action list for the company’s system by pointing to the company’s main web address and selecting a room file from the list. If desired, the action list index file can be viewed in an HTML browser by using an eXtensible Style Language file. A web developer can make any adjustments to the XSL file so the index file has the look of the company’s web site when viewed in an HTML browser. A sample XSL file, i!-ConnectLinxList.xsl, is supplied with i!-ConnectLinx and should be placed in the same directory on the web server as the index file. The URL contained in the index file can point to an additional index file to allow for tree style navigation. For instance, the main file might list cities where the company has offices, which point to an index file for each city. Each city index file might contain a list of buildings and point to building index files. Then each building index file contains the list of rooms in that building and points to the actual action list for each room.

Localization is the process by which an application is adapted to a locale, and describes a user’s environment or geographical location. i!-ConnectLinx provides the standard action name, help string and folder names for all the standard actions. This information is built directly into the i!-ConnectLinx module. If English is not the primary language for the room, the standard action text can be changed. The standard action text can be stored in a file called i!-ConnectLinxStdText.xml located in the doc:\user\connectlinx directory. When a standard action is added, the text from this file is used for the action name, the help string and folder names. The i!-ConnectLinxStdText.xml can be created in two ways. The i!-ConnectLinxStdTextTemplate.xml file can be altered directly and saved as i!-ConnectLinxStdText.xml in the doc:\user\connectlinx directory. However, this file is difficult to edit in a standard text editor so an XML file editor is recommended. Alternatively, the i!-ConnectLinxStdText.xml file can be created using the i!-ConnectLinxEngineStdTextWriter.axs file. To change the language: 1. Open this file in NetLinx Studio™. 2. Alter the text to support the language you choose. 3. Compile and download this file to a NetLinx Master. The i!-ConnectLinxStdText.xml is written out to the doc:\user\connectlinx directory. Once this file has been created once, it can be FTP’d to the NetLinx Master and placed in the doc:\user\connectlinx directory. When i!-ConnectLinx starts up, the text is read from this file and used for all standard actions. Programming i!-ConnectLinx appears on the NetLinx bus as a NetLinx device. This device has 1 port with channels, levels, commands and strings like most other devices. Channels i!-ConnectLinx supports the following channels: Levels i!-ConnectLinx supports the following levels: i!-ConnectLinx Channels Channel Description All Action to be executed for this action ID. i!-ConnectLinx Levels Level Description All Action number and level arguments

The commands are sent in the standard Send_Command format: SEND_COMMAND dvMP, "'SET ROOM NAME-Tesla'" SEND_COMMAND dvMP, "'ADD MACRO-vcr'" i!-ConnectLinx Commands 'SET ROOM INFO-[Room Name], [Room Location], [Room Owner]' Sets the room name, room location and room owner to be displayed in the action list file. 'SET ROOM NAME-[Room Name]' Sets the room name to be displayed in the action list file. 'SET ROOM LOCATION-[Room Location]' Sets the room location to be displayed in the action list file. 'SET ROOM OWNER-[Owner Name]' Sets the room owner to be displayed in the action list file. 'ADD MACRO-[Macro Name]' Adds a group of standard actions. See i!-ConnectLinxStdFunctionList.xls for a complete list of macro names. 'ADD STD-[ID]-[ID]&[ID]' Adds one or more standard actions by ID. The ‘&’ is used for "AND" and ‘-‘ is used for "THROUGH". 'ADD FOLDER-[Folder Name], [Parent]' Adds a folder to the action list. The parent specifies which parent folder the new folder is added to. If parent is not supplied, this folder is added to the root of the action list. 'ADD ACTION-[ID],[Action],[Help String],[Folder]' Adds an action. The ID and Action are required. The Help String appears in the action list file to help the user determine this action’s function more clearly. The Folder is the folder in which this action is added to, and must have been previously created. If the folder is not supplied, the action is added to the root of the action list. 'ADD NARG-[Action],[Arg Name],[Min],[Max],[Step,] [Default]' Adds a number argument to Action. The Arg Name (Argument Name) is required. The Min and Max define the limits for this argument in the range –32767 to 32767. The Step defines the minimum step between increments/decrements. The Default value defines the initial value this argument is set to when the user edits this argument. 'ADD LARG-[Action],[Arg Name],[Min],[Max],[Step], [Default]' Adds a level argument to Action. The Arg Name (Argument Name) is required. The Min and Max define the limits for this argument in the range –32767 to 32767. The Step defines the minimum step between increments/decrements. The Default value defines the initial value this argument is set to when the user edits this argument. 'ADD SARG-[Action],[Arg Name],[Min],[Max],[Default]' Adds a string argument to Action. The Arg Name (Argument Name) is required. The Min and Maxdefine the min and max length of the string. The Default value defines the initial value this argument is set to when the user edits this argument. 'ADD EARG-[Action], [Arg Name],[Default],[Enum1], [Enum2]...' Adds an enum argument to Action. The Arg Name (Argument Name) is required. The Default value defines the initial value this argument is set to when the user edits this argument. Enum1, Enum2,… define the available choices for the argument. 'GET NODE-[Name],[Start],[End]' Get the node description for Name including children from Start to End. Returns a PARENT string and multiple CHILD strings. 'GET ACTION-[Name]' Get the action description for Name. Returns ACTION string and mulitple argumnet strings (NARG, LARG, SARG and EARG). 'GET UUID' Get the UUID for this i!-ConnectLinx. Returns a UUID string. 'GET ROOM INFO' Get the room info for this i!-ConnectLinx. Returns ROOM NAME, ROOM LOCATION and ROOM OWNER strings.

i!-ConnectLinx Commands (Cont.) 'GET ROOM NAME' Get the room info for this i!-ConnectLinx. Returns a ROOM NAME string. 'GET ROOM LOCATION' Get the room info for this i!-ConnectLinx. Returns a ROOM LOCATION string. 'GET ROOM OWNER' Get the room info for this i!-ConnectLinx. Returns a ROOM OWNER string. 'DEBUGON' Turns on debug. 'DEBUGOF' Turns off debug. (Default) 'RESET' Resets the action list. 'VERSION' Sends version information to Master debug port (Master messaging). i!-ConnectLinx Strings String Description "'ARG[Argument ID]-[Argument String]'" Argument String for string and enum arguments for an action executed soon. 'PARENT-[Name],[Child Count],[Parent]' Describes a parent node. Returned by GET NODE command. 'CHILD[Child#]-[Name], [ChildCount],[Parent]' Describes a child of a node. Returned by GET NODE command. 'ACTION-[ID],[Action], [Help String],[Folder]' Describes an action. Returned by GET ACTION command. 'NARG-[Action],[Arg Name], [Min],[Max],[Step,][Default]' Describes a number argument to Action. 'LARG-[Action],[Arg Name], [Min],[Max],[Step],[Default]' Describes a level argument to Action. 'SARG-[Action],[Arg Name], [Min],[Max],[Default]' Describes a string argument to Action. 'EARG-[Action],[Arg Name], [Default],[Enum1],[Enum2]...' Describes an enum argument to Action. 'UUID-[UUID]' Provides the UUID for this i!-ConnectLinx. This ID can be used to identify this instance of i!-ConnectLinx from all other instances of i!-ConnnectLinx. 'ROOM NAME-[Room Name]' Provide the room name as displayed in the action list file. 'ROOM LOCATION-[Room Location]' Provides the room location as displayed in the action list file. 'ROOM OWNER-[Owner Name]' Provides the room owner as displayed in the action list file. 'FILE WRITE' Notification that the i!-ConnectLinx file is being written. 'FILE SAVED' Notification that the i!-ConnectLinx file is has been saved.

DEFINE_MODULE 'i!-ConnectLinxEngineMod' mdlCL(vdvCLActions) Where mdlCL is a unique module name. i!-ConnectLinxEngineMod Module Parameter vdvCLActions A virtual device number for programming NetLinx actions.

brussels • dallas • los angeles • mexico city • philadelphia • shanghai • singapore • tampa • toronto* • york 3000 research drive, richardson, TX 75082 USA • 469.624.8000 • 800.222.0193 • fax 469.624.7153 • technical support 800.932.6993 033-004-2641 2/05 ©2005 AMX Corporation. All rights reserved. AMX, the AMX logo, the building icon, the home icon, and the light bulb icon are all trademarks of AMX Corporation. AMX reserves the right to alter specifications without notice at any time. *In Canada doing business as Panja Inc.