View source for Polisy Developers:ISY:API:Scene Support:Scenes

<!--
   ** DO NOT EDIT ON THE WIKI WEBSITE - Source file is UDWiki/polisydev/isyapi/sceneSupport.scenes.wiki.txt **
   [[Polisy_Developers:ISY:API:Scene_Support:Scenes]]
 -->
[[Polisy_Developers | Polisy Developers]] : [[Polisy_Developers:ISY | ISY]] : [[Polisy_Developers:ISY:API | API]] : 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.

<pre>
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>
</pre>

==Link Types==

===Native===
''type="native"''

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

For more information see [[Polisy_Developers:ISY:API:Scene_Support:Native_Links | 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&rarr;ISY&rarr;Responder)''

===Default===
''type="default"''

Whatever command is sent by the controller is forwarded to the responder by the ISY.
''(Controller&rarr;ISY&rarr;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 [[Polisy_Developers:ISY:API:Appendix:REST_Return_Codes | REST return codes]]

Notes:
* URL Prefix: /rest

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

Returns all the [[Polisy_Developers:ISY:API:Appendix:Links | 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.
|-
|}

{| style="font-family: courier;"
|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
|}

{| style="font-family: courier;"
| 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
|}

{| style="font-family: courier;"
|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
|}

{| style="font-family: courier;"
|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 [[Polisy_Developers:ISY:API:Appendix:Link_Definitions | 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,)
|}

{| style="font-family: courier;"
|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&rarr;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 [[Polisy_Developers:ISY:API:Appendix:Link_Definitions | 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
|}

{| style="font-family: courier;"
| 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&rarr;ISY&rarr;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
|}

{| style="font-family: courier;"
| 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
|}