HomeVisionXL Plugins

The plug-in file is interpreted as a Tcl script and may contain all standard Tcl commands as well as some special HomeVision commands described below. Global level commands will be executed to initialize the plug-in. A plug-in will typically setup and arm event handlers that will be invoked when a certain event occurs. This can be an external event (eg: data has been received on a socket that was opened by the plug-in), a HomeVision event (eg: a special string was sent by the HomeVision controller), or a user event (eg: the user selects a menu entry created by the plug-in).

The author of a plug-in should make sure that both the plug-in initialization code and the event handlers return control back to the main program within a reasonable time. Otherwise the plug-in will cause the application to "freeze".

A number of example plug-ins can be found on the download page. In addition to providing useful functionality, these plug-ins can also be used to learn how to use the commands described below.

Object types

analog	Analog input port
flag	Flag
input	Input port
ir	Infrared signal
light	Custom Light
macro	Macro
output	Output port
pe	Periodic event
se	Scheduled event
temp	Digital temperature sensor
timer	Timer
var	Variable
x10	X-10 module
zone	IR Transmit zone
hvac	Thermostat
security	Security zone

HomeVisionXL plug-in command summary

hvAddObject objectType

Add a new object of the specified type. Valid object types are: flag, ir, light, macro, pe, se, timer and var.

hvConfig ?variable ?value??

Returns or sets a plug-in configuration variable. These variables will be saved in the homevisionrc file on exit of the application. This way user settings can be preserved between sessions. Variable names can be chosen freely.
If both arguments are specified, the configuration variable is set to the specified value. If value is an empty string then the configuration variable is destroyed. If only a variable name is specified, the current value of the configuration variable is returned. If no arguments are specified, a list of all currently existing configuration variables and their values is returned.

hvDelObject objectType

Delete an object of the specified type. Valid object types are: flag, ir, light, macro, pe, se, timer and var.

hvDownLoad

Loads the currently opened schedule into the HomeVision controller.

hvEventHook event ?script?

Define a script that will be executed when the specified event occurs. If script is an empty string then the current binding for the event is destroyed. If event is specified without a script, then the script currently bound to the event is returned, or an empty string is returned if there is no binding for the event. Valid events are:

ready	The main application has finished initializing and is ready for user interaction.
connect	The application has connected to the HomeVision controller.
open	A schedule file was opened.
download	The current schedule is about to be downloaded into the HomeVision controller.
loaded	The schedule has been downloaded into the HomeVision controller.
statusupdate	An automatic status update report was received.
x10update	An automatic x10 update or x10 house code update report was received.
flagupdate	An automatic flag update report was received.
varupdate	An automatic flag update report was received.
inputupdate	An automatic input port update report was received.
outputupdate	An automatic output port update report was received.
analogupdate	An automatic analog input port update report was received.
digitaltempupdate	An automatic digital temperature sensor update report was received.
change	The schedule in memory has been changed.
reorder	The user has reordered some objects. The script will be called with an additional parameter: a list consisiting of alternating object type and location map for all affected object types. The location map is a list giving the new location for each object of the indicated type.
exit	The application is about to exit.

hvExit ?options?

Cause the application to terminate. See hvOpenSchedule for the available options.

hvGetLine ?timeOut?

Wait for a line from the HomeVision controller. A timeout in milliseconds can be specified which defaults to 2000.

hvGuiInit

With this command the Tk extension to Tcl is enabled and initialized for use within the plug-in. This allows the use of the Tk GUI widgets in a plug-in for interaction with the user. The "." window is created in a withdrawn state.

hvHelp topic

Show the specified Help topic in the Help viewer.

hvHelpFile helpfile

Add the HTML pages in the specified helpfile to the HomeVisionXL help system. The helpfile should be a ZIP file containing one or more files in HTML format and optionally some GIF files. Only a limited set of HTML tags is supported and the only image format that can be displayed is GIF.

hvInfraredData signalNum ?data?

Returns or sets the infrared pulse data of the specified infrared signal.

hvImport plug-in procedure

Import a public procedure from another plug-in.

hvLastUpdate objectType ?set?

Returns a clock value for the last time the object type state was updated. If the set argument represents a true boolean value, the last update time is set to the current time. The application automatically sets the last update time for the standard object types, as well as for "status". A plug-in may set and query additional object types.

hvLightConfigure setting ?value?

Using this command the Custom Lighting system configuration can be accessed from within a plug-in. If no value is specified, the current value of the setting is returned. Otherwise the setting will be changed to the provided value, if it is valid. The available settings are:

method

The custom lighting system control method. Allowed values are:

none	Disable custom lighting
default	Using automatic serial messages
user	Using user created macros and variables

maxlevel

The maximum light level. Possible values are 1 through 255

port

The HomeVision com port to use for communication with the lighting system. This setting is only applicable for the default control method. Allowed values are: 1, 2, 3, 4.

header

The header character to use when sending a serial command to the lighting system. This setting is only applicable for the default control method. The value must be any single char.

macro

The macro to be executed for Custom Lighting commands. This setting is only applicable for the user control method. Possible values are 0 through 254.

idvar

The variable to use for passing the Light number to the macro. This setting is only applicable for the user control method. Possible values are 0 through 254.

addrvar

The variable to use for passing the Light's address to the macro. This setting is only applicable for the user control method. Possible values are 0 through 254.

extravar

The variable to use for passing the Light's extra byte to the macro. This setting is only applicable for the user control method. Possible values are 0 through 254.

cmdvar

The variable to use for passing the Lighting command to the macro. This setting is only applicable for the user control method. Possible values are 0 through 254.

data1var

The variable to use for passing the Lighting command's first data byte to the macro. This setting is only applicable for the user control method. Possible values are 0 through 254.

data2var

The variable to use for passing the Lighting command's second data byte to the macro. This setting is only applicable for the user control method. Possible values are 0 through 254.

ramprates

A list of descriptions of the available ramp rates for the Custom Lighting system.

hvLookupTable command ?arg ... ?

This command provides access to the lookup tables defined in the current schedule. Tables can be referenced by index or by name. Available subcommands are:

add ?name?

Add a new lookup table. If a name is specified the new table name will be set to that value

count

Returns the number of lookup tables defined

delete

Delete the highest numbered lookup table

index table

Returns the index of the specified table

name table

Returns the name of the specified table

value table ?index? ?value? ?index value ...?

Without any index specified, this command returns a list with all 256 entries from the lookup table. If only a single index is specified this command will return the value in the lookup table at the specified index. Otherwise the value for each of the specified indexes is set to the accompanying values.

hvMainMenu menu label ?label ...?

Create a new cascade menu from the HomeVisionXL main menu or return the name of an existing cascade menu. This can be used to easily add entries to the Plugins menu, creating it if necessary.

hvMainStatus text

Will arrange for the text to be displayed in the main window status area when (one of) the MainWindow widget(s) created by this plug-in is being displayed in the main window.

hvMainWindow pathname displayname ?show?

Creates a top level widget as a child of the HomeVision application main window. A "View" menu will appear in the HomeVision application menu bar. This "View" menu will have an entry for the Terminal Emulator and entries for each top level widget created by the hvMainWindow command. This allows the user to choose which information they like to see in the main window. The show argument can be set to 1 to force the new widget to appear when the plug-in is loaded.

hvMenu menu command ?options?

Change the main menu bar of the application. Valid menu names are initially: Main, File, Configure, Objects, Control, Other, Advanced and Help. When creating cascade menu entries, children of these menus can be added.

hvObjectAction objectType objectNum ?type? ?action?

Returns or sets the action for the object specified by objectType and objectNum. With the type argument high/on or low/off can be used to select the desired action for object types that can have two actions attached. Valid object types are: input, ir, macro, pe, se, timer and x10.

hvObjectCount objectType

Return the number of objects of the sepcified object type.

hvObjectData objectType objectNum ?data?

Returns or sets the low level data of the object specified by objectType and objectNum.

hvObjectDesc objectType objectNum ?description?

Returns or sets the description of the object specified by objectType and objectNum.

hvObjectId objectType objectNum

Returns the object ID of the object specified by objectType and objectNum. Only valid for object types: input, output and x10.

hvObjectLoad objectType objectNum ?loadflag?

Returns or sets the load name flag of the object specified by objectType and objectNum.

hvObjectName objectType objectNum ?name?

Returns or sets the name of the object specified by objectType and objectNum.

hvObjectState objectType objectNum ?state?

Returns or sets the last known state of the object specified by objectType and objectNum.

hvOpenSchedule filename ?option?

Close the current schedule and open the schedule specified by filename. If filename is an empty string, an empty new schedule is created. Possible options are:

-nosave

Don't save any changes to the current schedule.

-save

If there are changes to the current schedule, save them whithout bothering the user.

hvPlayWavFile fileName

Play the WAV file using the WAV play command configured on the HomeVisionXL PC software preferences screen.

hvPrint text

Print text using the Print command configured on the HomeVisionXL PC software preferences screen.

hvPublic procedure

Make a procedure in the plug-in public for other plug-ins to use.

hvScheduleName

Returns the filename of the current schedule file.

hvSendCommand command ?timeOut?

Send command to the HomeVision controller. The procedure returns any data in the controller's response. A timeout in milliseconds can be specified which defaults to 2000.

hvSerialConfigure port setting ?value?

This commands allows the serial expansion board configuration settings to be accessed from within a plug-in. The port argument selects which of the HomeVision com ports to configure. Possible values are 2, 3, and 4. The available settings are:

state

This setting indicates to the HomeVision controller if this serial expansion board is installed. Possible values are: enabled and disabled.

baudrate

The baud rate to use for the serial connection. Possible values are: 300, 600, 1200, 2400, 4800, 9600, and 19200.

timeout

The timeout to use for the serial port. Possible values are: None, 5ms, 10ms, 25ms, 50ms, 100ms, 200ms, and 400ms.

mode

The communication mode of the serial port. This is either full for a full-duplex connection (RS232 or RS485 4-wire) of hafl for a half-duplex connection (RS485 2-wire). This setting is only valid for serial ports 3 and 4.

binary

Binary data reception setting. Possible values are 0 (or false/no) and 1 (or true/yes). This setting is only valid for serial ports 3 and 4.

version

The hardware version of the serial expansion board. Possible values are 1 and 2.

hvStateString objectType objectNum

Returns a string describing the last known state of the object specified by objectType and objectNum.

hvSunRise ?date?

Returns the sunrise time as minutes past midnight for the specified date. If no date is specified, todays sunrise time will be returned. The sunrise time is calculated based on the configured user location settings. Date may be specified in several formats. Example: "3/23", "mar 23", "23 march", "tomorrow", "last week", "20070323", etc.

hvSunSet ?date?

Returns the sunset time as minutes past midnight for the specified date. If no date is specified, todays sunset time will be returned. The sunset time is calculated based on the configured user location settings. Date may be specified in several formats. Example: "23 mar", "March 23", "+3 weeks", "3 days ago", or even "stardate 61224.7".

hvTrigger string ?script?

Specify a script to be executed when a defined string is recieved from the HomeVision controller. The script is called with one additional argument. This argument will contain all characters received from the HomeVision controller starting at the trigger string. The script must return the number of characters processed by the script.

hvVariable variable ?value?

Returns or sets a .haf schedule variable. Valid variables are:

TempScale	0=Fahrenheit -1=Celsius
Latitude	-179.9 - 180.0
Longitude	-179.9 - 180.0
TimeZone	-12 - 12
WavPlayCommand
WavFilePath
PrintCommand
Device	Read-only
BaudRate	Read-only
HVDateTime	Read-only
HVVersion	Read-only
HVCheckSum	Read-only
HVTW523Stat	Read-only
HVRunning	Read-only
HVSelfTest	Read-only
HVError	Read-only
HVFileDateTime	Read-only
HVFileName	Read-only

hvVersion

The hvVersion command returns the current version of the main HomeVision software. This information can be used to check that the main program has all the capabilities needed for the plug-in to function.