HomeSeer IRTrans User Guide

Version 3

 

 


 

NOTE:  This guide as written refers to version 3.0.1 of the IRTrans plug-in and to HomeSeer version 3.

Introduction

The IRTrans plug-in for HomeSeer v3 allows HomeSeer to work with the IRTrans IR transmitter/receiver devices.

Key Features

o    Supports sending IR codes and detecting received IR codes.

o    Full support for selection of individual remotes, buses, and devices in triggers.

o    Full support for selection of individual remotes, buses, devices, and external emitters in actions.

o    IR sequence detection. (matching on a sequence of received signals within a time period)

o    IR code repeating. (ex. HSTouch users can hold a button down to repeat an IR code)

o    Scripting support for sending IR codes.

 

Installation

1.    If you have not already done so, install the IRTrans software that was included with your unit.  You may wish to check the IRTrans web site to ensure that you have the most current version installed.  Follow the instructions in the IRTrans User’s Manual.  Please ignore the portion of the manual that discusses IRTrans and HomeSeer as it is primarily referring older versions of HomeSeer.

2.    The IRTrans Server software must be running in order for the plug-in to function correctly, so you may wish to add it to your Startup Group or choose to run it as a Windows service so that it starts up with the PC.  If the IRTrans Server software is not running when the plugin is initialized, it will still continue to try to connect with the IRTrans Server software every 30 seconds.

3.    Test your installation of the IRTrans software by attempting to learn and send a few IR commands.  There is no point in proceeding further until everything checks out and is working properly.

4.    Install HomeSeer v3 if you have not already done so.  Start up HomeSeer and ensure the installation is working properly.

5.    Download and install the IRTrans plugin by clicking on  PLUG-INS | Manage located at the top of the HomeSeer web page:

a.    Expand the Additional Interfaces panel at the bottom to see a list of all the plug-ins available.

b.    Expand the Audio / Video and Infra-red (IR) Support panel and locate the IRTrans plug-in.

c.    Check the box to the left of the IRTrans logo to tag the package for installation.

d.    Scroll back towards the top of the list and you should see a Download and Install button.  Click on it to begin the installation.

Upon installation, the following files should be installed into the HS3 program folder, usually C:\Program Files (x86)\HomeSeer HS3.

FILE

DESCRIPTION

HSPI_IRTrans.exe

The HS3 Plugin Executable

IRTrans.NET.dll

IRTrans Server API Assembly - The plug-in uses this assembly to communicate with the IRTrans server.

\Config\hspi_irtrans.ini

Configuration options are stored here.  This file is automatically created the first time the plug-in runs.

 

Now that the plugin has been installed, it should appear in the Installed Plug-ins list as shown below.  Click on the red enable button to initialize the plug-in.

The IRTrans entry in the list will change as shown below:


Configuration

Now that the plug-in is installed, it’s time to get it configured properly.  You can access the configuration settings two ways:

1.    Click on the IRTrans link in the plug-in list as shown above.

2.    Use the pull-down menu at the top of any page by clicking on PLUG-INS | IRTrans | Configuration.

The configuration page as shown below will appear:

The configuration options are documented on the web page and need no further explanation.

Learning IR Signals

Learn new IR signals via the IRTrans learning feature accessible from the Windows tray.  Learning IR signals is discussed in the IRTrans Software Manual provided by the IRTrans Company.

 

Sending IR Signals

Sending learned IR signals through HomeSeer is accomplished either by creating an event, or utilizing the scripting interface.

Sending via a HomeSeer Event:

1.    Start by creating a new event or edit an existing one.

2.    Once you get to the point where you’re defining the “THEN” part of the event, select IRTrans Action from the drop list as shown below.


 

3.    Once you’ve chosen IRTrans Action, you’ll be presented with a series of drop lists as shown below:

 

4.    Select the action you want from the several types of IRTrans actions available:

ACTION

DESCRIPTION

Send IR Code

Sends a selected IR code one time.

Send IR Code Repeatedly

Sends a single IR code continuously until another event stops it, for a maximum time period of 20 seconds.

Stop IR Code Repeating

Stops any IR code that may be currently repeating.

Toggle Relay

If your IRTrans unit is equipped with relay(s), this action will toggle its current state.

Turn Relay On

If your IRTrans unit is equipped with relay(s), this action will turn the relay on.

Turn Relay Off

If your IRTrans unit is equipped with relay(s), this action will turn the relay off.

Pulse Relay

If your IRTrans unit is equipped with relay(s), this action will turn the relay on for about a second, then turn it back off.



If the action you’ve chosen is IR related, select the remote that contains the code you want to send, the command (code), and optionally the bus, device, and emitter that should be used to send it.  Depending on your combination of selections, the action may collapse on its own, or you may want to collapse it yourself when you’re finished.  The completed action will look similar to this:





Sending via a Script:

You can also control actions via HomeSeer scripts as well.

ACTION

SCRIPT COMMAND

Send IR Code

hs.PluginFunction("IRTrans","","SendIR", {"remote-name","remote-command", "bus", "device", "led-select"})

Send IR Code Repeatedly

hs.PluginFunction("IRTrans","","SendIRR", {"remote-name","remote-command", "bus", "device", "led-select"})

Stop IR Code Repeating

hs.PluginFunction("IRTrans","","SendIRR", nothing)

Toggle Relay

hs.PluginFunction("IRTrans","","ToggleRelay", {"bus", "device"})

Turn Relay On

hs.PluginFunction("IRTrans","","ToggleRelayOn", {"bus", "device"})

Turn Relay Off

hs.PluginFunction("IRTrans","","ToggleRelayOff", {"bus", "device"})

Pulse Relay

hs.PluginFunction("IRTrans","","PulseRelay", {"bus", "device"})

NOTE: Parameters in dark red are optional.  If bus/device is omitted, all busses/devices will be selected.  If led-select is omitted, the devices default emitters will be selected.


Single-Line Scripts:

If you want to call one of these functions in a single-line script, or the “execute immediate script command” action, you’ll have to prefix the hs.PluginFunction call with &n as shown in the example below:

&nhs.PluginFunction("IRTrans","","SendIR",{"Sony-tv","vol+",3})

Failing to add the &n will cause HomeSeer to log an error complaining about an invalid character when the script is executed.

Multi-Line Scripts:

If you’re accessing the plug-in from a script file you can call the functions as described in the table above, or you can obtain a reference to the plug-in and use that instead.  Using a reference allows a slightly shorter calling notation as shown in the example below:

 

‘ Obtain a reference to the plug-in

Irt = New HomeSeerAPI.PluginAccess(hs, “IRTrans”, “”)

 

‘ Call a few functions in the plug-in

Irt.PluginFunction(“SendIR”,{“sony-tv”,”pwr”})

Irt.PluginFunction(“SendIR”,{“sony-tv”,”mute”})

 

Detecting IR Signals

Detecting learned IR codes from within HomeSeer is accomplished by defining triggers.

Defining Triggers:

1.    Start by creating a new event, or editing an existing one from the Events page.

2.    Once you get to the point where you’re defining the “IF” part of the event, select IRTrans Trigger from the drop list as shown below:





3.    Once you’ve chosen the IRTrans Trigger, you’ll be presented with another drop list where you choose the specific type of trigger you want:

TRIGGER

DESCRIPTION

IR Code Received

Trigger fires whenever a specific IR code is received.

IR Code Sequence Received

Trigger fires whenever a specific series of IR codes are received in order within a short timeframe (sequence timeout) between received codes.  The sequence timeout can be adjusted from the plug-in’s configuration page and defaults to 2 seconds.  This allows up to 2 seconds to pass in between received codes and still consider the sequence a match.

If you find that you’re getting unintended sequence matches, try decreasing the sequence timeout a bit.  Conversely, if you find that the system is missing sequence matches, it could be that you’re not pressing the remote buttons fast enough and the sequence timeout should be lengthened.

IRTrans Changes to Disconnected

Trigger fires whenever the connection to the IRTrans server is broken.

IRTrans Changes to Connected

Trigger fires whenever the connection to the IRTrans server is reestablished.

IRTrans has been disconnected for exactly

Trigger fires when the connection to the IRTrans server has been broken for a specified period of time.

IRTrans has been connected for exactly

Trigger fires when the connection to the IRTrans server has been reestablished for a specified period of time.

 

4.    Depending on the trigger selected, other drop lists and selection boxes will appear necessary to complete the trigger definition:

TRIGGER

ADDITONAL CRITERIA

IR Code Received

You’ll also need to select which remote, command (IR code), and the bus and device.  If you don’t care what bus and/or device, choose (Any Bus) and/or (Any Device) on the appropriate drop list.

IR Code Sequence Received

Similar to “IR Code Received”, but allows you to add additional commands (IR codes).  Be sure to add them in the exact order you want them matched on.

IRTrans has been disconnected for exactly

You’ll need to specify a time duration.

IRTrans has been connected for exactly

You’ll need to specify a time duration.

NOTE:  HomeSeer automatically collapses the trigger when the required selections have been made.  These selections may include defaults that you don’t necessarily want.  If this happens, simply expand the trigger again and select the options you do want.

 


 

 

 

Defining Triggers With Conditions:

 You can also specify an IRTrans condition which any be used in conjunction with a trigger.  In this case, both the conditions and the trigger must match in order for the event to trigger.  A few IRTrans triggers can also be used as conditions if desired.  You define a condition as follows:

1.    After you’ve defined the trigger, click on the green plus sign to the far right of the trigger to add a condition.

2.    Select IRTrans Trigger from the list as described above.

3.    Select the IRTrans trigger condition desired as shown below:

4.    The trigger conditions are described in the following table:

TRIGGER CONDITION

DESCRIPTION

IR Code Received

You’ll also need to select which remote, command (IR code), and the bus and device.  If you don’t care what bus and/or device, choose (Any Bus) and/or (Any Device) on the appropriate drop list.

IR Code Sequence Received

Similar to “IR Code Received”, but allows you to add additional commands (IR codes).  Be sure to add them in the exact order you want them matched on.

IRTrans Changes to Disconnected

Trigger fires whenever the connection to the IRTrans server is broken.

IRTrans Changes to Connected

Trigger fires whenever the connection to the IRTrans server is reestablished.

IRTrans has been disconnected for exactly

Trigger fires when the connection to the IRTrans server has been broken for a specified period of time.

IRTrans has been connected for exactly

Trigger fires when the connection to the IRTrans server has been reestablished for a specified period of time.

NOTE:  HomeSeer automatically collapses the trigger when the required selections have been made.  These selections may include defaults that you don’t necessarily want.  If this happens, simply expand the trigger again and select the options you do want.