Re: Call for commentary on new UPB schema

[Ian Lowe <ianlowe@xxxxxxxxxxxxxxxxx>]

Seems fairly robust - I have one request to maintain consistency across
the schemas.

one of the xPL rules for schema definitions is that mandatory elements
of a message come first, and in a specific order - this can be easily
achieved below by swapping "command=" to the start of the
message, then
adding the UPB address elements below as required.

similarly for the status requests - the request command itself should
come first.

That's actually how the X10.basic schema is structured as well (for the
same reason).

my only complaint now... is that this stuff is US only, so I can't get
some!!! :D

Ian.

On Fri, 2005-12-02 at 16:48 -0500, Gerry Duprey wrote:
> 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
>
>
>
> xPL Links: http://www.xplproject.org.uk http://www.xplhal.com http://www.xpl.myby.co.uk
> To Post a Message: ukha_xpl@xxxxxxx
> To Subscribe:  ukha_xpl-subscribe@xxxxxxx
> To Unsubscribe:  ukha_xpl-unsubscribe@xxxxxxx
> Yahoo! Groups Links
>
>
>
>
>
>