What is the MLHAI Plugin?
MLHAI is a software plugin to add support the the HAI OmniPro and OmniLT line of security panels to the MainLobby 3 software suite. The MLHAI Plugin consists of:
1 – the MLHAI.dll plugin v. 3.0.X
2 – the MLHAI Agent that is installed on the PC that will have direct connection with the HAI panel
Zone status updates
X10 on / off / dim control
UPB on / off / dim control
Auxiliary temperature sensor support
Control over the Hi-Fi HAI audio system
MLServer 3.0.520 or newer
MainLobby 3 Client v 3.0.151 or newer
Microsoft .NET 2.0 installed and patched on both the Server and Agent PC (which can be same or different PCs)
MLHAI Plugin v 188.8.131.52 or newer
MLHAI Agent v 3.0.3117.39966 or newer
HAI Omni LT, Omni, Omni II, OmniPro, OmniPro II or OnQ HMS1050 security panels
HAI model 21A05-2 RS232 serial cable (ethernet connectivity under development) and a null serial cable
Appropriate lighting adapter (from HAI)
Appropriate thermostat (from HAI)
MLHAI Plugin Installation
You should have already installed MainLobby 3 Client, MainLobby Server 3.0.520 or newer on your system.
Make sure that MainLobby Client and MLServer are not running
Run the .exe which will copy the MLHAI.dll to the MLServer\Plugins directory.
The Plugin Settings window is used to tailor the settings.
Start MLServer Once MLServer launches open the Plugin window and verify that the MLHAI plugin is loaded. If it isn’t, check the box next to the plugin name and restart MLServer.
Install the MLHAI Agent The HAI plugin was designed with the ability to offload the CPU intensive polling of the HAI panel to a non MLServer PC. The Agent can be installed on the same PC, or a different one. The Agent connects via TCP to the MLHAI plugin that is running on the MLServer PC.
Run the MLHAI_Agent_Setup.exe on the PC that will connect to the HAI panel (either via serial or ethernet).
Your firewall and antivirus software on both the MLServer PC and the HAI Agent PC has to be opened on the communication port. Restart your PCs after making these changes.
Licensing MLHAI Plugin
Launch MLServer 3 and open the MLServer Help / Registration window. Look for the MLHAI plugin v 3.0.x. It should be enabled and in Trial mode if this is the first time MLHAI plugin has been installed on that PC. Add License by a Copy / Paste your MLHAI License from the email you got from Cinemar when you purchased the product. Click Save License. You can now activate your License on that PC. Click Activation Request button. An email form will open. If the PC is connected to the Internet, fill out the questions asked and click Submit (TIP: Fill in the Owner Information section in MLServer 3 (Help / Registration / Owner Information) to have the form pre-filled each time you register a MLServer 3 plugin). All responses must match your records when you purchased the software. Within 48 hours you will get an Activation code email. If you are not connected to the Internet, save the URL address for the form, and copy the License and PC code from the bottom of the form. Open this URL on a separate PC and enter the information in at that PC. When the email with the Activation code comes back to the email account you specified, you can copy the Activation code from one PC to another. As the registration text is case sensitive, if you retype the code, use UPPERCASE letters. Once the Activation email is received, Click the Activate Now button and copy / paste or type the Activation code and click Activate.
Configuring the MLHAI Agent
Launch the MLHAI Agent and open the settings window. The MLHAI communication Settings window should now be open.
Click on the Connections Tab. Set the comm port that you’re PC is connected to the HAI panel. You should be using the special serial cable that was purchased from HAI. The baud rate should be 9600 baud and you should click the Enabled check box for serial.
Click the Login button. Enter the PC security access code that you configured in the HAI panel. Consult HAI for information on how to set a PC access code. If you enter the wrong code and attempt to connect a couple of times unsuccessfully, the HAI panel will lock out all next attempts for one hour. Make sure you don’t forget the access code!! The default code is typically 1111.
If you have the com port setup correctly, have the right cable connected, have the HAI panel started, have the right login code – you can now click the Connect (Disconnect) button and you should now be connected to the HAI panel.
Click on the Setup button. This sends a command to poll the HAI panel for all Zones names. If a Zone name is found that is not a default name, it gets tracked by a MLServer 3 variable.
Click on the Event Log tab and click Create Log File. This will create a MLHAI.log file that can help with debugging. This should only be used if there is a suspect error, and should not be kept running as the file gets very large and can cause performance issues.
Click on the Zones tab: Select the zones that you want to monitor with the plugin. As the HAI panel doesn’t “tell” the RS232 port when something changed, the software has to “poll” the panel if a zone changed state. The more zones that require this constant polling, the slower the overall MLServer / LAN will be. So, if you only have a few zones or other devices to monitor, you can decrease the “Poll every X seconds” on the Scheduling tab for faster response to a change. If you have a lot of zones / devices, you will have to increase this time and the system will react slower to a changed zone.
Click on the Scheduling tab: Here you can select which thermostats to monitor. Select only the thermostats that exist and you want monitored. The properly configured HAI thermostat will then return it’s data and the MLHAI plugin will create MLServer variables with the current temp and thermostat settings.
The plugin monitors your MLServeCmds that turns on an X10 device via the HAI panel (see Supported MLServeCmds section below). This action also sets a MLServer variable with that state. The HAI panel also listens on the powerline for an X10 message. The HAI panel then “tells” the MLHAI plugin that it received an X10 message and the plugin then updates the MLServer variable with that X10 status change. If the X10 device does not transmit an X10 signal on the powerline when it is locally controlled (common), MLServer variables will be out of synch with the actual state of the device.
You can also select optional temperature sensors to monitor.
When you click “Start On Load”, this type of device will be polled as per the “Poll every X Seconds” when the plugin is started. Polling should not be set for shorter than 2 seconds or there may be system reliability issues.
Due to the design of the HAI panel, the fewer the devices to be monitored, the more real time the MLServer variable updating will be.
You can disconnect from the Panel by clicking the Disconnect button on the Connections tab. You can reconnect by clicking the same button.
You should consult the HAI provided support documents for configuring the panel properly for PC connectivity.
If you have installed a previous version of this beta then you must uninstall the old beta before installing this version.
This version of the Agent / Plugin requires MLServer version 3.0.527 located in the beta folder.
Theory of operation.
When MLServer runs and the MLHAI plugin loads it will start to look for the Agent(s) that have been defined in the list that have the Auto Discover option checked.
When the MLHAI Agent loads it will first connect to the HAI panel and it will get the current configuration from the panel. This includes all named data and current status from the entire panel. Once all the data has been collected from the panel the monitor choices are restored from the database and applied to the tables. This completes the panel initialization sequence.
Once the Agent has finished the panel initialization it will then turn on the network server and accept connections from the remote plugin(s). As soon as a plugin attaches to an agent the agent will dump the complete set of monitored server variables. This will get the MLServer variables in sync with the current state of the panel. From that point on new updates will be sent to the plugin only as required.
The plugin is now a member of the Security family. You can issue commands to the panel using either the traditional
or the family command syntax
This architecture allows for a single server to poll multiple panels or multiple servers to poll a single panel.
HAI connectivity guide
(reprinted from www.worthington.com)
Establishing a Serial Connection from PC Access to an HAI or HMS Controller is simple. All it requires is a HAI21A05-2 serial cable (phone cable with a RJ11 to DB-9 connector). Worthington Distribution strongly recommends using the manufacturer’s standard phone cable and connector over building cables. Nearly every time a custom cable is used the issue ends up being the cable. Once communication is established, custom cables can be substituted.
Create a new file in the PC Access software. Under Configure / Serial Choose the correct COM Port, Baud Rate 9600 See “T00124 Using An Elk USB to Serial Converter With HAI” if the PC does not have a serial port Plug the HAI21A05-1 DB-9 Adapter into the Serial port (note, the phone cord does not need to be attached). The PC Access should say ‘On-Line’ in the lower right corner ‘On-Line’ only means that the Adapter is present. It does not reflect actual communication with the panel. Use the phone cord from the HAI21A05-2 kit to connection the DB-9 Adapter to an HAI serial port. At default all HAI panels are defaulted to ‘Omni-Link’ and 9600 baud. Under Command choose ‘Set Time’. Hit OK and a box should quickly flash saying it is setting the time. You are now connected! Troubleshooting:
When starting out, it is always recommended to start with a defaulted file and defaulted panel. Once the PC is configured correctly this is not necessary, it just eliminates variables when troubleshooting. Code #1 in the PC Access file MUST match the User Code #1 that is currently in the controller when the initial connection is made. Once the connection is made, User Code #1 can be changed and the new configuration can be downloaded to the controller. Always start with the HAI21A05-2 cable kit. Homemade cables are often made wrong. Do not substitute a different phone cord until everything is working. If the DB-9 is Plugged into the selected COM port and it does not say ‘On-Line’ then there is an issue in the operating system or a hardware issue. Belkin USB to DB-9 Adapters generally do not work. Use an Adapter from Keyspan or the ELKUSB232 is available from Worthington Distribution. 2 pieces of software are not permitted to point at the same COM port at the same time. Possible conflicting software: WebLink, Media Center Plug in, 2 copies of PC Access open, Palm Programming Software, Premise SYS (runs as a service even when SYS is shut down), HomeSeer.
MLServer Event Variables for MLHAI
MLServer Commands for MLHAI
Within the MLHAI Agent, at the bottom left of the Settings window there is a Command Builder button. When you click this, a command list will be displayed. The list of available commands is listed here below. If in the command builder you click on a command in it's list...you will then see the appropriate parameters for that command.
MLHAI|<<alias>>~<<command>> or Security.<<alias>>|<<command>>
1.) Read this document
2.) Search www.cinemaronline.com/forums
3.) Post question on forum
07-15-2008 Version 3.0.3117.39966 1) Added support for OnQ version of Omni Pro II panel
07-09-2008 Version 3.0.3112.20465 1) Updates zone configuration options
06-30-2008 Version 3.0.3103.40100 1) Fixes command builder bug.
06-29-2008 Version 3.0.3102.21850
A completely new version of the plugin has been released. The HAI software is now comprised of a MLServer plugin and a stand-alone HAI Agent. The MLHAI plugin is the client that communicates with the new MLHAI Agent server application.
The new MLHAI Agent is a completely stand-alone application and can run on any PC including the MLServer PC. The agent communicates to the MLHAI plugin via TCP/IP and this should eliminate all MLServer bottlenecks due to panel polling.
1) Plugin Configuration - (see HAI Plugin Image 1). Creat a new alias and change the host name to the name or IP address of the PC where the HAI Agent is running. Do not use the common name "localhost". Do not change the port number unless there is a known conflict with this port on your network.
2) Agent Configuration - (see HAI Agent Image 1). a) Make sure the port number specified in the agent configuration box matches the port number you specified in the plugin. b) Then specify how you will communicate with the HAI panel. Configure either the network interface or serial port. c) Under general settings select the type of panel you will be controlling and any available options. d) Check off the Initialize Polling check box if you want the Agent to automatically start polling the panel on startup. e) Click the save settings button to store your preferences. f) Restart the Agent or issue the Initialize_Polling command.
New features in this release. 1) New client / server architecture to eliminate MLServer performance hit due to polling.
2) Adds button to hide / show Command Builder.
3) Adds ability to define features that are monitored and reported back to MLServer. (See HAI Agent Image 2). Uncheck or check the items that are to be monitored and click the Save Monitor Choices button after all your selections have been set. These settings are stored in a local database and restored on application launch.
4) The command queue has been divided into two queues. There is now a user command queue and a polling command queue. All MLServer commands are placed into the user command queue and all polling commands are placed into the polling queue. Commands in the user queue are given top priority over the polling queue. No commands are executed from the polling queue until all the commands in the user queue have been executed. (See HAI Agent Image 3).
MLServer Commands for MLHAI - OLD from version 1 of MLHAI plugin
Where CMD(0=Disarm, 1=Day, 2=Night, 3=Away, 4=Vacation, 5=Day Instant, 6=Night Delayed) AREA(1-25)
Arm Status Request Command
Zone Status Request Command
Request Temperature Command
Request Thermostat Data Command
MLServeCmd.MLHAI|TR~THERMOUNIT Where THERMOUNIT (1..64)
Set Thermostat Data Command
Where CMD (0 - MODE, 1 - FAN, 2-HOLD, 3-HEAT, 4-COOL, 5-HEAT, 6-COOL)
IF CMD = MODE, VALUE (0- OFF, 1-HEAT, 2-COOL, 3-AUTO)
CMD = FAN, VALUE(0-AUTO, 1-ON)
CMD = HOLD, VALUE(0-OFF, 1-ON)
CMD = HEAT, VALUE(Some Temperature Value)
CMD = COOL, VALUE(Some Temperature Value)
Where CMD(0-HEAT, 1-COOL)
VALUE(Temperature Value, 0-99)
Where P1 1...511
P2 0-OFF, 1-ON, 2-DIM, 3-BRIGHTEN, 4-LEVEL
IF P2=0 OR P2=1, P3= TIME 50m or 2h
IF P2=2 OR P2=3, P3= DIM OR BRIGHT LEVEL (1...9) AND P4 = TIME 50m or 2h
IF P2=4, P3=LEVEL
Example[ For OFF]:MLServeCmd.MLHAI|UNIT~1~0~50m
Example[ For ON]:MLServeCmd.MLHAI|UNIT~1~1~50m
Example[ For DIM]:MLServeCmd.MLHAI|UNIT~1~2~5~50m
Example[ For BRIGHTEN]:MLServeCmd.MLHAI|UNIT~1~3~5~50m
Example[For LEVEL]: MLServeCmd.MLHAI|UNIT~1~4~50
Where UNIT 1...511
TIME 50m or 2h
Where UNIT 1...511
CMD (0 - OFF, 1-ON, 2-SCENE)
IF (2-SCENE) PASS THE SCENEVAL
Example(With Scene): MLServeCmd.MLHAI|PLC~1~2~B(SCENE VALUE A-L(Upper Case))
Radio RA Phantom Button Command
Where UNIT 1...511 Where CMD( 0-RADIO OFF, 1-RADIO ON )
UPB Link Command
Where UNIT 1...511 Where CMD( 0-DEACTIVATE, 1-ACTIVATE, 2-STORE PRESET )
UPB Unit Command
Where UNIT 1...511
CMD(0-LED OFF, 1- LED ON)
LED( 1-8 )
Leviton SCENE Command
Where UNIT 1...511
CMD(0-OFF, 1-ON, 2-SET)
Centra SCENE Command
Where UNIT 1...511
ENERGY SAVER Command
Where UNIT 1...511
CMD (0-OFF, 1-ON)
TIME (like 50m, 2h)
KEYPAD EMERGENCY Command (Requires firmware version 2.8 or later)
Where AREA 1...8
EMERGENCYTYPE (1-Burglary, 2-Fire, 3-Auxilary) 1-ON)
RECORD/PLAY MEMO Command (Requires firmware version 2.8 or later)
Where PLAY=1 RECORD=2
IF CMD = 1 , VALUE(0 =OFF, 1-ON, 2-MUTE OFF, 3-MUTE ON)
IF CMD=2, VALUE( VOLUME 1.. 100 PERCENT)
IF CMD=3, VALUE(SOURCE 1...n)
IF CMD=4, VALUE( KEY 1 - 40)
ZONE = 1....n
Execute Macro button Command
WHERE VALUE 1....n
Zone Bypass Command
WHERE VALUE 1....n
WHERE VALUE 1....215
Zone Restore Command
WHERE VALUE 1....n
WHERE VALUE 1....215
Zone Restore All Command
WHERE VALUE 1....n