Contents |
The xPLHal Control Protocol (xHCP)
Version 1.5a, 11th May 2007
This document is the official XHCP 1.5 specification. Any application which seeks to be XHCP 1.5 compliant must adhere to the guidelines, syntax and semantics specified in this document. Distribution of this document is unlimited.
This document is Copyright (C) 2003-2007 by John Bent, Tony Tofts & Ian Jeffery. Distribution of this document is unlimited.
A complete archive of all revisions of XHCP is available at the following Web page: http://www.xpl.myby.co.uk/info/xhcp/archive/
Introduction
This document describes the operation of the xplHal Control Protocol (XHCP), which provides a mechanism for applications to communicate with, and control, the xPLHal Home Automation Server. The protocol is client-server, and consists of ASCII text messages being transmitted between a TCP client, and the xplHal server.
Requests from the client to the server are in the form of a command-word, followed by optional parameters, and terminating in a CrLf pair (ASCII characters 13 and 10 decimal, respectively).
Responses from the server take the form of a three-digit response code, followed by a textual representation of the response, and ending with a CrLf pair. Note that server implementations may simply send the letters OK as the textual portion of the response, therefore application developers should always use the three-digit response code to determine the outcome of a command, and never rely on the content of the textual portion unless specifically indicated to do so by this specification.
In situations where multiple lines of text are to be sent, either by the client or the server, the end of the transmission will be indicated by a single period (.) on a line of it's own. If the body of the multi-line text contains a period on a line of it's own, it should be doubled to avoid being incorrectly interpreted as an end-of-transmission.
When the server is returning a list of items to the client, developers are free to return items in any order they wish, unless the specification for a particular command indicates otherwise.
When examples are given in this document, messages that are sent by the client will be prefixed with C:, and responses from the server will be prefixed with S:.
Response Codes
The first digit of the response code can be used to broadly indicate the type of response, as follows: 1xx : An informational response, e.g. for help text etc. 2xx : A successful response. 3xx : An operation is in progress, and the client must send further data to complete the operation. 4xx : An operation has failed. 5xx : An error has occurred. 6xx : Replication-specific codes. Only valid for connections in REPL mode. 9xx : A debug response - these should be ignored by applications and are for use only by the development team.
Establishing a Connection
To establish a connection to the xPLHal server, a client makes a connection to TCP port 3865. Upon connection, the server will issue a 200 success response, such as the following:
200 XPL-XPLHAL.SERVER1 Version 1.0.3.1 XHCP 1.5 ready
The 200 response contains the following elements: - The xPL name for the server (in vendor-device.instance format) - The word "Version" followed by the version of the server (as defined by the author of the server) - The word "XHCP" followed by the version of XHCP to which the server conforms - Any additional text defined by the author of the server
What's New in V1.5
The following commands have been added to XHCP between v1.2 and v1.5:
LISTRULEGROUPS
The following commands are deprecated in V1.5:
ADDX10DEVICE
DELX10DEVICE
GETSOURCE
GETSUB
GETX10DEVICE
LISTX10STATES
RUNSCRIPT (replaced by RUNSUB)
Note that the 200 welcome banner now has a defined format, which all server implementations must adopt.
A complete archive of all revisions of XHCP is available at the following Web page: http://www.xpl.myby.co.uk/info/xhcp/archive/
Note that the official version of XHCP prior to v1.5 was v1.2. Versions 1.3 and 1.4 of this document were for internal use within the development community and were never published as official documents.