ISY Developers:API:V5:Node Server:REST Support in ISY

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


ISY_Developers : API : V5 : Node Server : REST support in ISY

REST is an easy to use URL based command set which allows the developer to communicate with the ISY.

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

See REST return codes

Notes:

  • URL Prefix: /rest/ns/<profileNumber>/
  • The profileNumber specified on the URL determines which ISY userid/password will be accepted by the ISY for the request.

Node Management

/nodes/<nodeAddress>/add/<nodeDefId>?primary=<primary>&name=<nodeName>[&nls=<nlsKey>]

Adds a node to the ISY. To make this node the primary, set primary to the same value as nodeAddress

nodeAddress The full address of the node (e.g. 'n005_dimmer_1')
nodeDefId The id of the node definition to use for this node
primary The primary node for the device this node belongs to
nodeName The name of the node
nls (Optional) NLS key string for information specific to this node

E.g.

/rest/ns/5/nodes/n005_dimmer_2/add/MyDimmer?primary=n005_dimmer_1&name=Dimmer 2&nls=012B

/add/nodes

Sends a request to the node server to have it add all of its nodes to the ISY. This API is intended for ISY clients, and is never used by a node server.

E.g.

/rest/ns/5/add/nodes

/nodes/<nodeAddress>/change/<nodeDefId>[?nls=<nlsKey>]

Changes the node definition to use for an existing node. An example of this is may be to change a thermostat node from Fahrenheit to Celsius.

nodeAddress The full address of the node (e.g. 'n005_dimmer_1')
nodeDefId The id of the node definition to use for this node
nls (Optional) NLS key string for information specific to this node

E.g.

/rest/ns/5/nodes/n005_tstat_1/change/ThermostatCelsius?nls=4511

/nodes/<nodeAddress>/remove

Removes a node from the ISY. A node cannot be removed if it is the primary node for at least one other node.

nodeAddress The full address of the node (e.g. 'n005_dimmer_1')

E.g.

/rest/ns/5/nodes/n005_dimmer_2/remove

/nodes/<nodeAddress>/set/hint/<value>

Adds a hint to the node. This ISY stores the value with the node but does not use this value in any way.

nodeAddress The full address of the node (e.g. 'n005_dimmer_1')
value A four byte integer

E.g.

/rest/ns/5/nodes/n005_dimmer_2/set/hint/101

Reporting status updates

/nodes/<nodeAddress>/report/status/<statusName>/<value>/<uom>

Updates the ISY with the current value of a driver control (e.g. the current temperature, light level, etc.)

nodeAddress The full address of the node (e.g. 'n005_dimmer_1')
statusName The name of the status value (e.g. 'ST', 'CLIHUM', etc.)
value The numeric status value (e.g. '80.5')
uom Unit of measure of the status value

E.g.

/rest/ns/5/nodes/n005_dimmer_2/report/status/ST/25.2/percent

Reporting a command

/nodes/<nodeAddress>/report/cmd/<command>
/nodes/<nodeAddress>/report/cmd/<command>/<value>
/nodes/<nodeAddress>/report/cmd/<command>/<value>/<uom>

[?<p1>.<uom1>=<val1>&<p2>.<uom2>=<val2>&<p3>…]

Sends a command to the ISY that may be used in programs and/or scenes. A common use of this is a physical switch that somebody turns on or off. Each time the switch is used, a command should be reported to the ISY. These are used for scenes and control conditions in ISY programs.

nodeAddress The full address of the node (e.g. 'n005_switch_1)
command The command to perform (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/ns/5/nodes/n005_switch_1/report/cmd/DON
/rest/ns/5/nodes/n005_switch_1/report/cmd/DON/80/percent
/rest/ns/5/nodes/n005_switch_1/report/cmd/DON?level.percent=80
/rest/ns/5/nodes/n005_switch_1/report/cmd/DON/80/percent?rate.uom58=0.3

Reporting ISY Request status

/report/request/<requestId>/success
/report/request/<requestId>/failed
/report/request/<requestId>/unsupported

When the ISY sends a request to the node server, the request may contain a requestId field. This indicates to the node server that when the request is completed, it must send a fail or success report for that request. This allows the ISY to in effect, have the node server synchronously perform tasks. This message must be sent after all other messages related to the task have been sent.

For example, if the ISY sends a request to query a node, all the results of the query must be sent to the ISY before a fail/success/unsupported report is sent.

requestId The request ID the ISY supplied on a request to the node server.

E.g.

/rest/ns/5/report/request/1234/success