Echelon ISI Manual do Utilizador

ISI Programmer’s GuideVersion 3 078-0299-01F

ISI Programmer’s Guide 8 Installing ISI Devices ISI devices may support plug-and-play or plug-touch-and-play installation. For plug-and-play insta

ISI Programmer’s Guide 98 To identify the smallest possible ISI implementation that meets your application needs, start with the leftmost column (I

99 ISI Programmer’s Guide IsiTick(), because using these functions causes the linker to include the more specific functions (including the DAS func

ISI Programmer’s Guide 100

101 ISI Programmer’s Guide 7 Transitioning between Managed and Self-Installed Networks This chapter describes how you can transition a self-install

ISI Programmer’s Guide 102 You can upgrade a network from a self-installed network to a managed network. You may do this to add non-ISI devices to

103 ISI Programmer’s Guide Appendix A API Data Types This appendix describes the data types used by the ISI library. Byte offset values shown ref

ISI Programmer’s Guide 104 ConnDesc Structure Contains details describing a connection. Used in the IsiConnection structure. Data Type Field Name

105 ISI Programmer’s Guide Byte offset Data Type Field Name Note N unsigned [5] UniqueId A unique identifier for the connection host, based o

ISI Programmer’s Guide 106 Byte offset Data Type Field Name Note N IsiCid Cid See IsiCid. N+7 unsigned long Selector Selector value 0 – 0x2F

107 ISI Programmer’s Guide IsiControl Value Note isiExtend 3 Extend a connection by calling IsiExtendEnrollment() using the assembly number passe

9 ISI Programmer’s Guide during development for capturing and interpreting ISI messages. The ISI Packet Monitor application is described in Develo

ISI Programmer’s Guide 108 IsiCsmi Structure Defines an enrollment information message (CSMI) sent by the ISI engine. Byte offset Data Type Field

109 ISI Programmer’s Guide Byte offset Data Type Field Name Note N unsigned Group The group (or device category) this connection applies to.

ISI Programmer’s Guide 110 Byte offset Data Type Field Name Note N+5 unsigned Variant Variant number for the offered connection. Variants ma

111 ISI Programmer’s Guide Byte offset Data Type Field Name Note N+6 unsigned : 2 Extended. Scope Scope of the resource file containing the fu

ISI Programmer’s Guide 112 The byte offset N is 10 for the IsiCsmoData structure used with ISI message types (IsiCsmo structure), and is zero when

113 ISI Programmer’s Guide IsiDiagnostic Value Note isiSubnetNodeAllocation 1 A local subnet/node ID has been allocated. isiSubnetNodeDuplicate

ISI Programmer’s Guide 114 Byte Offset Data Type Field Name Note 2 unsigned [6] Did Domain ID. This field is always 6 bytes long; the number

115 ISI Programmer’s Guide IsiEvent Value Note isiDirectionAny 2 Indicates that both input and output network variables may be applicable to this

ISI Programmer’s Guide 116 Byte Offset Data Type Field Name Note 18 unsigned long Extended.DeviceClass Value from the Device Class standard prog

117 ISI Programmer’s Guide IsiEvent Value Note isiCancelled 5 Connection has been cancelled by a timeout, user, or network action. The parameter

ISI Programmer’s Guide 10 increases the network bandwidth consumed for administrative ISI messages, possibly preventing regular network operation d

ISI Programmer’s Guide 118 IsiFlags Value Note isiFlagExtended 0x01 Enables the use of the extended DRUMEX, CSMOEX, CSMAEX, and CSMREX messages.

119 ISI Programmer’s Guide IsiMessage Structure Contains the header and body of an ISI protocol message. These messages are typically sent using I

ISI Programmer’s Guide 120 IsiMessageCode Value Note isiDidrm 0x09 Domain ID response isiDidcf 0x0A Domain ID confirmation isiTimg 0x0B Timing gui

121 ISI Programmer’s Guide IsiRdct Structure Defines a read connection table (RDCT) request message used for controlled enrollment. Byte offset Da

ISI Programmer’s Guide 122 IsiScope Value Note isiScopeManufacturer 3 Indicates that Profile and NvType values refer to user-defined scope 3 – 5 re

123 ISI Programmer’s Guide Appendix B API Functions This appendix describes the functions provided by the ISI library. Important: To minimize it

ISI Programmer’s Guide 124 IsiAcquireDomain() void IsiAcquireDomain(boolean SharedServicePin); Starts or re-starts the domain ID acquisition proces

125 ISI Programmer’s Guide IsiApproveMsgDas() boolean IsiApproveMsgDas(void); Determines if an incoming message is an ISI or service pin message by

ISI Programmer’s Guide 126 This function has no effect unless the ISI engine is running and the device is either in device or domain acquisition mo

127 ISI Programmer’s Guide Calling this function on a device that does not support connection removal while indicating an assembly number that is a

11 ISI Programmer’s Guide ISI does not support redundant routers, and the user is responsible for avoiding looping topologies. The network topolog

ISI Programmer’s Guide 128 IsiExtendEnrollment() void IsiExtendEnrollment(unsigned Assembly); Accepts a connection invitation on a device that supp

129 ISI Programmer’s Guide IsiFetchDevice() void IsiFetchDevice(void); Fetches a device by assigning a domain to the device from a domain address s

ISI Programmer’s Guide 130 To use the IsiFetchDomain() function, you must implement a when (resp_arrives) task and call the IsiProcessResponse() fu

131 ISI Programmer’s Guide selector, and rejects the open enrollment message if insufficient network variable aliases are available to meet that as

ISI Programmer’s Guide 132 IsiInitiateAutoEnrollment() void IsiInitiateAutoEnrollment(const IsiCsma* pCsma, unsigned Assembly); Starts automatic en

133 ISI Programmer’s Guide IsiIsRunning() boolean IsiIsRunning(void); Returns TRUE if the ISI engine is running and FALSE if the ISI engine is stop

ISI Programmer’s Guide 134 IsiMsgDeliver() void IsiMsgDeliver(IsiMessage* pMsg, unsigned Length, msg_out_addr* pDestination); Sends an ISI message

135 ISI Programmer’s Guide IsiPreStart() void IsiPreStart(void); Establishes runtime links between the ISI engine in the read-only memory (ROM) of

ISI Programmer’s Guide 136 IsiReturnToFactoryDefaults(); // Call NEVER returns! } // Self-installed network--start the ISI engine

137 ISI Programmer’s Guide IsiProcessResponse() boolean IsiProcessResponse(void); Processes a response to a request message sent in the domain acqu

ISI Programmer’s Guide 12 When used in a self-installed network, an ISI device will typically only require one address table entry for each group i

ISI Programmer’s Guide 138 cpNwrkConfig = OldNetConfig; if (cpNwrkConfig == CFG_NUL) { // For the first application start, set nciNetConfi

139 ISI Programmer’s Guide When selecting one of the specialized versions IsiStartS(), IsiStartDA(), or IsiStartDAS(), you must make sure to use th

ISI Programmer’s Guide 140 IsiStop() void IsiStop(void); Stops the ISI engine. Use one of the IsiStart() functions to re-start the ISI engine. The

141 ISI Programmer’s Guide Appendix C Callback Functions This appendix describes the callback functions that your application may provide for the

ISI Programmer’s Guide 142 IsiCreateCsmo() void IsiCreateCsmo(unsigned Assembly, IsiCsmoData* pCsmoData); Constructs the IsiCsmoData portion of a C

143 ISI Programmer’s Guide EXAMPLE The following example sends a periodic message: boolean SendApplicationPeriodic = FALSE; boolean IsiCreatePerio

ISI Programmer’s Guide 144 IsiGetConnection() const IsiConnection* IsiGetConnection(unsigned Index); Returns a pointer to an entry in the connectio

145 ISI Programmer’s Guide You must override the IsiSetConnection() and IsiGetConnection() functions if you override the IsiGetConnectionTableSize(

ISI Programmer’s Guide 146 IsiGetNextNvIndex() unsigned IsiGetNextNvIndex(unsigned Assembly, unsigned Offset, unsigned Previous); Returns the netwo

147 ISI Programmer’s Guide IsiGetPrimaryDid() const unsigned* IsiGetPrimaryDid(unsigned* pLength); Returns a pointer to the default primary domain

13 ISI Programmer’s Guide Earshot Problems Open media such as power line may experience occasional communication outages due to interference from o

ISI Programmer’s Guide 148 IsiGetWidth() unsigned IsiGetWidth(unsigned Assembly); Returns the width in the specified assembly. The width is equal

149 ISI Programmer’s Guide You must override the IsiGetConnection() and IsiGetConnectionTableSize() functions if you override the IsiSetConnection(

ISI Programmer’s Guide 150 IsiUpdateUserInterface() void IsiUpdateUserInterface(IsiEvent Event, unsigned Parameter); Provides status feedback from

151 ISI Programmer’s Guide Appendix D ISI Router Configuration This appendix provides information for preparing a LONWORKS router for use with an

ISI Programmer’s Guide 152 LONWORKS Routers and ISI Networks To prepare a LONWORKS router for use with an ISI network, configure the device as foll

153 ISI Programmer’s Guide Appendix E Glossary This appendix defines the key ISI terms.

ISI Programmer’s Guide 154 Term Definition Application message An ANSI/CEA-709.1 (EN14908-1) message with a message code in the range of 0 to 62.

155 ISI Programmer’s Guide Term Definition controller to specify the devices to be connected. Domain Address Server (DAS) A device present in ISI-

ISI Programmer’s Guide 156 Term Definition Network management The act of putting network configuration data into a persistent store (typically a da

www.echelon.com

ISI Programmer’s Guide 14 Limit Value Notes Maximum number of selectors per assembly 63 Recommended maximum number of selectors per assembly 4

15 ISI Programmer’s Guide 2 Quick Start This chapter provides a quick start for ISI developers. The source code for a simple ISI application is d

ISI Programmer’s Guide 16 Example ISI Application Most of the ISI protocol is implemented by the ISI engine that is part of the ISI library, and mu

17 ISI Programmer’s Guide 3 Self-Installation Basic Procedures This chapter describes the basic ISI procedures that will be implemented by most ISI

Echelon, LONWORKS, Neuron, NodeBuilder, LonMaker, 3120, 3150, and the Echelon logo are trademarks of Echelon Corporation registered in the United Sta

ISI Programmer’s Guide 18 Starting and Stopping Self-Installation void IsiPreStart(void); void IsiStart(IsiType Type, IsiFlags Flags); void IsiStar

19 ISI Programmer’s Guide applies to your application’s Node Object functional block, if available, or applies to the entire device if there is no

ISI Programmer’s Guide 20 If your device supports a single ISI type, you can use one of the three specialized versions of the IsiTick() function to

21 ISI Programmer’s Guide EXAMPLE 1 The following example for a device without domain acquisition tests for incoming ISI messages, and calls IsiPro

ISI Programmer’s Guide 22 not the domain address server. This method allows the device to make intelligent decisions about retries, preventing enr

23 ISI Programmer’s Guide Key advantage Active process— device is in control of proceedings and aware of success or failure Passive process, suppor

ISI Programmer’s Guide 24 Device DASIsiStartDeviceAcquisition() enters device acquisition modeIsiAcquireDomain() starts domain acquisition and send

25 ISI Programmer’s Guide EXAMPLE 1 The following example starts domain acquisition mode on a domain address server when the user presses a Connect

ISI Programmer’s Guide 26 Device DASIsiFetchDevice() starts device fetchingSend Service Pin messageRespond to Service Pin message by sending Wink m

27 ISI Programmer’s Guide function to obtain the current domain ID from any device in the network, even from those that only implement ISI-S, or th

1 ISI Programmer’s Guide Introduction This guide describes how you can use Interoperable Self-Installation (ISI) to create networks of control

ISI Programmer’s Guide 28 EXAMPLE 3 The following example fetches a domain on a domain address server when the user presses the Connect button on t

29 ISI Programmer’s Guide A connection host opens enrollment by sending a connection invitation. Once a connection host opens enrollment then any

ISI Programmer’s Guide 30 the application. Standard ISI profiles that define multiple assemblies must specify the order the assemblies are to be a

31 ISI Programmer’s Guide Opening Enrollment void IsiOpenEnrollment(unsigned Assembly); void IsiCreateCsmo(unsigned Assembly, IsiCsmoData* pCsmoDat

ISI Programmer’s Guide 32 function uses the IsiGetPrimaryGroup() function to obtain the associated group ID, and sets all fields to zero except the

33 ISI Programmer’s Guide EXAMPLE 1 The following example opens automatic enrollment: void IsiUpdateUserInterface(IsiEvent Event, unsigned Paramete

ISI Programmer’s Guide 34 } } EXAMPLE 4 The following example opens manual enrollment for a compound assembly with four selectors. The isiGetW

35 ISI Programmer’s Guide when (msg_arrives) { IsiMessage inMsg; unsigned myAssembly; if (IsiApproveMsg()) { memcpy(&inMsg, msg_in.data,

ISI Programmer’s Guide 36 ISI_DEFAULT_GROUP, // Group isiDirectionVarious, // NV direction 4, // Width 3251, // Profile nu

37 ISI Programmer’s Guide Applications need not distinguish between regular and extended incoming messages. You can provide feedback to the user wh

ISI Programmer’s Guide 2 Overview Control networks consist of intelligent devices like switches, thermostats, pumps, motors, valves, controllers, a

ISI Programmer’s Guide 38 Accepting a Connection Invitation void IsiCreateEnrollment(unsigned Assembly); void IsiExtendEnrollment(unsigned Assembly

39 ISI Programmer’s Guide You can eliminate this additional resource usage by deleting and re-creating a connection instead of extending it. You ca

ISI Programmer’s Guide 40 // drive the ISI-related LED: switch(isiState) { ... case isiApproved: case isiApprovedHost: SetConne

41 ISI Programmer’s Guide Implementing a Connection In a manual or controlled enrollment, when a connection host sends a connection invitation by b

ISI Programmer’s Guide 42 // (CSME) message. IsiCreateEnrollment(Assembly); break; ... // Processing for other states } //

43 ISI Programmer’s Guide IsiCreateEnrollment() or IsiExtendEnrollment()), or simply do nothing. The pending assembly remains pending until the en

ISI Programmer’s Guide 44 IsiEvent Value Note isiNormal 0 The ISI engine has returned to the normal, or idle, state for an assembly. The relate

45 ISI Programmer’s Guide IsiEvent Value Note isiWarm 7 The ISI engine has warmed up (i.e. a predetermined time with a random component has pass

ISI Programmer’s Guide 46 The following figure summarizes the typical sequence of events for a connection host using manual or controlled enrollmen

47 ISI Programmer’s Guide You can get more detailed ISI diagnostic events. These events are useful for debugging ISI applications and are not ty

3 ISI Programmer’s Guide This guide presents a library for Neuron® C—called the Neuron C ISI library—to create interoperable self-installed devices

ISI Programmer’s Guide 48 IsiDiagnostic Value Note isiSubnetNodeAllocation 1 A local subnet/node ID has been allocated. isiSubnetNodeDuplicate

49 ISI Programmer’s Guide EXAMPLE The following example deinstalls a device after the service pin is held for a long period: when (timer_expires(S

ISI Programmer’s Guide 50 Implementing a SCPTnwrkCnfg CP ISI applications must implement a SCPTnwrkCnfg configuration property that is implemented

51 ISI Programmer’s Guide 4 Quick Start, Revisited This chapter revisits the quick start example in Chapter 1 to add connection enrollment support

ISI Programmer’s Guide 52 Here is the quick start example from Chapter 1: #include <isi.h> when (reset) { // Clear all tables and start

53 ISI Programmer’s Guide void IsiUpdateUserInterface(IsiEvent event, unsigned parameter) { if (event == isiPending

ISI Programmer’s Guide 54 DeviceState Connection Host Response to Connect Button isiApprovedHost Yes An approved connection host is one that ha

55 ISI Programmer’s Guide case isiNormal: if (longPress) { IsiDeleteEnrollment(assembly); } else {

ISI Programmer’s Guide 56

57 ISI Programmer’s Guide 5 Developing and Debugging an ISI Application This chapter describes how to develop and debug applications using the Neur

ISI Programmer’s Guide 4 Table of Contents Introduction...

ISI Programmer’s Guide 58 General Considerations You can develop applications for the Neuron C ISI library using the NodeBuilder® 3.1 Development T

59 ISI Programmer’s Guide To enable debugging with the managed environment provided by the NodeBuilder and LonMaker tools, you must ensure that an

ISI Programmer’s Guide 60 since the different allocation algorithms used for managed and self-installed connections could result in duplicate resou

61 ISI Programmer’s Guide 6 Self-Installation Advanced Procedures This chapter describes advanced ISI procedures that are not typically used by al

ISI Programmer’s Guide 62 Overriding a Callback Function You can have the ISI engine call functions in your application in response to key ISI even

63 ISI Programmer’s Guide Function Name Reason to Override IsiGetAssembly() This function should be overridden for applications with compound asse

ISI Programmer’s Guide 64 Function Name Reason to Override IsiGetNextAssembly() This function should be overridden when providing for compound ass

65 ISI Programmer’s Guide Function Name Reason to Override IsiSetConnection() This function must be overridden when implementing a custom connecti

ISI Programmer’s Guide 66 in order to simplify development; however, most developers will tailor the ISI implementation by overriding the default i

67 ISI Programmer’s Guide Library Functions with Forwarders Forwarders are implemented in a way that eliminates any overhead for the indirection; t

5 ISI Programmer’s Guide Self-Installation Advanced Procedures ... 61 Ov

ISI Programmer’s Guide 68 IsiGetNvIndex(), and IsiGetWidth() handle connections of simple assemblies referring to a single network variable of a st

69 ISI Programmer’s Guide With that knowledge, an accepting device that implements a SFPTclosedLoopActuator functional block must associate S1 with

ISI Programmer’s Guide 70 // and a compatible network variable type return Y; } ... } unsigned IsiGetNvIndex(unsigned Assembly,

71 ISI Programmer’s Guide 2. Connection host enrolls local, normal, output network variable: direction(CSMOEX) = isiDirectionInput or isiDirectio

ISI Programmer’s Guide 72 formatted as a network variable update. Include an explicit address for the message with addressing details from an appl

73 ISI Programmer’s Guide Neuron ID to be tracked must be discovered and written to the addressTracking variable when a connection invitation is ac

ISI Programmer’s Guide 74 The connection table contains one entry for each simple connection the device has joined, and for each simple extension t

75 ISI Programmer’s Guide #define CONTABSIZE 16u static IsiConnection connectionBuffer; unsigned IsiGetConnectionTableSize(void) { return CONT

ISI Programmer’s Guide 76 deleted devices, monitor the time of the last update for each entry in the table and detect devices that have not recentl

77 ISI Programmer’s Guide // Iterate through the device table again and decrement the // credits at each call of IsiCreatePeriodicMsg(), removing a

ISI Programmer’s Guide 6 IsiDiagnostic Enumeration ... 112 IsiDidcf Struc

ISI Programmer’s Guide 78 request, and then repeats the process on the remaining devices. To accelerate device discovery, follow these steps: 1.

79 ISI Programmer’s Guide msg_out.dest_addr.bcast.rpt_timer = ENCODED_RPT_TIMER; msg_out.dest_addr.bcast.retry = RETRY_COUNT; msg_out.

ISI Programmer’s Guide 80 Creating a Connection with Controlled Enrollment You can create a connection from a connection controller using controlle

81 ISI Programmer’s Guide unsigned assembly) { IsiMessage request; msg_out_addr destination; request.Header.Code = isiCtrq; request

ISI Programmer’s Guide 82 break; case enrolling: // Just one member for this example; close enrollment ControlCommand(controlJo

83 ISI Programmer’s Guide The RDCT message includes optional host and member assembly fields that specify which connection table entries are reques

ISI Programmer’s Guide 84 request.Msg.Rdct.Index = recoveryJob.index++; request.Msg.Rdct.Host = request.Msg.Rdct.Member = ISI_NO_ASSEMBLY;

85 ISI Programmer’s Guide // connection table index provided. void SendConnectionTableResponse(unsigned index, boolean success) { IsiMessage

ISI Programmer’s Guide 86 } Sending an NV Update or Polling an NV from a Controller You can send an individual network variable update to, or poll

87 ISI Programmer’s Guide EXAMPLE 1 The following example sends a network variable fetch message to a device with a specified NV index, subnet ID,

7 ISI Programmer’s Guide IsiGetConnection() ... 144 IsiGetC

ISI Programmer’s Guide 88 EXAMPLE 2 The following example sends an explicit network variable update to a device in the device table created in the

89 ISI Programmer’s Guide msg_out.code = NM_opcode_base | (NM_query_nv_cnfg & NM_opcode_mask); msg_out.service = REQUEST; msg_out.

ISI Programmer’s Guide 90 monitored device changes. Controlled and automatic enrollment both address responsiveness by supporting event-driven upd

91 ISI Programmer’s Guide device to a peer-to-peer connection. To support controlled enrollment, the controller must maintain a device description

ISI Programmer’s Guide 92 for the device and all devices that it is connected to using the isiOpen and isiCreate requests. To support controlled en

93 ISI Programmer’s Guide 2. If the device supports automatic enrollment for monitoring and but does not support connection extension, the device

ISI Programmer’s Guide 94 You can use periodic processing in the ISI engine to schedule and send periodic heartbeat updates for any of the output n

95 ISI Programmer’s Guide this function; just set the application-specific flag if there is a message to send and return control to the ISI engine

ISI Programmer’s Guide 96 IsiFull This library contains the complete feature set as defined in this document. The IsiFull library may require devi

97 ISI Programmer’s Guide IsiCompactSHb This library supports the same features as the IsiCompactS library, with the addition of support for networ