HomeVisionXL Web Server Plugin

The Web Server plug-in provides the same functionality as the Web Server of the Windows HomeVision software with several additions: After installing and enabling the Web Server plug-in, full documentation of the features and operation of the Web Server will be available in the HomeVisionXL help system. The Web Server help pages can be accessed from the Help menu, or by pressing F1 on the Web Server configuration screen. You can browse through all the help pages for the Web Server using the << and >> buttons on the help viewer toolbar.

Basic operation

The Web Server responds to incoming requests from web browsers. Such a request specifies a Universal Resource Identifier (URI) and possibly some additional post data generated from a HTML form. A URI consists of a number of distinctive parts:
  1. The naming scheme of the mechanism used to access the resource.
  2. The name of the machine hosting the resource.
  3. The port number handling access to the resource (optional).
  4. The name of the resource itself, given as a path.
  5. A query string containing additional data to be forwarded to the resource (optional).
  6. The fragment identifier, specifying a location within the resource (optional).
An example of a URI containing all the parts is:

The different parts of this URI are:

  1. http
  2. localhost
  3. 11080
  4. index.cgi
  5. device=HomeVision
  6. location
The other characters in the URI are needed to be able to unambiguously distinguish the different parts.

The Web Server plug-in is only able to handle URIs for the HTTP and HTTPS mechanisms. The hostname has to refer to the machine the Web Server is running on. The port number can be configured on the Web Server configuration dialog.

In addition to the standard tags that may be present in a HTML document, the Web Server plug-in will scan the document for special HV tags and substitute the appropriate text. For details, see the help pages for the web browser.

Dynamically generated resources

The plug-in recognizes a few file extensions that indicate the type of resource:
.html and .htm
These are the usual HTML formatted files.
These are WML formatted files intended for WAP phones.
Plain text without embedded formatting information.
Cascading style sheet definitions.
.gif, .jpg, .jpeg, .png, .svg, .ico and .wbmp
Different image formats.
.js and .wmls
scripts to be sent back and executed by the browser.
In addition, the Web Server plug-in can run executable (a.k.a. CGI) programs or scripts that generate a page as output of the script. For Windows, files with extensions .bat, .exe, .tcl and .pl will be executed. For Linux type systems, any file not in the list above will be checked to determine if it is executable and, if it is, will be executed. The standard output and standard error of the executing file are returned to the web browser that initiated the request.

The executable generating the dynamic web pages may be written in a programming- or scripting language available on the machine that runs the Web Server. Examples: Batch files, sh script, tcl script, perl script, compiled C program, etc. The output of the program must start with one or more lines that complete the response header. In its simplest form this is just an empty line indicating the end of the response header. All other lines of the response header must contain an identifier, a colon and a value. Anything else will result in an error.

Any CGI program running longer than 5 minutes is assumed to be stuck in a loop and will be killed.

Dynamic content can also be generated via the <HV:Run> and <HV:Image> tags.

Real-Time Updates via Websockets

Traditional communication between a browser and a web server uses a request/response method. The browser makes a request, and the server responds to it. This method does not lend itself to server initiated updates. The HTML5 specification contains the concept of a websocket. Essentially, a websocket provides a two-way channel between a browser and a web server, allowing data to flow between the two at any time. The HomeVisionXL Web Server supports websockets.

For real-time updates to work, the following is required:

  1. The browser must support websockets.
  2. The browser must have JavaScript turned on.
  3. A method to provide automatic status updates from the HomeVision Controller for each object type. For most objects, this could be simply turning on "automatic reporting".

Browser Support for Websockets

As of the time version 7.0 of the Web Server plug-in was released, Firefox 9.x (PC and mobile versions) supports websockets and gradient buttons (as used for page, menu and action buttons).

Websocket Enabled Built-in Web Pages

For those browsers that also have support for websockets, the built-in web pages now use websockets to provide real-time updates of object status, without having to reload or click on the "Update" button.

Smartphone Support

A set of web files is available that make use of websockets to provide a set of real-time web pages suitable for a smartphone. These pages provide similar data as the normal PC-based built-in web pages but are formatted more for smartphones and tablets and make full use of the two-way websocket channel. When used with browsers that have websocket support, websockets provide a way for the server and the browser to pass data back and forth without having to reload the web page. This allows for an interaction with the HomeVision Controller that is more like a real-time application instead of a web browser session.

Real-time updates can be available for the following object types: X-10, Custom Lights, Flags, Variables, Inputs, Outputs, Analog Inputs, Digital Temperature Sensors, Thermostats (HVAC), and Security.

The Smartphone web files require HomeVisionXL 2.2 and Actions Plug-in version 1.x or later.

Secure Connections via Certificates

The Web Server provides a certificate-based, secure, encrypted connection. This type of connection provides two main benefits: an encrypted connection, and secure identification of users. All communications between the client and server is encrypted, and user names and passwords are not needed. You can set up your system to provide just an encrypted channel, where you still log in (although your password would now be encrypted), or an encrypted channel where you eliminate explicit logging in altogether.

The non-secure user/password (HTTP) and the secure certificates (HTTPS) methods can be used simultaneously.

Each potential user of the HomeVisionXL Web Server needs to be authenticated because you don't want just anyone to be able to control your house. The classic method is to use a username-password pair, but with a secure connection, the use of a client certificate by the browser serves this purpose. While the server identity is not as big a concern in this application, https doesn't support identifying only the client, so the server will need to be identified with a certificate as well.

The Certificate Wizard provides a means to easily generate, sign, and package the certificates needed to set up a secure connection for the Web Server.

Last modified: 12 June 2020, 13:13 CEST