LinuxHV Plugins

The user can define plugins to be incorporated into the HomeVision interface software. The software will search in various places for files with a .hap extension. If a HVPLUGINPATH environment variable exists, the directories specified in there will be searched first. Multiple directories can be specified by separating them with a colon. If the environment variable does not exist, the hvplugin directory in the user's HOME directory is checked. Finaly the plugin subdirectory from the location where the HomeVision software is installed is examined. If a plugin with the same name exists in more than one of the searched directories, only the first instance will be loaded. Plugins are loaded in alphabetical order, independent of the directory they are located in.

The plugin 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 plugin. A plugin 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 plugin), 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 plugin).

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

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

Object types

Many of the plugin commands take an object type as one of the arguments. The following object types exist: Some commands only support a limited set of object types.

HomeVision plugin command summary

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 plugin to function.

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

hvMainWindow pathname displayname ?show?
Creates a toplevel widget as a child of the HomeVision application main window. A "View" menu will appear in the HomeVision apllication menu bar. This "View" menu will have an entry for the Terminal Emulator and entries for each toplevel 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 plugin is loaded.

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 plugin is being displayed in the main window.

hvSendCommand command
Send command to the HomeVision controller. The procedure returns any data in the controller's response.

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

hvScheduleName
Returns the filename of the current schedule file.

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.

hvDownLoad
Loads the currently opened schedule into the HomeVision controller.

hvObjectCount objectType
Return the number of objects of the sepcified object type.

hvObjectName objectType objectNum ?name?
Returns or sets the name 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.

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

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

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

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.

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

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

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 plugin may set and query additional object types.

hvInfraredData signalNum ?data?
Returns or sets the infrared pulse data of the specified infrared signal.

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

hvConfig ?variable ?value??
Returns or sets a plugin 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.

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

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

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:

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.

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.

hvPublic procedure
Make a procedure in the plugin public for other plugins to use.

hvImport plugin procedure
Import a public procedure from another plugin.

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