(fwd) [UKHA_xAP] Revised Draft - X10 Schema

[Stuart Booth]

Any advances on this anybody??



On Tue, 29 Oct 2002 17:12:39 -0500, Gerry Duprey <<a
href="/group/xAP_developer/post?postID=qeuvL0L-CJmusYtLXX6NGAGoj1NY6TIk54FnVAOvrHvIAqoqT_dINoWlWcBmojVLJYiL0ubZm3g">gerry@c...</a>>
wrote:

Howdy All,

Tony and I have been working on a redraft of the X10 schema support.
This
draft is designed to support the more basic functions of X10
controllers. A
second, advanced/optional schema for X10 functions is in the works, but we
need to get this discussed/ratified first.

Please take a look and comment. If you think it's perfect, please say
so
(so we know how folks are). If you have comments/suggestions, lets discuss
them and see how they affect the draft.

Gerry


----

xAP - X10 Schema Specification
V1.0, October 28, 2002

** Overview
--------------
xAP X10 support is designed to control and report changes in X10
hardware. X10 commands. All X10 devices must implement these
portions of the X10 Schema.


** X10 Message Header
-------------------
xAP X10 support is specified with the Class=XAP-X10 specification in
the header. Supports class types are XAP-REQUEST and XAP-EVENT.
XAP-REQUEST are generally acted on by an X10 controller to do
something (like turning a light on) while XAP-EVENTs are generally
sent by an X10 controller to flag a change in state of a device.

Example of a typical XAP X10 header:

xap-header
{
v=11
hop=1
source=homevision
instance=hv1
class=XAP-X10
type=XAP-REQUEST
}

** X10 Device and House Specification
-------------------------------------
X10 command frequently need a target for their action. That target
can come in the form of a specific X10 device to act on or a X10 house
code.

House codes are groupings of devices that can work together. House
codes run from A to P (16 house codes).

X10 Devices consist of a house code and a unit number with no
intervening spaces. Each X10 House code can have 16 device, number
1-16. Examples of valid X10 device specifications are A4, B13, M7.


** X10 XAP-REQUEST Schema
-------------------------------
X10 request messages consist of a mandatory "Command=" name with
a
value from the list of supported actions. In addition, some requests
require or allow a Device= specification to define a list of X10
devices that that command will act on or a House= specification to
indicate the house code that a command will act on. Some commands
support either House= OR Device= (though usually not both at the same
time). Finally, commands that support an optional repeat count (like
DIM and BRIGHT) can include a Count= specification.

XAP-REQUESTs with invalid/unknown commands or commands with invalid
Device, House or Level parameters are ignored.

Device= specifications always contain one or more devices. If there
is more than one device, they are seperated from the previous device
with a comma and no intervening space. An example Device=
specification might be Device=A1,A4,B4,E10

House= specifications always contain one or more house code letters.
If there is more than one house code, they are seperated from the
previous house code with a comma and no intervening spaces. An
example House= specification might be House=A,F,G

Count= specification include exactly one numeric parameter. Each
command that supports Count= will provide the range of valid values it
supports via Count. Commands that do not use/need Count= should, like
any other unknown/used name/value pair, ignore them.


** X10 XAP-REQUEST Command listing
------------------------------

SELECT - Select the device(s) for future actions

Requires: Device=
Optional: None
Note: You do not need to use SELECT in most cases. Most of the
time, simply issue the command you need with the appropriate
Device= that should be affected. SELECT is used most often
when you need to execute a command on several devices in the
same house code at once (i.e. select devices A1, A4, A6, A7
and then issue a ON command for house code A). When affecting
multiple devices in the same house code, SELECT followed by a
house code oriented command will usually execute faster (less
X10 traffice needed).

ON - Turn the specified device(s) on

Requires: Device= OR House= (but not both)
Optional: None
Notes: House= will cause all currently selected devices in that
house code to be turned on

OFF - Turn the specified device(s)

Requires: Device= OR House= (but not both)
Optional: None
Notes: House= will cause all currently selected devices in that
house code to be turned off

DIM - Dim the specified devices (Device=) or selected devices in a
house code (House=) one or more steps. DIMming always refers
to traditional X10 dimming (16 steps).

Requires: Device= OR House= (but not both)
Optional: Count= (if omitted, a default of Count=1 is assumed)
Notes: Count= has a valid range of 1 to 16. Using House= will cause
all currently selected devices in that house code to be
dimmed

BRIGHT - Brighten the specified devices (Device=) or selected devices
in a house code (House=) one or more steps. BRIGHTening
always refers to traditional X10 brightening (16 steps).

Requires: Device= OR House= (but not both)
Optional: Count= (if omitted, a default of Count=1 is assumed)
Notes: Count= has a valid range of 1 to 16. Using House= will cause
all currently selected devices in that house code to be
brightened

ALL_LIGHTS_ON - Turn all devices that consider themselves light
control devices in the specified house code(s) on

Requires: House=
Optional: None
Notes: None

ALL_LIGHTS_OFF - Turn all devices that consider themselves light
control devices in the specified house code(s) off.


Requires: House=
Optional: None
Notes: Not too many X10 devices support ALL_LIGHTS_OFF

ALL_UNITS_OFF - Turn all devices in the specified house code(s) off.

Requires: House=
Optional: None
Notes: None

STATUS - Request status for the specified device(s)

Requires: Device= OR House=
Optional: You can use the keyword ALL for Device or House
Note: The ALL keyword (Device=ALL or House=ALL) is special and
exceptional here to allow a client to figure out the current
standings of all devices currently managed. You can still use
device specifications (i.e. E13) or house codes (i.e. D) for
the Device= and House= specifications.



** X10 XAP-REQUEST Examples
---------------------------------
Note: except for the first example, only the body portion of the X10
request is included in these examples (for brevity)

Example 1: Turn on several devices

xap-header
{
v=11
hop=1
source=homevision
instance=hv1
class=XAP-X10
type=XAP-REQUEST
}

XAP-X10.XAP-REQUEST
{
Command=ON
Device=A1,A2,A7,B3
}

Example 1a: Turn on several devices in the same house code

<xap x10 header>

XAP-X10.XAP-REQUEST
{
Command=SELECT
Device=A1,A2,A7
}

- second message -

<xap x10 header>

XAP-X10.XAP-REQUEST
{
Command=ON
House=A
}

Example 2: Dim a lamp

<xap x10 header>

XAP-X10.XAP-REQUEST
{
Command=DIM
Device=A3
}

Example 2a: Dim a lamp multiple steps at once

<xap x10 header>

XAP-X10.XAP-REQUEST
{
Command=DIM
Device=D4,E1
Count=4
}

Example 3: Turn all lights on in several house codes

<xap x10 header>

XAP-X10.XAP-REQUEST
{
Command=ALL_LIGHTS_ON
House=B,M
}

** X10 XAP-EVENT Schema
-----------------------------
An xAP complying X10 controller will send notices out whenever the
state of a controlled device changes. Further, events may be
solicited from the X10 controller with certain requests
(i.e. Command=STATUS).

All events are encoded with the device specification that was affected
as well as the type of change to the device. Events should be sent
only when the state of a device changes, but clients should be able
accept events that do not report an actual change to the clients idea
of the state of the device (i.e. client things A4 is currently ON and
then receives an event saying A4 is ON (redundant) - the client should
be able to process (and possibly ignore it) without error).

Certain events may cause multiple events to be sent out. For example,
if a request is made for ALL_UNITS_OFF for house code A and at the
time of the request, devices A4 and A10 are on, you will receive an
event saying that an ALL_UNITS_OFF was generated and receive an event
that A4 is now OFF and A10 is now OFF. You may consider those last
two events to be redundant (since a ALL_UNITS_OFF on house code A
should imply A4 and A10 are now off), but clients need to have as much
state transition information as possible.

Each event describes changes to a single device or house code. You
will never receive an event that has a comma delimited list of devices
or house codes - instead you'd receive multiple messages.

Events consist of a mandatory Event= followed by a listed event type.
Some events may include a Device= specification or a House=
specification (each event described below returns at most one of those
two - never both and it's never variable (i.e. the same event will
always use a Device= OR always use a House=)


** X10 Event Listing
------------------------------

ON - Device is ON

Requires: Device= specifies the device that is now ON
Optional: Level= (0-100 for controllers that can support it)
Notes: NONE

OFF - Device is OFF

Requires: Device= specifies the device that is now OFF
Optional: NONE
Notes: NONE

DIM - Device has been DIMmed one step

Requires: Device= specifies the devices that was dimmed
Optional: Level= (0-100 for controllers that can support it)
Notes: Most controllers cannot see a series of DIM commands
correctly and if a string of them is sent out, they
will often only report every other DIM command.

BRIGHT - Device has been BRIGHTend one step

Requires: Device= specifies the devices that was brightened
Optional: Level= (0-100 for controllers that can support it)
Notes: Most controllers cannot see a series of BRIGHT commands
correctly and if a string of them is sent out, they
will often only report every other BRIGHT command.

ALL_LIGHTS_ON - house has had all light type devices turned on

Requires: House= specifies the house code that had lights turned on
Optional: NONE
Notes: This will often be accompanied with a number of ON
events as well

ALL_LIGHTS_OFF - house has all light type devices turned off

Requires: House= specifies the house code that had lights turned off
Optional: NONE
Notes: This will often be accompanied with a number of OFF
events as well. Most existing X10 light controllers
do not respond to this command and may not in fact be
off after it received.

ALL_UNITS_OFF - house has all devices turned off

Requires: House= specifies the house code where units turned off
Optional: NONE
Notes: This will often be accompanies with a number of OFF
events as well.

** X10 XAP-EVENT examples
---------------------------------
Note: except for the first example, only the body portion of the X10
event is included in these examples (for brevity)


Example 1: Receive notification that a device is now on

xap-header
{
v=11
hop=1
source=homevision
instance=hv1
class=XAP-X10
type=XAP-EVENT
}

XAP-X10.XAP-EVENT
{
Event=ON
Device=A1
}


Example 2: All Units Off processed

<xap x10 header>

XAP-X10.XAP-EVENT
{
Event=ALL_UNITS_OFF
House=B
}

----

<xap x10 header>

XAP-X10.XAP-EVENT
{
Event=OFF
Device=B3
}

----

<xap x10 header>

XAP-X10.XAP-EVENT
{
Event=OFF
Device=B12
}


--
Gerry Duprey
Ann Arbor, MI 48103
<a href="http://www.cdp1802.org";>http://www.cdp1802.org</a>


--
Stuart Booth <<a
href="/group/xAP_developer/post?postID=R5eWMNXVaYPrTkzp-DJFaKzgICzlifoRZSpte7QJoThF5sJhVfzPtN5ums7HoZtS_IgWv-izgGQMb2zNOg">stuart@x...</a>>
xAPFramework.net - a xAP software development framework for .net

<a href="http://www.xapautomation.org/";>http://www.xapautomation.org/</a>
<a href="http://www.xapframework.net/";>http://www.xapframework.net/</a>