Echelon, LONWORKS, Neuron, NodeBuilder, LonMaker,
3120, 3150, and the Echelon logo are trademarks of
Echelon Corporation registered in the United States and
other countries. 3170 is a trademark of Echelon
Corporation.
Other brand and product names are trademarks or
registered trademarks of their respective holders.
Neuron Chips and other OEM Products were not designed
for use in equipment or systems which involve danger to
human health or safety or a risk of property damage and
Echelon assumes no responsibility or liability for use of the
Neuron Chips in such applications.
Parts manufactured by vendors other than Echelon and
referenced in this document have been described for
illustrative purposes only, and may not have been tested
by Echelon. It is the responsibility of the customer to
determine the suitability of these parts for each
application.
ECHELON MAKES AND YOU RECEIVE NO WARRANTIES OR
CONDITIONS, EXPRESS, IMPLIED, STATUTORY OR IN ANY
COMMUNICATION WITH YOU, AND ECHELON SPECIFICALLY
DISCLAIMS ANY IMPLIED WARRANTY OF MERCHANTABILITY
OR FITNESS FOR A PARTICULAR PURPOSE.
No part of this publication may be reproduced, stored in a
retrieval system, or transmitted, in any form or by any
means, electronic, mechanical, photocopying, recording,
or otherwise, without the prior written permission of Echelon
Corporation.
This guide describes how you can use Interoperable SelfInstallation (ISI) to create networks of control devices that
interoperate, without requiring the use of an installation
tool. This guide also describes how to use Echelon’s ISI
Library to develop devices that can be used in both selfinstalled as well as managed networks.
This guide refers to version 3.01 of Echelon’s ISI Libraries.
1 ISI Programmer’s Guide
Overview
Control networks consist of intelligent devices like switches, thermostats, pumps,
motors, valves, controllers, and a variety of other sensors and actuators that
communicate with each other to provide distributed monitoring and control. A
control network may be a small, simple network consisting of a few devices; may
be a large network in a building, factory, or ship consisting of tens of thousands
of devices; or may even be a very large regional network consisting of millions of
devices. In every case, the devices in the network must be configured to become
part of a common network, and to exchange data amongst themselves. The
process of configuring devices in a control network to establish communication
among the devices is called
Networks can be categorized by the method used to perform network installation.
The two categories of networks are
networks. A managed network is a network where a shared
management server
uses a tool to interact with the server and define how the devices in the network
should be configured and how they should communicate. Such a tool is called a
network management tool
is a network management tool that uses a network management server called the
®
LNS
tool and a server are used to initially establish network communication, they
need not be present all the time for the network to function. The network
management tool and server are only required whenever changes are made to the
network’s configuration.
network installation
managed networks
.
and
self-installed
network
is used to perform network installation. A user typically
. For example, Echelon’s LonMaker® Integration Tool
Server to install devices in a network. Although a network management
In a managed network, the network management tool and server allocate various
network resources, such as device and data point addresses. The network
management server is also aware of the network topology, and can configure
devices for optimum performance within the constraints of the topology.
The alternative to a managed network is a self-installed network. There is no
central tool or server that manages all of the network configuration in a selfinstalled network. Instead, each device contains code that replaces parts of the
network management server’s functionality, resulting in a network that no
longer requires a special tool or server to establish network communication or to
change the configuration of the network.
Devices in a self-installed network cannot rely on a network management server
to coordinate their configuration. Since each device is responsible for its own
configuration, a common standard is required to ensure that devices configure
themselves in a compatible way. The standard protocol for performing selfinstallation in L
Installation (ISI) Protocol
devices that meet topology and connection constraints described in this guide.
Larger or more complex networks must either be installed as managed networks,
or must be partitioned into multiple smaller subsystems, where each subnetwork
has no more than 200 devices and meets the ISI topology and connection
constraints. Devices that conform to the L
devices
.
ONWORKS networks is called the
. The ISI protocol can be used for networks of up to 200
ONWORKS ISI protocol are called
LONW
ORKS
Interoperable Self-
ISI
ISI Programmer’s Guide 2
This guide presents a library for Neuron
®
C—called the
Neuron C ISI library
—to
create interoperable self-installed devices. This library implements the ISI
protocol. This guide details the application programming interface (API) that you
will use to interact with the ISI library. For a detailed description of the ISI
protocol, see the
ISI Protocol Specification
.
LONW
ORKS
Networks can start out as self-installed networks using ISI and, as size or
complexity grows beyond the ISI limits, can be upgraded into a managed
network. A self-installed network may also be transitioned to a managed
network to take advantage of the additional flexibility and capability provided by
a network management tool and server. This guide also details recommended
procedures when transitioning from a self-installed network to a managed
network. By following these guidelines, self-installed networks can be easily
transitioned to managed networks while maintaining all of the configuration
information from the self-installed network.
The ISI protocol is a licensed protocol. The ISI Developer's Kit and Mini EVK
Evaluation Kit both include a license for development use of the ISI library with
®
Echelon's FT 3120
/FT 3150®/PL 3120/PL 3150/PL 3170™ Smart Transceivers or
Echelon's FTT-10A/LPT-11/PLT-22 Transceivers used in conjunction with
Neuron Chips. By signing a Revision J or newer OEM License Agreement (or an
amendment to a prior version that includes rights to the ISI protocol),
manufacturers can acquire a royalty-free license to produce devices incorporating
the ISI library and using an Echelon FT 3120/FT 3150/PL 3120/PL 3150/PL 3170
Smart Transceiver or an Echelon FTT-10A/LPT-11/PLT-22 Transceiver used in
conjunction with a Neuron Chip.
To use the ISI trademark or logo in your products, you must first certify your
LONM
ARK
products to the
3.4 Application-Layer Guidelines
the 15 July 2005 or newer version of the L
License Agreement.
To use the ISI libraries in products designed for us in a home environment, you
must also have a Digital Home Alliance Agreement in effect with Echelon.
Changes since Revision 2
This document describes version 3.01 of the ISI Library. Revision 3 of this
document added details on how to use network variables heartbeats, turnaround
connections, controlled enrollment, and also describes several new ISI libraries.
Revision 3.01 of this document adds details about developing applications for the
PL 3170 Smart Transceiver, and also describes the new IsiPl3170.lib library.
ISI devices may support
plug-and-play installation, installation is performed by plugging in the device.
No user interaction is required in this case. This is suitable for devices where
connections can be determined automatically. For example, all appliances in a
home may automatically connect to a home gateway. If power line transceivers
are used, then the network connection is created by plugging in the device so no
other steps are required to install an appliance in the home network.
ISI devices may support plug-touch-and-play installation, in which case some
minimal user interaction is required to either join a network or create a
connection. The interaction may be with a user interface device such as a user
interface panel. Alternatively, the interaction may be with the devices
themselves. For example, the user may push a button on a device to create a
connection. This button is called the
to the user using an LED, called the
Connect button and light on each switch and each lamp actuator. In this
example, the user selects switches and lights to be connected by pressing the
Connect buttons on the devices to be connected.
On a simple device, the Connect button may be the same as the Service button,
and the Connect light may be the same as the Service light. In this case, the
same button may be used to join an ISI network, join a managed network, join a
connection, and to restore the device’s self-installation data to factory defaults.
More complex devices may require multiple Connect buttons and lights. For
example, a device that supports multiple manual connections to multiple devices,
may use multiple Connect buttons and lights that are not shared with the Service
button and light.
plug-and-play
Connect light
or
plug-touch-and-play
Connect button
. A lighting system may have a
installation. For
. Feedback may be provided
ISI Types
There are two types of ISI networks—
networks, and
ISI-S, more complex topologies, and unique domain IDs. An ISI-DA network
must include one or more
devices in an ISI-DA network must be ISI-DA compatible. The DAS devices are
present to help manage the ISI-DA network. The protocol implemented by the
domain address servers is called the
servers do not take on the full roll of network management servers. Instead, they
are only used to coordinate assignment of unique domain IDs and to maintain an
estimate of network size to optimize use of available channel bandwidth.
ISI-DA
for self-installed networks that support more devices than
domain address server (DAS)
ISI-S
for simple and standalone ISI
devices, and all the
ISI-DAS
protocol. The domain address
ISI Messages
The ISI protocol defines a standard set of messages that are used to coordinate
the installation of devices in an ISI network. The ISI engine that is part of the
ISI library automatically generates and processes most ISI messages. It is
sometimes useful to view ISI messages when debugging an ISI application. The
ISI Developer’s Kit includes an ISI Packet Monitor application that you can use
ISI Programmer’s Guide 8
during development for capturing and interpreting ISI messages. The ISI Packet
Monitor application is described in
Implementation
this section. All of the ISI messages are described and documented in the
Protocol Specification
in Chapter 4. A few of the key ISI messages are introduced in
. Following are a few of the most important ISI messages:
Developing and Debugging the ISI
ISI
Device Resource Usage Message (DRUM)
•
broadcast by all ISI devices. It includes the physical address (Neuron
ID), logical address (domain, subnet, node IDs), non unique ID, and
channel type for the device. The extended version of this message adds a
device class and usage field for use in device tracking. You can enable
the extended version by passing isiFlagExtended into IsiStart*() (see
Starting and Stopping Self-Installation
Connection Status Messages (CSMs)
•
create, maintain, and delete connections. There are multiple types of
connection status messages, including messages to manually create a
new connection (CSMO), automatically create a new connection (CSMA
and CSMR), and delete a connection (CSMD). The CSMO, CSMA, and
CSMR messages include the group ID, primary functional profile,
primary network variable type and direction, variant number, and
number of network variables for an offered connection. Devices that
receive these messages can use the information—plus optional user
interaction—to determine whether or not to join the connection. The
extended version adds fields to determine if the connection is
acknowledged or polled, the scope of the connection and parts of the
program id, and the primary network variable member. You can enable
the extended version by passing isiFlagExtended into IsiStart*() (see
Starting and Stopping Self-Installation
Timing Guidance Message (TIMG)
•
broadcast by all domain address servers. It includes information about
network size and latency. It is an optional message, but if available, ISI
devices use this information to schedule all periodic message based on
network size. This ensures efficient use of the channel bandwidth and
minimizes the overhead of the ISI protocol
—this message is periodically
—this message is periodically
in Chapter 2).
—this group of messages is used to
in Chapter 2).
ISI Limits
This section describes ISI limits. Some of the limits depend on options selected
by your device application, and some depend on which ISI library you choose to
link with your application. The ISI libraries and features of each are described in
Optimizing the Footprint of ISI Applications
need to know the resulting limits for your devices. Guidelines for documenting
these limits will be available at
www.echelon.com/isi.
. Those who use your devices will
Device Count Limits
ISI networks support up to 32 devices for ISI-S networks and up to 200 devices
for ISI-DA networks. ISI networks will not immediately stop functioning if these
limits are exceeded. Increasing the number of devices over the supported limits
9 ISI Programmer’s Guide
increases the network bandwidth consumed for administrative ISI messages,
possibly preventing regular network operation due to an increased collision rate.
Networks should be designed with some headroom. A reasonable limit is 80%.
ISI-S networks that reach 26 devices should be considered for an upgrade to ISIDA (which might be as simple as adding a DAS), and ISI-DA networks exceeding
160 devices are prime candidates for an upgrade to a managed LNS network.
Channel Types and Limits
The supported channel types for the ISI protocol are PL-20 power line and
TP/FT-10 free topology twisted pair.
The maximum channel limit for a device using the IsiCompactManual or
IsiCompactAuto library is one channel. For devices using any of the other
libraries, the limit is two channels. ISI-DAS devices always support two
channels.
The IsiCompactManual and IsiCompactAuto libraries are provided for featurelimited implementations of ISI devices with minimum memory footprint. The
functionality of the ISI libraries is described in
Applications
.
Optimizing the Footprint of ISI
Supported Topology and Routers
ISI-S networks are limited to a single channel that is segmented with physical
layer repeaters according to the standard channel properties—none for PL-20
channels, or multiple for TP/FT-10 channels provided there is never more than
one physical layer repeater between any two points of communication. In other
words, you can have one N-way repeater, much in the way of an N-port Ethernet
hub. A physical layer repeater is similar to a hub (signal booster without
filtering logic).
ISI-DA networks can have one or two channels. ISI-DA networks with two
channels must include a router configured as a repeater. Each channel must
meet the same requirements as a channel for ISI-S without a DAS described
above. The router must be preconfigured to be compatible with ISI networks, or
otherwise capable of joining an ISI network.
If a domain address server is used in a two-channel network with a PL-20 and
TP/FT-10 channel, it should be located on the PL-20 channel. One of the
functions of the domain address server is to determine the slowest channel of the
network that it is located on. If a domain address server is located on the PL-20
channel, it will start-up with knowledge of the slowest channel. If it is located on
the TP/FT-10 channel, it will have to learn of the existence of the PL-20 channel
by discovering one of the PL-20 devices. This may take some time. Conversely, if
the domain address server is located on the TP/FT-10 channel and all PL-20
devices are removed from the network, the domain address server should be reset
to relearn the network topology.
ISI Programmer’s Guide 10
ISI does not support redundant routers, and the user is responsible for avoiding
looping topologies. The network topologies described in this section will not
cause looping topologies.
Connection Complexity
A single device can join multiple connections; limited by available address, alias,
and connection table space on the device. Devices can map one or more network
variables to a single selector, but it is the device's responsibility to ensure that at
most one input network variable is mapped to a single selector. The number of
network variables in any given connection and on any single device is only
limited by device resources (alias, address, and connection table space).
Connections can include an unlimited number of devices. Devices supporting
aliases (those not built with the IsiCompactManual or IsiCompactAuto library)
can extend connections; that is, a single network variable on a device can join
multiple connections at the same time. Devices using the IsiCompactManual or
IsiCompactAuto libraries cannot extend connections (no support for aliases) and
cannot replace or remove connections (no support for removal) other than by
returning the device to factory settings. A standard mechanism is supported
with each ISI device to return to factory defaults.
Identification of Connections
Connections are established using a process called
accept a connection invitation and join a connection on the basis of a single
network variable type alone. For example, a device can choose to join a
connection that uses a SNVT_switch network variable. A device may accept a
connection invitation and join a connection on the basis of a single functional
block. For example, a device can choose to join a connection that offers data from
a SFTPclosedLoopSensor functional block with the SNVT_xxx output
implemented as a SNVT_amp network variable.
that can be understood (and accepted or refused) solely by knowledge derived
from the standard resource file set. Enrollment procedures that require
additional knowledge are collectively named
although such a connection may not be limited to a single manufacturer. For
example, a group of manufacturers may share knowledge required in the
understanding (accepting) of those connections. The complexity of manufacturerspecific connections is unlimited (but cannot exceed 63 selectors, and should not
exceed 4 selectors). For example, a single manufacturer-specific open enrollment
message can contain a number of different standard and non-standard functional
profiles. The simple case of a manufacturer-specific connection allows enrollment
of user network variables and profiles.
Address Table Size
Neuron C applications should maximize the address table size using the
#num_addr_table_entries compiler directive. The maximum size for Neuron C is
15. Even though most ISI devices require fewer address table entries when selfinstalled, implementing a 15-entry address table if space is available allows for
versatile and complex connections when used in a managed network.
enrollment
Standard connections
. A device may
are those
manufacturer-specific connections
,
11 ISI Programmer’s Guide
When used in a self-installed network, an ISI device will typically only require
one address table entry for each group it can join. Since the ISI application has
complete control over the groups it might belong to (by means of the
IsiGetAssembly(), IsiGetNextAssembly(), and IsiCreateCsmo() overrides), the
maximum size address table can be determined by the application developer.
This is not the case in a managed network, where a 15-entry address table is
normally required for flexible use of a device.
Alias Table Size
When designing an application that is to be used in a managed network, a rule of
thumb is to declare a minimum number of alias table entries of at least
Z
, with A and Z being 3 or 5 and
application. You can declare a maximum of 62 aliases. This rule-of-thumb often
provides a good size estimate, although you may have a better understanding of
the expected alias table requirements based on analysis of typical use-cases and
expected connection scenarios for the device.
The IsiCompactManual and IsiCompactAuto libraries do not support aliases, and
therefore do not use the alias table at all. In these cases, declaring an alias table
following the above guidelines is recommended to allow for use of the device in a
managed network.
Other ISI libraries support aliases, and allocate alias table entries each time an
ISI connection is extended (using the IsiExtendEnrollment() function call). One
alias table entry is typically required for each network variable that is associated
with the assembly that is used with the IsiExtendEnrollment() function, unless
the assembly is not yet bound at that time. An API is provided to determine the
connection status of a given assembly (IsiIsConnected() function), and a function
is provided to determine the number of remaining, unused, alias table entries
(IsiGetFreeAliasCount()). The number of IsiExtendEnrollment() calls made for
the same assembly over time cannot be predetermined (unless the application
never calls this function, and never accepts automatic enrollment). For those
applications, the above rule-of-thumb is recommended for a reasonable minimum
alias table size.
NVs
equal to the number of NVs declared by the
A
+
NVs
/
Automatic enrollment always calls IsiExtendEnrollment(), unless the ISI library
does not support connection extensions. In this case, IsiCreateEnrollment() is
used instead.
Domain Table Size
The domain table holds two entries by default. This is the required minimum
size of the domain table for an ISI device. If you use the #num_domain_entries
compiler directive to construct an ISI application that implements just one
domain table entry, the device will not function correctly. The error log contained
in the device will report an invalid_domain (138) error, resulting from an attempt
to start the ISI engine with less than two domain table entries.
ISI Programmer’s Guide 12
Earshot Problems
Open media such as power line may experience occasional communication
outages due to interference from other power line devices or neighboring
networks. In addition, an open media device may receive packets from devices
using the same media in neighboring networks. The ISI protocol handles
transient communication outages gracefully: when devices fail to recognize
network problems or changes to network address or connection information due
to transient outages, devices will recover once the outage has come to an end.
Occasional and unexpected receipt of network data from distant sites will cause
no harm, but if this possibility exists, a domain address server and ISI-DA can be
used to logically isolate the networks and prevent inadvertent connections
between devices in neighboring networks. Critical processes such as device and
domain ID acquisition are protected with a user-confirmed protocol, preventing
devices from being hijacked by other sites in earshot.
The following table shows a summary of key limits:
Limit Value Notes
Maximum device count ISI-S 32
Recommended maximum device
count ISI-S
Maximum device count ISI-DA 200
Recommended maximum device
count ISI-DA
Maximum number of network
variables per device
Maximum number of aliases per
device
Maximum number of
connections per device
26
160
254
254, optional
Limited by
device
resources, but
cannot exceed
254
See text on previous page.
Devices may contain
larger numbers of NVs or
aliases, but those with an
index > 254 cannot be
used with an ISI network.
If an ISI device is moved
to a managed network, it
can reveal extra
functionality with
additional NVs and
aliases.
The ISI libraries provide a
default implementation of
an ISI connection table
with 8 entries, but the
application may override
this with a larger or
smaller table.
Maximum number of connection
assemblies per device
13 ISI Programmer’s Guide
254
This is determined by the
NV maximum, but cannot
exceed 254.
Limit Value Notes
Maximum number of selectors
per assembly
Recommended maximum
number of selectors per
assembly
63
4
ISI and Energy Storage Devices
In simple devices, such as a light or a switch, a common implementation uses an
energy storage power supply, as described in the
Power Line Smart Transceiver Data Book
supply can be referred to as an
certain worst-case circumstances, the maximum packet size that can be sent is
limited. ISI implements two versions of DRUM, CSMO, CSMA, and CSMR
messages (See
The normal version is short enough to be sent by an energy storage device, and is
restricted to usage with standard network variable types and standard functional
profiles only. Since energy storage devices can receive any length message, they
can only host connections that use SNVTs and SFPTs, but can join a connection
that uses UNVTs and UFPTs. Compound assemblies that are based on a single
functional profile and hosted on an energy storage device also need to start with
member 1.
ISI Messages
energy storage device
in this chapter and the
. A device using this type of power
PL 3120, PL 3150 and PL 3170
. In these devices, under
ISI Protocol Specification
).
The extended versions of these messages contain additional functionality, but
result with the message potentially being too long to be transmitted by an energy
storage device. The extended message types do not have the limitations
summarized above.
By default, the ISI engine recognizes all supported message types, but will only
issue the shorter versions of the DRUM, CSMO, CSMA, and CSMR messages. To
enable the use of the extended DRUMEX, CSMOEX, CSMAEX, and CSMREX
messages, specify
All ISI devices may use the standard message formats if the functionality
provided by the extended formats is not required, but energy storage devices may
not use the extended formats. Energy storage devices may be capable of
successful transmission of the extended messages under certain conditions.
However, this should not be relied upon, since these conditions include the
momentary line condition and part tolerance details that cannot be relied upon
for mass production.
ISI domain address servers for power line channels cannot be built with energystorage power supplies. These devices would fail to transmit DIDRM and DIDCF
messages under worst-case conditions (line voltage, line impedance, and part
tolerances).
isiFlagExtended
when starting the ISI engine.
ISI Programmer’s Guide 14
2
Quick Start
This chapter provides a quick start for ISI developers. The
source code for a simple ISI application is described.
The code examples used in this document do not describe a
complete application and are provided as example code only.
Example code is not optimized for code size or performance.
Any code used from this document should be tested with
your application and you may be able to reduce code size by
optimizing the code for your application. See the ISI Web
page at
examples.
www.echelon.com/isi for complete working ISI
15 ISI Programmer’s Guide
Example ISI Application
Most of the ISI protocol is implemented by the
ISI engine
that is part of the ISI
library, and much of the related application development is to make calls to the
ISI engine’s API and override some of the ISI engine’s default implementations
with application-specific versions.
The ISI engine sends and receives ISI messages and manages the network
configuration of your device. You can create a simple ISI application by starting
the ISI engine, periodically calling the ISI engine, and processing any messages
that arrive. The following program is an example of a simple ISI application that
performs these tasks:
when (timer_expires(isiTimer)) {
// Call the ISI engine to perform periodic tasks
IsiTickS();
}
when (msg_arrives) {
if (IsiApproveMsg()) {
// Process an incoming ISI message
(void) IsiProcessMsgS();
}
}
The first line includes a required compiler directive, followed by the standard
isi.h header file. This file specifies the available ISI library functions. These
functions are described in the rest of this guide.
The first when task is the reset task. In this task, a call to the IsiStartS() library
function initializes and starts the ISI engine. For ongoing maintenance, the
second when task periodically calls the IsiTickS() function 4 times each second.
Finally, the last when task identifies incoming application messages as ISI
messages with the IsiApproveMsg() library function, and processes them with the
IsiProcessMsgS() function.
To build an ISI application, you must link the application with one of the ISI
libraries as described in
Optimizing the Footprint of ISI Applications
in Chapter
5.
ISI Programmer’s Guide 16
3
Self-Installation Basic
Procedures
This chapter describes the basic ISI procedures that will be
implemented by most ISI applications. Chapter 5 describes
more advanced procedures. The functions described in this
chapter are further described in Appendices B and C and the
data structures used by these functions are documented in
Appendix A.
17 ISI Programmer’s Guide
Starting and Stopping Self-Installation
void IsiPreStart(void);
Type
void IsiStart(IsiType
void IsiStartS(IsiFlags Flags);
void IsiStartDA(IsiFlags Flags);
void IsiStartDAS(IsiFlags Flags);
void IsiStop(void);
void IsiIsRunning(void);
You can start and stop the ISI engine. The ISI engine sends and receives ISI
messages and manages the network configuration of your device. You will
typically start the ISI engine in your reset task when self-installation is enabled,
and you will typically stop the ISI engine when self-installation is disabled.
You can use the IsiStart() function to start the ISI engine using any ISI type.
You can use specialized versions of the IsiStart() function to minimize the
memory footprint of your application. Devices that only support a single ISI type
may use one of the following functions:
•IsiStartS()—starts the ISI engine for a device that does not support
domain acquisition.
, IsiFlags
Flags
);
•IsiStartDA()—starts the ISI engine for a device that supports domain
acquisition, but is not a domain address server.
•IsiStartDAS()—starts the ISI engine for an ISI-DAS application that
supports domain acquisition and is a domain address server.
For PL 3170 devices, you must call the IsiPreStart() function from the
when(reset) task before calling any other ISI functions. This function establishes
the runtime links between the ISI engine in the read-only memory (ROM) of a PL
3170 Smart Transceiver and the callbacks in the application. You must call this
function even if you do not plan to start the ISI engine.
The IsiPreStart() function is supported only for PL 3170 devices, and is not
supported for other device types.
You can stop the ISI engine by calling the IsiStop() function. When you stop the
ISI engine, callbacks into the application will no longer occur. Most ISI functions
that the application might invoke, such as the IsiTickS() function introduced
earlier, have a benign behavior when the engine is stopped. The application need
not track the engine’s state therefore, and may make the same set of ISI API
calls in any state. The behavior of each ISI function in the idle state is described
later in this document. The IsiIsRunning() function may be called at any time
and returns a non-zero value if the engine is running.
All ISI devices must have a standard way to enable and disable self-installation.
This enables self-installed devices to be installed into managed networks as
described in Chapter 6. To provide this interface, include a SCPTnwrkCnfg
configuration property implemented as a configuration network variable that
ISI Programmer’s Guide 18
applies to your application’s Node Object functional block, if available, or applies
to the entire device if there is no Node Object functional block. The configuration
property has two values—CFG_LOCAL and CFG_EXTERNAL. When set to
CFG_LOCAL, your application can enable self installation. When set to
CFG_EXTERNAL, your application must disable self installation. Network
management tools automatically set this value to CFG_EXTERNAL to prevent
conflicts between self-installation functions and the network management tool.
Implementing a SCPTnwrkCnfg CP
See
for more details.
To maximize compatibility with network management tools used for managed
networks, insert an 800 millisecond to one-and-a-half second delay before calling
any of the IsiStart() functions. This delay can be implemented with a call to the
delay() or scaled_delay() function, other application processing, or a combination
of application processing plus a call to the delay() or scaled_delay() function.
Without this delay, a network tool may fail to confirm a state change when
commissioning the device for the first time, or for the first time after a change to
the device’s application.
XAMPLE 1
E
The following example declares a SCPTnwrkCnfg configuration property that
applies to the device, tests its value on startup, waits for 800ms, and starts
the ISI engine without support for domain acquisition.
when (reset) {
if (cpNetConfig == CFG_LOCAL) {
scaled_delay(31745UL); // 800ms delay
IsiStartS(isiFlagNone);
}
}
See Implementing a SCPTnwrkCnfg CP for more important
considerations.
Implementing Periodic Services
void IsiTick(IsiType
void IsiTickS(void);
void IsiTickDa(void);
void IsiTickDas(void);
You must periodically call the IsiTick() function after you have started the ISI
engine as described in the previous section. You should call this function
approximately every 250ms. You can use a timer task to implement the periodic
service.
19 ISI Programmer’s Guide
Type
);
If your device supports a single ISI type, you can use one of the three specialized
versions of the IsiTick() function to minimize the memory footprint of your
application.
The IsiTick() and IsiTickDas() functions are not supported for PL 3170 devices.
XAMPLE
E
The following example calls the IsiTickS() function every 250ms:
You can determine if an incoming message is an ISI message, and you can pass
all ISI messages to the ISI engine for processing. To determine if a message is an
ISI message, call the IsiApproveMsg() function. This function returns a non-zero
value if the incoming message is an ISI message and the ISI engine is running.
To process an ISI message, call one of the IsiProcessMsg()
functions. If the
IsiProcessMsg() function returns FALSE, then the message has been recognized.
You can use the IsiProcessMsg() function to process an ISI message on a device
that supports multiple ISI types. If your device supports a single ISI type, you
can use one of the three specialized versions of the IsiProcessMsg() function to
minimize the memory footprint of your application.
The IsiProcessMsg() functions pass the received message to the ISI engine, which
handles all of the processing. You can perform any application-specific
processing for the received message before calling the IsiProcessMsg() function.
Domain address servers need to use the IsiApproveMsgDas() function to approve
an incoming message. This is necessary for the device acquisition process
watching for service pin messages. Domain address servers also need to
implement the IsiProcessResponse() function. Not using either of these functions
will cause the domain or device acquisition processes to fail. Both
IsiApproveMsgDas() and IsiProcessResponse() share the same return values as
IsiApproveMsg() and IsiProcessMsg(), respectively.
ISI Programmer’s Guide 20
E
XAMPLE 1
The following example for a device without domain acquisition tests for
incoming ISI messages, and calls IsiProcessMsgS() to process them:
when (msg_arrives) {
if (IsiApproveMsg() && IsiProcessMsgS()) {
// TODO: process unprocessed ISI messages here (if any)
} else {
// TODO: process other application messages here (if any)
}
}
EXAMPLE 2
The following partial DAS example tests for incoming ISI messages and
responses on a domain address server. For a complete implementation of a
DAS device, the IsiStartDas() and IsiTickDas() functions must also be called
at a minimum.
when (msg_arrives) {
if (IsiApproveMsgDas() && IsiProcessMsgDas()) {
// TODO: process unprocessed ISI messages here (if any)
} else {
// TODO: process other application messages here (if any)
}
}
when (resp_arrives) {
if (IsiProcessResponse()) {
// TODO: process unprocessed responses here (if any)
}
}
Acquiring a Domain Address
void IsiAcquireDomain(boolean
void IsiStartDeviceAcquisition(void);
void IsiCancelAcquisition(void);
void IsiCancelAcquisitionDas(void);
void IsiFetchDomain(void);
void IsiFetchDevice(void);
There are three methods to assign a domain to an ISI device:
1. The domain may be fixed and assigned by the device application. All ISI
devices must initially support this method since an initial application
domain is assigned prior to acquiring a domain using one of the other
methods. This enables all devices to be used in an ISI-S network.
2. A device that supports domain acquisition can acquire a unique domain
address from a domain address server. If a domain address server is not
available, domain acquisition will fail and the ISI engine will continue to
use the most recently assigned domain (initially, the default domain).
Devices that support domain acquisition also support multiple,
redundant, domain address servers. Domain address acquisition is
initiated by the user and controlled by the device acquiring the domain,
SharedServicePin
);
21 ISI Programmer’s Guide
not the domain address server. This method allows the device to make
intelligent decisions about retries, preventing enrollment during the
domain acquisition. It also allows the device to increase automatic
enrollment performance following the completion of domain acquisition.
3. A domain address server can assign a domain to a device without a
request from the device. This minimizes the code required in the device,
and can be used with all devices. This process is called
4. A domain address server can fetch the domain from any of the devices in
a network and assign it to itself. This keeps multiple domain address
servers in a network synchronized with each other, or allows a
replacement domain address server to join an existing ISI network. This
process is called
A domain address server must support both methods 2, 3 and 4. It can allow a
device that supports domain acquisition to acquire a domain, it can fetch any ISI
device, and it can fetch a domain from another device.
A domain address server can fetch a domain from any device in the network to be
joined. To install a replacement domain address server, or to install redundant
domain address servers into an existing, previously configured, network, each
domain address server can query the current domain configuration from any
previously configured device in the network. This is called
and this process is typically initiated by the user via the newly installed domain
address server.
fetching a domain
.
fetching a device
fetching a domain
,
.
The following table summarizes the first three procedures:
Acquire Domain Fetch Device Fetch Domain
Description
Initiated on
Code required
Devices that
support domain
acquisition use
this procedure to
obtain a unique
domain address
from a domain
address server
Device after
enabling device
acquisition on
the domain
address server
On device and on
domain address
server
A domain address
server assigns a
unique domain
address to an ISI
device
Domain address
server
On domain address
server
A domain address
server acquires the
domain from
another previously
installed device in
the network
Domain address
server
On domain address
server
ISI Programmer’s Guide 22
Key advantage
Active process—
device is in
control of
proceedings and
aware of success
or failure
Supports
installation of
replacement or
redundant domain
address servers
Acquiring a Domain Address from a Domain Address
Server
To acquire a domain address from a domain address server, start the ISI engine
using the IsiStartDA() function, or using the IsiStart() function with the
isiTypeDa type.
A domain address server must be in device acquisition mode to respond to
domain ID requests. To start device acquisition mode on a domain address
server, call the IsiStartDeviceAcquisition() function.
To start domain acquisition on a device that supports domain acquisition, call the
IsiAcquireDomain() function.
A typical implementation starts the domain acquisition process when the
Connect button is activated and a domain is not already assigned. If
SharedServicePin is set to FALSE, the IsiAcquireDomain() function also issues a
standard service pin message—this allows using the same installation paradigm
in both a managed and an unmanaged environment. If the application uses the
physical service pin to trigger calls to the IsiAcquireDomain() function, the
system image will have issued a service pin message automatically, and the
SharedServicePin flag should be set to TRUE in this case.
When calling IsiAcquireDomain() with SharedServicePin set to FALSE while the
ISI engine is not running, a standard service pin message is issued nevertheless,
allowing the same installation paradigm and same application code to be used in
both self-installed and the managed networks.
After domain acquisition has been enabled by calling IsiStartDeviceAcquisition()
on the domain address server and it has been started on the device by calling
IsiAcquireDomain(), the device responds to the isiWink ISI event with a visible or
audible response. For example, a device may flash its LEDs. The user confirms
that the correct device executed its wink routine and the DAS application then
confirms the device by calling IsiStartDeviceAcquisition() once again. Once
confirmed, the domain address server grants the unique domain ID to the device.
The device notifies its application with ISI events accordingly.
23 ISI Programmer’s Guide
DeviceDAS
IsiAcquireDomain()
starts domain acquisition
and sends the DIDRQ
domain request message
Collect all domain response
messages for 1.5s
Application receives isiWink
event and provides visual or
audible feedback to the user
Respond to the DIDRQ
domain request message
with a DIDRM domain
response message
IsiStartDeviceAcquisition() signals that
the user confirmed acquisition of the
correct device via a Connect button or
other user interface
Respond to user confirmation by
sending a DIDCF domain
confirmation message to device
Device joins
domain as
advised by DAS
The device automatically cancels domain acquisition if it receives multiple, but
mismatching, domain response messages in step 4. This may happen if multiple
domain address servers with different domain addresses are in device acquisition
mode, and all respond to the device’s query.
Devices should support the domain acquisition process whenever possible (device
resources permitting) over the Fetch Device process described below—the domain
acquisition process provides a more robust process with features such as
automatic retries and other desirable side effects, like automatic connection
reminders.
The IsiCancelAcquisition() function causes a device to leave domain acquisition
mode. The cancellation applies to both device and domain acquisition. After this
function call is completed, the ISI engine calls IsiUpdateUserInterface()with the
IsiNormal event. On a domain address server, use the IsiCancelAcquisitionDas()
function instead.
ISI Programmer’s Guide 24
E
XAMPLE 1
The following example starts domain acquisition mode on a domain address
server when the user presses a Connect button on the server:
when (connect_button_pressed) {
IsiStartDeviceAcquisition();
}
Once started, the domain address server remains in this state for 5 minutes
unless cancelled with an IsiCancelAcquisitionDas() call. Each successful
device acquisition retriggers this timeout.
XAMPLE 2
E
The following example starts domain acquisition on a device when the user
pushes a Connect button on the device:
when (connect_button_pressed) {
IsiAcquireDomain(FALSE);
}
Fetching a Device from a Domain Address Server
A domain address server can use the IsiFetchDevice() function to assign the DAS’
unique domain ID to any device. Unlike the IsiAcquireDomain() function, the
IsiFetchDevice() function does not require any action, or special library code, on
the device. To fetch a device, call the IsiFetchDevice() function on the domain
address server.
DAS devices must make this feature available to the user. With this feature, it is
not required that devices support domain acquisition in order to participate in an
ISI network that uses unique domain IDs.
Similar to the domain acquisition process detailed above, fetching a device also
requires a manual confirmation step to ensure that the correct device is paired
with the correct domain address server:
25 ISI Programmer’s Guide
DeviceDAS
Send Service
Pin message
Respond to Wink
message with suitable
audible or visual
feedback
User confirms correct
device selection by
sending a second
Service Pin message
IsiFetchDevice()
starts device
fetching
Respond to Service
Pin message by
sending Wink
message
Respond to matching
Service Pin message by
assigning local domain
E
XAMPLE 3
to remote device
The following example fetches a device on a domain address server when the
user presses the Connect button on the server:
when (connect_button_pressed) {
IsiFetchDevice();
}
//Handle responses to requests in IsiFetchDevice()
when (resp_arrives) {
if (IsiProcessResponse()) {
// TODO: process unprocessed responses here (if any)
}
}
Fetching a Domain for a Domain Address Server
A domain address server can use the IsiFetchDomain() function to obtain a
domain ID. Unlike the IsiAcquireDomain() function, the IsiFetchDomain()
process does not require a domain address server to provide the domain ID
information, and does not use the DIDRM, DIDRQ, and DIDCF standard ISI
messages. Instead, the domain address server uses the IsiFetchDomain()
ISI Programmer’s Guide 26
function to obtain the current domain ID from any device in the network, even
from those that only implement ISI-S, or that do not implement or execute ISI at
all. This is typically used when installing replacement or redundant domain
address servers in a network: a domain address server will normally use the
IsiGetPrimaryDid() override to specify a unique, non-standard, primary domain
ID. A replacement domain address server, or a redundant domain address
server, needs to override this preference by using the domain ID that is actually
used in the network. This is provided with the IsiFetchDomain() function.
DeviceDAS
IsiFetchDomain()
starts domain
fetching
Send Service
Pin message
Respond to Service
Pin message by
sending Wink
message
Respond to Wink
message with suitable
audible or visual
feedback
User confirms correct
device selection by
sending a second
Service Pin message
Respond to matching
Service Pin message by
assigning remote
domain to local device
27 ISI Programmer’s Guide
E
XAMPLE 3
The following example fetches a domain on a domain address server when
the user presses the Connect button on the server:
when (connect_button_pressed) {
IsiFetchDomain();
}
//Handle responses to requests in IsiFetchDomain()
when (resp_arrives) {
if (IsiProcessResponse()) {
// TODO: process unprocessed responses here (if any)
}
}
If no unambiguous domain ID is already present on the network, the domain
address server will use its default domain ID, as advised with the
IsiGetPrimaryDid() callback, as a unique domain ID.
Enrolling in a Connection
You can exchange data between devices by creating
variables on the devices. Connections are like virtual wires, replacing the
physical wires of traditional hard-wired systems. A connection defines the data
flow between one or more output network variables to one or more input network
variables. The process of creating a self-installed connection is called
Inputs and outputs join a connection during open enrollment, much like students
join a class during open enrollment. This section describes the ISI connection
model and describes the procedures required to create a connection.
ISI Connection Model
Connections are created during an
user, a connection controller, or a device application. Once initiated, a device is
selected to open enrollment—this device is called the
in a connection may be the connection host—the connection host is responsible
for defining the open enrollment period and for selecting the connection address
to be used by all network variables within the connection. Connection address
assignment and maintenance is handled by the ISI engine, and is transparent to
your application.
Even though any device in a connection may be the connection host, if you have a
choice of connection hosts, network resource utilization will be optimized if you
pick the natural hub as the connection host. For example, in a connection with
one switch and multiple lights, the switch is the natural hub. In a connection
with one light and multiple switches, the light is the natural hub. If there is no
natural hub—multiple switches connected to multiple lights for example—using
one of the devices with an output network variable will optimize network
resource utilization.
open enrollment
connections
between network
enrollment
period that is initiated by a
connection host
. Any device
.
ISI Programmer’s Guide 28
Loading...
+ 129 hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.