ISY Developers:API:V5:Scene Support:Scenes

From Universal Devices, Inc. Wiki
Jump to: navigation, search

ISY_Developers : API : V5 : Scene Support : ISY Scenes

Scenes

The terminology for scene has dual meanings in ISY because in some cases it describes the group (scene) object that contains a set of controller and responder nodes, and in others it describes a single controller (and its links to responders) within the group (scene).

Controller
A node such as a light switch that can control responders (e.g. can turn something on/off)
In some cases, a controller may also be a responder.
Responder
A node such as a lamp that can be controlled by a controller (e.g. can be turned on/off)
Group
Often referred to as a scene, a group is an object containing a collection controllers and responders. It may contain many controllers and many responders. The group itself acts as a scene controller that also supports native Insteon links.
Scene
A single controller linked to one or more responders.

ISY scenes define how controllers control and communicate with responders in the scene. The ISY group itself acts as a controller and therefore also has links to all of the responders in the scene.

https://<isy>/rest/links/groups/39520

<groups>
   <group id="39520">
      <ctl id="1B 99 17 1">
         <rsp>
            <link linkdef="I_DIMMER" type="native" node="A B9 44 1">
               <p id="OL">
                  <val uom="51" prec="0">85</val>
               </p>
               <p id="RR">
                  <val uom="25" prec="0">27</val>
               </p>
            </link>
            <link linkdef="I_TEMPLINC" type="native" node="1D 6F 15 1">
               <p id="CLISPH">
                  <val uom="14" prec="0">61</val>
               </p>
               <p id="CLISPC">
                  <val uom="14" prec="0">81</val>
               </p>
               <p id="CLIFS">
                  <val uom="99" prec="0">8</val>
               </p>
               <p id="CLIMD">
                  <val uom="98" prec="0">3</val>
               </p>
               <p id="CLIEMD">
                  <val uom="2" prec="0">0</val>
               </p>
            </link>
            <link type="ignore" node="ZW060_1"/>
            <link type="default" node="ZW033_1"/>
            <link type="default" node="1B 99 17 1"/>
         </rsp>
      </ctl>
      <ctl id="39520">
         <rsp>
            <link linkdef="I_DIMMER" type="native" node="A B9 44 1">
               <p id="OL">
                  <val uom="51" prec="0">100</val>
               </p>
               <p id="RR">
                  <val uom="25" prec="0">31</val>
               </p>
            </link>
            <link linkdef="I_DIMMER" type="native" node="1B 99 17 1">
               <p id="OL">
                  <val uom="51" prec="0">100</val>
               </p>
               <p id="RR">
                  <val uom="25" prec="0">31</val>
               </p>
            </link>
            <link linkdef="I_TEMPLINC" type="native" node="1D 6F 15 1">
               <p id="CLISPH">
                  <val uom="14" prec="0">68</val>
               </p>
               <p id="CLISPC">
                  <val uom="14" prec="0">75</val>
               </p>
               <p id="CLIFS">
                  <val uom="99" prec="0">8</val>
               </p>
               <p id="CLIMD">
                  <val uom="98" prec="0">3</val>
               </p>
               <p id="CLIEMD">
                  <val uom="2" prec="0">0</val>
               </p>
            </link>
            <link type="cmd" node="ZW060_1" cmd="CLIMD">
               <p id="">
                  <val uom="67" prec="0">3</val>
               </p>
            </link>
            <link type="default" node="ZW033_1"/>
         </rsp>
      </ctl>
   </group>
</groups>

Link Types

Native

type="native"

A direct link between the controller and the responder (e.g. Insteon links, Z-Wave associations, etc.). (Controller→Responder)

For more information see Native Links

Command

type="cmd"

Same as Default except when the controller sends an On command the ISY sends the command specified in the link to the responder. (Controller→ISY→Responder)

Default

type="default"

Whatever command is sent by the controller is forwarded to the responder by the ISY. (Controller→ISY→Responder)

Ignore

type="ignore"

No link is made between the controller and responder.

Link Management

Unless otherwise specified, all REST commands use HTTP GET method.

See REST return codes

Notes:

  • URL Prefix: /rest

/links[/groups/<groupId>[/controllers/controllerId[/responders/<responderId>]]]

Returns all the links, or just the links for the specified group, controller and/or responder.

groupId The node address of the ISY group (scene) node. If not specified then return all links.
controllerId The ISY node address of a controller in the group. If not specified then return all links for the group.
responderId The ISY node address of a responder in the group. If not specified then return all links for the controller.
e.g.
/rest/links
/rest/links/group/39520/
/rest/links/group/39520/controllers/1B 99 17 1
/rest/links/group/39520/controllers/1B 99 17 1/responders/1D 6F 15 1

/links/groups/<groupId>/member/<memberId>/remove

Remove the node from the group. All links to and from this node with other controllers and responders in the group are also removed.

groupId The address of the ISY group node containing the node to be removed
memberId The address of the node to be removed
e.g. /rest/links/groups/21151/member/ZW017_1/remove

/links/groups/<groupId>/controllers/controllerId/responders/<responderId>/update/default

Change the link between controllerId and responderId to link type default

groupId The address of the ISY group node containing the controller and responder
controllerId The node address of the controller
responderId The node address of the responder
e.g. /rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/default

/links/groups/<groupId>/controllers/controllerId/responders/<responderId>/update/ignore

Change the link between controllerId and responderId to link type ignore

groupId The address of the ISY group node containing the controller and responder
controllerId The node address of the controller
responderId The node address of the responder
e.g. /rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/ignore

/links/groups/<groupId>/controllers/controllerId/responders/<responderId>/update/linkdef/<linkDefId>[?<p1>.<uom1>=<val1>&<p2>.<uom2>=<val2>&<p3>…]

Change the link between controllerId and responderId to link type native.

groupId The address of the ISY group node containing the controller and responder
controllerId The node address of the controller
responderId The node address of the responder
linkDefId The id of the link definition
pN Nth Parameter name (e.g. 'ol')
uomN Unit of measure of the Nth parameter (e.g. 'seconds', 'uom58')
valN The numeric value of the Nth parameter (e.g. '80', '80.01' etc,)
e.g. /rest/links/groups/21151/controllers/1 FA 19 1/responders/A 5E 21 1/update/linkdef/I_STD?ol.percent=85&rr.uom25=30

/links/groups/<groupId>/controllers/controllerId/responders/<responderId>/update/linkdef/<linkDefId>/cmd/<command>[/<value>[/<uom>]][?<p1>.<uom1>=<val1>&<p2>.<uom2>=<val2>&<p3>…]

Change the link between controllerId and responderId to link type native with a command. (Controller→Responder)

groupId The address of the ISY group node containing the controller and responder
controllerId The node address of the controller
responderId The node address of the responder
linkDefId The id of the link definition
command The command to be used in the link (e.g. 'DON', 'CLISPH', etc.)
pN Nth Parameter name (e.g. 'level')
uomN Unit of measure of the Nth parameter (e.g. 'seconds', 'uom58')
valN The numeric value of the Nth parameter (e.g. '80', '80.01' etc,)

Commands may also have an unnamed parameter

value The value of the unnamed parameter.
uom Unit of measure of the value of the unnamed parameter
e.g.
/rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/linkdef/ASSOC_CMD/cmd/DON
/rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/linkdef/ASSOC_CMD/cmd/DON/80
/rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/linkdef/ASSOC_CMD/cmd/DON/80/percent
/rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/linkdef/ASSOC_CMD/cmd/DON?level.percent=80
/rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/linkdef/ASSOC_CMD/cmd/DON/80/percent?rate.uom58=0.3

/links/groups/<groupId>/controllers/controllerId/responders/<responderId>/update/cmd/<command>[/<value>[/<uom>]][?<p1>.<uom1>=<val1>&<p2>.<uom2>=<val2>&<p3>…]

Change the link between controllerId and responderId to link type command. (Controller→ISY→Responder)

groupId The address of the ISY group node containing the controller and responder
controllerId The node address of the controller
responderId The node address of the responder
command The command to be used in the link (e.g. 'DON', 'CLISPH', etc.)
pN Nth Parameter name (e.g. 'level')
uomN Unit of measure of the Nth parameter (e.g. 'seconds', 'uom58')
valN The numeric value of the Nth parameter (e.g. '80', '80.01' etc,)

Commands may also have an unnamed parameter

value The value of the unnamed parameter.
uom Unit of measure of the value of the unnamed parameter
e.g.
/rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/cmd/DON
/rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/cmd/DON/80
/rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/cmd/DON/80/percent
/rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/cmd/DON?level.percent=80
/rest/links/groups/21151/controllers/ZW010_1/responders/ZW017_1/update/cmd/DON/80/percent?rate.uom58=0.3