AMX RMS 3.0 Programmer Guide
NetLinx Programmer’s Guide
RMS
Resource Management Suite 3.0
Software
AMX Limited Warranty and Disclaimer
AMX Corporation warrants its products to be free of defects in material and workmanship under normal use for three (3) years from the date of purchase from AMX Corporation, with the following
exceptions:
• Electroluminescent and LCD Control Panels are warranted for three (3) years, except for the display and
touch overlay components that are warranted for a period of one (1) year.
• Disk drive mechanisms, pan/tilt heads, power supplies, and MX Series products are warranted for a period of
one (1) year.
• AMX Lighting products are guaranteed to switch on and off any load that is properly connected to our lighting products, as long as the AMX Lighting products are under warranty. AMX Corporation does guarantee
the
control of dimmable loads that are properly connected to our lighting products. The dimming performance or
quality cannot be guaranteed due to the random combinations of dimmers, lamps and ballasts or transformers.
• Unless otherwise specified, OEM and custom products are warranted for a period of one (1) year.
• AMX Software is warranted for a period of ninety (90) days.
• Batteries and incandescent lamps are not covered under the warranty.
This warranty extends only to products purchased directly from AMX Corporation or an Authorized
AMX Dealer.
All products returned to AMX require a Return Material Authorization (RMA) number. The RMA
number is obtained from the AMX RMA Department. The RMA number must be clearly marked on
the outside of each box. The RMA is valid for a 30-day period. After the 30-day period the RMA will
be cancelled. Any shipments received not consistent with the RMA, or after the RMA is cancelled,
will be refused. AMX is not responsible for products returned without a valid RMA number.
AMX Corporation is not liable for any damages caused by its products or for the failure of its products to perform. This includes any lost profits, lost savings, incidental damages, or consequential
damages. AMX Corporation is not liable for any claim made by a third party or by an AMX Dealer
for a third party.
This limitation of liability applies whether damages are sought, or a claim is made, under this warranty or as a tort claim (including negligence and strict product liability), a contract claim, or any
other claim. This limitation of
liability cannot be waived or amended by any person. This limitation of liability will be effective even
if AMX Corporation or an authorized representative of AMX Corporation has been advised of the
possibility of any such damages. This limitation of liability, however, will not apply to claims for personal injury.
Some states do not allow a limitation of how long an implied warranty last. Some states do not allow
the limitation or exclusion of incidental or consequential damages for consumer products. In such
states, the limitation or exclusion of the Limited Warranty may not apply. This Limited Warranty
gives the owner specific legal rights. The owner may also have other rights that vary from state to
state. The owner is advised to consult applicable state laws for full
determination of rights.
EXCEPT AS EXPRESSLY SET FORTH IN THIS WARRANTY, AMX CORPORATION
MAKES NO OTHER WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING ANY
IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE. AMX CORPORATION EXPRESSLY DISCLAIMS ALL WARRANTIES NOT
STATED IN THIS LIMITED WARRANTY. ANY IMPLIED WARRANTIES THAT MAY BE
IMPOSED BY LAW ARE LIMITED TO THE TERMS OF THIS LIMITED WARRANTY.
Software License and Warranty Agreement
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 PRERELEASE 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.
Table of Contents
Overview............................................................................. 1
System Requirements ....................................................... 3
Concepts ............................................................................ 5
Network Configuration............................................................. 5
Device Monitoring Framework ................................................ 7
Device Values............................................................................. 8
Parameter Values ....................................................................... 9
Status Types............................................................................. 11
Notification Process .............................................................. 12
Alert Messages ......................................................................... 12
Advise Messages ..................................................................... 12
Upgrading from MeetingManager 1.0 ............................ 15
Basic Changes ...................................................................... 15
Lamp Hours........................................................................... 16
Communication Timeout ....................................................... 17
Custom Source Usage .......................................................... 18
Source Usage and Multiple Displays .................................... 19
Time Synchronization............................................................ 21
Migrating from The Device Monitoring
Worksheet to RMS CodeCrafter ........................................ 22
Getting Started................................................................. 23
Using RMS CodeCrafter ....................................................... 23
Interfacing with the RMS SDK............................................... 25
Service Mode ........................................................................ 27
Device Parameter Persistence.............................................. 27
Custom Device Monitoring Programming..................... 29
RMS NetLinx Programmer’s Guide
i
RMSCommon.axi .................................................................. 30
RMSDevMonRegisterCallback() ............................................... 30
RMSDevMonSetParamCallback()............................................. 31
RMS Engine module ............................................................. 31
RMS Device Monitoring Support Modules ............................ 34
RMSBasicDeviceMod ............................................................... 34
RMSProjectorMod..................................................................... 35
RMSTransportMod.................................................................... 36
RMSSldProjMod........................................................................ 37
Programming............................................................................. 38
Control Failure........................................................................... 40
Device Information .................................................................... 40
Monitoring Source Usage...................................................... 41
Source Select............................................................................ 41
Monitoring Many NetLinx-connected Devices....................... 43
RMSNLDeviceMod.................................................................... 43
Monitoring A Single NetLinx-connected Device.................... 45
Registering Devices .............................................................. 46
Registering Parameters ........................................................ 46
Setting Parameter Values ..................................................... 52
NetLinx Modules............................................................... 55
Non-RMS Modules................................................................ 55
KeyboardMod............................................................................ 55
RMSEngineMod Module ....................................................... 55
Commands................................................................................ 56
Strings ....................................................................................... 60
Channels ................................................................................... 62
Levels........................................................................................ 62
Module Definition ...................................................................... 62
Touch Panel Pages................................................................... 62
ii
RMS NetLinx Programmer’s Guide
RMSUIMod Module............................................................... 63
Commands ............................................................................... 63
Module Definition ...................................................................... 64
Touch Panel Pages .................................................................. 65
RMSWelcomeOnlyUIMod Module ........................................ 66
Commands ............................................................................... 66
Module Definition ...................................................................... 67
Touch Panel Pages .................................................................. 67
RMSHelpUIMod Module ....................................................... 68
Commands ............................................................................... 68
Module Definition ...................................................................... 68
Touch Panel Pages .................................................................. 69
RMSNLDeviceMod Module................................................... 70
Commands ............................................................................... 70
Module Definition ...................................................................... 70
Touch Panel Pages .................................................................. 70
RMSProjectorMod Module .................................................... 71
Commands ............................................................................... 71
Strings ...................................................................................... 72
Channels .................................................................................. 72
Module Definition ...................................................................... 73
Touch Panel Pages .................................................................. 73
RMSTransportMod Module ................................................... 74
Commands ............................................................................... 74
Strings ...................................................................................... 75
Channels .................................................................................. 76
Module Definition ...................................................................... 76
Touch Panel Pages .................................................................. 77
RMSBasicDeviceMod Module............................................... 77
Commands ............................................................................... 77
Strings ...................................................................................... 78
RMS NetLinx Programmer’s Guide
iii
Channels ................................................................................... 78
Module Definition ...................................................................... 79
Touch Panel Pages................................................................... 79
RMSSldProjMod Module....................................................... 79
Commands................................................................................ 79
Channels ................................................................................... 80
Module Definition ...................................................................... 80
Touch Panel Pages................................................................... 80
RMSSrcUsageMod Module................................................... 81
Commands................................................................................ 81
Channels ................................................................................... 81
Module Definition ...................................................................... 82
Touch Panel Pages................................................................... 82
i!-ConnectLinx .................................................................. 83
Using i!-ConnectLinx ............................................................. 84
Standard Actions................................................................... 86
Action Arguments.................................................................. 88
Action Persistence and Distribution ...................................... 89
International Issues / Localization ......................................... 90
Programming......................................................................... 91
Channels ................................................................................... 91
Levels........................................................................................ 91
Commands................................................................................ 92
Strings ....................................................................................... 94
Module ...................................................................................... 95
iv
RMS NetLinx Programmer’s Guide
Overview
Overview
The Resource Management Suite products are PC server applications designed to
manage rooms and equipment. The RMS server also monitors equipment in the
rooms and sends notifications for room problems and help requests. The RMS
server allows for the logging of room and device use, errors that occur, and
offline events. The RMS server offers a variety of build-in reports for historical
and statistical analysis, as well as device monitoring through a user extensible
framework. This framework allows you to customize what devices should be
monitored, the conditions that indicates a problem or fault, and what type of
problem or fault this condition represents. The RMS server generates
notifications and routes them to different personnel when a fault condition
occurs, routing such notifications to the appropriate personnel as determined by
the notification configuration.
The RMS Software Development Kit (SDK) is composed of a series of modules
that allow users to monitor equipment errors and usage, view appointments,
display welcome images and messages, and view current appointment details
from any NetLinx compatible touch panel. Users can create presets to be
executed when a meeting starts from the actions available through i!-
ConnectLinx.
i!-ConnectLinx provides the mechanism to expose actions to the RMS server and
to manage action execution on the NetLinx system. In the RMS web pages users
can create control functions which are essentially macro sequences of
i!-ConnectLinx actions. These control function macros can be directly executed
or scheduled from the RMS web pages. i!-ConnectLinx handles these requests
and presents it to the NetLinx program for execution. See the i!-ConnectLinx
help file for details on programming i!-ConnectLinx.
RMS NetLinx Programmer’s Guide
1
Overview
2
RMS NetLinx Programmer’s Guide
System Requirements
System Requirements
The RMS SDK is a set of NetLinx and TPDesign files that are included in your
control system programs. To utilize this SDK, you will need the following
applications installed:
NetLinx Studio 2.5 (or later)
TPDesign 4 v2.6 (or later) for G4 panels
TPDesign 3 v3.16 (or later) for G3 panels
RMS NetLinx Programmer’s Guide
3
System Requirements
4
RMS NetLinx Programmer’s Guide
Concepts
Concepts
Network Configuration
The RMS application is a client/server application where the NetLinx system acts
as the client and the RMS application server listens for connections from NetLinx
systems. NetLinx and the RMS application server communicate using TCP/IP
sockets. In order to establish communication, each NetLinx system must be able
to resolve and connect to the RMS application server. This can be accomplished
with a variety of Network configurations including local area networks (LAN),
wide area networks (WAN), and the Internet.
In order to communicate with RMS, a NetLinx system must have the RMS
modules added to its programming. The RMSEngineMod module includes the
core API and communication stack that allows Netlinx to communicate with the
RMS server.
Since each NetLinx system acts as the client, it must be configured to
communicate to the RMS server using the 'SERVER-' command in NetLinx
programming. NetLinx can accept either an IP address or a HostName for the
server. NetLinx supports DNS so if you are using a HostName, the HostName
must be registered with the DNS server that NetLinx has been configured to use.
The DNS server configuration will be picked up automatically through DHCP if
the DNS servers are registered with the DHCP server. For more information on
configuring DNS servers in NetLinx, see the NetLinx master’s instruction
manual.
Optionally, the server IP or host name can be placed in a file called ServerInfo.txt
and placed in the RMS directory of the NetLinx master's file system. If this file is
present, the RMS communication module ignores the SERVER- command and
uses the address supplied in the file. Enter the IP address or hostname on a single
line using a text editor and FTP the file to the NetLinx master. If the RMS
directory does not exist, you can create it and place the file in the directory.
By default, NetLinx and the RMS server will communicate using TCP/IP port
3839. Port 3839 is registered to AMX Resource Management Suite with IANA
(http://www.iana.org/assignments/port-numbers). This can be changed to suit
your particular facility but it must be changed in both the RMS server software
RMS NetLinx Programmer’s Guide
5
Concepts
and each NetLinx system. In the RMS server, this is accomplished through the
Configuration Wizard. In NetLinx, this is accomplished through the 'SERVER-'
command in NetLinx programming.
If using the ServerInfo.txt file, append a ":" and the port number to the server IP
address or host name.
MeetingManager 1.0 used port 9090 for communications. If you are upgrading
from MeetingManager 1.0, you may wish to continue to use port 9090. During
the upgrade process, you are prompted to change to port 3839 or continue to use
port 9090. If you change to port 3839, you need to upgrade all NetLinx systems
to use the modules from the RMS 2.0 SDK. You can use port 9090 with both
MeetingManager 1.0 and 2.0 NetLinx systems.
Once a NetLinx system has been programmed with the RMS modules and the
server's IP address or HostName, the NetLinx system automatically connects to
the RMS server.
Install Checklist
Is the RMS server's host name registered with your DNS server?
Yes • Configure each NetLinx system to point the correct DNS server and supply the
HostName to the NetLinx programmer to use in the 'SERVER-' command. The
DNS server configuration will be picked up automatically through DHCP if the
DNS servers are registered with the DHCP server.
No • Determine the IP address of the RMS server and supply this to the NetLinx
programmer to use in the 'SERVER-' command.
Do you want to use 3839 as the TCP/IP port for communications between Netlinx
and the RMS server?
Yes • No changes need to be made in either the RMS server or NetLinx.
No • Configure the TCP/IP in the RMS server using the Configuration Wizard and
supply the new port to the NetLinx programmer to use in the 'SERVER-'
command.
6
RMS NetLinx Programmer’s Guide
Concepts
Device Monitoring Framework
RMS provides device monitoring through a user extensible framework. This
framework allows you to customize what devices are monitored, the conditions
that indicate a problem or fault, and what type of problem or fault this condition
represents. RMS generates notifications when a fault condition occurs, as
determined by the notification configuration.
Each room has one or more monitored devices. Each device can be a physical
device, such as a video projector, or a logical device, like the RMS software.
However, each monitored device must be associated with a NetLinx-connected
device. In the case of a video projector, this device would be the IR card, Serial
Card or IP Socket used to communicate with the projector. The RMS software is
associated with the NetLinx master itself.
Each monitored device has one or more device parameters that represent
monitored items. For instance, monitoring lamp hours of a video projector is
accomplished through a "Lamp Hours" parameter that belongs to the "Video
Projector" device. All parameters must be associated with a device.
In order to monitor a device, the NetLinx system must register the device and one
or more parameters with RMS. For instance, monitoring of lamp hours of the
video projector is only available if the NetLinx system has added the appropriate
code. In many cases, this is as simple as adding a RMS support module.
RMS NetLinx Programmer’s Guide
7
Concepts
Device Values
Each monitored device has a set of values used in its description. These values
are supplied when the device is registered and consist of the following:
Device Values
Device Number This is the device number of the device, as defined in the NetLinx
program. Devices are tracked by Device ID so this value must be
unique within the devices of a given room. For instance, you can have
multiple "1:1:0" devices as long as there is only one device with a
Device ID of "1:1:0" in the room.
Name This is the name of device. This name is displayed on the
administrators console and readily identifies the device.
Manufacturer This is the manufacturer of the device. If this value is not supplied
during registration, the manufacturer of the NetLinx-connected device
will be used.
Model This is the model number of the device. If this value is not supplied
during registration, the model name of the NetLinx-connected device
will be used.
Device Type This is the device type of the NetLinx-connected device. This might be
"NI-2000" or "NXP-TPI/4 Touch Panel". This is available for Axcess
and NetLinx devices. This information is registered automatically by
the RMS server.
Serial Number This is the serial number of the NetLinx-connected Device. This is only
available for NetLinx devices. This information is registered
automatically by the RMS server.
Firmware Version This is the firmware version of the NetLinx-connected device. This is
only available for NetLinx devices. This information is registered
automatically be the RMS server.
Address and
Address Type
This is the physical address and address type for the
Netlinx-connected device. This information describes how the device
is connected to the NetLinx master. A device connected via ICSNet
will display "ICSNet" for the address type and the hardware's network
address for the address. A device connected via IP will display
"TCP/IP" for the address type and the IP address for the address.
Axcess devices will display "AXLink" for both values. This information
may be useful for diagnosing device connectivity problems.
This information is registered automatically by the RMS server.
8
RMS NetLinx Programmer’s Guide
Concepts
Parameter Values
Each parameter has a set of values used to determine what conditions indicate a
problem and what type of problem this condition represents. These values are
supplied when the parameter is registered and consist of the following:
Parameter Values
Name This is the name of parameter. This name is displayed on the
Parameter Type This value indicates if this value is a number or a string. This
Value and Units This is the current value of the parameter. Units are appended
Threshold Value and
Comparison Operator
RMS server console and readily identifies the parameter.
Parameters are tracked by name so this name must be unique
within the parameters of a given device. For instance, you can
have multiple "Lamp Hours" parameters as long as there is
only one "Lamp Hours" parameter per monitored device.
information is used to determine how to perform certain
operation, such as addition and comparisons between the new
and threshold values. For instance, comparing "10" and "2" as
strings results in "10" less than "2" but comparing them as
numbers results in "2" less than "10".
to the value when displayed in the web console.
The threshold value is the value for which this parameter is
considered to indicate a problem or fault. The comparison
operator is used to detect when the value changes from the
un-faulted to the faulted condition. The comparison operators
"Less Than", "Less Than or Equal To", "Greater Than",
"Greater Than or Equal To", "Equal To", and "Not Equal To"
can be used for string and number parameters. The
comparison operators "Contains" and "Does Not Contain" are
primarily used for string parameters.
For example, "Lamp Hours" might have a threshold value of
1000 and any value over this would require maintenance. The
comparison operator would then be "Greater Than". When this
parameter changes from a value that is not greater than 1000
to a value that is greater than 1000, the fault status is set.
When the value changes from a value greater than 1000 to a
value not greater than 1000, the fault status is cleared. These
value are supplied during registration but can be modified by
the administrator from the RMS server console.
RMS NetLinx Programmer’s Guide
9
Concepts
Parameter Values
Status Type The status represents the type of problem a faulted condition
represents. Status Types include "Help Request",
"Maintenance Request", "Room Communication Error",
"Control System Error", "Network Error", "Security", and
"Equipment Usage."
For example, when "Lamp Hours" changes from an un-faulted
(not greater than 1000) to a faulted (greater than 1000), this
change represents a "Maintenance Request" status that
requires an AV technician to repair the equipment. If the
"Device Online" parameter changes from "Online" to "Offline",
this change could represent a "Security" or "Control System
Error" status.
These value are supplied during registration but can be
modified by the administrator from the RMS server
console.
Reset Flag and Reset
Val ue
Minimum and Maximum
Values
Enumeration List This value is used to restrict the range of the threshold and
These values determine if and how the parameter can be reset
from the RMS server console. If the Reset Flag is set, then the
administrator can reset the value remotely. When the administrator selects "Reset" from the console, the Reset Value is copied to the Value and the faulted condition is cleared. These
values are useful for parameters such as VCR "Run Time"
which would be manually reset when the VCR is cleaned.
These values are used to restrict the range of the threshold
and reset values that the administrator can enter on the
RMS server console. These values would be used when the
parameter represents a value with a bounded range, such as a
Vol u me Level.
reset values that the administrator can enter on the
RMS server console. This value would be used when the
parameter represents a value with a bounded list, such as a
list containing the values Power On and Power Off.
All parameters must be registered by the NetLinx system. The administrator
cannot add parameters from the RMS console. The administrator can modify
Threshold Value, Comparison Operator, and Status Type for any parameter. This
provides the administrator with the ability to set their own thresholds and
re-classify messages based on their facility. For instance, an administrator can set
the Video projector's "Lamp Hours" threshold to the expected lamp life of a
newly replaced lamp or change the "Device Communicating" parameter from a
"Control System Error" to a "Security" status if the projector is in danger of being
stolen.
10
RMS NetLinx Programmer’s Guide
Concepts
Status Types
RMS supports the following status types for device monitoring: "Help Request",
"Maintenance Request", "Room Communication Error", "Control System Error",
"Network Error", "Security", and "Equipment Usage."
While there are no firm rules for what these status types mean and how they are
used, AMX provides the following description of each status type and
recommends that your usage is consistent with these descriptions.
Status Types
Help Request A user generated help request such as a help button on the
touch panel.
Maintenance Request A user or monitored equipment generated maintenance
Room Communication Error A loss of communication between the room and the
Control System Error Any error that represents a control system error, such as an
Network Error Any network related error. These would most commonly be
Security Any security related issue. It might be appropriate to
Equipment Usage Any issue that does not require repair or maintenance and
request. Maintenance issues would include items that
require a technician to visit the room.
RMS server.
offline device or loss of communication with a device.
associated with loss of communication with devices that
communicate via IP.
classify issues that might normally be classified as Control
System or Network errors as Security issues instead. This
might include a touch panel going offline or loss of
communication with a projector depending on the physical
security of these devices.
that is mainly used for status.
RMS NetLinx Programmer’s Guide
11
Concepts
Notification Process
As NetLinx sends parameter updates to the RMS server, the RMS server checks
to see if the parameter's threshold value has been reached. This comparison is
made by checking the previous value of the parameter against the threshold and
by checking the new version of the parameter against the threshold using the
threshold comparison operator. If the comparison for the old value is False and
the comparison for the new value is True, then the parameter triggers an Alert
message. If the comparison for the old value is True and the comparison for the
new value is False, then the parameter triggers an Advise message. Therefore an
Alert message is generated when a parameter reaches its threshold, and an
Advise message is generated when a parameter returns to its normal operating
range.
Alert Messages
When an Alert message occurs, the RMS server first checks to see if message
should be logged to the various log services. A message is created for each log
service using the Log Text of the parameter's Alert template, or the default
template if a custom template has not been assigned. Next, the RMS server
checks for any notifications in the Notification List matching the group, room,
and status type for the parameter and dispatch any messages via SMTP or SNPP
as needed using the appropriate text from the template assigned to the parameter.
Advise Messages
When an Advise message occurs, the RMS server first checks to see if the
parameter is configured for sending Advise messages. If not, no messages are
sent and no Log entries are created. If the parameter has been configured for
Advise messages, the message is logged and dispatched via SMTP an SNPP as
described above. However, the Advise template assigned to the parameter, or the
default Advise template if no template has been assigned to the parameter, is used
to generate the text for the log entries and messages.
For instance, if the previous value for Projector Lamp Hours is 999 and the new
value is 1001 and the threshold is set to 1000 and the threshold operator is set as
"Greater Than", the RMS server checks to see if the previous value compared to
the threshold, i.e. 999 is Greater than 1000 is False, has a different result than the
new value compared to the threshold, i.e. 1001 is Greater than 1000 is True. This
12
RMS NetLinx Programmer’s Guide
Concepts
change results in an Alert message being logged using the RMS logging settings.
Also, a message is sent to all users registers for a notification matching the
parameters group, room and status type.
If the Lamp Hours changes from 1001 to 999, the RMS server triggers an Advise
message. If the parameter is configured to send Advise messages, the message is
sent to the log and to all users registered for a notification matching the
parameters group, room, and status type.
RMS NetLinx Programmer’s Guide
13
Concepts
14
RMS NetLinx Programmer’s Guide
Upgrading from MeetingManager 1.0
Upgrading from
MeetingManager 1.0
Basic Changes
If you are currently running MeetingManager 1.0 NetLinx code, you should plan
to migrate to the new RMS 2.0 SDK. The RMS 2.0 SDK offers a more flexible
and complete API and improved reporting capabilities for the RMS Server
administrator.
In general, migrating from MeetingManager 1.0 SDK to RMS 2.0 SDK is a
simple process. The RMS 2.0 SDK requires the following changes:
All "MeetingManager" modules should be changed to "RMS' modules.
For instance, "MeetingManagerProjectorMod" should be changed to
"RMSProjectorMod".
"The MeetingManager SDK include file,
"MeetingManagerDeviceMonitor.axi" has been changed to
"RMSCommon.axi"
All SDK constants functions names including "MM" have been
changed to "RMS". For instance, "MMNetLinxDeviceOnline" is now
"RMSNetLinxDeviceOnline" and "MM_PARAM_SET" is now
"RMS_PARAM_SET"
Many of the SDK changes can be handled by using RMS CodeCrafter; it can
import data from a MeetingManager 1.0 Device Monitoring Worksheet and
generate an include file that uses the new RMS 2.0 SDK. However, changes to
your code will be required. The new parameter access functions will be named
"RMSSet…" instead of "MMSet…". You need to change your code to call the
"RMSSet…" functions in order to use the code generated by RMS CodeCrafter.
If you have not used the MeetingManager 1.0 Device Monitoring worksheet,
your code will need to be changed by hand. The easiest way to make this change
is to change all "MeetingManager…" modules to "RMS…" modules. For
instance, "MeetingManagerProjectorMod" should be changed to
"RMSProjectorMod". Additionally, you will need to copy the RMS module TKO
RMS NetLinx Programmer’s Guide
15
Upgrading from MeetingManager 1.0
files from the RMS 2.0 SDK directory to your project directory in order to
compile.
In addition, all "MM…" API functions and constants should be changed to use
the "RMS…" function or constant, which is as simple as changing "MM" to
"RMS". To avoid making these tedious changes, you could overwrite your
existing MeetingManagerDeviceMonitor.axi from the MeetingManager 1.0 SDK
with the MeetingManagerDeviceMonitor.axi from the RMS 2.0 SDK. This new
file will define all the MeetingManager 1.0 SDK functions and constants and, in
the case of functions, will call the RMS equivalents. Using
MeetingManagerDeviceMonitor.axi in new projects is not recommended.
These changes constitute the bulk of the RMS 2.0 SDK changes. The new
modules will enable most of the new functionality available in RMS 2.0 servers.
There may be a couple of other changes required to take full advantage of the
RMS 2.0 SDK so check the next sections to see if they apply to your program.
After making this change, you will need to recompile and download your code.
Lamp Hours
In order to take full advantage of the Lamp Hours reporting and Manage Lamp
Hours view, Projector Lamp Hours must be reported to the RMSProjectorMod
support module. If you created your own "Lamp Hours" parameter, the code in
your program is sending the lamp hour value directly to MeetingManager.
In order to take advantage of the new Lamp Hours features, change your call that
notifies the RMS server of the lamp hours change to:
RMSSetLampHours(Projector Device, Lamp Hours)
For instance, if you have a Named device called "Projector" with a real device
called dvProj and a parameter for this device named "Lamp Hours", the
MeetingManager 1.0 Device Monitoring Worksheet created a function called
MMSetProjectorLampHours() which your code called to notify MeetingManager
of the Lamp Hours change. You will want to change your code from:
MMSetProjectorLampHours(Value)
To
RMSSetLampHours(dvProj,Value)
16
RMS NetLinx Programmer’s Guide
Upgrading from MeetingManager 1.0
If you did not use the worksheet, your code probably calls MMChangeParam() to
notify MeetingManager of the Lamp Hours change. You will want to change
your code from:
MMChangeParam (dvProj,MM_PARAM_SET,Value)
To
RMSSetLampHours(dvProj,Value)
Communication Timeout
In MeetingManager 1.0, communication timeout for a source other than a
Projector or a VCR was handled by creating a named device and a parameter for
that device called "Device Communicating". This method will still work under
RMS 2.0 without changes.
However, a new report in RMS 2.0, Device Communicating Quality of Service,
requires that device communications be monitored using a support module, such
as RMSProjectorMod or RMSTransportMod. To handle devices other than
projectors and VCRs, a new support module, RMSBasicDeviceMod, was added.
RMSBasicDeviceMod monitors a device for Power, Communication Status,
Control Failure (optional), and IP Address. This module simplifies monitoring
device communications.
To use this new module, make the following changes to your programming:
Remove the registration of the named device and the "Device
Communicating" parameter.
Remove the calls to parameter access function, such as
MMSetDeviceCommunicating(), in your code, which should be
located under the DATA_EVENT for the device to be monitored.
Include a new RMSBasicDeviceMod module for the device to be
monitored.
Call RMSSetDeviceInfo() to set the name, manufacturer, and model of
the device to be monitored.
Call RMSSetCommunicationTimeout() to change the default timeout
from 300 seconds to another value unless the 30 second default is OK
for your program.
Make sure to leave a polling command that elicits a response from the device.
The RMSBasicDeviceMod will expect to receive a string from the device every
RMS NetLinx Programmer’s Guide
17
Upgrading from MeetingManager 1.0
30 seconds, or any value you set using RMSSetCommunicationTimeout (). If a
string is not received within the timeout period, a loss of device communication
is reported to the RMS server.
If you are using RMS CodeCrafter output that imported the custom "Device
communicating" parameter from a MeetingManager 1.0 worksheet, simply
change the Module type for the device from "Custom (No Module)" to "Basic
Device", and delete the "Device Communicating" parameter.
Custom Source Usage
In order to take full advantage of the Source Usage reporting and Manage Source
Usage view, Source Usage must be reported to the RMSSrcUsageMod support
module. The new RMSSrcUsageMod is backwards compatible with the old
module. If you are only using standard sources and you have not customized
MeetingManagerSrcUsageMod module for custom sources, you only need to
change the DEFINE_MODULE line to use RMSSrcUsageMod, recompile, and
download.
If you have customized MeetingManagerSrcUsageMod with custom sources, as
indicated by a value of MM_MAX_CUSTOM_SOURCES greater than 0 in your
customized version of MeetingManagerSrcUsageMod.axs, you will need to
migrate these custom sources to the RMSSrcUsageMod.axs file.
RMSSrcUsageMod supports custom sources in two ways. The first way is the
same as MeetingManagerSrcUsageMod, where you can set
MM_MAX_CUSTOM_SOURCES to the number of custom sources and add
source names to MM_CUSTOM_SOURCES. This method is deprecated in RMS
2.0 although it still works.
The recommended method for adding custom sources to RMSSrcUsageMod is
through custom i!-ConnectLinx actions. RMSSrcUsageMod will watch for the
registration of custom i!-ConnectLinx actions and automatically register any
actions starting with "Select " as a source select. For instance, if your system has
a Reel to Reel player, which is not supported in i!-ConnectLinx as a standard
source, you can track the usage of this source in the RMS server by registering
this as a custom actions called "Select Reel to Reel":
SEND_COMMAND vdvCLActions,'ADD ACTION-1,Select Reel To
Reel,,Sources'
18
RMS NetLinx Programmer’s Guide
Upgrading from MeetingManager 1.0
RMSSrcUsageMod will extract the text after "Select " and register the remaining
text as a custom source, Reel to Reel in this case. RMSSrcUsageMod will then
monitor the channel specified in the ADD ACTION command, channel 1 in this
case, and when the channel turns on, RMSSrcUsageMod will start a timer and
time the usage of Reel to Reel.
For more information i!-ConnectLinx programming, see the i!-ConnectLinx help
file installed with the RMS SDK.
Source Usage and Multiple Displays
In MeetingManager 1.0, tracking source usage for multiple displays was
accomplished by using multiple copies of MeetingManagerSrcUsageMod, where
one MeetingManagerSrcUsageMod was added for each display. Each source was
timed from the moment the source was turned on until another source was turned
on or the system was turned off. Multiple MeetingManagerSrcUsageMod
modules allow tracking of one or more sources at the same time since each
MeetingManagerSrcUsageMod module could track one source.
While this method still works in RMS 2.0, RMSSrcUsageMod supports a new
method for tracking multiple sources. RMSSrcUsageMod supports a new
command, Multisource, which tells RMSSrcUsageMod that it should track each
source independently.
In this mode, RMSSrcUsageMod times each source from the time the source is
turned on until the source is turned off. RMSSrcUsageMod allows multiple
sources to be active at the same time and tracks these sources independently.
System Off no longer plays a role in source usage; source usage is determined by
the state of the i!-ConnectLinx channel for each individual source.
Since this new mode monitors source usage channels differently, your
programming may need to change. MeetingManagerSrcUsageMod assumed all
sources, including system off, were mutually exclusive and the OFF states of the
channels were ignored. For instances, selecting a source could be accomplished
with
Select VCR:
PULSE[vdvCLActions,1011]
Select DVD: PULSE[vdvCLActions,1014]
System Off: PULSE[vdvCLActions,1002]
RMS NetLinx Programmer’s Guide
19
Upgrading from MeetingManager 1.0
When using RMSSrcUsageMod in Multisource mode, RMSSrcUsageMod does
not assume sources are mutually exclusive, the OFF states are used to stop source
usage timing and system off is ignored. Selecting a source now requires this
code:
Select VCR:
ON[vdvCLActions,1011], OFF[vdvCLActions,1014]
Select DVD: ON[vdvCLActions,1014], OFF[vdvCLActions,1011]
System Off: OFF[vdvCLActions,1011], OFF[vdvCLActions,1014]
You must turn off the source usage channel for a source when it is no
longer selected.
Using feedback assignments for source selects works for Multisource as well,
since it mimics ON and OFF:
[vdvCLActions,1011] = (CurrentSource = VCR)
[vdvCLActions,1014] = (CurrentSource = DVD)
where CurrentSource is a variable representing the currently selected source. If
your system supported both a main source and a preview source, your code might
look like this:
[vdvCLActions,1011] = (CurrentSource = VCR OR PreviewSource =
VCR)
[vdvCLActions,1014] = (CurrentSource = DVD OR PreviewSource =
DVD)
The code produced by RMS CodeCrafter is similar in concept to the code above
and will work for either Single-source or Multi-source source usage tracking.
To take advantage of this new feature in RMS 2.0 when using RMS CodeCrafter,
simply check the "Using multiple display devices" checkbox on the "Room
Information/Options" page. If you are not using RMS CodeCrafter, make the
following programming changes in your code:
Remove all instances of MeetingManagerSrcUsageMod except one,
along with the i!-ConnectLinx device definitions associated with these
modules.
Change the remaining instance of MeetingManagerSrcUsageMod to
RMSSrcUsageMod.
In DEFINE_START, call this function: RMSSetMultiSource(TRUE).
Make sure your activations of i!-ConnectLinx source channels use ON
and OFF or feedback assignments instead of PULSE.
20
RMS NetLinx Programmer’s Guide
Upgrading from MeetingManager 1.0
Time Synchronization
In MeetingManager 1.0, time synchronization for the master was accomplished
by using i!-TimeManager. Starting with RMS 2.0, time synchronization is built
into the RMS Suite. Each NetLinx system's time is automatically updated based
on the RMS server's time while accounting for the time zone and Daylight Saving
settings of the server and each room.
If you are running RMS SDK 2.0, you no longer need to include i!-TimeManager
in your program. However, there are ways to configure RMS to allow i!-
TimeManager to handle time synchronization. If the RMS SDK automatically
detects that i!-TimeManager is present, based on the device vdvTMEvents being
defined, then the RMS SDK will automatically defeat the RMS time
synchronization. You can manually disable the RMS time synchronization by
calling this function:
RMSDisableTimeSync()
If the RMS SDK automatically disables time synchronization because it
determined that i!-TimeManager was present, the following entry will appear in
the log (note the line number may differ):
RMS: Detected i!-TimeManager, disabling RMS Time Sync
(RMSCommon.axi line 930)
RMS NetLinx Programmer’s Guide
21
Upgrading from MeetingManager 1.0
Migrating from The Device Monitoring Worksheet to RMS CodeCrafter
If you installed MeetingManager prior to version 2.1 you may have used the
Device Monitoring Worksheet to generate your device monitoring code. All
changes mentioned in Upgrading from MeetingManager 1.0 section on page 15
are still necessary but it is easier to do with the assistance of RMS CodeCrafter.
To bring your worksheet into CodeCrafter for editing:
1. Dowload RMS CodeCrafter from AMX.com if you do not already have the
application (the application is included in the RMS 3.0 SDK installation for
your convenience).
2. Install and open RMS CodeCrafter.
3. Select File > Open > Import Spreadsheet.
4. Locate your MeetingManager Device Monitoring Worksheet (.XLS).
5. Click Open.
Consult the RMS CodeCrafter instruction manual for further information on
using the RMS CodeCrafter application.
22
RMS NetLinx Programmer’s Guide
Loading...