ISY Developers:API:V5:Node Server:Configuration
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.
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
|
/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>