RE: Topic 1: Base Level Status Schema

[Kevin Hawkins]

Ok - I'm going to have a go at reviving this topic so that we can put it to
bed.......these are ideas to provoke a reaction !!

How about.. a status.report message is sent by a xAP device in two
situations, firstly in response to a status.request message that is
targeted
at the device, and (optionally) secondly periodically or unrequested should
the developer wish . The status.report schema contains an 'interface' body
section which is shared also by the status.change schema (used when
something changes) and the status.instruct schema (used to ask a device to
change state).
Within this we have defined a basic body section called 'interface'
that contains information useable by all the schemas. Other body parts can
be added to allow more complex reporting or perhaps optional values added
to
'interface' that can be ignored by simple devices.

So taking the status.request .... If the message is targeted at a
xAP device without any subinstances (ie effectively the devices UID that
ends in '00') then the status of all its I/O is reported in one xAP
message.
If the status request is sent targeted at a particular sub instance then
only that specific I/O should report its status. The ramifications of
supporting only one of these options needs discussing. (Ian I am conscious
of your concerns here)

Examples based on a 1 switch input, 1 relay output, 1 volume knob
xAP device.
Source Address UID

ACME.ExampleDevice.Test FF222200
ACME.ExampleDevice.Test:Switch FF222201
ACME.ExampleDevice.Test:Relay FF222202
ACME.ExampleDevice.Test:Volume FF222203


xap-header <<< A targeted request at the switch input
{
....
class = status.request
...
target = ACME.ExampleDevice.Test:Switch
}
interface <<< Note no content in the body section - see later
{
}


xap-header <<< The response from the Switch input
{
...
UID=FF222201
class=status.reponse
source=ACME.Exampledevice.Test:Switch
}
interface
{
state=ON
level=NA <<< means it does not support a level attribute
}

If the volume control had been targeted it might have returned a body of

interface
{
state=ON
level=30%
}

The body in the status request is actually not needed unless we have a use
for different levels/types of status requests (? anyone think we do ?) -
possibly interfaces.inputs interfaces.outputs interfaces.full
interfaces.short . One possible option is to put the last two digits of the
UID in the body of a status.request message to ask the status of a
particular UID avoiding the need to send a targeted message and allowing
for
devices that don't support targeting..any thoughts ?? ie...

interface
{
UID=01
}

this also has the effect of forcing a device UID to reveal it's
source address (sub ID name) in the response.

I think we need to be able to report a STATE of the following
ON
OFF
UNKNOWN (the device does have a state but it is currently unknown)
NA (the device has no State)
ERROR (no such device - do we need this ??)

And to report a LEVEL of

0% to 100% the need for the % sign is debateable
UNKNOWN
NA
ERROR

The only thing this doesn't address well is centre zero devices like
a balance control on a HiFi where 50% would be centre basically.

So what about the situation of multiple subs reporting their state when
the whole device is addressed - two possible scenarios - multiple bodies or
one body.


xap-header <<< A targeted message at the whole device
{
....
class = status.request
...
target = ACME.ExampleDevice.Test (should this be
ACME.ExampleDevice.Test.>
perhaps)
}
interface
{
}

MULTIPLE BODIES - the first scenario

xap-header <<< The response
{
...
UID=FF222200
class=status.reponse
source=ACME.Exampledevice.Test
}
interface.01 <<< where the indexing relates to the UID
{
state=ON
level=X
name=switch <<< we need to get at the subID name somehow
}
interface.02
{
state=OFF
level=X
name=relay
}
interface.03
{
state=ON
level=30%
name=volume
}

OR alternatively perhaps the three body parts being named

interface.switch
interface.relay
interface.volume and then the UID=value being included in the body
as in

interface.volume
{
State=ON
Level=30%
UID=03
}

or possibly the UID value not reported at
all ???

SINGLE BODY - the second scenario

xap-header <<< The response
{
...
UID=FF222200 <<< note the UID is the '00' one
class=status.reponse
source=ACME.Exampledevice.Test
}
interface <<<
{
switch=ON
relay=OFF
volume=ON
volume=30%
}

The awkward thing here with a single body section is reporting NA
and Unknown for devices and the fact that the same name pair gets used
twice
for state and level. Currently this is allowed in the spec but requests
have
been made to disallow it. Also it is not possible to match UID's to names
easily. Although it seems shorter and more readable it is problematic.
Anyone a workaround for this ??

___________________________________________________________________________

Now .... On the control side of this the 'interface' body section actually
works in reverse to control a device so you can send a message

xap-header <<< A targeted message at the volume control say
{
....
class = status.instruct
...
target = ACME.ExampleDevice.Test:volume

}
interface
{
state=ON <<< this may seem redundant but must be sent to keep
it simple
level=30%
}


I have not put a lot of thought into the section and class / schema
naming here - so I am sure we can come up with some more intuitive names.
What this achieves though is simple consistent control and status
monitoring
of a device, allowing a third party controller or application eg HomeSeer
to
monitor and control a device without prior knowledge of the device. GREAT

One thing still to think about... Should we differentiate inputs and
outputs, so it is evident to HomeSeer say that it can't control an input -
I
think we should - maybe my 'interfaces' body section should actually be two
bodies called 'input' and 'output'.

I am also assuming that a status.change message is sent immediately
an input OR output changes state even if it is the result of a xAP
instruction from another device - it is sort of a confirmation message but
more importantly it allows other devices , particularly controllers to keep
state information simply. I also think this may need to be a single message
relating only to one I/O line , and therefore report a UID - a full status
message covering all I/O sent under the '00' UID would not readily identify
the changed I/O, an indeed there could be several changed states. However
it
has the advantage that coincident changes are probably reported as such
rather than sequentially.


Please comment - we need to get this sorted so that legacy
controllers eg HV, ACE and HomeSeer - plus newer applications like Harmony,
Autom8it and HomeBrain can see a simple way to implement xAP.

Kevin