Difference between revisions of "ISY Developers:API:V5:Node Server:Configuration"

From Universal Devices, Inc. Wiki
Jump to: navigation, search
(Created page with "<!-- ** DO NOT EDIT ON THE WIKI WEBSITE - Source file is v5NodeServerConfig.wiki.txt ** --> ISY_Developers : API : ISY_Developers:API:V5 |...")
(No difference)

Revision as of 18:02, 9 January 2019


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).

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