JDS Stargate Plug-in
From HomeSeer
This plug-in is designed to allow HomeSeer HS2 and HSPRO to monitor and control functions of the JDS Stargate controller.
[edit] Requirements
There are several requirements to using the HomeSeer JDS Stargate plugin:
- HomeSeer Version 2.1.122 or higher must be installed.
- A JDS Stargate, JDS Stargate IP, JDS Stargate Lite, TimeCommander, TimeCommander Plus, or RCS CS30 must be installed in your home.
- The Stargate must be connected to your HomeSeer computer via a COM port.
- Your Stargate Devices should be defined using the WinEVM program in order to import them into HomeSeer.
[edit] Installation
- To install the JDS Stargate plugin plug-in for HS2, select the “Updater” button on the web interface, or select “Updates” from the “Help” menu. Follow the on-screen instructions for the Updater.
- Select the JDS Stargate plugin plug-in on the package selection screen, then follow the on-screen instructions to finish the update process, and restart HomeSeer.
- After restarting HomeSeer, click the “Setup” tab and then the “Interfaces” tab on the web site. Click “Disabled” to enable the plugin, on X10, IR, or "Other" interfaces. See below for more information. Click “Save” at the bottom of the screen to start the plugin.
- To use the JDS Stargate plugin, you must first register the plug-in. There are two methods of registration, depending upon the information that you have been provided from the time of purchase.
- Click “Unregistered” or “Trial” button on the line containing the JDS Stargate plugin Plug-in to register. This will display the Registration Screen.
- Enter your License ID and Password included on your order receipt. Click the “Register” button. If you have any technical difficulties, see the Support section of this manual and open a ticket at or help desk.
Select only the interfaces you wish to use (X10, Infrared, and Other). You can use just the functionality of the Stargate that you need. You will also probably want to select JDS Stargate as one of your "Other" interfaces. Note that if you wish to control Stargate variables, flags, etc. you must select the Stargate as one of your "Other" interfaces.
[edit] JDS Stargate Configuration Screen
Baud Rate The baud rate should be set to 9600 for JDS Stargate and 2400 for JDS Time Commander.
Poll Interval Timed polling is one way of compensating for things that eventually get out of sync in even the best-designed system When the Stargate plug-in is started, it reads the current states of the various digital and analog inputs, relays, X10 devices, and so on from the Stargate. Timed polling allows you to repeat this initial query at selected intervals. The Box will allow you to set how how often the Panel should be polled (in seconds). The Checkboxes on the next line allow you to select which categories of Stargate devices you would like to include in the polling procedure. All devices will update automatically without polling, but Analog inputs and external relays (RS-485) must be polled. Please read the note on this page for more information.
Debug Controls
The output of the debug functions is complex and non-intuitive. Explaining how to interpret it is far beyond the scope of this help file. Using the functionality in this section is recommended only under the direction of HomeSeer or plug-in tech support.
All of these functions are time-consuming and generate a lot of log entries, so they should not be left on when not actively in use. These are defined as follows.
Function Debug
When checked, this turns on a function-by-function trace that writes to the HomeSeer log. This should be regarded as undocumented, because it is only implemented in certain areas of the plugin. Again, the output is only really useful to someone who knows the internal structure of the plug-in, so it is primarily for the use of tech support.
COMM Debug
This provides a low level window into everything that goes in or out over the serial link between the HomeSeer PC and the Stargate. This is used for troubleshooting the serial link and making sure that it is sending and receiving what it is supposed to. The output is obscure, and requires the Stargate protocol specification document to interpret.
HS Trace On
This isn’t a plug-in function at all, but rather a way of controlling through the plug-in a debug function that is built into HomeSeer. It controls the creation of a file called hstrace.log in the HomeSeer program directory that traces internal HomeSeer program execution. It is useful primarily to HomeSeer tech support.
IRXP Backup
If you use the Infrared portion of the plugin interface, this button will get all the data from the Infrared XPanders and write it to the log. This button will only appear if the Infrared interface is enabled.
WinEVM Connect {This information from Jeff Stein of JDS Technologies} It is possible to run the Stargate WinEVM console and the HomeSeer Stargate plug-in together. Setting this up is a three part process. You will need a second serial cable. This cable connects to the Stargate COM2 or COM3 port on one end and to a free PC serial port on the other end. Since WinEVM is limited in the serial ports that it can understand, you should probably consider putting WinEVM on the PC’s COM1 or COM2 (and on Stargate’s COM1) and the HomeSeer plug-in on the higher ports on each side. The Second Cable is essentially identical to the primary Stargate cable; an RS-232 data cable with a RJ-11 connector on the PC end and a DB-9 or DB-25 connector on the PC end. The easiest way to do this is to use a ‘silver satin’ flat RJ-11 data (not phone) cable and an RJ-11 to DB9 or RJ-11 to DB25 adapter.
The selected port on the Stargate needs to be configured as a Modem port.
The unit on the Stargate’s secondary port needs to announce itself to the Stargate by sending a CONNECT<cr> string. This can be enabled from the HomeSeer configuration dialog by checking the WinEVM Connect box. If WinEVM Connect is enabled, it also enables a button on the Control panel that allows you to send the connect string manually. The connect string may also be sent through the scripting interface.
Timer Display This enables a timer within the plugin, so that when any timer is loaded in the Stargate, HomeSeer will count down and reflect the values in the corresponding device. This can be useful if you are using hs.DeviceValue to read the number of seconds left before a Timer expires.
Setting the Stargate clock Enter your Latitude and Longitude, then click "Set Time" to set the Stargate time. This is controlled by the plugin and your PC's clock, so the Stargate time will reflect these. Importing WinEVM databases
- Click on the "Browse" button to browse to your DBF files. This will display a dropdown list that you can use to browse for the file.
- Click "Import/Update Devices," the page will refresh, and you will see a number of checkboxes to select the devices you would like to import:
- Check the devices that you want to Import, and check "Overwrite Existing Devices" to update your HomeSeer devices with your WinEVM information.
- Click "GO!". The plugin will write a message to the log when the import has been completed, usually this will only take a few seconds.
Save Settings Click this button to save all of the settings from the plugin. This occurs automatically whenever the plugin is shut down.
[edit] JDS Stargate Status Screen
Message Count Display This is a three column list display. The first column displays the mailbox number (1-8). The second column displays the number of new messages in that mailbox. The third column displays the number of old (already played) messages in that mailbox.
Voice Mail Function Buttons The Drop-down list controls which mailbox (1-8) these function buttons will control.
Playback Device Selection This list allows you to configure which Stargate audio output is used for voice mail playback. Choices are one or more of : Stargate speaker, Stargate line output, Intercom (internal phone), or CO line (external phone). This is a multiple-select list, so press Ctrl+Click to select more than one output.
VOX Setting This allows setting of the Stargate voicemail VOX threshold (build 3.08a of Stargate Firmware and above). Click the "Set VOX" button to send this information to Stargate.
Start Schedule This instructs the Stargate to start running it’s programmed schedule. (This has no relation to HomeSeer events or devices. It is a Stargate command.)
Stop Schedule This instructs the Stargate to stop running it’s programmed schedule. (This has no relation to HomeSeer events or devices. It is a Stargate command.)
Connect This call sends the “Connect<CR>” sequence required when the HomeSeer plug-in is being used as a secondary Stargate interface.
Log Window This is the display window for the log and status functions. It shows the text output returned by the Stargate.
Stargate Status This displays the System Status text readout from the Stargate.
Message Log The ‘Message Log’ button dumps the contents of the Stargate message log to the log display window. The ‘Clear’ button underneath the phone log button tells the Stargate to clear the message log.
Phone Log The ‘Phone Log’ button dumps the contents of the Stargate phone log to the log display window. The ‘Clear’ button underneath the phone log button tells the Stargate to clear the phone log.
[edit] Stargate ASCII Out functions
The Stargate plug-in has several sets of functions that can be activated by using the ‘ASCII Out’ function from a Stargate schedule. Currently implemented are Shell to DOS, Play Media File, and Execute Script. Using Play WAV file (ASCII Out) from the Stargate This works ALMOST exactly as with WinEVM. Using ASCII Out from the Stargate, a line prefixed with '@@' will be played as an audio file using HomeSeer's media capability (actually Windows Media). THe difference lies in it's interpretation of file locations. Since HomeSeer isn't (we most definitely hope) in the same directory as Stargate, the plug-in cannot make the same assumptions about file location. Thus, file location works as follows:
- If no path is specified, it will look in the current directory and then along the system path.
- If the filename is prefixed with '.\', it will look in the 'media' subdirectory under the HomeSeer directory.
- If the filename is prefixed with '*\', it will look in the StarGate directory specified in the Config dialog box.
- If another absolute or relative path is specified in the filename, it will attempt to use that path.
Refer to the description of ‘ASCII Out’ in the Stargate documentation. Using DOS shell (ASCII Out) from the Stargate This works exactly as with WinEVM. Using ASCII Out from the Stargate, a line prefixed with '&&' will be passed to the DOS shell to execute. Refer to the description of ‘ASCII Out’ in the Stargate documentation. Calling HomeSeer scripts (ASCII Out) from the Stargate Using ASCII Out from the Stargate, a line prefixed with '$$' will be passed to the the HomeSeer script engine as a script file name. See the 'Run()' command in HS Scripting documentation and refer to the description of ‘ASCII Out’ in the Stargate documentation. The equivilant of RunEx() is also available, using The format:
ASCII-Out”filename.vbs:function(variable)
With filename being the script file name, function being the function or subroutine name within the file, and variable being a variable number or string. Thus, an event could be written in Stargate
EVENT: Phone Call If CO: Ring 2 Then ASCII-Out:’$$phonecall.vbs:CallerID(<CID>) End
Using Stargate’s CID macro (in the ASCII_Out dialog box). This would send the caller ID string to a user-written script in HomeSeer that would do whatever with it.
ASCII Capture Using ASCII Out from the Stargate, a line prefixed with '>>' will be saved in the plug-in and can be read using the scripting LastAscii() method. This is intended primarily for harnessing the Stargate’s Caller ID functionality, but also can be used for anything else that you can devise.
[edit] Stargate Phone Pad
This window allows direct control of the Stargate Phone functionality. From the "Stargate Control" page, click on "JDS Stargate Phone Pad". The buttons form the dial string in the box at the top of the page, then click "Dial" to send this to Stargate. The phone panel is intended to duplicate the functionality of the manual telephone control utility window in WinEVM. As a result, operation is slightly less than intuitive. You assemble a dial string in the top window, and then click the ‘Dial’ button to send it to the Stargate. Normally, a phone session starts by taking the line Off Hook, and ends by placing it back On Hook. The rest of the buttons should be self-explanatory.
[edit] Accessing the Stargate Infrared Interface
In order to use the Infrared Xpander interface through the Stargate, the Stargate must be installed as the Infrared interface. From the "Interfaces" tab of the HomeSeer setup page, click "Disabled" under the Infrared column on the JDS Stargate line, then click "Save" at the bottom of the page. Access to the Infrared functionality is through the standard Infrared interface facilities (scripting and control panel) defined in HomeSeer. See the HomeSeer manual for further information.
The reason that there is no import method for the Stargate Infrared database is as follows. Under HomeSeer the Infrared commands are grouped into devices (not related to HomeSeer devices - these are the physical devices that the Infrared commands control. This mapping extends into the way that they are stored in the HomeSeer database. Since WinEVM has no concept of Infrared devices, there is no way of reliably mapping an existing WinEVM Infrared database into HomeSeer. An import facility was written and then abandoned for just this reason. Rather, it is recommended that you re-learn the Infrared commands under HomeSeer.
[edit] Interface Scripting
The following scripting interface consists of methods on the Stargate plug-in object, This is only available to the user in HomeSeer 1.52 Build 26 and above. Scripting capability at this point is divided by function into:
- Internal clock functions
- Status and log functions
- Voice mail functions
- Schedule functions
- Stargate polling
- SendConnect
- SelectPlaybackDevice
Getting the plug-in object
In order to call any public method of a plug-in from VBScript (HomeSeer’s scripting language), you first have to get an object representing the plug-in. The easiest way to do this is by using the .plugin() method of the Homeseer object. The following code fragment performs this function:
dim oSG set oSG = hs.plugin(“JDS StarGate”)
The interface methods documented here are then methods of oSG. This same method works for any other plug-in if you know what the names of the interface methods are.
[edit] Stargate Internal Clock Functions
SetTime(strLatitude As String, strLongitude As String) Set the Stargate time/date from the PC system clock. The plug-in reads the station latitude and longitude, clock time and time zone information directly from the operating system.
SetStargateTime(strLatitude As String, strLongitude As String) This function is for when you want tu use a different latitude and longitude for the Stargate clock settings for some reason. (Stargate doesn’t track well for some locations outside of the US.) The arguments are integer values for latitude and longitude, expressed as strings. The best way to set this up is probably to establish these as global variables in HomeSeer. The control panel uses the names ‘Site Latitude’ and ‘Site Longitude’ for these. The plug-in reads the clock time and time zone information directly from the operating system.
GetStargateTime() Returns the current Stargate date and time as a string. Status and Log Functions Public Function ReadSystemStatus() As String This reads the system status from the Stargate and returns the result as a multi-line string.
Public Function ReadMessageLog() As String This reads the message log from the Stargate and returns the result as a multi-line string.
Public Function ClearMessageLog() As String This erases the contents of the Stargate message log
Public Function ReadPhoneLog() As String This reads the phone log from the Stargate and returns the result as a multi-line string.
Public Function ClearPhoneLog() As String This erases the contents of the Stargate phone log
[edit] Voice Mail Functions
Stargate supports up to eight voice mailboxes (see the Stargate documentation for further details.) Each of these functions takes the mailbox number as the first argument. For single mailbox configurations, this should always be 1. The function names should be self-documenting. Public Sub PlayFirstMessage(mbx As Integer)
Public Sub PlayNextMessage(mbx As Integer)
Public Sub PlayRepeat(mbx As Integer)
Public Sub PlayStop(mbx As Integer)
Public Sub PlayAllMessages(mbx As Integer)
Public Sub PlayAllNewMessages(mbx As Integer)
Public Sub PlayForward5Sec(mbx As Integer)
Public Sub PlayBack5Sec(mbx As Integer)
Public Sub PlayCallerID(mbx As Integer)
Public Sub PlayDeleteMessage(mbx As Integer)
Public Function GetMessageCount(mbx As Integer, ByRef newMStargates As Integer, ByRef oldMStargates As Integer) As Boolean
Public Function GetMessageCountV(mbx As Integer, ByRef newMStargates As Object, ByRef oldMStargates As Object) As Boolean
This one needs a little explaining. It is the same as PlayGetMessageCount() except that the two ByRef count variables are typed as Objects, for use on ASP pages, in VB scripts, and the like.
Public Function SetVoxThreshold(voxLevel As Integer) as Integer
This allows scriptable setting of the Stargate voicemail VOX threshold (build 3.08a and above). The function returns the old value of the VOX level. Please note that unlike the control page version of this function, the plug-in does not ‘remember’ VOX levels set through SetVoxThreshold(). Stargate, of course, remembers, but this information is unreadable.
[edit] Schedule functions
Public Sub StartSchedule() Starts the Stargate schedule.
Public Sub HaltSchedule() Halts the Stargate schedule.
SendConnect() This call sends the “Connect<CR>” sequence required when the HomeSeer plug-in is being used as a secondary Stargate interface.
SelectPlaybackDevice SelectPlaybackDevice(iSetting As Integer, Optional bPersist As Boolean) This selects the audio output device for voicemail playback. It is the equivalent of the selection on the control page.
- The iSetting argument selects the device or devices to play back voice mail messages through. It is made up of one or more of the following flags:
- PLAYBACK_SPEAKER = &H1
- PLAYBACK_LINE = &H2
- PLAYBACK_CO = &H4
- PLAYBACK_ICM = &H8
- The bPersist argument tells the function whether or not to save the setting to the registry. If it is False, the setting will be lost when HomeSeer restarts. If it is True, the setting persists. The default is False.
PhoneHangup() Hangs up the Stargate phone line. Takes no arguments. This command has no Control page equivalent.
PhoneDial(strNumber) Dials (sends Touch-Tone) to the Stargate phone line. The strNumber argument is the dial string to send. This command has no Control Page equivalent.
Public Function SendRaw(ByVal Send As String, ByVal AckType As Integer) As String SendRaw allows a script to send a command string directly to the Stargate. See the Stargate protocol specification for string formats. This command has no Control page equivalent.
ThenMacro(intMacro as Integer) This function allows direct access to (execution of) the Stargate/TC Then macros. The intMacro argument is an integer corresponding to the macro ordinal number (1-256, Base 1) to be executed. (Note: the JDS.ini file lists the macros with Base 0 numbering.) Returns TRUE if macro name/number was found, FALSE otherwise. There is no way of determining programmatically whether the macro itself executed successfully.
Version The version method returns a string made up of the plug-in major version number, minor version number, and build number, such as 2.1.90. It takes no arguments. This method has no Control page equivalent.
LastAscii The LastAscii method returns the last ASCII string captured by the plug-in. See the description of the ASCII Capture functionality. This method has no Control page equivalent.
[edit] Email-Aware Functions
Public Function ShortName() As Object Takes no arguments. Returns a string giving the default 'short name' of the module.
Public Function HelpText() As Object Takes no arguments. Returns a string containing the help text for that specific module. This will be rolled into the email message that is returned when Help is requested of the email processor.
Public Function ProcessLine(strLine As Object) As Object Takes one argument consisting of a command/request line as a string. This is the 'guts' of the functionality. This function interprets the command/request, performs the directed actions, and returns the results, if any. Result strings are defined by the specific module implementations. The return string is displayed in the response email generated by the processor. The following commands are supported:
START Starts the Stargate schedule
HALT Halts the Stargate schedule
READ_MESSAGE_LOG Returns the text of the Stargate phone log
CLEAR_MESSAGE_LOG Clears the Stargate phone log
READ_STATUS Returns the Stargate status read-out
READ_PHONE_LOG Returns the text of the Stargate phone log
CLEAR_PHONE_LOG Clears the Stargate phone log
[edit] Polling Stargate Devices
Public Sub PollStargate(iPollMask As Integer) This initiates a ‘read’ of the various StarGate devices, similar to that performed when the plug-in starts up. An optional argument is a device mask, which selects the device types to be read. The mask is made up of one or more of the following values:
- POLL_VARIABLES = &H1
- POLL_FLAGS = &H2
- POLL_DIGITAL = &H4
- POLL_ANALOG = &H8
- POLL_RELAYS = &H10
- POLL_X10 = &H20
- POLL_ALL = &H3F
[edit] Event Functionality
The HomeSeer Stargate plug-in has the ability to create events in HomeSeer and to trigger those events based on events received from Stargate. These events are created automatically in HomeSeer by the plug-in and are stored in the JDS group. Since the plug-in accesses these events by name in order to trigger them, please do not rename them. Also, please note that these are specific events, not event types. Events are linked to actions in the normal way, by opening the event in HomeSeer and associating the appropriate X10, script, voice, or other action with it. Not all events in the ‘JDS’ category are designed to be linked to, so please read the sections on the individual events. Phone Event This is triggered by activity on the Stargate phone board. Whenever activity activity comes in from the phone board, an event called "_PhoneEvent_" is triggered. Two callback functions are then used to get the specific event information from the plug-in, since events don’t pass arguments.
Public Function GetLastPhoneEvent() As Integer This function returns the last phone event received by the Stargate as a numeric value. Since an effort has been made to use the Stargate values themselves as closely as possible, the numbering system is a trifle non-intuitive.
- 112 - Off hook (internal)
- 113 - On hook (internal)
- 210 - No dial tone
- 211 - Dial tone "" ""
- 240 - External phone ring (GetLastPhoneDigit() returns ring number)
- 5xx - Touch tone digit - Intercom (GetLastPhoneDigit() returns digit; 10 = -0, 11 = *, 12 = #)
- 6xx - Touch tone digit - External (GetLastPhoneDigit() returns digit; 10 = -0, 11 = *, 12 = #)
The value 10 is used for the digit ‘0’ deliberately, as the value 0 is often used to represent ‘no value’. (The plug-in uses –1 for that.)
Public Function GetLastPhoneDigit() As Integer For those events that have digits associated with them (i.e. received DTMF), this function returns the last digit received, as described above.
Here’s a very minimal script sample demonstrating this. This script would be attached to the "_PhoneEvent_" event in HomeSeer.
Sub Main()
Dim oPlug
Dim iEvent
Dim iDigit
Set oPlug = hs.plugin("JDS Stargate")
iEvent = oPlug.GetLastPhoneEvent
iDigit = oPlug.GetLastPhoneDigit
hs.WriteLog("PHONE_SCRIPT", "Phone event " & iEvent & " digit " & iDigit)
End Sub
