Self-Installation Policy and Guidelines
Revision 6, August 28, 2003
Introduction
This summarizes Echelon's policy and guidelines for implementing
and supporting applications that use self-installation. The following section
defines self-installation as well as other key terms used in this document.
Definitions
- Network configuration data consists of the following network
address components contained within a device: device domain IDs, device
subnet IDs, device node IDs, device group IDs, network variable selectors,
aliases, and NV/message destination addresses.
- Network management is the act of putting network configuration
data into a persistent store (typically a database) with the intent
of making the network configuration data in a network of devices consistent
with the network configuration data in the persistent store, and maintaining
that consistency over time.
- A network management application is an application that
performs network management.
- A self-installed device is a device that modifies its network
configuration data, but does not modify the network configuration data
of other devices.
- A self-installed network is a network that contains self-installed
devices.
- A local input is an input from a hardware component on a
device such as a rotary dial, dip switch, keypad, infrared controller,
or pushbutton; or, a keyed input on the device such as a backplane
connector with different settings for each slot in a backplane.
- A locally assigned value is a value that is assigned based
on a local input.
- A cloned device is a device that does not have a unique
domain/subnet/node address on its network.
Support Policy
Echelon supports customers developing self-installed applications, as
long as the applications meet the restrictions and follow the guidelines
identified in this document. Echelon also supports the development of
network management applications, as long as they use the LNS® network
operating system to perform all network management functions. Echelon
does not support the development of network management applications that
do not use LNS or that attempt to bypass the use of LNS, which means
the development of a device that modifies the network configuration data
of other devices is not supported.
Restrictions
- A self-installed device cannot change
the network configuration data on another device.
- A self-installed device cannot perform network management.
- A self-installed network cannot include routers, and is
therefore limited to a single channel. Layer 1 or 3 repeaters may be
used.
- A self-installed device that also supports installation
by a network management tool must implement a LonMark® compliant
Node object with a SCPTnwrkCnfg configuration property (CP), as defined
in the LonMark Node Object functional profile. As described in the
profile, when the SCPTnwrkCnfg CP is set to CFG_EXTERNAL, the device
application must disable all self-installation functions to prevent
conflicts with any network management applications.
Guidelines
The application for a self-installed device may be implemented in Neuron® C,
or in the host programming language for a device that uses a ShortStack™ Micro
Server or MIP. Neuron C includes
functions for performing self-installation. Self-installation code is
not included with ShortStack, but sample code is available and will be
provided on request. While self-installation with ShortStack is supported,
the sample code has undergone limited testing and is therefore provided
as-is. Sample code is not available for the MIP, though a MIP developer
can port the ShortStack self-installation example to the MIP host API.
A self-installed device may use network variables and/or application
messages for communicating with other devices. Network variables must
be used for interoperable interfaces. Application messages may be used
to implement closed interfaces and proprietary configuration interfaces.
For example, a service tool may send proprietary application messages
via domain-wide broadcast to reconfigure all the devices within a closed
system. If a device supports installation with devices from other manufacturers,
any proprietary application configuration must also be implemented using
configuration properties implemented either as configuration network
variables or within configuration files.
A self-installed device must follow these guidelines for setting its
network configuration data:
- Domain: A device may be a member of one or two domains.
Each domain may be fixed or may be locally assigned. The Neuron C update_clone_domain() function or the ShortStack lonUpdateDomain() function (with the clone flag set to TRUE) is used to assign a domain ID. The Neuron C update_domain() function cannot be used.
- Subnet/node ID: A device has a subnet/node ID for each of
its domains. Fixed, typically at 1/1 for all devices. Use a cloned
device to allow duplicate sunbet/node IDs on a network. This disables
subnet/node ID addressing. Subnets may be used like groups. This allows
intersecting multi-cast connections, where one connection is defined
by a subnet and another is defined by a group, with some common members
and some non-common members. If subnets are used for multicast connections,
the subnet ID must be set by a local input. The Neuron C update_clone_domain() and ShortStack lonUpdateDomain() (with the clone flag set to TRUE)
functions are also used to assign a device’s subnet and node
IDs. The Neuron C update_domain() function cannot be used.
- Address table: all entries are group IDs, turnaround, subnet
broadcast, or domain broadcast. Subnet/node ID addressing cannot be
used. The only supported services are unacknowledged and repeated.
Acknowledged messages, authentication, and priority are not supported.
If groups are used for connections, the group ID must be set by a local
input. The Neuron C update_address() function or the ShortStack lonUpdateAddress() function is used to update an address table entry. Message tags may
be used. Each message tag corresponds to an entry in the address table.
- NV config table. NV selectors are assigned at the time of
manufacture. NVs to be connected must be assigned the same selector.
Multiple input NVs on the same device cannot share the same NV selector,
so an alias connection (see next bullet) must be used on a sending
device to simultaneously update multiple NVs on a receiving device.
The sending device and the receiving device may be the same device
if turnaround connections are used.. The Neuron C update_nv() function
or the ShortStack lonUpdateNvConfig() function is used to update an
NV config table entry.
- NV alias table. The alias table specifies additional NV
selectors for the NVs defined in the NV config table. The NV selectors
are assigned as specified in the previous paragraph. The Neuron C update_alias() function or the ShortStack lonUpdateAliasConfig() function is used
to update an NV alias table entry.
