Echelon ISI User Manual

ISI Programmer’s Guide

Version 3

078-0299-01F

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.

Echelon Corporation www.echelon.com

Introduction

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.

(or newer), and sign

ONMARK Certified Products Logo

3 ISI Programmer’s Guide

Introduction........................................................................................................................... 1

Overview ............................................................................................................... 2

Changes since Revision 2 .................................................................................... 3

Table of Contents ................................................................................................. 4

Installing ISI Devices .......................................................................................... 8

ISI Types............................................................................................................... 8

ISI Messages......................................................................................................... 8

ISI Limits.............................................................................................................. 9

Device Count Limits .................................................................................... 9

Channel Types and Limits ........................................................................ 10

Supported Topology and Routers.............................................................. 10

Connection Complexity.............................................................................. 11

Identification of Connections .................................................................... 11

Address Table Size..................................................................................... 11

Alias Table Size.......................................................................................... 12

Domain Table Size ..................................................................................... 12

Earshot Problems....................................................................................... 13

ISI and Energy Storage Devices ....................................................................... 14

Quick Start.......................................................................................................................... 15

Example ISI Application ................................................................................... 16

Self-Installation Basic Procedures ..................................................................................... 17

Starting and Stopping Self-Installation ........................................................... 18

Implementing Periodic Services........................................................................ 19

Handling an Incoming Message........................................................................ 20

Acquiring a Domain Address............................................................................. 21

Acquiring a Domain Address from a Domain Address Server................ 23

Fetching a Device from a Domain Address Server .................................. 25

Fetching a Domain for a Domain Address Server ................................... 26

Enrolling in a Connection.................................................................................. 28

ISI Connection Model ................................................................................ 28

Opening Enrollment .................................................................................. 31

Receiving an Invitation ............................................................................. 36

Accepting a Connection Invitation............................................................ 38

Implementing a Connection ...................................................................... 41

Canceling a Connection ..................................................................................... 42

Deleting a Connection........................................................................................ 43

Handling ISI Events .......................................................................................... 43

Deinstalling a Device ......................................................................................... 48

Recovering from a Programming Error ............................................................ 49

Declaring Network Variable Arrays ................................................................. 49

Using the run_unconfigured Compiler Directive............................................. 49

Implementing a SCPTnwrkCnfg CP................................................................. 50

Quick Start, Revisited......................................................................................................... 51

Developing and Debugging an ISI Application.................................................................. 57

General Considerations ..................................................................................... 58

Developing and Debugging the Application............................................. 58

Developing and Debugging the ISI Implementation............................... 58

ISI Programmer’s Guide 4

Self-Installation Advanced Procedures .............................................................................. 61

Overriding a Callback Function........................................................................ 62

Forwarders ......................................................................................................... 65

Assembly Number Allocation ............................................................................ 67

Supporting Compound Assembly Connections ................................................ 67

Creating a Polled Connection............................................................................ 70

Creating an Acknowledged Connection............................................................ 71

Turnaround Connections................................................................................... 73

Customizing the ISI Connection Table............................................................. 73

Getting ISI Version Information....................................................................... 75

Discovering Devices ........................................................................................... 75

Accelerating Device Discovery .......................................................................... 77

Creating a Connection with Controlled Enrollment........................................ 80

Recovering Connections..................................................................................... 82

Sending an NV Update or Polling an NV from a Controller........................... 86

Monitoring Data from a Controller and Designing Devices for Monitoring . 89

Polling......................................................................................................... 90

Controlled Enrollment............................................................................... 90

Automatic Enrollment ............................................................................... 92

Selecting a Monitoring Method................................................................. 93

Sending Periodic Heartbeats............................................................................. 93

Sending Application-Specific Periodic Messages ............................................. 94

Optimizing the Footprint of ISI Applications .................................................. 95

IsiFull ......................................................................................................... 96

IsiCompactAuto.......................................................................................... 96

IsiCompactManual..................................................................................... 96

IsiCompactS ............................................................................................... 96

IsiCompactSHb .......................................................................................... 97

IsiCompactDa............................................................................................. 97

IsiCompactDaHb........................................................................................ 97

All Compact Libraries................................................................................ 97

IsiPl3170..................................................................................................... 98

Transitioning between Managed and Self-Installed Networks........................................101

API Data Types ..................................................................................................................103

ConnDesc Structure......................................................................................... 104

IsiAbortReason Enumeration.......................................................................... 104

IsiCid Structure................................................................................................ 104

IsiConnection Structure .................................................................................. 105

IsiConnectionHeader Structure ...................................................................... 105

IsiConnectionState Enumeration ................................................................... 106

IsiControl Enumeration................................................................................... 106

IsiCsma Structure............................................................................................ 107

IsiCsmc Structure ............................................................................................ 107

IsiCsmd Structure............................................................................................ 107

IsiCsme Structure ............................................................................................ 107

IsiCsmi Structure............................................................................................. 108

IsiCsmo Structure ............................................................................................ 108

IsiCsmoData Structure.................................................................................... 108

IsiCsmr Structure ............................................................................................ 112

IsiCsmx Structure............................................................................................ 112

IsiCtrp Structure.............................................................................................. 112

IsiCtrq Structure.............................................................................................. 112

5 ISI Programmer’s Guide

IsiDiagnostic Enumeration ............................................................................. 112

IsiDidcf Structure ............................................................................................ 113

IsiDidrm Structure .......................................................................................... 113

IsiDidrq Structure............................................................................................ 114

IsiDirection Enumeration................................................................................ 114

IsiDrum Structure ........................................................................................... 115

IsiEvent Enumeration ..................................................................................... 116

IsiFlags Enumeration ...................................................................................... 117

IsiMessage Structure ....................................................................................... 119

IsiMessageCode Enumeration......................................................................... 119

IsiMessageHeader Structure........................................................................... 120

IsiRdcs Structure ............................................................................................. 120

IsiRdct Structure.............................................................................................. 121

IsiScope Enumeration...................................................................................... 121

IsiTimg Structure............................................................................................. 122

IsiType Enumeration ....................................................................................... 122

API Functions ....................................................................................................................123

IsiAcquireDomain().......................................................................................... 124

IsiApproveMsg() ............................................................................................... 124

IsiApproveMsgDas()......................................................................................... 125

IsiCancelAcquisition()...................................................................................... 125

IsiCancelAcquisitionDas() ............................................................................... 125

IsiCancelEnrollment()...................................................................................... 126

IsiCreateEnrollment()...................................................................................... 126

IsiDeleteEnrollment() ...................................................................................... 127

IsiExtendEnrollment()..................................................................................... 128

IsiFetchDevice()................................................................................................ 129

IsiFetchDomain() ............................................................................................. 129

IsiGetFreeAliasCount().................................................................................... 130

IsiImplementationVersion() ............................................................................ 131

IsiInitiateAutoEnrollment() ............................................................................ 132

IsiIsBecomingHost()......................................................................................... 132

IsiIsConnected() ............................................................................................... 132

IsiIsRunning() .................................................................................................. 133

IsiIssueHeartbeat() .......................................................................................... 133

IsiLeaveEnrollment() ....................................................................................... 133

IsiMsgDeliver()................................................................................................. 134

IsiMsgSend()..................................................................................................... 134

IsiOpenEnrollment() ........................................................................................ 134

IsiPreStart()...................................................................................................... 135

IsiProcessMsg() ................................................................................................ 136

IsiProcessResponse()........................................................................................ 137

IsiProtocolVersion().......................................................................................... 137

IsiReturnToFactoryDefaults()......................................................................... 137

IsiStart() ........................................................................................................... 138

IsiStartDeviceAcquisition() ............................................................................. 139

IsiStop()............................................................................................................. 140

IsiTick()............................................................................................................. 140

Callback Functions ............................................................................................................141

IsiCreateCsmo() ............................................................................................... 142

IsiCreatePeriodicMsg() .................................................................................... 142

IsiGetAssembly() .............................................................................................. 143

ISI Programmer’s Guide 6

IsiGetConnection() ........................................................................................... 144

IsiGetConnectionTableSize()........................................................................... 144

IsiGetNextAssembly()...................................................................................... 145

IsiGetNextNvIndex()........................................................................................ 146

IsiGetNvIndex()................................................................................................ 146

IsiGetPrimaryDid() .......................................................................................... 147

IsiGetPrimaryGroup()...................................................................................... 147

IsiGetRepeatCount() ........................................................................................ 147

IsiGetWidth().................................................................................................... 148

IsiQueryHeartbeat()......................................................................................... 148

IsiSetConnection()............................................................................................ 148

IsiSetDomain() ................................................................................................. 149

IsiUpdateDiagnostics() .................................................................................... 149

IsiUpdateUserInterface()................................................................................. 150

ISI Router Configuration...................................................................................................151

LONWORKS Routers and ISI Networks........................................................ 152

Glossary..............................................................................................................................153

7 ISI Programmer’s Guide

Installing ISI Devices

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

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

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

, 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

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

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

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

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:

#pragma num_alias_table_entries 6 #include <isi.h>

when (reset) { // Clear all tables and start the ISI engine scaled_delay(31745UL); // 800ms delay IsiStartS(isiFlagNone); }

mtimer repeating isiTimer = 1000ul / ISI_TICKS_PER_SECOND;

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

ISI Programmer’s Guide 16

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

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.

network input SCPTnwrkCnfg cp cp_info(reset_required, device_specific) cpNetConfig;

device_properties { cpNetConfig = CFG_EXTERNAL };

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

The following example calls the IsiTickS() function every 250ms:

#include <isi.h>

mtimer repeating isiTimer = 1000ul / ISI_TICKS_PER_SECOND;

when (timer_expires(isiTimer)) { IsiTickS(); }

Handling an Incoming Message

boolean IsiApproveMsg(void);

Type

boolean IsiProcessMsg(IsiType

boolean IsiProcessMsgS(void);

boolean IsiProcessMsgDa(void);

boolean IsiProcessMsgDas(void);

boolean IsiApproveMsgDas(void);

boolean IsiProcessResponse(void);

);

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

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

Passive process, supporting resourcerestricted device implementations

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

Device DAS

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

IsiStartDeviceAcquisition() enters device acquisition mode

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

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

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

Device DAS

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

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.

Device DAS

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

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

+ 129 hidden pages