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

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 ?-encrypt? ?-keep? ?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, unless the -keep option was specified. 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.

The -encrypt option encrypts the value of the variable before it is stored in the resource file. Of course this does not provide a very secure method of storing secret information, but it does prevent passers-by reading sensitive information off your screen.
[The -encrypt option was introduced in HomeVisionXL 2.0b14]

The -keep option allows configuration variables to be set to the empty string.
[The -keep option was introduced in HomeVisionXL 2.0b18]

hvConfigFile subcommand ?args?

Plug-ins that need to store some data in a file can use this command to simply manage these configuration files. The command will make sure the data is stored in a directory appropriate for the current platform.

The following subcommands are available:

path

Returns the configuration path: a list of directories to be searched when accessing configuration files.

open name ?access?

The command will look for a file with the specified name in all the relevant directories. If found, the file will be opened and the file handle is returned to the caller. An error occurs if the file cannot be found.

create name ?access? ?permissions?

The command will create a file with the specified name in the first directory of the configuration path where the user has sufficient permissions for creating files. The handle to the opened file is returned to the caller. An error occurs if the file cannot be opened in any of the directories on the configuration path.

rename oldname newname

Rename a configuration file, overwriting the target if it exists. This can be useful when the configuration data is first saved to a temporary file. Only if no errors occur, the actual configuration file is overwritten using this subcommand.

delete name

Delete any existing configuration files with the specified name on the configuration path. No errors occur if no such file exists or if the file can not be deleted.

The name argument may contain a single file name or a relative path to a file. The access argument indicates the way in which the file is to be accessed. This may be specified as (r|w|a)[+][b] or a list containing one or more of RDONLY, WRONLY, RDWR, APPEND, BINARY, CREAT, EXCL, NONBLOCK, and TRUNC. The permissions argument specifies the permission settings for the created file.
[The hvConfigFile command was introduced in HomeVisionXL 2.0b9]

hvConstant ?-index? ?category? ?name? ?value?

Obtain or modify a named constant. When executed without any arguments, the command will return a list of named constant categories.

When only a category is specified, a list of named constants within that category is returned. If no category by that name exists, the command produces an error.

When both a category and a name are specified, the value of the named constant within the specified category is returned. If either the category or the named constant doesn't exist an error is returned.

If a category, a name, and a value is specified, the value of the named constant is updated. If the category and/or the named constant does not exist, it will be created. If the maximum number of categories or named constants has already been reached, the command returns an error.

If the -index option is specified, instead of returning a constant or category by name its internal identification is returned. This may be useful for creating action code. When the -index option is used, the value argument must not be present.
[The hvConstant command was introduced in HomeVisionXL 2.0b11]
[The -index option was introduced in HomeVisionXL 2.2]

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.
disconnect	The application has disconnected from the HomeVision controller.
open	A schedule file was opened.
new	A new empty schedule file was created.
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 consisting 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.
download	The current schedule is about to be downloaded into the HomeVision controller.
loaded	The schedule has been downloaded into the HomeVision controller.
remdownload	The current schedule is about to be downloaded into the HomeVision controller by a remote internet HomeVisionXL application (Introduced in HomeVisionXL 2.0b18).
remloaded	The schedule has been downloaded into the HomeVision controller by a remote internet HomeVisionXL application (Introduced in HomeVisionXL 2.0b18).
loadprogress	This event fires periodically during a schedule download. The command bound to this event will be called with an extra argument indicating the percentage of the download that has completed. (Introduced in HomeVisionXL 2.1)
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.
lightupdate	An automatic custom lighting update report was received.
hvacupdate	An automatic HVAC system update report was received.
securityupdate	An automatic security zone update report was received.
systrayhide	The main application has withdrawn to the system tray.
systrayshow	The main application has been restored from the system tray.
exit	The application is about to exit.

hvExecTrigger ?string?

Submit a string to the trigger parsing code, causing any matching triggers to be executed.
[The hvExecTrigger command was introduced in HomeVisionXL 0.80]

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.
[The hvHelp command was introduced in HomeVisionXL 0.80]

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 image files. Only a limited set of HTML tags is supported and the only image formats that can be displayed are GIF and PNG.

hvInfraredData signalNum ?data?

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

hvImport ?-name name? procedure

Import a public procedure from another plug-in. Calling the procedure will actually run the procedure in each plug-in that published it. As a result the return value from invoking the command is a list with the return values from the procedure in each of the plug-ins that published it.
Using the -name option the command can be given a name in the importing plug-in that differs from the published name. This may be necessary to resolve a clash with an existing command in the plug-in. It also opens up the possibility to put the imported command in a namespace.
[The hvImport command was introduced in HomeVisionXL 0.58]
[The -name option was introduced in HomeVisionXL 2.2]

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.

hvLogMessage message

Log the specified message to the HomeVisionXL log file.
[The hvLogMessage command was introduced in HomeVisionXL 2.0b14]

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.
[The hvMainMenu command was introduced in HomeVisionXL 1.14]

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 or the system tray menu. Valid menu names are initially: Main, File, Configure, Objects, Control, Other, Advanced, Help and Tray. When creating cascade menu entries, children of these menus can be added.
[The Tray menu was introduced in HomeVisionXL 2.2]

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.

hvObjectLabel objectType objectNum state ?label?

Returns or sets the label for the input or output port state.

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? ?event?

Returns or sets the last known state of the object specified by objectType and objectNum. If the event argument is true, other plug-ins will be informed of the change by running the eventhook those plugins registered for the relevant object update event.
[The event argument was introduced in HomeVisionXL 2.3]

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 without bothering the user.

hvPlayWavFile fileName

Play the WAV file using the WAV play command configured on the HomeVisionXL PC software preferences screen.
[The hvPlayWavFile command was introduced in HomeVisionXL 1.10]

hvPrint text

Print text using the Print command configured on the HomeVisionXL PC software preferences screen.
[The hvPrint command was introduced in HomeVisionXL 1.10]

hvPublic ?-origin? name ?command prefix ...?

Allow other plug-ins to invoke code in the current plug-in. The calling plug-in would import the specified name using the hvImport command.

If present, the command prefix specifies the command name and zero or more initial arguments of the command to run in the current plug-in when the calling plug-in invokes the imported command name. If absent, the published name will also be used as the command prefix in the current plug-in.

When the -origin option is specified, the name of the calling plug-in will be appended to command prefix before any arguments specified by the calling plug-in when calling the imported command name.
[The -origin option was introduced in HomeVisionXL 2.0b13]

The command returns the names of all plug-ins that have imported the procedure.
[The hvPublic command was introduced in HomeVisionXL 0.58]

hvQuit ?delay?

Terminate the plug-in. A delay may be specified during which time the plug-in will not be terminated, not even if the HomeVisionXL application itself is shutting down. The delay parameter is measured in milliseconds.

The delay parameter is normally only used in the exit event hook code. It allows the plug-in to perform its clean up actions. This command may be reissued later to correct the delay in case the cleanup takes less or more time than expected.

If the command is used to terminate the plug-in before the exit event has been received, the plug-in will be disabled.
[The hvQuit command was introduced in HomeVisionXL 2.0b8]

hvScheduleData

Similar to hvConfig, except the data becomes part of the currently opened schedule instead of being stored in the HomeVisionXL resource file.
[The hvScheduleData command was introduced in HomeVisionXL 2.1]

hvScheduleName

Returns the filename of the current schedule file.

hvSendCommand command ?timeout? ?repeat?

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. The maximum number of attempts to send the command and get a response may be specified using the repeat argument. HvXL will perform up to 2 attempts by default.
[The repeat argument was introduced in HomeVisionXL 2.3]

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 half 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.

description

A (short) description for the serial port. This string is displayed in all serial port commands and can be used as a reminder of the function of the serial port.
[The description setting was introduced in HomeVisionXL 2.1]

hvServer serverType subcommand ?arg?

Configure the remote internet server settings. The existing server types are: telnet and inet. If a subcommand has an optional newValue argument and the argument is present, the setting is updated. Otherwise the command returns the current setting. Allowed subcommands are:

address ?newValue?

If the computer has multiple network interfaces, you can select on which network interface the server will be listening for incoming connection requests. The empty string will bind the server to all available network interfaces. You can confine the server to all IPv4 interfaces only by specifying 0.0.0.0, or all IPv6 interfaces by specifying ::.

clients

Returns a list of the currently connected clients in the format IP-address:port.

kill client

Disconnect the specified client.

password ?newValue?

If you want to require the client to provide a password when accessing the server, enter the password here. If you don't want to require a password, leave this field blank.

port ?newValue?

You must tell the software which port number you want it to use on your computer. It defaults to using port 1034 for the Telnet Server and 1043 for the Homevision Server.

start

Start or restart the specified server. This command returns an empty string if the server started successfully, or an error message when it failed.

state ?newValue?

Interrogate or modify the state setting for the specified server. The state setting controls whether an attempt will be made to start the server on startup of HomeVisionXL.

stop ?kill?

Shut down the specified server. No new connections will be accepted after running this command until the server is started again. Existing connections will not be torn down, unless the kill argument is specified and has a logical true value (true, 1, on, yes, etc).

[The hvServer command was introduced in HomeVisionXL 2.1]

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 received from the HomeVision controller. The string is case insensitive.

When the string appears in the serial output from the Homevision controller, the script is invoked with one additional argument. This argument is a string containing all characters received from the HomeVision controller starting at the trigger string. The script must return a value indicating the result of processing the string:

• If the trigger has been processed successfully, the script must return the total number of characters that were consumed from the input string in order to process the trigger.
• If more data is needed to properly process the trigger, the script should return 0. In that case the script will be called again when more serial data is available.
• If the script cannot correctly parse the string and it can determine that appending more data to the string will never lead to anything valid either, it should return -1.

[Negative return values are supported since HomeVisionXL 2.1]

hvTriggerMessage message

Problems encountered while processing a trigger string can be reported to the application using this command. The messages will be displayed on the Serial Command Test screen.
[The hvTriggerMessage command was introduced in HomeVisionXL 2.0b1]

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
DST	0 (no), 1 (US), 2 (EU)
WavePlayCommand
WaveFilePath
WriteToFilePath
LogDirectory
PrintCommand
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
ResourceFile	Read-only
I2CSlaveDict	Read-only (2.0b17)
ImagePath	Read-only (2.0b18)

Additionally all other properties from the General section of the HomeVisionXL resource file may be interrogated. These properties can not be modified. Some of the more useful ones for plug-ins are:

Device	Read-only
BaudRate	Read-only
HomeVisionPro	Read-only
PaperSize	Read-only
ToolTips	Read-only

hvVersion

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