Call for commentary on new UPB schema

[Gerry Duprey <gerry@xxxxxxxxxxx>]

Howdy Folks,

I've finished my underlying UPB framework and am successfully talking to
and
tracking status of my houses UPB switches.  The next step is layering an
xPL
"skim-coat" to integrate UPB to xPL.

To that end, I'm proposing the following schema for UPB control.  I think
about trying to extend the lighting schema, but I really don't think it's a
fit.

I'd appreciate any thoughts on this.  UPB switches are quite complex
beasties and unlike X10, there is a *lot* in the basic UPB protocol that
all
devices support.

-----

xPL UPB Schema

Overview:

UPB (Universal Powerline Bus) is a competitor to X10 for control of lights
and appliances over a homes existing powerlines.  Unlike X10, UPB includes
checksums to insure that if a message is corrupted, the corruption can be
detected.  In addition, all UPB devices can be told to send an
acknowledgment that they received a command, allowing the controller to
really *know* what state the device is in.  All UPB devices that allow
local
control (i.e. have a switch on them) also can send reports when that switch
(or switches) are used. Most UPB devices can be programmed into up to 16
"scenes" (called links in UPB terminology).  The UPB network
allows upto 250
"links" and a device can be "attached" to any 16 of
them.  The network
allows 250 devices and you can have multiple networks for very large
installations.  Finally, UPB uses a much more powerful signal in a lower
frequency than X10, allowing it to travel further and get
"through" most
obstructions in the powerline.

UPB Devices tend to be rather complex units and are generally configured
from a computer using a tool called UPStart.  This tool lets you assign a
unique device ID, assign links, establish what happens when switches are
pressed, tell it how fast to "fade" up or down to a new level and
often even
the color of the pilot light and how it should change (or not) in order to
reflect the devices state.

While X10 and UPB both seem to share some similarities (they both
communicate over powerlines and are used largely for lighting), it is best
if you do not try to fit every UPB concept into the X10 mold.  You'll
likely
get frustrated and not take full advantage.

In order to talk to a computer, a device called a PIM is needed.  Many UPB
vendors provide them and they come in RS232 serial and USB flavors
(possibly
one that talks directly to am Ethernet network in the future).

This schema provides access to nearly all the UPB command, control and
reporting features while staying relatively simple to use.  At this time,
modification to UPB devices (setting names, assigning and deassigning
links,
etc) is not supported, but a future schema may add them, if it makes sense.


Commands:

upb.basic defines commands that nearly all UPB devices support (some
special
devices, like I/O devices, may not directly support these).

upb.basic

This allows devices and links (or what would be called scenes in other
lighting schemes) to be controlled.  Sending a command that results in the
devices state being changed will generate a trigger message, but a command
that results in no change (turning off a light that is already off) will
not
generate a trigger message in response to the command.

[network=#]
[[device=#][link=#]]
[channel=#]
command=[onoffgotostart-fadestop-fadeactivatedeactivate]
[level=0-100]
[faderate=[snapdefault<time>]

--

network=#
is optional and if not supplied, defaults to the primary network.  Most
of the time, it is not needed.

device=# -or- link=#
A command needs one and only one of these to determine the device or the
link the command will take action on.  Note that not all commands are
applicable to all devices.

Devices and links have identifiers from 1 to 250.

Device 0 is special and is a broadcast device -- ALL UPB devices on the
network will respond to a command to device 0 (great way to shut every
light in the house down).

Link 0 is special in that whatever link command you send will affect the
last directly commanded link.  For example, if you send a specific command
to link 42 and then sent a separate command to link 0 immediately after,
the second command would apply to link 42.  Because it's easy for another
link to "get in" between when you send one command and another,
this is
not recommended as it can result in the "wrong" link be applied
to.

channel=#
is optional and if not supplied, the command applies to all channels of
the device.  Most devices have a single channel (a channel usually being
something that is controlled, like a dimmer or relay).  In devices that
control two or more items, you can direct messages to specific device on a
specific channel.  If channel numbers are supplied, they are in the form
of 1, 2 or 3 (or higher).  Channel 0 is taken as "all channels".

command=[onoffgoto]
UPB devices do not have the concept of on and off, just of being at a
certain level (where level 0 is off).  on is a synonym for goto with
a level of 100.  off is a synonym for goto with a level of 0.

goto requires a level= and can optionally take a faderate=.  on
does not require but can have either level= or faderate= or both.
off accepts neither level= or faderate=.

command=[start_fadestop_fade]
start_fade is very similar to goto.  In fact, I can't see any
difference between them.  It requires a level= and can accept
a faderate=

stop_fade tells the switch to stop dimming at whatever level it's at and
hold that level.  This is mostly used when a switch has been told to
fade/goto a certain level over a longish time (say 10 seconds or 15
minutes).  stop_fade immediately halts further fading and holds the switch
at whatever level it was at when stop_fade was received.  stop_fade does
not need or accept level= or faderate=

command=[activatedeactivate]
These commands apply only to links (the are ignored for devices).  Sending
activate for a link causes all devices that are associated with that link
to assume the state described when the link was setup.  Each device
assigned to a link may be set to go to a different level at different
rate.

Don't confuse activate with goto.  Goto directed at a link will cause all
devices associated with that links ID to "goto" the level you
pass.  You
are basically addressing a 'group' of devices, all of which will have the
same level after the link is done.

Contrast that with activate where each device may have a different level
after the link, based on how the switch was setup to respond to that
link.

deactivate generally tells all items associated with the specified link to
turn off.  This isn't a hard and fast rule -- devices like IO interfaces
and such may respond to this differently -- but for most appliance/light
modules, it means "turn off".  In many ways, deactivate for a
link is
similar to a "goto" to that link with a level=0.  However, as
mentioned, a
device can choose to attach a different meaning to deactivate so it is not
the same as the "goto" "level=0".  Thats uncommon, but
you need to be
aware.

level=[0-100]
For the on/goto/start_fade commands, level= tells what level, between 0%
and 100%, the device should go to.  For non-dimming devices, level is
generally interpreted as 0=off >0=on and 100% is often used in these
cases.

Depending on how the switch and the optional presence of the faderate=
option, the switch may immediately switch to the new level or may slowly
ramp or fade to that level over time.

faderate=[snapdefault<time>]
For the on/goto/start_fade commands, faderate= tells the device how long
it should take to achieve the level= specified.  snap means take effect
immediately -- no ramp or slow fade, just do it instantly.  default tells
the switch to use whatever default fade rate it was programmed with (each
switch can have a "default" fade rate set for it).

time is one of the accepted times, in seconds, for the switches.  Valid
times for dimmers are:

0.8, 1.6, 3.3, 5, 6.6, 10, 20, 30, 60, 120, 300, 600, 900, 1800 or 3600

If a time is specified that does not match one of the above, the nearest
time (up or down) to it is used. At the bottom, anything from 0.4 down is
rounded down to "snap" and 0.5 to 0.8 is 0.8, at the top,
anything over
1 hour (3600) is capped at one hour.

If the value to faderate= is invalid (not a number or snap or default), it
is treated as default


upb.request

This allows a sender to learn about devices, links, room and other items
that make up a UPB network.

[network=#]
[[device=#][link=#][room=name]]
request=[networkinfodeviceinfodevicestatedevicelistlinkinfolinklistroominforoomlist]

--

network=#
is optional and if not supplied, defaults to the primary network.  Most of
the time, it is not needed.

device=#, link=# or room=name
If asking for information on a device, link or room, the appropriate
identifier must be supplied.  When asking for information not related
to these three items, then none of them should appear.  In any
case, either one or or none of these will appear in a message -- never
more than one.

request=
request=networkinfo
Send information back about the specified (or default) network using the
upb.netinfo schema.  If a request for information on an unknown network
is made, the reply will contain only the network= and status=not-found.

request=deviceinfo
sends all that we know about a given device using the upb.devinfo
schema. If a request for information on an unknown device is made,
the reply will contain only the network=, device= and status=not-found.

request=devicestate
send the current state of the device in a upb.device schema message.
If a request for information on an unknown device is made, the reply
will contain only the network=, device= and status=not-found.

NOTE: state is also returned in the deviceinfo request, so this is used
as a "lower-overhead" request, but you could use either.

request=devicelist
send a list of known device #s.  In order to reduce the size of the xPL
message, devices are sent no more than 16 per device= item (for a max of
16 device= items per message) and may have ranges to compress the data
(i.e. 1,2,3,8,9,10 is replaced with 1-3,9-10).  The schema is
upb.devlist.

request=linkinfo
sends all that we know about a given link using the upb.linkinfo schema.
If a request for information on an unknown link is made, the reply will
contain only the network=, link= and status=not-found.

request=linklist
send a list of known link #s.  In order to reduce the size of the
xPL message, links are sent no more than 16 per link= item (for
a max of 16 link= items per message) and may have ranges to compress the
data (i.e. 1,2,3,8,9,10 is replaced with 1-3,9-10).  The schema is
upb.linklist

request=roominfo
send all that we know about a give room using the upb.roominfo schema.
If a request for information on an unknown room is made, the reply will
contain only the network=, room= and status=not-found.

request=roomlist
send a list of known rooms.  Unlike links and devices, there is only
one room name per room= in the message.  Since most houses don't
have too many rooms (7-20), this should be able to fit them.  The schema
is upb.roomlist

Status/Trigger Messages:

Status messages are sent whenever a valid upb.request message is received.

upb.netinfo
network=#
status=[oknot-found]
name=[network name, if known]
password=[network password, if known]
device-count=#
link-count=#
room-count=#

upb.devinfo
network=#
device=#
status=[oknot-found]
name=[device name, if known]
room=[room name, if known]
is-dimmable=[truefalse]
level=[0-100]
manufacturer=id,name
product=id,name
firmware-version=x.y
serial-number=###
channel-count=#
link-count=#
link=linkid,level,faderate
link=linkid,level,faderate
link=linkid,level,faderate
There can be upto 16 link= entries for a device

upb.devlist
network=#
status=[oknot-found]
device=[#,[#,[#,[#...]
device=#-#[#,[#-#...]
There will be at most 16 device= entries per messages.  Each line
describes a block of 16 possible devices.  Not all block will have devices
in them, so ranges and lists of device IDs are allowed.

Remember that there can be "holes" in the device IDs (i.e.  there
may
devices from 1-16, except for 7 which isn't used).

Possible sample entries look like:

device=1-16
device=17-20,30-32
device=33,35,37,39,41,50

Blocks with no known devices in them are omitted.  So you should not
assume order, count or quantity of the device= entries.  Accept the in any
order and  make no assumptions about what range of numbers each entry
contains.


upb.linkinfo
network=#
link=#
status=[oknot-found]
name=[link name, if known]
device-count=#
device=deviceid,level,faderate
device=deviceid,level,faderate
device=deviceid,level,faderate
There can be upto 16 device= entries for a device

upb.linklist
network=#
status=[oknot-found]
link=[#,[#,[#...]
link=[#-#[,#[,#[,#-#...]
There will be at most 16 link= entries per messages.  Each line describes
a block of 16 possible links.  Not all block will have links in them, so
ranges and lists of link IDs are allowed.

Remember that there can be "holes" in the link IDs (i.e.  there
may
links from 1-16, except for 7 which isn't used).

Possible sample entries look like:

link=1-16
link=17-20,30-32
link=33,35,37,39,41,50

Blocks with no known links in them are omitted.  So you should not assume
order, count or quantity of the link= entries.  Accept the in any order and
make no assumptions about what range of numbers each entry contains.

upb.roominfo
network=#
link=#
name=[room name]
status=[oknot-found]
device-count=#
device=#
device=#
device=#
There is no upper limit on the number of device= entries for a room, but
for large rooms, you could just enumerate the devices and build the room
list by looking at each devices assigned room.

upb.roomlist
network=#
status=[oknot-found]
room=
room=
There is not upper limit on the number of room= lines.  Unlike device and
link lists, there is only one room name per entry.  If there are a large
number of rooms, you could just enumerate the devices and build the room
list by looking at each devices assigned room.


Triggers:

Triggers are only sent when the state of the device changes, either due to
a
command or due to something on the UPB network commanding a switch (or a
end-user pressing the switch).  If you issue a command that changes nothing
(i.e. turn off a light that is already off, no trigger is sent);


upb.device

Indicates a change of state for a device.  channel= is only sent if the
device has >1 channel.  level= will be only 0 or 100 for non-dimming
devices.

network=#
device=#
[channel=#]  // Only for multi-channel devices
state=onoff
level=0-100


upb.link

Links do not "change state" like devices.  Rather, they are
'triggers'
themselves.  As such, link reports are not changes in status, but simply
"reports" than the described link activity occurred on the UPB
network.

network=#
link=#
action=[activatedeactivategotostart-fadestop-fade]
[level=0-100]
[faderate=[snapdefault<time>]

level= and faderate= are only included if the transmitted link command
included them (they are only possible for goto and start-fade).

----

Gerry
--
Gerry Duprey
Ann Arbor, MI 48103
http://www.cdp1802.org