MLCycleStates Plugin

From Cinemar Wiki
Jump to: navigation, search

Plugin Syntax

MLServeCmd.MLCycleStates|<<command>>~<<params>>


Plugin About

This is a plug-in to control the state variables in MLServer.

Supported commands:

Next~<<variable>> Prev~<<variable>> First~<<variable>> Last~<<variable>> Set~<<variable>>~<<state#>>

MLCycleStates Plug-In Documentation


Overview

The following paragraphs detail the installation, configuration and usage of the MainLobby / MLServer MLCycleStates state variable tracking Plug-In.

Installation and Configuration

Installation

Run the MLCycleStates.exe setup program and follow the on screen prompts.

Configuration

This plug-in must be configured prior to using it in a MainLobby scene. Highlight the MLCycleStates plugin in MLServer and click on the Settings button to bring up the State Variable Tracking configuration screen. You will be presented with a form as shown in Figure 1.


Usage

A state variable is defined as any MLServer variable that is allowed to take on many values. Each value represents a state and each state has an associated MLServer command that is triggered whenever the variable enters the state. For instance let’s say you have a server variable called TStatModes. This variable is used to track the current mode of your thermostat. As in the example below the variable has been configured to allow three unique states, Off, Heat and Cool. Each of these states has been assigned a unique MLServer command. See Figure 1.

Right clicking on the values in the State Variables tree will bring up the appropriate menu options for creating and maintaining these variables.

NOTES

1. When you define variable states make sure you define the values in the Data column using sequential numbers starting at 1 and incrementing by 1 for each defined step. See the example in the figure below. The plug-in uses the values in this column to properly identify the next and previous states of a variable.

2. When you add or remove a row from the Variable States grid please make sure to move your cursor off the row that was edited before clicking on the Done button. If you forget to do this the State Variables tree may not properly refresh. Your updates will be saved but the tree display mat be out of sync. If this happens simply right-click on the tree and select the refresh option.


DELETING A ROW

To delete a row, simply select the row with your mouse and press the DELETE key on your keyboard.

Supported Commands

Initialize (Defaults to the first data element in the Cycle State; otherwise, does nothing if an element has already been selected)

MLServer Command:

Next~vName

Where

vName = MLServer variable name

Example:

MLServeCmd.MLCycleStates|Initialize~Zones_Thermostat


Next (Advance to the next state value)

MLServer Command:

Next~vName

Where

vName = MLServer variable name

Example:

MLServeCmd.MLCycleStates|Next~TStatModes


Prev (Advance to the previous state value)

MLServer Command:

Prev~vName

Where

vName = MLServer variable name

Example:

MLServeCmd.MLCycleStates|Prev~TStatModes


First (Advance to the first state value)

MLServer Command:

First~vName

Where

vName = MLServer variable name

Example:

MLServeCmd.MLCycleStates|First~TStatModes


Last (Advance to the last state value)

MLServer Command:

Last~vName

Where

vName = MLServer variable name

Example:

MLServeCmd.MLCycleStates|Last~TStatModes


Set

(Set a variable to a known state)

MLServer Command:

Set~vName~State

Where

vName = MLServer variable name

State = One of the defined states (1..n)

Example:

MLServeCmd.MLCycleStates|Set~TStatModes~1

Set the TStatModes variable to its first state.


MLServer Two-Way Support

This plug-in will modify the appropriate MLServer variable when its state is changed. Two MLServer variables are created in the format:

VariableName_Label = Current State Label from grid

VariableName_Data = Current State Data from grid


Example

MLServeCmd.MLCycleStates|Prev~TStatModes

Set (Set a variable to a known state)

MLServer Command:

Set~vName~State

Where

vName = MLServer variable name

State = One of the defined states (1..n)


Example

MLServeCmd.MLCycleStates|Set~TStatModes~1

Set the TStatModes variable to its first state.


Example

MainLobby Client Button Label

SOURCE 3{{cav66_c{{{{clientname}}_rscontroller}}z{{{{clientID}}_rszone}}_source}}

The Russound plugin creates variables like: cav66_c1z1_source = Some Source#

So if we examine the above dynamic variable: {{cav66_c{{{{clientname}}_rscontroller}}z{{{{clientID}}_rszone}}_source}}

Let's first start by simplifying and letting you know that clientID and clientname are the same variable. So let's convert the above to:

{{cav66_c{{{{clientname}}_rscontroller}}z{{{{clientname}}_rszone}}_source}}

In our sample scenes, depending upon certain button presses and through the MLCycleSates plugin AudioZones database, we create variables that track the current clients russound controller (rscontroller) and russound zone (rszone) that the user is currently in.

The clientname is what is specified in MainLobby's OPTIONS > STARTUP under MainLobby clientname.

So you should see variables like the following in MLSERVER's variable window:

myclient1_rscontroller = 1

myclient1_rszone = 1, 2, 3, 4, 5 or 6

Assuming your clientname is myclient1.

and let's assume that the variable cav66_c1z4_source = 3

Similar to a math formula, we work from the inside of the curly brackets out replacing variables...this is how MainLobby interprets the label. I will show you step by step how each variable is replaced.


1: Original dynamic Variable {{cav66_c{{{clientname}}_rscontroller}}z{{{{clientname}}_rszone}}_source}}

2: Replace {{Clientname}} = myclient1 {{cav66_c{{myclient1_rscontroller}}z{{myclient1_rszone}}_source}}

3: Replace {{myclient1_rscontroller}} = 1 {{cav66_c1z{{myclient1_rszone}}_source}}

4: Replace {{myclient1_rszone}} = 4 {{cav66_c1z4_source}}

5: Replace {{cav66_c1z4_source}} = 3 3

So now the resulting dynamic variable equals 3. If you look at that button, it probably has a local off state. If that off state equals 3 and the dynamic variable equals 3 it will show whatever tinting and opacity settings you've established for that off state. Otherwise it will show the onstate.


More

Tracking Client’s Currently Selected Zone Exercise


You may have opted to install multiple touch screens and/or tablets on your project. It’s usually a good idea to allow each client (touch screen) to have the flexibility to control any and every room.

This exercise will illustrate how to build a system that is easily expandable and extremely powerful. Although your hardware may be different than this example, many of the concepts can be used.

We’ll assume this install includes a Russound Whole House Audio Controller. This exercise will also require the MLCycleStates Plugin.


About MLCycleStates

MLCycleStates is a great plugin that can serve a variety of useful functions. For example, you might need a single button in your interface to do multiple tasks such as cycle through your thermostats Heat, Cool, Off and Auto Modes. You can also use MLCycleStates to simulate radio button controls.

Setting up your Audio Zones in MLCycleStates 1. Let’s start by going into MLServer and from the Plugins window, double-click on the MLCycleStates Plugin.

2. Locate AudioZones in the tree and expand it by pressing the plus symbol

3. You’ll see a list of Zones such as Kitchen, Basement, Master Suite, etc. You can easily change the name of the Zone’s to match your setup. You can also delete a row by selecting the row and pressing DELETE on your keyboard. Ideally, you’ll setup the data column and label to match your configured Russound Zones. So if you have Kitchen wired as Zone 1 on your Russound, match that to the data field.

4. By default, the MLCycleStates Plugin creates two variables based on the name. audiozones_data audiozones_label These variables are not created until at least one command is sent to the MLCycleStates plugin which we will get into later.

5. Because we want each client to independently be able to move between zones, we’ve checked the Prefix Client Name on Server Variables. Assuming a MainLobby client makes a call to the MLCycleStates AudioZones state, the variable created will now look like:

clientname_audiozones_data

clientname_audiozones_label

6. You’ll also notice an MLServeCmd column. Here users can specify an MLServeCmd to be sent as the user moves between each record. In this case, we want to create a variable for each client that tracks which controller and zone the user desires control. Any instances of {{clientname}} will be replaced with the requesting client’s name.

MLServeCmd.Macro|SetVariable|{{clientname}}_rscontroller~1!SetVariable| {{clientname}}_rszone~1

Making a Single Button Cycle Through Each Zone

1. From MainLobby’s Menu Bar, select Add.

2. Press EDIT and select the button you just added

3. In the buttons label field, type:

{{{{clientname}}_AudioZones_label}}

This will dynamically display the name of the label as you’ve defined in the AudioZones cycle state.

4. In the MLServeCmd field for that same button type:

MLServeCmd.MLCycleStates|Next~AudioZones

This will initially start at record one of the AudioZones states and increment through each record upon each press while in launch mode. Once it reaches the end of the records, it will jump back up to record one. Each time, it will update the data and label field variables as well as send the MLServeCmd associated with that record.

In some cases you may want to jump to a particular zone rather than cycle through one at a time. In that case, you can place multiple buttons in your scene or even rooms of a floorplan. Then enter the appropriate record to jump to for each button:

MLServeCmd.MLCycleStates|Set~AudioZones~4

This will jump right to record four.

Sending: MLServeCmd.MLCycleStates|Next~AudioZones would then move you to record five.