(fwd) [xapautomation] Re: X10 Schema(s) - Gerry''s, with xAP 1.2 amendments...

[Stuart Booth]

On Tue, 10 Dec 2002 14:29:53 -0000, "Patrick Lidstone
<<a
href="/group/xAP_developer/post?postID=gV0e0H4RzICIQ0mUSqu41omLOjW4Zp3T54uue5uUTLfs6vIC9mzK6NVhcIfOVcJW84WbarDme0f3EziH0rYt">patrick@l...</a>>"
<<a
href="/group/xAP_developer/post?postID=gV0e0H4RzICIQ0mUSqu41omLOjW4Zp3T54uue5uUTLfs6vIC9mzK6NVhcIfOVcJW84WbarDme0f3EziH0rYt">patrick@l...</a>>
wrote:

Thanks Mark.
A couple of quick comments:

1. I think it's useful to include numeric codes in addition to text
codes.

e.g.

XAP-X10.event
{
EvDesc=OFF
EvCode=3
Device=B3
}

2. In the same vein, should the desciption be more human readable
(e.g. All lights off cf. ALL_LIGHTSOFF)

3. Is there a case for inclusion of the raw X10 commands (or is this
something that is too CM12U specific) e.g. Raw=8664 is dim A to 16/22
units.

4. Dimming/Bright-ing - should we allow dim level to be optionally
specified as %age.

5. Is provision for aliasing device names out of scope? If not, it
would be nice to be able to address the device by name...

Patrick

--- In <a
href="/group/xAP_developer/post?postID=QnJP6bEQQGdLezQjOuriyJXLaC9_m188SailWZqU8GH3j6WEQuikb1qyt8BmGr-8BxnIeXn7OEcNEukyLJ-CaOiaQe4">xapautomation@xxxxxxx</a>,
"Mark Harrison"
<Mark.Harrison@e...> wrote:
>
> xAP - X10 Schema Specification
> V1.1, December 10, 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=12
> hop=1
> uid=FF1234????
> class=XAP-X10.request  XAP-X10.event
> source=*.*
> }
>
> ** 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.
>
>
> ** XAP-X10.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-X10.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.
>
>
> ** XAP-X10.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.
>
>
>
> ** XAP-X10.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=12
> hop=1
> uid=FF12344321
> class=XAP-X10.request
> source=ACME.My.Controller
> }
>
> XAP-X10.request
> {
> Command=ON
> Device=A1,A2,A7,B3
> }
>
> Example 1a: Turn on several devices in the same house code
>
> <xap x10 header>
>
> XAP-X10.request
> {
> Command=SELECT
> Device=A1,A2,A7
> }
>
> - second message -
>
> <xap x10 header>
>
> XAP-X10.request
> {
> Command=ON
> House=A
> }
>
> Example 2: Dim a lamp
>
> <xap x10 header>
>
> XAP-X10.request
> {
> Command=DIM
> Device=A3
> }
>
> Example 2a: Dim a lamp multiple steps at once
>
> <xap x10 header>
>
> XAP-X10.request
> {
> Command=DIM
> Device=D4,E1
> Count=4
> }
>
> Example 3: Turn all lights on in several house codes
>
> <xap x10 header>
>
> XAP-X10.request
> {
> Command=ALL_LIGHTS_ON
> House=B,M
> }
>
> ** XAP-X10.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.
>
> ** XAP-X10.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=12
> hop=1
> uid=FF12344321
> class=XAP-X10.event
> source=ACME.My.Controller
> }
>
> XAP-X10.event
> {
> Event=ON
> Device=A1
> }
>
>
> Example 2: All Units Off processed
>
> <xap x10 header>
>
> XAP-X10.event
> {
> Event=ALL_UNITS_OFF
> House=B
> }
>
> ----
>
> <xap x10 header>
>
> XAP-X10.event
> {
> Event=OFF
> Device=B3
> }
>
> ----
>
> <xap x10 header>
>
> XAP-X10.event
> {
> Event=OFF
> Device=B12
> }



The xAP website: www.xapautomation.org


Your use of Yahoo! Groups is subject to
<a href="http://docs.yahoo.com/info/terms/";>http://docs.yahoo.com/info/terms/</a>


--
Stuart Booth <<a
href="/group/xAP_developer/post?postID=zLHBb1CM0f1U0gnV4IfGtM24i9lgOmHNVYNIFoQsUwVE8pzsWYuP7kgq7Ubys_uAAlCM8AGE_CnAS7lVRQZd">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>