MLVantage Plugin

From Cinemar Wiki
Jump to: navigation, search

MLVantage Cinemar Main Lobby Server Plug-in for Vantage Controls Automation Systems

Installation and Programming Guide


Overview

Cinemar’s Main Lobby provides a rich and exciting interface for a variety of control, entertainment and information systems. With Main Lobby Server, Main Lobby client user interfaces can connect to a variety of third-party hardware through various plug-ins. The MLVantage plug-in allows Main Lobby scenes to control lighting and home automation control hardware provided by Vantage Controls. Some features of the MLVantage plug-in are:

• Ability to set the value of any Vantage lighting load, switch, or programming variable
• Instantaneous status feedback on the current value of a Vantage item allowing Main lobby graphics elements (switches, sliders, etc.) to show the actual state of an item, even if changed outside Main Lobby
• Send any Vantage V-Command or any arbitrary string control to a Vantage master controller
• Receive and Main Lobby Server command from a Vantage master controller, thus allowing Main Lobby scenes to change in response to Vantage events
• Set and monitor Vantage thermostats, or create virtual thermostats

This document will explain the installation, configuration and programming of the MLVantage plug-in. It is assumed that the user is familiar with Vantage Controls hardware, terminology, software programming and also with Main Lobby programming. For more information, consult the documentation provided with the respective systems.


Section One – Installation

1. Copy the file MLVantage.dll to the Main Lobby Server Directory C:\Program Files\MLServer\Plugins\ (note: for the BETA release this path is absolute)

2. Register the MLVantage dll by typing the following command at the command prompt:

regsvr32.exe “c:\program files\MLServer\plugins\mlvantage.dll”

3. Connect the MLServer PC to the Vantage Master Controller using an RS232 connection or an Ethernet connection using a Vantage IP enabler. Refer to your Vantage Master Controller documentation for information on RS232 or Ethernet connections.


Set Up

Initial Configuration

1. Start MLServer and restore the configuration window if necessary.

2. In the MLServer window, locate MLVantage in the plug-ins list box, select it, and press settings. The MLVantage Configuration Dialog will appear.


3. First, select the settings tab. This will allow you to configure the communications settings and retrieve the Vantage system status. Select Serial or IP communication. For Serial communication enter the proper comm port; for IP communication, enter the IP address and port of the IP enabler. Be aware that the IP enabler can only accept one TCP/IP connection at a time. If you plan to connect to the master controller with Q-Link or WebPoint, you must shut down MLServer first (or provide a second IP enabler with a unique address)


4. Next, you must inform MLVantage of the configuration of the connected Vantage system. Click the SETUP VANTAGE SYSTEM button and the following dialog will appear.


5. Vantage configuration information can be read by loading the Q-Link file used to program the system, or by loading the backup flash. Enter a Q-Link file or select Read from Back Flash

6. MLVantage creates variables containing the values or current state of all the Vantage items (loads, switches, etc.) which can be displayed in Main Lobby. These variables are created automatically from the names entered into Q-Link. If you would rather not have these variables automatically generated, uncheck the options to auto-assign Vantage variables.

7. Names are created in the form mlvantage_address_name, where address is the vantage address of the item, and name is the Q-Link name of the item. You may choose to include or exclude either of these. In the case where a duplicate variable is created, MLVantage will append an additional counter to the end of the variable.

8. You may choose to clear all information currently in the system, or to simply update the system with new information. If Clear Configuration is not checked, only items not present in the current configuration will be added and named.

9. Press OK to complete configuration.

10. Press SAVE SETTINGS to save your information

Editing the configuration

You may now change, delete, or add MLServer variables corresponding to Vantage items. While it is possible to modify the “mlvantage_” prefix on the variables, it is recommended that it be left as is. This helps organize the variables in MLServer and distinguish them from variables from other plug-ins.

To edit variables for module loads, select the modules tab. In this list, you will see a list of modules and the values of each of the loads in the module. If you click on a module, you will bring up a dialog window allowing you to edit the variable names



In the same fashion stations loads and switches may be viewed and their variables modified by selecting the Stations tab. A station list appears, and the corresponding load and switch MLServer variables may be set by clicking on the station.


If a Thermostat station is selected, a special thermostat configuration dialog will appear. In this dialog, you may change the name of the variable assigned to the thermostat, and select the units (Fahrenheit or Celsius).


If you choose to use the Flash virtual Vantage thermostat provided with MLVantage, you may choose if the four additional hidden buttons (Mode, Fan, Day/Night, Outdoor) are displayed on the face of the thermostat. If you choose to create your own thermostat display, there are MLVantage commands to set the thermostat values (described below) and several variables containing thermostat information. These variables are prefixed with the thermostat MLServer variable name entered in the configuration dialog. Variables are:

Variable Name Values

varname_heatspday Temperature in chosen units
varname_heatspnight Temperature in chosen units
varname_coolspday Temperature in chosen units
varname_coolspnight Temperature in chosen units
varname_indoortemp Temperature in chosen units
varname_outdoortemp Temperature in chosen units
varname_daynight 0 = day, 1 = night
varname_fanstate 0 = auto, 1 = on
varname_mode 0 = off, 1 = cool, 2 = heat, 3 = auto


Finally, Vantage Variables may be modified by clicking on the Variables tab



Remember to click the SAVE SETTINGS button to save the configuration. Saving is not automatic!

Programming

Once the Main Lobby server plug-in for Vantage is configured there only two fundamental mechanisms by which Main Lobby communicates with Vantage: sending commands to Vantage, and reflecting the status of Vantage items on Main Lobby button items thru MLServer variables. Both are illustrated by the following example:

Example – Create a slider to control a dimmable light.

A dimmable outdoor flood light is connected to the Vantage system on Master 1, Enclosure 2, Module 1, Load 3. In the MLVantage plug-in, the light has been named Vantage_SOutdoorFlood.

1. In an open Main Lobby scene in Design Mode, open the library window and select the button Slider01_cont, and click add.

2. Switch to Edit Mode, and select the button to bring up the button properties panel.

3. In the Label field type the name of the MLServer variable corresponding to the Vantage load to be controlled. This variable name should be placed in double braces {{variable_name}} as shown. Placing the variable name in braces within the label field causes the slider to assume the value of the variable. This technique may also be used with other Main Lobby button items such as progress meters.

4. In the MLServeCmd field type the command to set the Vantage load to the value currently indicated by the slider. The command should be: MLServeCmd.MLVantage|SetMLoad~<Master#>~<Enclosure#>~<Module#>~<Load#>~{{value}}~<FadeRate>

Typing {{value}} for the value parameter in this command sends the current value of the slider to the SetMLoad Function.


Notes:
• For sliders, you may choose a continuous slider (slider01_cont) or a release slider (slider01_release). A continuous slider will send a continuous stream of commands to Vantage, causing the load value to track the slider as it is moving. A release slider will not update until the user has released the mouse button (or ceased touching a touchscreen).

• When using a slider, it is recommended to uncheck the Click option in the button properties panel. This prevents the outline box from appearing when the slider is selected.

• If you wish to hide the numeric value of the slider, click the Hide Value option.


MLVantage provides several other commands for communicating with or controlling the Vantage system. Commands are not case sensitive. Following is a list of currently available commands. Commands are entered in the form

MLServeCmd.MLVantage|<command>~<param1>~<param2>….

Commands

SetMLoad – Set a module load to a specific value.
Syntax: SetMLoad~<Master#>~<Enclosure#>~<Module#>~<Load#>~<Value>~<optional FadeRate>
Example: Set Load 3 in Module 2 of Enclosure 2 of Master 1 to 50% with a 0 fade rate

MLServeCmd.MLVantage|SetMLoad~1~2~2~3~50~0


ToggleMLoad – Toggles a master load. If the load value is 0, the load is set to 100%, otherwise the load is set to 0.

Syntax: ToggleMLoad~<Master#>~<Enclosure#>~<Module#>~<Load#>~<optional FadeRate>

Example: Toggle Load 3 in Module 2 of Enclosure 2 of Master 1 with a 0 fade rate

MLServeCmd.MLVantage|ToggleMLoad~1~2~2~3~50~0


SetSLoad – Set a station load to a specific value.

Syntax: SetSLoad~<Master#>~<Station#>~<Load#>~<Value>~<optional FadeRate>

Example: Set Load 1 on station 20 of Master 1 to 100% with a 1 second fade rate

MLServeCmd.MLVantage|SetSLoad~1~20~1~100~1


ToggleMLoad – Toggles a station load. If the load value is 0, the load is set to 100%, otherwise the load is set to 0.

Syntax: ToggleSLoad~<Master#>~<Station#>~<Load#>~<optional FadeRate>

Example: Toggle Load 1 on station 20 of Master 1 with a 0 fade rate

MLServeCmd.MLVantage|ToggleSLoad~1~20~1~0


SetVariable – Set a Vantage variable to a specified value. Syntax: SetVariable~<Master#>~<Variable#>~<Value#>

Example: SetVariable 3 of Master 2 (also called variable 10023) to 75

MLServeCmd.MLVantage|SetVariable~2~3~75


Set – Set any vantage item to a value by it’s MLServer variable name Syntax: SetVariable~<Name>~<value>~<optional faderate>

Setting the value to ‘T’ will cause the item to toggle

Example: Set the item mlvantage_n_outdoor_flood to 50%

MLServeCmd.MLVantage|Set~mlvantage_n_outdoor_flood~50


SwitchEx – Execute the programming on a specific Vantage switch (see VSW V-Command in Vantage documentation for more details) Syntax: SwitchEx~<Master#>~<Station#>~<Switch#>~<state>

Example: Execute switch 4 of station 25 on Master 1 with press-and-release state

MLServeCmd.MLVantage|SwitchEx~1~4~25~6


IREx – Execute the programming on a specific Vantage IR button Syntax: IREx~<Master#>~<IR Zone#>~<IR Button #>~<Mode>

Example: Execute button 5 in IR Zone 1 on Master 1 with press-and-release state

MLServeCmd.MLVantage|IREx~1~1~5~6


TStatTemp – Set a temperature set point on a Vantage Thermostat Syntax: TStatTemp~<Thermostat Name>~<value>~<type> <value> is the degrees in the chosen units to set the temp to, ‘+’ to increment, or ‘-’ to decrement <type> may be ‘DayHeat’, ‘NightHeat’, ‘DayCool’ or ‘NightCool’

Example: Increment the day-heat setpoint for the mlvantage_mainfloor_tstat

MLServeCmd.MLVantage|TStatTemp~mlvantage_mainfloor_tstat~+~DayHeat


TStatMode – Set the operation mode on a Vantage Thermostat Syntax: TStatMode~<Thermostat Name>~<value> <value> may be ‘off’, ‘cool’, ‘heat’, ‘auto’ or ‘I’. I = increment

Example: Set the mlvantage_mainfloor_tstat to cool.

MLServeCmd.MLVantage|TStatMode~ mlvantage_mainfloor_tstat~cool


TStatFan – Set the Thermostat Fan control to auto or on Syntax: TStatFan~<Thermostat Name>~<value> <value> may be ‘auto’, ‘on’ or ‘T’. T = toggle

Example: Toggle the fan on the mlvantage_mainfloor_tstat

MLServeCmd.MLVantage|TStatFan~ mlvantage_mainfloor_tstat~T


TStatDayNight – Set the Thermostat Day/Night Setting Syntax: TStatFan~<Thermostat Name>~<value> <value> may be ‘day, ‘night’ or ‘T’. T = toggle

Example: Set mlvantage_mainfloor_tstat to day

MLServeCmd.MLVantage|TStatDayNight~ mlvantage_mainfloor_tstat~day


SendVantageCommand – Send a V-Command or any other arbitrary string to vantage Syntax: SendVantageCommand~<command>

Example: Send the Vantage V-command VIR to cause an IR code to be send (see V-command documentation for more details.

MLServeCmd.MLVantage|SendVantageCommand~VIR 1 0 1 4

(note: tilda’s ‘~’ are not used since this command is send verbatim to Vantage using Vantage’s syntax rather than Main Lobby syntax)


The Vantage system can also send MLServer commands to Main lobby allowing the Main Lobby scenes to be changed, MLServer variables set, or other actions. This is accomplished simply by sending the MLServeCmd directly from Vantage using the SerialOut event to the comm port connected to the MLServer computer.

For example, you may want to cause your main lobby client display to switch to a “door_camera.mls” scene when a motion sensor or other event is detected by Vantage. Program a SerialOut event in response to the motion sensor to send the following command:

MLServeCmd.MLCmd|ChangeScene~client~door_camera.mls

Where “client” is the name of your MainLobby client. Use ALL to make all clients change


Thermostats

Two flash thermostats are provided to emulate Vantage thermostats.


To use these thermostats, create a button and enter the path to VantageThermostat.swf or VantageThermostatMini.swf in the JPG image or flash field of the Button Properties Panel. In the label field, enter the name of the MLServer variable assigned to the thermostat (as entered in the MLVantage thermostat configuration dialog. Do not use braces { }.

The Fan, Mode, Outdoor and Day/Night buttons may be shown or hidden by sending the following MLServe Command:

MLServeCmd.MLVantage|ShowTStatButtons~<t-stat name>~<value>

Where value is “show”, “hide”, or “T” (toggle).