Difference between revisions of "ISY Developers:API:V5:Node Server:Configuration"
|Line 55:||Line 55:|
:link definitions define the support for native links between nodes used in ISY scenes (see [[ISY Developers:API:V5:
:link definitions define the support for native links between nodes used in ISY scenes (see [[ISY Developers:API:V5:| Native Links]])
Revision as of 19:01, 14 January 2019
Node Server Configuration on ISY
|/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
- 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.
- link definitions define the support for native links between nodes used in ISY scenes (see Native Links)
- A node definition defines the status and commands available to a node.
- 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).
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:
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:
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|