ISY Developers:API:V5:Node Server:Configuration

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


ISY_Developers : API : V5 : Node Server : Configuration

Node Server Configuration on ISY

Files

/editor Contains all the XML editors files (.xml)
/linkdef Contains all the XML link definitions (.xml)
/nodedef Contains all the XML node definitions (.xml)
/nls Contains all the NLS properties files (.txt)
/version.txt Contains the version of these files

These files are normally supplied as a .zip file by the node server developer and installed by the user through the ISY Admin console. In each directory, one or more files may be used. All filenames are restricted to 8.3 format.

If the node server developer creates a new version of the files, they can be installed over the old ones on the ISY. It is up to the node server developer to ensure any required backwards compatibility of nodes.

e.g. Example Zip File contents

        /editor/edit.xml
/linkdef/ldef.xml
/nodedef/ndef.xml
/nls/EN_US.txt
/version.txt
/editor
An editor defines the parameters for a widget in the client, such as a combobox, a numeric field etc. It defines the set of values and the unit(s) of measure available. An editor may contain multiple <range> entries, each of which must have a unique UOM.
/linkdef
link definitions define the support for native links between nodes used in ISY scenes (see Native Links)
/nodedef
A node definition defines the status and commands available to a node.
/nls
A single NLS file is used for each language. The naming convention is <language>_<countryCode>.txt (e.g. en_US.txt for USA English)
NLS is a set of name/value pairs used to display values in national language (such as English).

Note: for compatibility, Insteon also has an I_EMAP.XML file, see Insteon for how it is used.

Network Connection

From Isy to Node Server

The REST API is used to communicate with a node server when using a network connection. The ISY uses basic authentication with either http or https to communicate with the node server. A custom base URL is also prepended to the REST command, allowing the node server to customize the location of its REST support.

For example, if a base URL of /nodeservers/joe is configured, then the following URL would be sent to the node server to query a node:

/nodeservers/joe/nodes/<nodeAddress>/query

Having a base URL also allows a device to support multiple node servers, each with its own unique base URL.

From Node Server to Isy

The node server must use basic authentication with either http or https to communicate with the ISY. It must also know the profile number the node server has been assigned on the ISY because most REST API calls require this number in the URL. The ISY uses the profile number to ensure only the nodes owned by the profile can be modified, and to choose the ISY user number the node server should be using.

For example, if the node server has been assigned profile number 5, then something like the following URL would be used to update device status in ISY:

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

Responses

When a Node Server receives a REST command, one of the following responses must be sent out immediately, before processing the request. The ISY will send a similar response after processing a request (see ISY REST Return Codes)

      200 - HTTP_OK
    Valid request received, will run it
401 - HTTP_UNAUTHORIZED
User authentication failed (the userid and/or password is missing or incorrect)
404 - HTTP_NOT_FOUND
Unrecognized request received and ignored.
503 - HTTP_SERVICE_UNAVAILABLE
Valid request received but ignored because system too busy to run it

REST API

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/
  • Only the admin user has authority for the node server configuration APIs.


Node Server Profile Connections


/profiles/ns/<profileNumber>/connection

Get one or all node server profiles with their connection information

profileNumber The profile to return, or 0 to return all profiles

e.g.

/profiles/ns/0/connection - Returns all profiles
/profiles/ns/3/connection - Returns profile 3

/profiles/ns/<profileNumber>/connection/remove

Removes the profile from the ISY

profileNumber The profile to return, or 0 to return all profiles

e.g.

/profiles/ns/3/connection/remove

/profiles/ns/<profileNumber>/connection/set/network ?ip=<ip>&baseurl=<baseurl>&name=<name>&nsuser=<nsuser> &nspwd=<nspwd>&isyusernum=<isyusernum>&port=<port> &timeout=<timeout>&ssl=<ssl>&enabled=<enabled>

Adds a network profile to the ISY.

If there is an existing profile then it is replaced, therefore all parameters must always be specified.

profileNumber The profile to create or update
ip IP Address of Node Server
baseurl Base URL
name Name of this profile
nsuser User in Node Server
nspwd Password for User in Node Server
isyusernum Isy User number (0 for ISY Admin user)
port Port in Node Server
timeout Request timeout
ssl Use SSL true/false
enabled Profile enabled in ISY true/false

e.g.

/rest/profiles/ns/3/connection/set/network
?ip=192.168.0.1
&baseurl=/my/base
&name=My Portal
&nsuser=blah
&nspwd=blahPassword
&isyusernum=0
&port=80
&timeout=500
&ssl=true
&enabled=true

/profiles/ns/<profileNumber>/install

ISY instructs the node server to install itself on the ISY (upload profile to ISY, create default nodes etc.)

profileNumber The profile to install

e.g.

/profiles/ns/7/install

Node Server Profile Files


/profiles/ns/<profileNumber>/files

Returns the list of all files for the specified profile.

profileNumber The profile, or 0 to return list of files for all profiles

e.g.

/profiles/ns/0/files



/profiles/ns/<profileNumber>/files/remove

Removes all files for the specified profile (does not remove the profile connection information).

profileNumber The profile to remove

e.g.

/profiles/ns/2/files/remove

/profiles/ns/<profileNumber>/download/<dir>/<filename>

Returns the file specified file.

profileNumber The profile
dir The directory containing the file
filename The file to download

e.g.

/profiles/ns/2/download/EDITORS/I_EDIT.XML

ISY Core Profile Files

ISY has native support for Insteon, Z-Wave, Zigbee and some other protocols. They all use the same concepts as node servers but have a few differences and additional APIs. Each of these is separated into product families.

Product Family Number Description
Default 0 Core driver implementation, currently only used for Insteon
RCS 3 RCS Thermostat and Relay products
Z-Wave 4 Z-Wave products
Generic 6 Used for ISY scene support
UDI 7 Universal Devices products
Brultech 8 Brultech Energy Monitors
NCD 9 NCD devices
Node Servers 10 Node Servers

/profiles/download/core

Download a .zip file containing all the profile files for all the core ISY profiles such as Insteon, Z-Wave, etc. (i.e. everything but family 10 Node Servers)

This is much more efficient than downloading files individually.

e.g.

/profiles/download/core

/profiles/files

Returns the list of profile files for all product families (i.e. Insteon, Z-Wave, node servers, etc.).

e.g.

/profiles/files

/profiles/family/<familyNumber>/files

Returns the list of all profile files for the specified product family

familyNumber The product family

e.g.

/profiles/family/3/files

/profiles/family/<familyNumber>/profile/<profileNumber>/files

Returns the list of profile files for a single profile in the specified product family

familyNumber The product family
profileNumber The profile

e.g.

/profiles/family/10/profile/3/files

/profiles/family/<familyNumber>/profile/<profileNumber>/download/<dir>/<filename>

Returns a file from the specified profile.

familyNumber The product family
profileNumber The profile
dir The directory containing the file
filename The file to download

e.g.

/profiles/family/10/profile/3/download/EDITORS/EDIT.XML

Examples

File List

An example list of all profile files configured on an ISY.

<profiles>
   <profile family="-1" id="1">
      <files dir="NLS">
         <file name="EN_US.TXT"/>
      </files>
      <files dir="EDITOR"/>
      <files dir="NODEDEF"/>
      <files dir="LINKDEF"/>
   </profile>
   <profile family="1" id="1">
      <files dir="NLS">
         <file name="EN_US.TXT"/>
      </files>
      <files dir="EDITOR">
         <file name="I_EDIT.XML"/>
      </files>
      <files dir="NODEDEF">
         <file name="I_NDEFS.XML"/>
      </files>
      <files dir="EMAP">
         <file name="I_EMAP.XML"/>
      </files>
      <files dir="LINKDEF">
         <file name="I_LDEFS.XML"/>
      </files>
   </profile>
   <profile family="3" id="1">
      <files dir="EDITOR">
         <file name="EDITORS.XML"/>
      </files>
      <files dir="NODEDEF">
         <file name="NDEFS.XML"/>
      </files>
      <files dir="NLS">
         <file name="EN_US.TXT"/>
      </files>
   </profile>
   <profile family="4" id="1">
      <files dir="NLS">
         <file name="EN_US.TXT"/>
      </files>
      <files dir="EDITOR">
         <file name="EDITORS.XML"/>
      </files>
      <files dir="NODEDEF"/>
      <files dir="EMAP"/>
      <files dir="LINKDEF">
         <file name="ZW_LDEFS.XML"/>
      </files>
   </profile>
   <profile family="6" id="1">
      <files dir="NLS">
         <file name="EN_US.XML"/>
      </files>
      <files dir="EDITOR">
         <file name="EDIT.XML"/>
      </files>
      <files dir="NODEDEF">
         <file name="NDEFS.XML"/>
      </files>
      <files dir="EMAP"/>
      <files dir="LINKDEF">
         <file name="LDEFS.XML"/>
      </files>
   </profile>
   <profile family="7" id="1">
      <files dir="EDITOR">
         <file name="EDITORS.XML"/>
      </files>
      <files dir="NLS">
         <file name="EN_US.TXT"/>
      </files>
      <files dir="NODEDEF">
         <file name="NDEFS.XML"/>
      </files>
   </profile>
   <profile family="8" id="1">
      <files dir="EDITOR">
         <file name="EDITORS.XML"/>
      </files>
      <files dir="NLS">
         <file name="EN_US.TXT"/>
      </files>
      <files dir="NODEDEF">
         <file name="NDEFS.XML"/>
      </files>
   </profile>
   <profile family="9" id="1">
      <files dir="EDITOR">
         <file name="EDITORS.XML"/>
      </files>
      <files dir="NLS">
         <file name="EN_US.TXT"/>
      </files>
      <files dir="NODEDEF">
         <file name="NDEFS.XML"/>
      </files>
   </profile>
   <profile family="10" id="7">
      <files dir="EDITOR">
         <file name="EDITORS1.XML"/>
      </files>
      <files dir="NLS">
         <file name="EN_US.TXT"/>
      </files>
      <files dir="NODEDEF">
         <file name="NDEFS.XML"/>
      </files>
   </profile>
   <profile family="10" id="24">
      <files dir="EDITOR">
         <file name="EDITORS1.XML"/>
      </files>
      <files dir="NLS">
         <file name="EN_US.TXT"/>
      </files>
      <files dir="NODEDEF">
         <file name="NDEFS.XML"/>
      </files>
   </profile>
</profiles>