MLHSPlugin Plugin

From Cinemar Wiki
Revision as of 23:38, 16 August 2007 by Deanb2 (Talk | contribs) (MainLobby Client MLHSPlugin examples)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

About

The MLHSPlugin provides for bidirectional integration between MainLobby Server and Homeseer. This provides significant capability as both product's advantages can be leveraged for a comprehensive home automation and media control solution.


January, 4th 2005




Copyright © 2004, Krumpholz Enterprises, All Rights Reserved

Documentation written by Morgan Lavelle aka “Brave Sir Robbin” and Krumpholz Enterprises.

For more excellent “How To” type of documentation, visit www.cocoontech.com.


Overview

If you've been searching for a polished, professional front end for your sophisticated HomeSeer automated home, look no further. MainLobby offers a configurable high-end graphical front end for media library and control software and HomeSeer provides a flexible and powerful back end. Tie the two together with the MLHSPlugin, and you can create awesome, custom looking screens for your sophisticated automated home. You will get much more value out of your HA investment by easily designing user friendly screens that anyone in your home can use. Not to mention the wows that you will hear by your family and friends! Want to see some examples of screens that some talented users have created? The enclosed link will connect you to the User Screen Interface Samples page on the MLHSPlugin Message Forum: http://forums.homeseer.com/showthread.php?t=90016

1.) HomeSeer: (www.homeseer.com) - Backend Automation interface tool HS is a very powerful home automation system that essentially can control everything from the alarm system, to the devices in the home theater, the weather management system, to lights throughout the home via X10 and ZWave lighting controls. Throughout the five years of using HomeSeer, I have been able to interface and control just about everything and anything using the HomeSeer scripting and plugin architecture, but have always desired a simple to implement yet professional looking front end user interface to my home. So hence came the interest in MainLobby after a 4 hour conversation with Cinemar last summer regarding the integration between HomeSeer and MainLobby.

2.) MainLobby/MainLobby Server (or also known as MLServer) - www.cinemaronline.com - Front End User Interface Tool MainLobby is the user interface system that allows one to create and display the desired visual interface for your automated home and is installed on all client devices/computers. Supported devices currently are any recent Windows based computer, touch screen, and TabletPC. MainLobby Server is the engine/database and connectivity interface between all Cinemar product offerings, and provides your MainLobby client devices the "status/state" information. MainLobby Server combined with MainLobby (without HomeSeer) has the capability of controlling certain hardware devices directly.

3.) The MainLobby-HomeSeer Two-Way Communication Plugin operates as a technology "data" bridge between HomeSeer and MainLobby Server. This architecture was chosen because it allows each of these services to reside on a single or separate networked computer. The communication between both systems is almost instantaneous. The MLHSPlugin is actually two components, one plugin for MainLobby Server, and another plugin for HomeSeer. Both of the two plugins connect to each other on startup and immediately communicate information that was configured by the user. Whenever a HomeSeer device state change occurs, the HomeSeer MLHSPlugin is notified and then will send the data to its MainLobby Server MLHSPlugin counterpart. The MainLobby Server will then notify all MainLobby client computers of the updated device state. When a user clicks on a button via a MainLobby interface screen that is designated to turn on a light, MainLobby Server sends the "Turn light ON" command request via the MLHSPLugin to HomeSeer. HomeSeer then performs the requested task, automatically triggers a device state change, and sends the updated information back to MainLobby Server. MainLobby Server then records the state change and notifies all active MainLobby clients. All of this is seamless to the user. This architecture allows you the ultimate in flexibility to install HomeSeer and MainLobby Server either on the same computer, or on separate network accessible computers (even separated by the Internet). The MainLobby client software can be available on network connected PC's, wireless touch screen tablets, or even operable using standard remote control devices and a TV.

How it works:

• During execution, the MLHSPlugin HomeSeer plugin creates variables within MainLobby Server (MLServer).

• Subscribed HomeSeer device "value" and device "string" status changes are sent by the MLHSPlugin HomeSeer plugin to the MainLobby Server variables - which can then be displayed on MainLobby clients.

• MainLobby clients can initiate HomeSeer commands and events to manage lights, thermostats, security system, and audio/video devices already controlled by HomeSeer.

• The HomeSeer scripting interface can now initiate MainLobby Server MLServeCmd's. (Very powerful)

New Enhancements:

• HomeSeer Events are now enhanced with an MLHSPlugin Actions tab that will allow you to directly enter an MLServer MLServeCMD. This is useful is situations where you want to configure a event trigger based on some occurrence (for example alarm intrusion) and then want all of the MainLobby client computer to display a message or change to a specific screen.

• Dynamic Graphic Support. You can now configure icons that dynamically change on a MainLobby screen based on the HomeSeer device state.

For more information on what HomeSeer home automation software entails please visit http://www.homeseer.com .

For more information on MainLobby, which also has other software packages including Music Lobby, Weather Lobby and DVD Lobby, please visit http://www.cinemaronline.com.

Product Requirements

The MainLobby-HomeSeer (MLHSPlugin) requires the following: • Purchase or 30 day trial of MainLobby (MainLobby provides license to MainLobby Server) - www.cinemaronline.com You may enhance your MainLobby visual capability by extending it to manage your Music and DVD collection via MusicLobby and Dvdlobby, Weather updates from Internet via WeatherLobby, and web browsing capability via WebLobby). Products can be purchased individually or as an entire package. Note: 30 day trial offers evaluation of all products in one download!

• Purchase or 30 day trial of HomeSeer Home Automation Software - www.homeseer.com

• Purchase or 30 day trial of MLHSPlugin (You will receive the HomeSeer and MainLobby Server plugins available for download via HomeSeer Updater (From HomeSeer, select Help, select Updates)

Disclaimer/License Agreement

This plug-in provides two-way communication between the MainLobby Server and HomeSeer home automation systems. In order for this plug-in to provide any functionality, the user is therefore required to purchase (or implement the 30 day trial versions) and agree to the software licensing and support terms of all three respective software products. MLHSPlugin is licensed as “personal hobby use only” and requires a license for each HomeSeer installation. Commercial licenses are available and inquiries should be directed to developer. While we make every effort to provide quality software products, and since we cannot test this software in every potential computing environment, the developer of this software does not guarantee that this product is free from defects. The user therefore accepts that this product is provided "AS IS" and its usage is therefore at the users own risk. The developer of this software makes no warranties as to the performance, merchantability, fitness for a particular purpose, upgradeability/compatibility to future MainLobby Suite and/or HomeSeer product versions, or warranties of any kind whether expressed or implied. Product support inquiries regarding Cinemar (MainLobby Suite - www.cinemaronline.com) and HomeSeer Technologies (HomeSeer- www.homeseer.com) should be directed to the respective software provider support forums. Support questions for this product, should be directed to the MLHSPlugin forum on the HomeSeer technologies message board.

The developer of this software retains the right to release an advanced version of this plugin with additional MainLobby / HomeSeer integration features in the future. An upgrade charge to switch from the consumer to the advanced version may apply.

At the time of this writing, the author of this plugin has had limited accessibility to validate functionality of this software with HomeSeer 2.0. The above statements of pricing and future compatibility are based on "best guess" anticipated development efforts, and therefore, the above statements may change according to the actual efforts required to certify this application with HomeSeer 2.0.

Thank you for your support and understanding.


Visit the MLHSPlugin Support Forum Frequently

Be sure to visit the MLHSPlugin support forum frequently as it provides:

• Latest product support information and additional “How to” steps

• Latest interim product updates

• Related Cinemar product announcements

• Interaction with other MLHSPlugin users


The MLHSPlugin support forum is accessible via the HomeSeer Message board via (http://forums.homeseer.com/forumdisplay.php?f=683).

Installation Instructions (Start Here)

This tutorial will help install the software needed, and properly set-up integration to insure proper communication exists between MainLobby and HomeSeer. A sample “switch” setup will also be provided for a MainLobby screen (so it can control a HomeSeer device). Please note that this plugin is really composed of two separate plugins, one for HomeSeer and one for MainLobby. Each plugin will have a setup screen that will need to be configured.

Downloading, Installing, and Configuring the HomeSeer MLHSPlugin

The first step is to download MLHSPlugin installation package via the HomeSeer Updater. This installation package will include the plugin for the MainLobby Server (MLHSPlugin.DLL) and the plugin for the HomeSeer application (HSPI.MLHSPlugin.OCX). Once downloaded/installed via the HomeSeer Updater, you will need to add the plugin to the HomeSeer Active Interfaces and configure the plugin.

Start the HomeSeer updater by clicking “Help”, then “Updates” from within the HomeSeer main device screen.



Select the “Next” button through the next three screen selections. You will see the HomeSeer Updater launch. When it launches, wait for the multiple colors to appear on the plugin selections. Select the MLHSPlugin (check box). Write down the trial code given in the bottom of this display then click on OK in the lower right corner. The updater will download the compressed plugin files, stop HomeSeer, and then proceed to install the plugin on your computer.

Select “Return to HomeSeer” after the plug-in is finished installing. Now go to the “View”, “Options” menu in the main HomeSeer screen. An Options interface box will appear. Click on the “Interfaces” tab. Then click on the combo box down arrow in the Plug-Ins (RF, I/O, Security, Custom) dialog box as shown below. Select the MLHSPlugin:


After selecting the MLHSPlugin, you may now be informed that a valid license key has not been entered and then prompted to enter your serial number or license key (see menu below). At this time, enter the serial number or license key that was allocated to you by the HomeSeer store (www.HomeSeer.Com/Buy.html) or the appropriate trial key via the HomeSeer Updater.


Once you have completed entering the serial number/license key, click on OK/TRY/UNLOCK to continue.

Click on the “OK” button to close the OPTIONS screen and then restart the HomeSeer program. This will properly load the HomeSeer MLHSPlugin.

Once the HomeSeer program restarts you should see the MLHSPlugin option in the top menu bar. Select “MLHSPlugin”, then “Show/Configure Plugin”. If the MLHSPlugin menu is not visible on your menu bar, then select VIEW and Options from the HomeSeer menu bar. You are now presented with the OPTIONS configuration screen. Now select the MLHSPlugin in the ACTIVE INTERFACES dialog box and click on SETUP.

The ABOUT MLHSPlugin screen will appear (as shown below). At this time, please read the disclaimer/license agreement. If you agree to these terms, check the “I agree to the license agreement…” and then click OK:


This HomeSeer MLHSPlugin configuration/status screen will now be displayed:


Important: Select the “Enable this plugin” option on the bottom left of this screen. Then select the devices you wish to use with MainLobby. Then click on “Subscribe to Above Devices”. Take note of the port that is set to communicate with MainLobby Server’s MLHSPlugin (in this example it is 2410). You have now completed the plugin setup with HomeSeer.

Downloading/Installing/and Configuring MainLobby Server and MainLobby Client

Downloading MainLobby (ML) Trial or Licensed Product View

1. Go to the Cinemar website (http://www.cinemaronline.com/mainlobby.html) and click on the “Free Trial” button below the price display to request a fully functional MainLobby trial suite. An Email will be shortly sent to you with the download link.

2. Once you get the Email download the MainLobby/Music Lobby/DVD Lobby trial program file.

3. Now go to the Cinemar website and download the MainLobby Server program (http://www.cinemaronline.com/mlserver.html).

Note all of these software packages have a 30-day (fully functional) free trial.


Setting Up MainLobby Server (MLServer):


IMPORTANT: It is suggested to Shutdown HomeSeer before installing the MainLobby Server.

Shut down HomeSeer. Then double click on the MainLobby Server (mlserversetup_135.exe) file you downloaded from the above link. Accept all the default values during this installation. (It is highly recommended that the default installation path of C:\Program Files\MLServer not be altered!)

While HomeSeer is still shut down, go ahead and install the Music Lobby/DVD Lobby/Music Lobby trial. Unzip the file downloaded above (file name is mainlobby_dvdlobby_musiclobbytrial.zip). This will uncompress a “setup.exe” file. Double click on this file to start the setup program. Use all the default settings for this installation as well. (Again, it is highly recommended not to alter the default C:\Program Files\Cinemar main installation path).

Installing/Configuring the MainLobby Server MLHSPlugin

Once MainLobby Server is installed, you will need to copy the MainLobby MLHSPlugin from the HomeSeer Updater directory to the MainLobby Server Plugins directory. If you forget this step, all of this will not work:

1.) Open your HomeSeer application folder. Usually, this is C:\PROGRAM FILES\HOMESEER. There should be an UPDATES folder, and within the Updates folder should be the MainLobby-HomeSeer Plug-in1.1.0.xx (xx=version #) source directory that the HomeSeer Updater downloaded. By default this would be C:\Program Files\HomeSeer\updates\MainLobby-HomeSeer Plug-In1.1.0.XX. We will now refer to this path as the “MLHSPlugin source installation folder”.

2.) From the MLHSPlugin source installation folder, copy the MLServer MLHSPlugin Install.EXE to the computer that you have installed MLServer on. Now execute the MLServer MLHSPlugin Install.EXE file from the computer that you have installed MLServer on. The following screen should be displayed:


Click NEXT


Please read. If you are executing this file on the computer where MLServer is installed on then click NEXT.


Now enter the path to where the MLServer\Plugins directory is. By default MLServer\Plugins directory is in the c:\program files\mlserver\plugins folder. Click NEXT



Click INSTALL followed by FINISH.


3.) Copy the MLHSPluginExample.MLS file (located in the MLHSPlugin source installation folder) to your MainLobby Cinemar folder. On a default installation, this folder is located in C:\Program Files\Cinemar. If MainLobby has not been installed (per the instructions, you have only installed MainLobby Server so far), then remember to perform this step later.

After installing and registering all of the Cinemar MainLobby software according to the above directions, double-click on the MainLobby Server’s icon to launch the MainLobby Server program. You should see the menu below:


You can select the check boxes “Start Server on Startup” and “Minimize on Startup” depending on your desired restart methods. Do not start the MainLobby Server at this time.

In the bottom “Plug-Ins” text box select the MLHSPlugin and then click on the “Settings” button (to the right). This will now bring up the following menu:



This menu looks very similar to the HomeSeer MainLobby’s plugin setup screen. You can tell the difference by looking at the top title bar (MainLobby Server says “MainLobby Server MLHSPlugin – Settings Screen”, HomeSeer says “HomeSeer MLHS Plugin”).

Note that for this particular example we are going to place the MainLobby Server on the same computer as the HomeSeer server. Therefore the HomeSeer Computer Name of “localhost” and HomeSeer Computer TCP Port need to be 2410 in both the HomeSeer and MainLobby setup screens mentioned above.

Also, select the “Enable this plugin” setting on the lower left. Then click on “OK”. Your MainLobby HomeSeer plugins setup is now complete.

Setting Up A Network Attached MainLobby Client Machine:

Running a MainLobby screen on a client machine requires the machine to be on your internal “LAN” network. For this example we are assuming the client machine and server machines are behind the same firewall and do not require any ports to be opened or forwarded via a firewall/router.

Install the MainLobby Client on the client machine by copying the “setup.exe” file that was uncompressed from the Email linked zip file (from above). Insure no instances of HomeSeer are running on this client machine, and then double click on that file to launch its setup program. Again, make sure you use all the default installation settings.

Copy the sample MainLobby screen that was used above to this client’s C:\Program Files\Cinemar directory.

Start the MainLobby client program on this client machine. Open the sample MLHSPluginexample.mls example screen. Move your mouse to the top of the screen so the setup dialog box is visible. Click on “Options” to bring up the screen shown below:


Now instead of using the “localhost” setting under the Computer Name (Server) enter the IP Address of the MainLobby Server’s IP address. Also enter the name of this client’s machine in the “MLServer Client ID” text block.

Save this screen then exit and restart the MainLobby client program on this client machine. Open the example screen above. You should now be able to control the lights via this screen from this client machine.

Go to the MainLobby Server machine and look at the MainLobby Server’s main screen. You should see now see the client machine connected to this server in the “Clients Connected” text box. Notice that you can have a maximum of ten client machines connected to this server machine. The screen below shows a “Kitchen” client machine (whose IP address is 192.168.1.102) connected to the MainLobby Server.

MLHSPlugin Methodology:

When a HomeSeer device changes state (from Off to On) the device house and unit code, along with this new device value gets sent to the MainLobby Server. The MainLobby Server then offers this information to MainLobby. When a command for a device change is issued from MainLobby (to turn a HomeSeer device On), this communication works in the opposite fashion.

Now start HomeSeer and wait until HomeSeer has completed its start up sequence.

Now start the MainLobby Server by clicking on the “Start” button on the top of the MainLobby Server screen (as shown in the menu below). You should see HomeSeer connected to the MainLobby Server by looking at the message bar on top of both HomeSeer and MainLobby Server’s setup status screens, and also by looking at the values being passed to the MainLobby server.

Look at MainLobby Server’s main screen (screen initially displayed when you first started MainLobby Server) and click on the “View in Window” button in the variables group. You should similar Name and Value displays:


mlhsplugin_statustext CONNECTED


mlhsplugin_connectionstate

7=Means connected


mlhsplugin_hssystemuptime x Days x Hours x Minutes x Seconds (HomeSeer “up” time, updated every 10 minutes)


mlhsplugin_sunrise

Sunrise time set by HomeSeer

mlhsplugin_XX …… “Devices Value”

Device Value


This insures that HomeSeer is communicating with the MainLobby Server.

MLHSPlugin will attempt to properly translate as MLS variables the various HomeSeer device state (On, Off, Dim), device string, and device value information as best as possible. MLHSPlugin will assign the state or device string into a MLS variable as MLHSPlugin_C10 and the value of a device into MLS variable as MLHSPlugin_C10_Value. For example, when a HomeSeer device is dimmed, the MLS variable MLHSPlugin_C10 will contain “Dim 50%” and the MLS variable MLHSPlugin_C10_Value will contain the numeric value 50.The numeric value is important when using sliders and button states as they require a numeric value instead of text string information.

Summary

Your Client and Server machines are now setup for MainLobby communication to HomeSeer. Most users using this plugin will probably be new to MainLobby, so some time must be spent learning how to use this program (designing screens/library buttons).

If all is not working properly please check the above communications checks and guidelines between the two plugins, between the MainLobby Server and Homeseer, and the MainLobby Server and any client machines that are used.

For further help and information on MainLobby please visit the MainLobby Forums at http://www.caseserve.com/cinemar/phpBB2/index.php.

For further help with HomeSeer visit http://board.homeseer.com/.


For help with both programs, plus additional information on home automation and home theater (such as port forwarding How-to’s) visit http://cocoontech.com

Creating Your First MainLobby Interface Screen

Now it is time to try your first MainLobby interface screen. As part of the MLHSPlugin download, the HomeSeer Updater has placed an “MLHSPluginExample.MLS” example file in the HomeSeer\Updates folder. Please copy this example file from the HomeSeer\Updates folder (usually c:\program files\HomeSeer\Updates\MainLobby-HomeSeer xxxxx where xxxxx is the version number) to the MainLobby directory (usually c:\program files\cinemar).

Working with the MLHSPlugin Example ML Scene - Basic

The overall objective of this chapter is to first provide you an overview of the basic functionality of the MainLobby – HomeSeer integration via the MLHSPlugin. Second, we will review the chapters of the MainLobby user manual that should then give you a better overview on how to create MainLobby screens (scenes) from the beginning.

Open the MainLobby (client program). If this is your first time (or if no settings have been modified) a default screen should appear. Move your mouse to the very top of the screen and you will see an interface (drop down) dialog box appear. This is how you will exit, select a screen to open, enter design or run modes, save your screens, etc… This screen will always appear every time you move your mouse to the top of the screen.

One important step is to change the default way MainLobby exits the program (presently it is via the “Esc” key). By default pressing the ESC key in MainLobby will exit the program without allowing you to save your work. Click on the “Options” followed by the “Startup” (left side of screen) button in this dialog box. You will see the menu below:



Under the “Exit Key Shortcut” drop down box, select “NONE”. Also note that in this example, the “Computer Name (For MLServer) is “localhost” because MainLobby Server (MLServer) is running on the same machine in the example. If this were the client machine, this entry would need to be the name or IP of the machine that was running MainLobby Server. Also note the “ML Server Port” is 5004. This is the port number that needs to match the port setting in MainLobby Server’s main screen above. We recommend that you do not change the MLServer port. You can also change the “ML Server Client ID” text block to reflect the name of the machine where this MainLobby Server is residing on. Click on the “OK” button on the lower right after completing the above settings.


MainLobby Edit Environment Overview

The MainLobby screen-editing environment takes a little getting use to. First you must understand the “Button Modes”. ‘Edit’ means when you click on a button you can edit its features (via a configuration menu), ‘Design’ means you can move your buttons around and even align them together with the “Align” button, ‘Launch’ means that the screen is in its unedited view mode and is now executing.

The “Library” button shows all the possible types of buttons that can be used with MainLobby. Experimentation is required to get that ultimate screen. Save often as you are experimenting.

Modifying the MLHSPlugin MainLobby Example File

Click on the “OPEN” button in the top right of the drop down dialog box. Select the MLHSPluginExample.mls screen, and then click on “OPEN”. The MainLobby example screen should now be displayed.

We will be editing the group of buttons shown below for the first example:


This group is currently set to control the HomeSeer Device C10. The left “OFF” button will turn the device off, the right “ON” button will turn the device on, the “-“ button will dim the device, the “+” button will brighten the device and the center “OFF” button will display the device’s present state (in this case On, Off, or Dim to xx%).

To edit a button click on the “Edit” button under the “Button Mode” dialog box selection in the top of this MainLobby screen. Then click on the right “ON” button. You will now see a button edit dialog box as shown below:


The command syntax to send commands to the MainLobby Server is MLServeCMD.MLHSPlugin followed by the typical HomeSeer command to turn a device on (for this C10 device’s case it is MLServeCMD.MLHSPlugin|HS_ExecX10:C10~On).

Notice this command is already displayed in the MLServeCMD dialog box. Change this command for one of your HomeSeer devices that you registered with the plugin in the steps above. You can immediately test the command by clicking on the “test” button to the right of the dialog box. Click the “OK” button on the lower right.

Now lets edit the “+” button. Since you are still in the “edit” mode click on the “+” button. You should see the following dialog box appear:


Notice the command syntax in the MLServeCMD dialog box needed to brighten the HomeSeer device C10. Change this command for your device you would like to test, then click on the “OK” button.

Change the “-“ and the “OFF” commands to suite your device you are testing.

Click on the center rectangular gray button below the “Device C10” text in the center of this group. You will now see the following dialog box:


This box will display the current status of the HomeSeer Device C10. Notice the syntax entered in the “Label” text box. The command is mlhsplugin_”Device” surrounded by double brackets. For example, for device C10 enter {{MLHSPlugin_C10}}. Change this entry for your device you are testing.


Important Note:

MLHSPlugin will attempt to properly translate as MLS variables the various HomeSeer device state (On, Off, Dim), device string, and device value information as best as possible. MLHSPlugin will assign the state or device string into a MLS variable as MLHSPlugin_C10 and the value of a device into MLS variable as MLHSPlugin_C10_Value. For example, when a HomeSeer device is dimmed, the MLS variable MLHSPlugin_C10 will contain “Dim 50%” and the MLS variable MLHSPlugin_C10_Value will contain the numeric value 50.The numeric value is important when using sliders and button states as they require a numeric value instead of text string information.

A summary of the above examples commands and their proper syntax for turning the example HomeSeer device C10 ON, OFF, Bright, and Dim as well as showing the devices current status are listed below:

The command to turn device C10 ON is: MLServeCMD.MLHSPlugin|HS_ExecX10:C10~On

The command to turn device C10 OFF is: MLServeCMD.MLHSPlugin|HS_ExecX10:C10~Off

The command to brighten C10 (in 20% increments) is:

MLServeCMD.MLHSPlugin|HS_ExecX10:C10~BRIGHT~20

The command to dim C10 (in 20% increments) is:

MLServeCMD.MLHSPlugin|HS_ExecX10:C10~DIM~20

The command to toggle the device state for C10 is:

MLServeCMD.MLHSPlugin|ToggleDevice:C10

To display device C10’s current state or device string information enter:

{{mlhsplugin_c10}} in the “Label” dialog box. To display device C10’s current value information enter {{MLHSPlugin_C10_Value}}.

An entire set of the commands available is listed at the end of this document.

Creating MainLobby Scene Screens from Scratch - Advanced

This section will describe how to create a new MainLobby scene from the beginning. While we can not demonstrate every aspect of the MainLobby application, we will provide an overview of the areas of MainLobby that pertain to the MLHSPlugin.

Prerequisites: • Installed and functioning HomeSeer software.

• Installed and functioning MLServer software.

• Installed and functioning MLHSPlugin software. Some HomeSeer devices should already be subscribed and device data should be stored into MLServer variables.

• MainLobby client software installed and configured on at least one workstation.

If you have not already started the MainLobby client software then please do so now.

MainLobby Client MLHSPlugin examples

Label

You can put text on or around the button by typing in the label field. Depending on the button, the text may be positioned below or around the button. You may also adjust font size, color, alignment and the actual font used. All fonts are embedded within MainLobby. It does not look on the user’s system for additional fonts. This is where you can display HomeSeer device information that has been subscribed and sent to MLServer via the MLHSPlugin. Enter the following using the HomeSeer X10 House/Unit code (replace C10 with HS device house/unit code):

{{MLHSPlugin_C10}} for device state/device string textural information {{MLHSPlugin_C10}} for device value information


MLServeCMD (Send Cmd’s to MLServer or to HomeSeer via MLHSPlugin)

This is a command structure that sends commands between MainLobby clients and MLServer. MainLobby Server is a new Server side application written for MainLobby and other Cinemar software. It allows the Cinemar applications to have mutliple clients and send information back to the server. MainLobby clients can now communicate bi-directionally with a server to issue commands to control hardware and other software connected to the server as well as send macros.

It is available for download and requires MainLobby 2.30a or higher. MainLobby creates a file called mlserverconnect.ini in your Cinemar folder. If you are trying to connect to MLServer located on a networked computer, edit the ini file using Notepad changing the serverDomain to the name of the computer you are connecting to. From MainLobby, when you edit a button you will notice an MLServeCmd line in the button properties. You need to install the MainLobby Server software on the computer you'd like to control.

Entering the command sequence MLServeCMD.MLHSPlugin|HS_ExecX10:C10~ON would send the command to HomeSeer (via MLHSPlugin) and turn of the HomeSeer device C10.

MainLobby to HomeSeer Commands

HS_Run

Overview Runs HomeSeer located script. Scripts must be located in the scripts directory in the HomeSeer application directory.
Parameter Type Description
scr string Is the filename of the script to run. Do not include the path in the script name.
Example MLServeCMD.MLHSPlugin|HS_Run:myscriptname.txt

HS_RunEX

Overview Runs a function in a script with a parameter. This will also return a value from the called script. Scripts must be located in the scripts directory in the HomeSeer application directory.
Parameter Type Description
scr string is the filename of the script to run. Do not include the path in the script name.
func string The name of the function to execute.
param variant A parameter to send to the function. This can be a string or numeric value.
Example MLServeCMD.MLHSPLugin|HS_RUNEX:scriptname~function~parameter

HS_SendIR

Overview Send an I/R command to an attached infrared device. Each extra comma adds a 1/4 delay.
Parameter Type Description
ir string Is a string of I/R text commands. These are the same commands that are listed for each of the keys for a particular device.
Return value Type Description
none
Example This example sets the "vcr" to "record"
MLServeCMD.MLHSPLugin|HS_SendIR:VCR,Record

HS_WriteLog

Overview Write a message to the HomeSeer event log
Parameter Type Description
class string Is a string that defines the type of event like "Error" or "Info". It can be anything you like. Common message types are "Info”, “Warning", and "Error".
message string Is the text to be displayed in the log, like a descriptive error message.
Return value Type Description
none
Example MLServeCMD.MLHSPLugin|HS_WriteLog:Info~Any Text Message

HS_TriggerEvent

Overview Force HomeSeer to trigger an event.
Parameter Type Description
name string Is the name of the event you want to trigger. The actions for the event are executed. Note that the name is not case sensitive. Events "Evening" and "evening" would be considered the same. If there were duplicate event names, only the first one found would run.
Return value Type Description
integer 1 if error, else 0 if no error. If an error is detected, and error message is written to the event log.
Example MLServeCMD.MLHSPLugin|HS_TriggerEvent:TurnOutSideLightsOn

HS_DisableEvent

Overview Marks a HomeSeer event as disabled. All triggers are suspended until the event is re-enabled.
Parameter Type Description
evname string Is the event name to disable. Note that the name is not case sensitive.
Return value Type Description
none
Example MLServeCMD.MLHSPLugin|HS_DisableEvent:TurnOutSideLightsOn

HS_EnableEvent

Overview Marks an HomeSeer event as enabled.
Parameter Type Description
evname string Is the event name to enable. Note that the name is not case sensitive, and the event must have already been disabled.
Return value Type Description
none
Example MLServeCMD.MLHSPLugin|HS_EnableEvent:TurnOutSideLightsOn

HS_SetDeviceString

Overview Sets a string as the device status. The string "message" is displayed in the device status column. This appears on the web page and the local device list. This can be used to display the status of special devices like thermostats and weather stations. Note that this does not affect the actual X10 status for the device, which can be accessed by DeviceValue().
Parameter Type Description
device string Is the X10 housecode unitcode of the device like "A1"
message string Is the status string for the device, like "72 degrees" (without quotes)
Return value Type Description
none
Example MLServeCMD.MLHSPLugin|HS_SetDeviceString:A1~72 degrees

HS_SetDeviceStringByName

Overview Sets a string as the device status. The string "message" is displayed in the device status column. This appears on the web page and the local device list. This can be used to display the status of special devices like thermostats and weather stations. Note that this does not affect the actual X10 status for the device, which can be accessed by DeviceValue().
Parameter Type Description
Device string Is the name of the device including it location like den table lamp. Note the name is not case sensitive and is made up of device location and device name.
Message string Is the status string for the device, like "72 degrees" (without quotes)
Return value Type Description
none
Example MLServeCMD.MLHSPLugin|HS_SetDeviceStringByName:Den Table Lamp~72 degrees

HS_SetDeviceValue

Overview Sets a value that is associated with this device. Values are used to hold the dim level of a device. You can also use them as user variables in your scripts. Note that HomeSeer will overwrite this value if an X10 command was received for this device. If you are going to use this as storage for your own information, pick a device that does not exist in your home. You can also use virtual devices (devices in the range "q->z", or unit codes between 17 and 99), as these devices will never be affected by X10 power line activity.
Parameter Type Description
device string Device code like “A1”.
value long A numeric value like 50.
Return value Type Description
none
Example MLServeCMD.MLHSPLugin|HS_SetDeviceValue:A1~50

HS_SetDeviceValueByName

Overview Sets a value that is associated with this device. Values are used to hold the dim level of a device. You can also use them as user variables in your scripts. Note that HomeSeer will overwrite this value if an X10 command was received for this device. If you are going to use this as storage for your own information, pick a device that does not exist in your home. Same function as SetDeviceValue except you pass this function the actual text name of the device.
Parameter Type Description
device name string The name of the device must contain both the location and name. If the device was name lamp, and its location was living room, the device_name parameter would be living room lamp.
value long A numeric value like 50.
Return value Type Description
none
Example MLServeCMD.MLHSPLugin|HS_SetDeviceValueByName:Living Room lamp~50

HS_ExecX10

HS_ExecX10ByName

Overview Execute a device command using the actual house code and device code.
Parameter Type Description
Code string Is a string of devices like "A1" or "A1plus2plus3plus9". HS_ExecX10ByName would require device name (Living Room Lights) instead of House and Unit Code.
Cmd string Is the name of the command as a string. See the table below for more information.
Dimval integer
(optional)
Is the % dim for "Dim" and "Bright" commands. For the "Pre-set Dim" command, this is a value between 0 and 31.
data2 integer
(optional)
Is the second data byte for the "Extended" X10 command. The dimval parameter is the first data byte if the command is "Extended"
wait boolean
(optional)
This command is not implemented by MLHSPLugin.
Return value Type Description
integer 1 if successful else 0 if error
Commands are not case sensitive. Commands valid for Z-Wave devices are shown in BLUE.
Command Description
NoCmd This is used to send X-10 address information only - no X-10 commands are sent.
All Units Off Sends the X-10 All Units Off command to the house code provided.
All Lights On Sends the X-10 All Lights On command to the house code provided.
On Turns on the device.
Off Turns off the device.
Dim Dims the device to the level specified in DimVal (Relative dim for X-10 devices, absolute dim for Z-Wave devices)
DDim Dims the device to the level specified in DimVal regardless of device type. (Absolute dim) If the device is configured as a Leviton Extended Dim, then an Extended Data command is sent. If the device is PCS Preset Dim, then Preset Dim is sent. If the device is Z-Wave, then a Z-Wave set level command is sent.
Bright Sends the X-10 Bright command to the device.
Dim to Off Sends several X-10 dim commands to the device to insure it is off.
DimAB Dims to the absolute level specified in DimVal by sending bright or dims according to its present last known level in HomeSeer.
DimBF Dims to an absolute level specified by DimVal after going to full brightness first
All Lights Off Sends the X-10 All Lights Off command to the house code provided. Note: Not many devices support the All Lights Off command.
Extended Sends an X-10 Extended Data Command - the first byte of data goes in DimVal, and the 2nd byte goes in Data2
Hail Request Sends an X-10 Hail Request command
Hail Ack Sends an X-10 Hail Acknowledge command
Preset Dim Sends an X-10 Preset Dim command. DimVal is the preset dim level specified between 0 and 31
Status On Sends an X-10 Status Response "On"
Status Off Sends an X-10 Status Response "Off"
Status Request Sends an X-10 Status Request message
Example MLServeCMD.MLHSPLugin|HS_ExecX10:H8~On
MLServeCMD.MLHSPLugin|HS_ExecX10:H8~Off
MLServeCMD.MLHSPLugin|HS_ExecX10:H8~Dim To Off
MLServeCMD.MLHSPLugin|HS_ExecX10:H8~DDim~50
MLServeCMD.MLHSPLugin|HS_ExecX10:H8plus9plus10~On
MLServeCMD.MLHSPLugin|HS_ExecX10:H8plus9plus10~Off
MLServeCMD.MLHSPLugin|HS_ExecX10ByName:Bath lights~On
MLServeCMD.MLHSPLugin|HS_ExecX10ByName:Bath lights~Off
MLServeCMD.MLHSPLugin|HS_ExecX10ByName:Bath lights~Dim To Off

HS_Speak

Overview Speak some text.
Parameter Type Description
text string Is the string you want to speak. It may also be the complete path to a WAV file, and the WAV file will be played.
Return value Type Description
none
Example MLServeCMD.MLHSPLugin|HS_Speak:Hello World

HS_MuteSpeech

Overview Read/Write property. Temporarily mutes the speech output. By setting this property to FALSE, all speech output is silenced until this property is set back to true. This mutes ALL speech, including speech sourced from scripts.

The status bar in the main HomeSeer display window will display Mute while speech is muted.

Parameter Type Description
TRUE boolean speech output is silenced.
FALSE boolean speech output is enabled.
Return value Type Description
none
Example MLServeCMD.MLHSPLugin|HS_MuteSpeech:True
MLServeCMD.MLHSPLugin|HS_MuteSpeech:False

HS_ClearLog

Overview Clears the HomeSeer event log in memory. The event log file "ah.log" is untouched.
Return value Type Description
none
Example MLServeCMD.MLHSPLugin|HS_ClearLog

HS_Launch

Overview Launches a given application. The function will return before the application finishes launching.

Parameter Type Description
name string Is the name of the exe file to launch. It can be a simple application name (the path to the application would have to be in your system path) or it can be a full pathname to the file. Application files can also be launched and the application that owns the file will be executed. For example, you could set the name to "c:\docs
parameters string Any parameters or command line switches that are to be passed to the application
direc string The working directory the application is launched from. Leave an empty string for most applications.

Example

MLServeCMD.MLHSPLugin|HS_Launch:c:\filename.exe~command~c:\


HS_ControlThermostat

Overview This function gives direct access to thermostats. Thermostats are supported with special .THM scripts. The command parameter is the entry function that is called. Keep in mind that the functionality of these commands is dependent on your THM script/hardware. The functions available are:
SetSetPoint Sets the current heat (or Cool) set point
SetFan Sets the current fan mode (0=On?, 1=Off?)
SetMode Sets the current operation mode (1=Heat, 2=Cool)
SetCoolSetPoint Sets the current cool set point (if supported by thermostat)
Parameter Type Description
device String Device code of thermostat like "J1". This is configured device code.
Command String Command : SetSetPoint, SetFan, SetMode, SetCoolSetPoint
Value String Value to set if setting temperature, mode, or fan.
Return value Type Description
none
Example MLServeCMD.MLHSPLugin|HS_ControlThermostat:J1~SetSetPoint~78
MLServeCMD.MLHSPLugin|HS_ControlThermostat:J1~SetFan~0
MLServeCMD.MLHSPLugin|HS_ControlThermostat:J1~SetFan~1
Macro to set thermostat to cool and set SetPoint to 78 degrees:
MLServeCMD.Macro|MLHSPlugin|HS_ControlThermostat:Y1~SetMode~2!MLHSPlugin|HS_ControlThermostat:Y1~SetSetPoint~78
Macro to set thermostat to heat and set SetPoint to 70 degrees:
MLServeCMD.Macro|MLHSPlugin|HS_ControlThermostat:Y1~SetMode~1!MLHSPlugin|HS_ControlThermostat:Y1~SetSetPoint~70

HomeSeer to MainLobby Commands

HS.Plugin (“MLHSPlugin”).MLServeCMD

The HomeSeer MLHSPlugin allows you to send MLServeCMD’s to MainLobby. This is very powerful as it allows HomeSeer scripts or HomeSeer Events to send commands to your MainLobby infrastructure. Please see the HomeSeer MLHSPlugin Message Forum for additional “How to” type of instructions. Enclosed are a few of the many possibilities:

To Send a Text Message to ML Clients for 60 Seconds

hs.plugin("MLHSPlugin").MLServeCMD "MLServeCmd.MLCmd|Msg~All~Testing~This is a test of the emergency broadcast system~60"


Send MLServeCMD from HomeSeer script to change MainLobby Client Scene

hs.plugin("MLHSPlugin").MLServeCMD "MLServeCmd.MLCmd|ChangeScene~All~newscenename.mls"