i.LON® SmartServer 2.
Echelon, LON, LONWORKS, LonTalk, Neuron, LONMARK, 3120, 3150, LNS, LonMaker, and the Echelon logo are trademarks of Echelon Corporation registered in the United States and other countries. LonPoint and LonSupport are trademarks of Echelon Corporation. Other brand and product names are trademarks or registered trademarks of their respective holders.
Table of Contents 1 Introduction to the SmartServer SOAP/XML Interface ............... 1-1 1.1 1.2 1.3 1.4 2 About This Document ......................................................................1-1 Programming Samples ....................................................................1-2 Getting Started ................................................................................1-2 SmartServer SOAP/XML Interface Upgrades .................................1-2 1.4.1 Version 4.
3.4.5 Write Functions..........................................................................3-7 3.4.6 Delete Functions........................................................................3-7 3.5 Performance Issues.........................................................................3-7 4 Using the SmartServer Data Server ............................................. 4-1 4.1 4.2 4.3 Creating and Modifying the Data Point XML Files...........................4-2 Overview of the Data Point XML File .
8.2 8.3 9 Creating and Modifying the Analog Functional Block XML File...........8-2 Analog Functional Block SOAP Interface........................................8-2 8.3.1 Using the List Function on an Analog Functional Block ............8-2 8.3.2 Using the Get Function on an Analog Functional Block............8-3 8.3.3 Using the Set Function on an Analog Functional Block ..........8-12 8.3.4 Using the Delete Function on an Analog Function Block ........8-13 Scheduler.....................................
14 LONWORKS Driver ......................................................................... 14-1 14.1 LONWORKS Networks.....................................................................14-1 14.1.1 Using the List Function on a LONWORKS Network.................14-1 14.1.2 Using the Get Function on a LONWORKS Network ................14-1 14.1.3 Using the Set Function on a LONWORKS Network.................14-5 14.1.4 Using the Delete Function on a LONWORKS Network..........14-11 14.2 LONWORKS Channels......
16.1.1 Using the List Function on M-Bus Channels .........................16-1 16.1.2 Using the Get Function on M-Bus Channels .........................16-1 16.1.3 Using the Set Function on M-Bus Channels .........................16-4 16.1.4 Using the Delete Function on M-Bus Channels ....................16-5 16.2 M-Bus Devices ..............................................................................16-6 16.2.1 Using the List Function on M-Bus Devices............................16-6 16.2.
20 Using the SOAP Interface as a Web Service ............................. 20-1 20.1 Referencing and Inheriting from the WSDL...................................20-1 20.1.1 Referencing and Inheriting from the WSDL Using .NET 3.5 Framework ...................................................20-1 20.1.2 Referencing and Inheriting from the WSDL Using .NET 2.0 Framework ...................................................20-6 20.2 Instantiating and Initializing the Web Service Client ...................20-11 20.2.
22.1.1 Installing Echelon SmartServer JAX-ES Programming Example ..........................................................22-1 22.1.2 Installing Eclipse IDE for Java EE Developers......................22-1 22.1.3 Installing the Java Development Kit ......................................22-1 22.1.4 Installing Maven 2.2.1............................................................22-1 22.1.5 Setting System Environment Variables .................................22-2 22.2 Creating a JAX-WS Client ............
i.LON SmartServer 2.
1 Introduction to the SmartServer SOAP/XML Interface The SmartServer contains a powerful microprocessor with a real-time, multi-tasking operating system that manages its various applications. These applications include alarming, scheduling, data logging and network variable type translation. Generally, you will configure these applications with the SmartServer Web pages, as described in the i.LON SmartServer 2.0 User’s Guide. The i.LON SmartServer 2.
Echelon strongly recommends that you use the SOAP interface to configure the applications of your SmartServer. The SmartServer performs error-checking on all data written in a SOAP message, so that invalid data will not be written to any of the XML files. The SmartServer will not perform error-checking on any XML files downloaded to it via FTP, and so manually editing the XML files may cause errors during the boot process.
introduced for the e2 release, and the version 3.0 namespace was introduced for the e3 release. Support for the different namespaces as follows: • i.LON 100 servers running the Release 1.0 software only support the version 1.0 namespace. This means that a SmartServer running the Release 1.0 software can only respond to SOAP messages from other SmartServers running the Release 1.0 software. • i.LON 100 servers running the e2 software support the version 1.0 and 1.1 namespaces. This means that an i.
i.LON SmartServer 2.
2 SOAP Messages and the SmartServer WSDL File This chapter contains general information about the SOAP/XML interface you will need to know before using the SOAP functions described in this manual. It includes the following major topics: • SmartServer Naming Structure. The section describes how the SmartServer’s data configuration is organized. • SmartServer WSDL File. This section describes the version 4.0 WSDL file, which defines the SOAP/XML interface.
2.2 SmartServer WSDL File Each SmartServer includes two WSDL (Web Service Description Language) files: iLON100.wsdl and iLON100_System.wsdl. The iLON100.wsdl file defines most of the SmartServer SOAP/XML interface, and contains all the information an application will require to use the SOAP/XML interface. The iLON100_System.wsdl contains the system service methods used to check and configure the SmartServer’s settings.
2.4.1 SOAP Request PAGE 182.4.2 SOAP Response 2005-02-02T11:30:15.
2.5.1 SOAP Envelope The SOAP envelope is the highest level in a SOAP message. The SOAP envelope is the highest level of a SOAP message. The SOAP envelope for any message sent to the SmartServer must conform to the W3C SOAP 1.1 proposed Technical Recommendation: http://www.w3.org/TR/2000/NOTE-SOAP-20000508/. The SOAP envelope portion of the sample input message shown in section 2.3 includes the following: PAGE 20 A time stamp indicating when the message was sent. Per the ISO 8601 standard, the timestamp is in local time, with appended time zone indicators to denote the difference between local time and UTC. A unique identifier assigned to the SmartServer. By default, this is set to the third Neuron ID in the block of 16 Neuron IDs the SmartServer. You can define the unique ID. The IP address of the SmartServer that sent the SOAP message.
xSelectStatement - networkName/channelName/deviceName/functionBlockName/pointName Parameter1Value Parameter2Value ...
... PAGE 22 6 Instance doesn't exist Net/VirtCh/iLON App Example 3 (error occurs at the global level): PAGE 23Error Code 15 2.5.4 Error Description No Data Comment Namespace The namespace uniquely identifies message names, parameters, and types within the message call. On the SmartServer, the namespace identifier displays both the product name and the embedded software version. This enables a mechanism to distinguish the SOAP interface of different Echelon products and versions. To ensure that this string points to a unique name on the Internet, the namespace includes the echelon.com domain suffix.
Item_Data and Item_Cfg inherit from Item Because Item is the base class for all types passed in the Get /Set /Delete, Read /Write, and Invoke functions, you can pass any kind of configuration or state information in the corresponding message. Message Name Description Request Object Response Object List Retrieves a list of Items. xSelect Item_Coll Get Retrieves the configuration of items. Item_Coll Item_CfgColl Set Creates items or overwrites the configuration of existing items.
Collection type Item type of You can cast an item to a more specialized type using meta data (the xsi:type attribute) that is passed along with the application data. The xsi:type attribute describes the actual type of an item and is passed as an attribute of the - element. If the sent type is the expected base type (Item, Item_Cfg or, Item_Data), no xsi:type attribute is sent. For more information on xsi types, go to www.w3.org/TR/xmlschema-1/#Instance_Document_Construction. 2.5.
The following code samples demonstrate supported xSelect statements.
Example 9 – Select a formatter report: xSelect = "//Item[@xsi:type=”TemplateManager_NVT_Cfg”][UCPTlanguage="enu"] [UCPTname="#0000000000000000[0].standard"][position()>=0 and position()<10]" Notes: • For List functions, you must include an xSelect statement in the SOAP message request. • For Get, Delete, and Read functions, the xSelect statement in the SOAP message request is optional.
Driver 2.
Net/LON/iLON App/Data Logger[0]/nvoDlLevAlarm[0] #0000000000000000[0].SNVT_alarm 2.7 UCPTcurrentConfig Each application on the SmartServer stores the namespace version of the client that last set its configuration (via a Set function) its last configuration.
2.10.1 Configuration Data The following example demonstrates how to use a Get function to obtain the configuration of a data point on the Data Server (Dp_Cfg) using the unique of the data point. Request Message PAGE 31 1 ON 100.0 1
2.10.2 Web Binding You can use the WebBinder application on the SmartServer to send a SOAP message when a data point update occurs.
20 PAGE 33 0 - Net/LON/iLON App/Data Logger[0] 2008-04-08T11:30:00.062-07:00 2008-04-08T11:22:42.762-07:00 2008-04-08T11:30:00.
3 SmartServer Applications and the SOAP/XML Interface This chapter provides an overview of the applications supported by the SmartServer, and of how you can use the SOAP/XML interface to configure these applications and use the data they generate. This chapter includes the following major sections: • Overview of SmartServer Applications. This section provides a description of each of the applications that the SmartServer supports. • SmartServer XML Configuration Files.
manage these tasks. You can also create a Real-Time Cock to create events based on sunrise and sundown times. • 3.2 Type Translation. You can use the Type Translator application to translate data from one network variable data type to another. You will need to create Type Translators, and optionally Type Translator Rules, to translate your data. SmartServer XML Configuration Files The configuration of each SmartServer application is stored in an XML file.
3.3 SmartServer Resource Files There are many configuration properties you can configure with the SOAP functions described in this document. This document provides a general description of each property, and other information you will need when configuring each one, such as minimum and maximum values for scalar properties, and maximum string lengths for string properties. This information is also contained in the SmartServer resource files.
3.3.3 User-Defined Network Variable Type (UNVT) Device Resource Files Device manufacturers create UNVT device resource files to describe non-standard, manufacturer specific network variables. Using the same mechanisms as the standard resource files, these files describe how to format data from a particular manufacturer's device. On the SmartServer, you can find all device resource files in the /root/lonworks/types directory.
Precision – Single floats always use 7 digits of precision, including digits before and after the decimal point. Double floats always use 14 digits of precision. For the rest of the base types, precision is determined by the type definition Digit Grouping Symbol – Always comma "," Digit Grouping – Always in the form "123,456,789" Negative Sign Symbol – Always the minus sign "-" Negative Number Format – Always "-1.
3.4.2 Get Functions You can use the Get function to retrieve the configuration of any application instance or item that you have added to the SmartServer. For example, you could use the Get function to retrieve the configurations of the Alarm Generators, Data Loggers, Schedulers, and other application instances that have been added to the SmartServer.
3.4.4 Read Functions You can use the Read function to read the value, status, or priority of a data point on the Data Server (Dp_Cfg), read the entries in an alarm log or data log, and read the events scheduled in a Scheduler or Calendar. To use the Read function, you need to provide the of the item to be read. This could be a data point, or an Alarm Notifier, Data Logger, Scheduler, or Calendar functional block.
i.LON SmartServer 2.
4 Using the SmartServer Data Server The SmartServer’s internal Data Server is a software component that abstracts any data element of any bus into a data point. This enables the SmartServer’s built-in applications and your custom SmartServer Web pages to operate on these abstractions without regard of the device driver (e.g., LONWORKS, Modbus, M-Bus, Virtual, and Freely Programmable Module [FPM]).
Two of the most important properties in the Data Server for any data point are the and properties. The property represents the current status of the data point. The property represents the current value of the data point. The Data Server updates these properties in real time, and they are very useful to many SmartServer applications.
• The data points on the SmartServer’s internal automated systems device (i.LON App), which contains the functional blocks representing the SmartServer’s built-in applications, are stored in a Dp.xml file in the root/config/network/Net/LON/iLONApp directory on the SmartServer flash disk by default. • The data points for an external LONWORKS digital input/output device connected to the SmartServer might be stored in a Dp.
0 OFF 0.0 0 1 ON 100.0 1 4.3 Data Server SOAP Interface You can use the SOAP interface to perform the following functions on a data point on the Data Server.
You can use additional filters in the xSelect statement to return a specific set of data points on the Data Server. These filters include the data point’s and properties, and its position on the data server. Request (return all data points on the internal SmartServer automated systems device [i.LON App]) PAGE 47Alternatively, you can specify one or more data point properties such as in an xSelect statement to filter the items returned by the Get function. Note: You should not attempt to retrieve the configuration of more than 100 data points with a single call to the Get function. Request (return all SNVT_switch data points on the internal SmartServer automated systems device [i.LON App]) PAGE 48Property Description The name of the data point in the following format: . The direction of the data point (Dp_In, Dp_Out, or Dp_In_Out [unspecified]), and its xsi type, which corresponds to the bus on which the data point resides (e.g., LON_Dp_Cfg for a LONWORKS data point) . This determines the icon used to represent the data point in the navigation pane on the left side of the SmartServer Web interface.
Property Description standard (SNVT) format type included in the resource files on the SmartServer, or any user-defined (UNVT) format type included in resource files uploaded to the SmartServer. For more information on the resource files, see SmartServer Resource Files. If you do not set this property, it is set to RAW_HEX and the data point uses raw hex values.
Property Description function to edit the unit strings of data point fields. This read-only property is assigned to the data point automatically, and is based on the point’s . It defines the base type of the data point, as defined in the base_type_t enumeration in the BAS_Controller resource files for the SmartServer. This property specifies the maximum number of fields that the data point may have.
Property Description it exists for the data point type selected. This value represents the minimum value the data point can be updated to. Note: You can use the Set function to change this limit in the Data Server. However, you must program your application to enforce the new limit, as the SmartServer will continue to enforce the limit taken from the resource files. Optional. This value is initially taken from the i.LON 100 resource files, if it exists for the data point type selected.
or more - elements. Each
- element includes a property that specifies a unique data point to be created or modified. Each
- element may also include a series of properties that define the configuration of the new (or modified) data point within the Data Server. This set of properties is the same, whether you are creating a new data point or modifying an existing data point.
include the data point’s and properties and the position on the SmartServer. You can also use the in an xSelect statement to specify that the Read function return the data point values in raw hex or return the values of the fields within structured data points individually. Note: You cannot use the position () filter with in an xSelect statement that includes the filter.
Response 0 - Net/LON/iLON App/VirtFb/temp_thermostat Dp_In;xsi:type=“LON_Dp_Cfg” 0 2008-03-14T16:34:11.310-07:00 21.
Property Description A flag indicating whether the data point is hidden or shown in the navigation pane on the left side of the SmartServer Web interface. This property may have the following values: 0 – shown 1 – hidden A timestamp indicating the last time the configuration of the data point was updated. This timestamp uses the ISO 8601 format, which is as follows: YYYY-MM-DDTHH:MM:SS.sssZPhh:mm The current value in the data point.
• If is set to 0, the Data Server returns polls the data point and returns the updated value regardless how current the data point is. • If is disabled, the Data Server returns cached values regardless how old the data point values are. This is the default. 4.3.5 Using the Write Function on the Data Server A data point's value and priority level are initially set when the data point is added to the Data Server.
SC_RECALL 2 When you are writing to the fields of structured data points, you may also want to fill in the property. If you assign the default value 1 to this property, the change you make to the data point will be propagated to the network.
Response 0 - Net/LON/iLON App/VirtFb/nvoSwitch Dp_Out;xsi:type=“LON_Dp_Cfg” 0 85
4.3.
For example, consider a scenario where a SOAP application uses the Write function to write to the value of a data point called “nvoValue”. Assume that the last application to write to the value of nvoValue used priority level 75 when it updated the data point. In that case, the current application must use a priority value between 0 and 75 (inclusive) to successfully write a new value to the data point.
data point is still registered on its respective bus. The following code sample demonstrates how to use the Delete function to delete a data point on the Data Server: Request - Net/LON/iLON App/VirtFb/nvoSwitch
Response PAGE 61much slower (40 data point updates per second) than IP-852 connections (1,000 updates per second). • An LNS uplink binding is a connection between a SmartServer and an LNS Server. LNS uplink bindings replace the LNS uplink feature that was used in the e3 release for data point connections between an i.LON 100 e3 server and an LNS Server. • An enterprise binding is a connection between a SmartServer and a Webbinder Target Server.
Dp_In_WebBinding;xsi:type="Dp_Ref" 0 4.4.2 Using the Get Function on a Web Connection You can use the Get function to retrieve the configuration of any Web connection that you have added to the SmartServer’s Data Server.
Property Description The name of the source data point in the Web connection in following format: . The direction of the data point in the Web connection. This is always Dp_In_WebBinding. A flag indicating whether the source data point in the Web connection is hidden or shown in the navigation pane on the left side of the SmartServer Web interface.
Property Description Acknowledged messaging service (ST_WEB_ACK). This means that the sending device expects to receive confirmation from the receiving device that a data point update was delivered. The sending application is notified when an update fails, but it is up to the developer of the sending device to handle the notification in the device application. If you create a Web connection with the Set function, this property is optional. 4.4.3 • .
Request PAGE 665 Data Loggers You can use Data Loggers to monitor activity on your network. Each Data Logger will record updates to a group of user-specified data points into a log file. The information recorded for each update includes the value and status that the data point was updated to. Each SmartServer supports up to ten Data Loggers. The log files for each Data Logger are stored in the location specified by the Data Logger’s property.
- Net/LON/iLON App/Data Logger[0] 8000010128000000[4].UFPTdataLogger 0 2008-02-27T13:41:25.910-08:00 #8000010128000000[4].UFPTdataLogger_Cfg.
SmartServer will require a reboot to read the configuration of the downloaded file. Additionally, the SmartServer performs error checking on all SOAP messages it receives before writing to the XML file. It will not perform error checking on any XML files you download via FTP, and thus the application may not boot properly. However, if you plan to create and manage the #8000010128000000[4].UFPTdataLogger.
- Net/LON/iLON App/Data Logger[0] #8000010128000000[4].UFPTdataLogger;xsi:type=“LON_Fb_Cfg” 0 IS_NOTSYNCED
5.3.2 Using the Get Function on a Data Logger You can use the Get function to retrieve the configuration of any Data Logger that you have added to the SmartServer.
Property Description The name of the data logger in the following format: . The program ID and functional profile template used by the data logger. This property is always 8000010128000000[4].UFPTdataLogger. A flag indicating whether the data logger functional block is hidden or shown in the navigation pane on the left side of the SmartServer Web interface.
Property Description Either LT_HISTORICAL or LT_CIRCULAR. This indicates whether the log is a historical or circular. A historical data log stops recording data point updates when it is full. A circular data log removes older values when the log is full and it receives new updates. The amount of memory allocated to the log file, in kilobytes.
Property Description The path of the data log file on the SmartServer flash disk, relative to the /root/data folder and including the extension of the format. By default, a data log file is stored in the root/data/Net/LON/i.LON App (Internal) folder, and it is named Data Logger [x], where x is the index number of the Data Logger functional block. A Data Logger can record updates for multiple data points.
Property Description 214,748,364.0 seconds. The Data Logger will check for updates to the data point at this interval. If you do not want to poll data before updates to the log are possible, you should set this to a value greater than or equal to the value specified for the property.
Request - Net/LON/iLON App/Data Logger[3] #8000010128000000[4].UFPTdataLogger;xsi:type="LON_Fb_Cfg" 0 2008-02-28T11:53:57.930-08:00 LON_Fb_Cfg.
Request (data point updates recorded during a specific interval) //Item [UCPTlastUpdate>=" 2008-02-28T13:15:00.000+00:00"] [UCPTlastUpdate<=" 2008-02-28T13:20:00.360+00:00"] [position()> =last()-64][@xsi:type="UFPTdataLogger_Data"] - Net/LON/iLON App/Data Logger[3]
Response PAGE 76entries in the log file. A counter indicating the number of times the log file has been modified. The counter is not increased when data is added to the end of the log, but only if some modifications are made to the existing data. The volume of the log file that has been consumed, as a percentage. For example, the value 90.0 indicates that the log is 90% full.
5.3.4.1 Local Times and Coordinated Universal Time The timestamps for the and properties conform to the ISO 8601 standard. They are expressed in local time, with appended time zone indicators that show the relationship to the Coordinated Universal Time (UTC ). UTC is an international time standard and is the current term for what was commonly referred to as Greenwich Meridian Time (GMT).
2008-02-28T14:00:00.070-08:00 1 1.
6 Alarm Generator Use the Alarm Generator application to generate alarms based on the values of the data points in your network. Each time you create an Alarm Generator, you will select an input data point and a compare data point. The Alarm Generator will compare the values of these data points each time either one is updated. You will select the function the Alarm Generator will use to make the comparison.
- Net/LON/iLON App/Alarm Generator[0] 8000010128000000[4].UFPTalarmGenerator 0 2008-02-28T15:29:23.220-08:00 #8000010128000000[4].UFPTalarmGenerator_Cfg.
Get Retrieve the configuration of any Alarm Generator that you have added to the SmartServer. Set Create a new Alarm Generator, or overwrite the configuration of an existing Alarm Generator. Delete Delete an Alarm Generator. 6.3.1 Using the List Function on an Alarm Generator Use the List function to retrieve a list of the Alarm Generators that you have added to the SmartServer.
2008-02-28T15:45:26.060-08:00 #8000010128000000[4].UFPTalarmGenerator_Cfg.
Property Description deleted. In this case, it has the following values: IS_NOTSYNCED IS_DELETED A timestamp indicating the last time the configuration of the Alarm Generator was updated. This timestamp uses the following format: YYYY-MM-DDTHH:MM:SSZ The name of the file containing the configuration web page for the Alarm Generator on the SmartServer flash disk, absolute or relative to /web/user/echelon folder. This property is #8000010128000000[4].UFPTalarmGenerator_Cfg.
Property Description point every five seconds to ensure that each application gets a current value for each poll. It is important to note this as you set poll rates for various applications, as you may end up causing more polls than is efficient on your network.
Property Description Point – lowLimit2Offset The value entered for must be greater than that entered for , and the value entered for must be less than that entered for . The default value for each property is 0. If any of these properties are left empty, they will not be used to check for alarm conditions.
Property Description will be generated. The of this data point will be updated to the status AL_ALM_CONDITION when an alarm is generated, unless the selected for the Alarm Generator is FN_LIMIT. In this case, the status will be updated to any of four alarm statuses, based on the offset limit that caused the alarm. For more information on this, see Hysteresis Levels and Offset Limits.
Property Description e-mail messages each time they are updated to an alarm status. For more information on this, see Alarm Notifier. 6.3.2.1 Alarm Priority Levels You can select a priority level for the Alarm Generator by filling in the property. When doing so, you must reference each priority level with the identifier listed in the following table.
Identifier Description FN_NE Not equal. An alarm will be generated if the input value is not equal to the compare value. FN_LIMIT Compare against the limits defined by the high and low limit offset fields. For more information, see Hysteresis Levels and Offset Limits. Different comparison functions should be used for different data point types, depending on the of the data point.
Offset Limit Alarm Generated When....
Event Input Data Point Status Comments Value of input data point goes below hysteresis level for the second alarm condition. AL_HIGH_LMT_ALM1 Updated back to the first alarm condition, as the data point has not yet reached the hysteresis level for that condition. Value of input data point goes below hysteresis level for the first alarm condition. AL_NO_CONDITION Updated back to normal status. 6.3.
0.0 none FN_EQ 0.0 0.
i.LON SmartServer 2.
7 Alarm Notifier Use the Alarm Notifier application to log user-defined alarm conditions, and to generate e-mail messages and data point updates each time an alarm condition occurs. This section provides an overview of how Alarm Notifiers work, including how you can define alarm conditions and program your Alarm Notifiers to respond to them. User-Defined Alarm Conditions When you create an Alarm Notifier, you will specify a group of input data points.
In addition, the Alarm Notifier application generates a summary log that summarizes the log entries made by all the Alarm Notifiers that were classified as active alarms. This file is called sumlog0, and can also be found in the /root/AlarmLog directory of your SmartServer. You can create the log files in either a text format (.csv) or binary format (.dat). You will establish this when you create your Alarm Notifiers.
0 0 Alarm Notification user@echelon.
7.3 Alarm Notifier SOAP Interface You can use the SOAP interface to perform the following functions on an Alarm Notifier application: Function Description List Generate a list of the Alarm Notifiers that you have added to the SmartServer. Get Retrieve the configuration of any Alarm Notifier that you have added to the SmartServer. Set Create a new Alarm Notifier, or overwrite the configuration of an existing Alarm Notifier.
7.3.2 Using the Get Function on an Alarm Notifier You can use the Get function to retrieve the configuration of any Alarm Notifier that you have added to the SmartServer. You must reference the Alarm Notifier whose configuration is to be returned by its in the input you supply to the function, as shown in the example below. Request PAGE 98255 Online AL_NO_CONDITION 0 Mail[UCPTnickName=“Alarm Notification “] DataPoint[@dpType=“Output” and UCPTnickName=“Net/LON/iLON App/ Data Logger[0]/nviDlClear[0]”] ON 255
Property Description The name of the file containing the configuration web page for the Alarm Notifier on the SmartServer flash disk, absolute or relative to /web/user/echelon folder. This property is #8000010128000000[4].UFPTalarmNotifier_Cfg.htm by default.
Property Description An alarm notification will occur each time any of the input data points defined for an Alarm Notifier are updated, and the data point’s matches the status defined for any of the Alarm Notifier’s active or passive alarm condition sets. You can specify as many input data points as you like per Alarm Notifier.
Property Description Each element defines a group of active and passive alarm destinations the Alarm Notifier will use. The active destinations are signified by a list of child elements within the element. The passive destinations are signified by a list of child elements within the element. For a description of the properties that must be defined within each of these child elements, see Active and Passive Alarm Destinations.
Property Description sub-property in the element are described below: : When this property is set to 0, each new alarm will be recorded in the Alarm History Log when it initially occurs. No further entries will be recorded into the log for the alarm. When this property is set to 1, each new alarm will be recorded in the Alarm History Log when it initially occurs, and additional entries in the Alarm History Log will be added each time the status of the alarm changes.
Property Description The priority level to be assigned to the data point when it reaches an alarm condition. This must be an integer between 0 (high priority) and 255 (low priority). You can use priority levels to sort the alarms with the summary log view, or with the SmartServer Web pages. The default value is 0. A user-defined description of the alarm condition for this data point. This can be a maximum of 201 characters long. 7.3.2.
Property 7.3.2.2.1 Description The path of the attachment file that will be sent with the e-mails this profile sends. This must be a file path on the SmartServer flash disk. For example: /root/Data/log1.csv. The path can be a maximum of 1024 characters long. E-mail Variable Substitutions The following table lists the variable substitutions you can use to fill in the property within each mail element. Variable Substitution Description {status} Alarm type name.
Variable Substitution Description {alarm_hour_12} Alarm Time Hour (12 hour). The time the alarm was triggered on a 12-hour clock. For example, this would return 10 for an alarm that occurred at 10:00 AM or 10:00 PM. {alarm_hour} Alarm Time Hour (24 hour). The time the alarm was triggered on a 24-hour clock. For example, this would return 16 for an alarm that occurred at 4 PM. {alarm_time_am_pm} Alarm time AM/PM.
Variable Substitution {dp_value_alias} Description Data Point Value (by Alias Name). The of the data point and its at the time that the alarm was triggered. The property is expressed with the LonFormat="# [scope]." attribute. This is the format defined by the data type used by the data point. {dp_preset_alias} Data Point Preset (by Alias Name). The of the data point and its at the time that the alarm was triggered.
Property Description assigned level 126-255 would use the second destination. NOTE: If you use the Configuration Plug-In to modify the configuration of an Alarm Notifier after creating it with the SOAP/XML interface, and the property had been set to a value greater than 1, the property will be reset to 0. The user-defined text will be used to describe the alarm condition in the Alarm Notifier’s log file. This can be a maximum of 201 characters long.
DataPoint[@dpType=“Output” and UCPTnickName=“Net/LON/iLON App/Data Logger[0]/nviDlClear[0]”] ON 255 0 0 255 0 0 You can optionally fill in the property for each element.
Property Description The delay, in minutes, to wait for an alarm to be acknowledged before sending an e-mail to the e-mail profile for the destination. If the alarm is not acknowledged before this time expires, the e-mail profile will be used. The default value used if this property is not set is 0. In this case, the e-mail profile will be used as soon as the alarm occurs. The maximum is 65,535. 7.3.
Net/LON/iLON App/VirtFb/temp_f Net/LON/iLON App/VirtFb/temp_f Net/LON/iLON App/Digital Output 1/nviClaValue_1 Net/LON/iLON App/Digital Output 1/nviClaValue_1
created. An Alarm Notifier will not generate a log file until it has generated an alarm notification. You should not attempt to read more than 100 log entries with a single Read request. The following code demonstrates how to use a Read request to generate a list of up to the first 100 entries stored in a specific Alarm Log. Request PAGE 112made. The type of log requested (either HISTORICAL or SUMMARY). Timestamps indicating the log times of the first and last log entries in the log file. A counter indicating the number of times the log file has been modified. The counter is not increased when data is added to the end of the log, but only if some modifications are made to the existing data. The volume of the log file that has been consumed, as a percentage.
Property Description The priority level currently assigned to the data point (0-255). The priority level of a data point determines which applications can write to its value. You can modify the value of this property with the Write or ResetPriority functions. The name of the alarm notifier in which the log entry is stored in the following format: . A timestamp indicating the time that the alarm occurred.
7.3.5 Using the Write Function on an Alarm Notifier Log File You can use the Write function to acknowledge or write a comment to a log entry on an Alarm Notifier. The following table describes the properties you can define in the input parameters you supply to the function to acknowledge an alarm. Request PAGE 115Property Description property, see Input Data Points. • AUTO_CLEAR: The alarm was automatically cleared from the alarm log when it occurred. You can cause an Alarm Notifier to automatically clear all alarms for a data point by setting property for the data point to 1 when you create your Alarm Notifier with Set. • MANUAL_ACK_MANUAL_CLEAR: The Alarm has not been acknowledged or removed from the active list.
Response 0 - Net/LON/iLON App/Alarm Notifier[0] 2008-03-03T11:39:21.960-08:00 HISTORICAL 2008-02-29T17:50:00.580-08:00 2008-02-29T17:50:00.
Response 0 - Net/LON/iLON App/Alarm Notifier[0]
i.LON SmartServer 2.
i.LON SmartServer 2.
8 Analog Function Block You can use Analog Function Blocks to perform a variety of statistical operations on the values of the data points in your network, and store the result of each operation in an output data point. You can perform these operations on as many input data points as you like per Analog Function Block.
Net/LON/iLON App/Digital Output 2/nviClaValue_2 value 900 Net/LON/iLON App/Digital Input 1/nvoClsValue_1 value FN_NUL<
querying items of a UFPTanalogFunctionBlock_Cfg type as its input, as shown in the example below. The List function returns an - element for each Analog Functional Block that you have added to the SmartServer. The next section describes the properties included in each of these elements. You could use the list of
- elements returned by this function as input for the Get function. The Get function would then return the configuration of each Analog Functional Block included in the list.
Net/LON/iLON App/Digital Input 1/nvoClsValue_1 value FN_NUL 100 FN_AVERAGE 0 PAGE 123Property Input Description Analog Function Block. The input data points for an Analog Function Block are defined by a list of elements with dpType attributes of ="Input". For each element, you must specify an index number to be used within the Analog Function Block (UCPTindex), the name of the data point (UCPTpointName), and the interval to use when polling the data point’s value (UCPTpollRate). The poll rate must be specified as an integer between 0-6553.
Property Description property is defined. Output This element defines the output data point for this function block. You must specify the assigned to the output data point within this element. The value of this data point will be updated with the result of each comparison or statistical operation that the Analog Function Block performs.
Property Description select a compare data point by filling in the element, which is described later in the table. Scenarios that may assist you in understanding how to use this property are included in the Comparison Functions section. The output function for the Analog Function Block.
Property Description The value the output data point will be assigned when it is overridden, and the property is set to OV_SPECIFIED. The delay, in seconds, the Analog Function Block wait after a reset before polling the values of the input data points. When this value is 0, the Analog Function Block will resume polling the input data points at the rate specified by the property after a reset. This field has a range of 0.0-6553.0. 8.
Identifier Value Assigned To The Output Data Point the analog function block are True. For an example of how you could use the FN_OR function in this way, see the FN_OR Example section. i.LON SmartServer 2.
8.3.2.2 Comparison Functions The following table lists and describes the comparison functions you can use to fill in the property. You must reference each function by the identifier listed in the table. Identifier Description FN_GT Greater than. Returns True if the value of the input data point is greater than that of the compare data point (or the value assigned to the property, if it is defined). FN_LT Less than.
20 30 40 50 35 EMPTY 0.0 0 70 80 40 50 35 EMPTY 100.0 1 8.3.2.2.2 FN_OR Example In this example, there are four input data points and one compare data point, all of the type SNVT_count. There is one output data point, of the type SNVT_switch.
8.3.3 Using the Set Function on an Analog Functional Block Use the Set function to create new Analog Functional Blocks, or to overwrite the configuration of existing Analog Functional Blocks. The Analog Functional Blocks to be created or written to are signified by a list of - elements in the input parameters supplied to the function.
8.3.4 Using the Delete Function on an Analog Function Block You can use the Delete function to delete an Analog Functional Block. To delete an Analog Functional Block, you provide an - element with a UFPTanalogFunctionBlock_Cfg type that includes the property of the analog functional block to be deleted. The following code sample demonstrates how to use the Delete function to delete an Analog Functional Block: Request PAGE 132
9 Scheduler You can use the Scheduler application to schedule periodic updates to the data points in your network. You will select a data point, or group of data points, for each Scheduler you create. These data points will be updated to specific values on the dates and times that the Scheduler is active. The dates and times that the Scheduler is active, as well as the values the Scheduler will assign to the data points, are user-defined.
comes from the local Calendar object via an internal binding between the nvoEcDateEvent output of the Calendar, and the nviDateEvent input of the NodeObject. After a restart, the Scheduler recalculates the last Scheduler operation. It also sets the data point nvoDateResync to “100.0 1”, which updates the SmartServer’s exception list. You can set the value of nvoDateResync to “100.0 1” and then return it back to “0.0 0” with the Write function at any time to refresh the exception list manually.
1 1 1 0 1 Weekend 255 0 00:00:00 ET_LOCK 1 0 0 0
Note: Section 21.1.3, Creating a Scheduler and Calendar in Visual C# .NET, includes a C# programming example demonstrating how to use the Scheduler SOAP interface to create and read a data logger. Section 21.2.3, Creating a Scheduler and Calendar in Visual Basic.NET, includes a Visual Basic example demonstrating how to do this. 9.3.1 Using the List Function on a Scheduler You can use the List function to retrieve a list of the Schedulers that you have added to the SmartServer.
Net/LON/iLON App/Digital Output 2/nviClaValue_2 0 2000-01-01 2037-12-31 0 Weekday 255 0 00:00:00 ET_LOCK 1
The function returns an - element for each Scheduler referenced in the input parameters supplied to the function. The properties included in each element are initially defined when the Scheduler is created. You can write to these properties with the Set function. The following table describes these properties. Property Description The name of the Scheduler in the following format: .
Property Description will be decreased with every heartbeat. The element contains two properties that define the dates that the Scheduler applies to. The property defines the start date, and the property defines the end date. You must fill each property in using the following format: YYYY-MM-DD If the start date is undefined (0000-00-00), it means any date up to and including the end date.
2 10:00:00 0.0 0 0.
exception that occurs over a specific range of dates. The actual date or range of dates in which these exceptions occur are stored in the #8000010128000000[4].UFPTcalendar.xml file. The subsequent table lists and describes the properties that should be defined within each element.
Property Description The exceptions for the date-based schedule specify the dates on which the date-based schedule will be active. These exceptions are signified by a list of elements. Each exception must be referenced by its name (UCPTexceptionName). You will define the name of an exception and the dates is applies to when you create it with the Calendar application. For more information on this, see Chapter 10, Calendar. 9.3.2.
Property Description SNVT_switch data point using either of the following statements: ON ON If you are creating an event that is to occur sometime before or after sunrise or sundown, specify in a LonFormat attribute whether the offset specified in the property is to be added to or subtracted from the calculated sunrise or sundown time.
9.3.3 Using the Read Function on a Scheduler You can use the Read function to retrieve the events scheduled in any Scheduler that you have added to the SmartServer. You can filter events using an xSelect statement and specifying one or more Scheduler items. You can use the following filters in an xSelect statement when using the Read function on a Scheduler: UCPTlastUpdate UCPTeventFilter position() When an event occurs.
- Net/LON/iLON App/Scheduler[0] 2008-03-01T00:00:00.000-08:00 2008-04-01T00:01:00.000-07:00
- 2008-03-01T00:00:00.
This element may have one of the following values: • ET_LOCK: A #LOCK event. • ET_UNLOCK: An #UNLOCK event. • ET_NUL: Event is based on the time-of-day, or sunrise or sundown. This element indicates whether the event is in a day-based schedule or a date-based exception schedule. This property may have one of the following values: • DayBased: Event is scheduled in a daily schedule. • DateBased: Event is scheduled in an exception schedule.
When creating or modifying a Scheduler with this function, you may want to use output from the Get function as the basis for your input. You would then only need to modify the values of each property to match the new configuration you want, as opposed to re-creating an entire string like the one shown below, to generate your input. The following example updates the nviClaValue_1 SNVT_switch data point on the Digital Ouput 1 functional block on the SmartServer.
0 1 1 1 1 1 0 1 Weekend 255 0 00:00:00 ET_LOCK
0 - Net/LON/iLON App/Scheduler[0]
9.3.5 Using the Delete Function on a Scheduler You can use the Delete function to delete a Scheduler. To delete a Scheduler, you provide an - element with a UFPTscheduler_Cfg type that includes the property of the scheduler to be deleted.
i.LON SmartServer 2.
10 Calendar You can use the Calendar application to define the exceptions that you will reference when creating the date-based schedules for your Schedulers. Each exception you create represents a date, or a group of dates. When you reference an exception in a Scheduler, you will be able to assign the dates for that exception a unique schedule. This may be useful when creating a Scheduler that requires different schedules for holidays than regular weekdays, or during different seasons of the year.
Holiday 0 2008-03-12 DW_NUL DW_NUL DW_NUL 2015-12-31 DW_NUL DW_NUL
SmartServer. Get Retrieve the configuration of the Calendar that you have added to the SmartServer. Set Create a new Calendar, or overwrite the configuration of an existing Calendar. Read Retrieve information about exceptions for some period of time Delete Delete a Calendar. Note: Section 21.1.3, Creating a Scheduler and Calendar in Visual C# .NET, includes a C# programming example demonstrating how to use the Calendar SOAP interface to create and read a data logger. Section 21.2.
Response 0 - Net/LON/iLON App/Calendar #8000010128000000[4].UFPTcalendar;xsi:type=“LON_Fb_Cfg” 0 2008-03-05T16:09:15.700-08:00 #8000010128000000[4].UFPTcalendar_Cfg.
Property Description Calendar. This property is always 8000010128000000[4].UFPTcalendar A flag indicating whether the Calendar functional block is hidden or shown in the navigation pane on the left side of the SmartServer Web interface. This property may have the following values: 0 – shown 1 – hidden This property only appears if the data logger is not synchronized with an LNS network database or it has been deleted.
Property Description You can specify the dates that the Event Calendar applies to by creating exceptions. The exceptions that have been created for an Event Calendar are signified by a series of elements. Each element contains a group of child elements, each of which defines an exception date. The ability to create multiple elements allows you to create groups of exceptions that can be applied to a schedule together.
Property Description The element contains a series of child elements and properties that define the dates that the exception applies to. These are described in the next section, Defining Exception Dates. 10.3.2.2 Defining Exception Dates The element contains a series of child elements and properties that define the dates that the Calendar is active.
WILDCARD means that the starting date is the 1st. • Setting the of to DW_ WILDCARD means that the ending date is the 31st. Specifies the days of the month in which the exception will be valid during the interval specified by the and elements. For example, you could specify every third day during the interval, every fourth day, and so on. See Daily Recursions for a table listing the possible values for this property.
Identifier Description DM_SECOND_MON Second Monday of each month DM_SECOND_TUE Second Tuesday of each month DM_SECOND_WED Second Wednesday of each month DM_SECOND_THU Second Thursday of each month DM_SECOND_FRI Second Friday of each month DM_SECOND_SAT Second Saturday of each month DM_THIRD_SUN Third Sunday of each month DM_THIRD_MON Third Monday of each month DM_THIRD_TUE Third Tuesday of each month DM_THIRD_WED Third Wednesday of each month DM_THIRD_THU Third Thursday of each month
Identifier Description DM_FIFTH_FRI Fifth Friday of each month DM_FIFTH_SAT Fifth Saturday of each month DM_LAST_SUN Last Sunday of each month DM_LAST_MON Last Monday of each month DM_LAST_TUE Last Tuesday of each month DM_LAST_WED Last Wednesday of each month DM_LAST_THU Last Thursday of each month DM_LAST_FRI Last Friday of each month DM_LAST_SAT Last Saturday of each month DM_EVERY_SUN Every Sunday of the date interval. DM_EVERY_MON Every Monday of the date interval.
Identifier Description MN_JAN January MN_FEB February MN_MAR March MN_APR April MN_MAY May MN_JUN June MN_JUL July MN_AUG August MN_SEP September MN_OCT October MN_NOV November MN_DEC December MN_EVERY_MONTH Every month during the interval the Calendar is active. MN_EVERY_2_MONTH Every other month during the interval the Calendar is active. MN_QUARTERLY Every third month during the interval the Calendar is active.
Identifier Description active. MN_EVERY_11_MONTH Every eleventh month during the interval the Calendar is active. MN_NUL Value not available. If this is chosen, the Calendar will use every month. 10.3.2.5 Exception Examples The following section presents a series of examples that demonstrate how to create exceptions that use wild cards and recursions. Consider a case where you need to create an exception to apply to a specific range of dates, year after year.
DW_WILDCARD DW_WILDCARD DW_WILDCARD 2008-05-31 DW_WILDCARD DW_WILDCARD DW_WILDCARD DM_FOURTH_SUN MN_NUL Now consider a case where you need to create an exception to
Net/LON/iLON App/Calendar enter an optional description 2000-01-01 2037-12-31 3 RecurringWeekendException Recurring Weekend Exception 0 PAGE 164position() Position of the events in previously selected list. You can use this filter to limit the number of events in a result. You can compare the number of events to be returned using equal, less (or equal), or great (or equal). You can request a maximum of 500 events, however, more than 500 events may be returned. Note: The last instance of an exception before the specified start date is always returned (if it exists), and it is not counted by the position() constraint.
events within the timeframe from to . The first element specifies the number of days from to the first event in the specified timeframe. The first signed long in the structure indicates the number of days until the event is valid, and the second one indicates the days until the event is invalid. The second element specifies the number of days from to the last event in the specified timeframe. 10.3.
i.LON SmartServer 2.
11 Real-Time Clock You can use the real-time clock on the SmartServer to schedule events to start or stop based on the calculated sundown or sunrise, or a configured amount of time before or after the sundown or sunrise. The real-time clock includes an astronomical position sensor that calculates the position of the sun based on the time-of-day stored on the SmartServer and the location (geographic coordinates) of the SmartServer, which you specify.
Alternatively, you can create and manage the #8000010128000000[4].UFPTrealTimeClock.xml file manually with an XML editor and download it to the SmartServer via FTP. Echelon does not recommend this, as the SmartServer will require a reboot to read the configuration of the downloaded file. Additionally, the SmartServer performs error checking on all SOAP messages it receives before writing to the XML file.
Request - Net/LON/iLON App/Real Time Clock
Response 0 - Net/LON/iLON App/Real Time Clock #8000010128000000[4].
Property Description The program ID and functional profile template used by the real-time clock. This property is always 8000010128000000[4].UFPTrealTimeClock A flag indicating whether the real-time clock functional block is hidden or shown in the navigation pane on the left side of the SmartServer Web interface.
The first invocation of the Set function will generate the #8000010128000000[4].UFPTrealTimeClock.xml file in the root/config/network///iLONApp || directory of the SmartServer, if the file does not already exist. When modifying an existing real-time clock, any optional properties omitted from the input will be erased. Old values will not be preserved, so you should fill in every property when writing to a real-time clock, even if you are not changing all of the values.
Response 0 - Net/LON/iLON App/Real Time Clock
i.LON SmartServer 2.
12 Type Translator You can use Type Translators to convert data points from one network variable type to another. This may be useful when comparing data points from different vendors that use different types, and are not compatible with each other. When creating a Type Translator, you will choose a Type Translator Rule. The Type Translator Rule defines the network variable type of the data points the Type Translator will accept as input, and the network variable type it will convert these data points to.
12.2 Creating and Modifying the Type Translator XML File You can create and manage the #8000010128000000[4].UFPTtypeTranslator.xml file with the Set SOAP function. The following section, Type Translator SOAP Interface, describes how to use Set and the other SOAP functions provided for the Type Translator application. Alternatively, you can create and manage the #8000010128000000[4].UFPTtypeTranslator.xml file manually with an XML editor and download it to the SmartServer via FTP.
12.3.2 Using the Get Function on a Type Translator You can use the Get function to retrieve the configuration of any type translator that you have added to the SmartServer. You must reference the type translator whose configuration is to be returned by its in the input you supply to the function, as shown in the example below. Request PAGE 176Property Description 1 – hidden This property only appears if the data logger is not synchronized with an LNS network database or it has been deleted. In this case, it has the following values: IS_NOTSYNCED IS_DELETED A timestamp indicating the last time the configuration of the real-time clock was updated.
Property Description enumeration). In this case, the value of the output data point will be updated with the value of the input data point each time a translation is made. Input Output The input and output data points that the Type Translator will translate are signified by a list of elements. Each element contains the following three properties: • . The name of the data point in the following format: .
When modifying an existing type translator, any optional properties omitted from the input will be erased. Old values will not be preserved, so you should fill in every property when writing to a type translator, even if you are not changing all of the values. When creating or modifying a type translator with this function, you may want to use output from the Get function as the basis for your input.
• The 16 SNVT_switch data points to be translated are defined by a list of elements that have a “Dp Type” attribute of “Input”. The input data points referenced by must have a property of #0000000000000000[0]. SNVT_switch data point and a in the range of Input0 to Input15. • The SNVT_state output data point is defined by a element that have a “Dp Type” attribute of “Output”.
Each time a type translation is made, the SNVT_occupancy output data point is assigned a value based on the current enumeration stored in the SNVT_lev_desc input data point, as described in the following table: SNVT_lev_desc (input point) SNVT_occupancy (ouput point) ST_NUL OC_NUL ST_OFF OC_UNOCCUPIED ST_ON OC_OCCUPIED ST_HIGH OC_BYPASS ST_LOW or ST_MED OC_STANDBY The following code demonstrates how to use the Set function to create a type translator that uses this :
ST_HIGH value: 75.0 state: 1 (ON) ST_MED value: 50.0 state: 1 (ON) ST_LOW value: 25.0 state: 1 (ON) The following code demonstrates how to use the Set function to create a type translator that uses this : PAGE 182OC_BYPASS function: SET_STATE setting: 100 rotation: 80.24 OC_STANDBY function: SET_STATE setting: 60.2 rotation: -40 The following code demonstrates how to use the Set function to create a type translator that uses this : PAGE 183The following code demonstrates how to use the Set function to create a type translator that uses this : - Net/LON/iLON App/Type Translator[6] Net/LON/iLON App/VirtFb/nviScene_1 #0000000000000000[0].
- Net/LON/iLON App/Type Translator[7] Net/LON/iLON App/VirtFb/nviScene_1 #0000000000000000[0].
SNVT_setting_TO_SNVT_switch 0 12.3.4.8 SNVT_state_TO_16xSNVT_switch You can use this Type Translator Rule to convert a single SNVT_state input data point to up to 16 SNVT_switch output data points. The value of the state field of each of the SNVT_switch input data points will be assigned to a field in the SNVT_state output data point.
• The SNVT_switch input data point is defined by a element that has a “Dp Type” attribute of “input”. The input data point referenced by must have a property of #0000000000000000[0]. SNVT_switch and a property of Input0. • The SNVT_lev_disc output data point to be translated is defined by a element that have a “Dp Type” attribute of “Output”.
Request - Net/LON/iLON App/Type Translator[1]
Response 0 - Net/LON/iLON App/Type Translator[1]
i.LON SmartServer 2.
i.LON SmartServer 2.
13 Type Translator Rules You can use the Type Translator Rule SOAP functions to create additional Type Translator Rules for the SmartServer, or to modify the Type Translator Rules provided with the SmartServer software. Each Type Translator Rule defines the network variable type of the data points a Type Translator will accept as input, and the network variable type these data points will be translated to.
#0000000000000000[0].SNVT_switch nvoSwitch #0000000000000000[0].
Delete 13.3.1 Delete a type translator rule. Using the List Function on a Type Translator Rule You can use the List function to retrieve a list of the Type Translator Rules that you have added to the SmartServer. The List function takes an element that includes an xSelect statement querying items of a UFPTtypeTranslator_Rule_Cfg type as its input, as shown in the example below.
Translates the state and value fields from two SNVT_switch input DPs to one output SNVT_swicth DP #8000010128000000[4].UFPTtypeTranslator_Rule_Cfg.htm nviSwitch1 #0000000000000000[0].SNVT_switch nviSwitch2 #0000000000000000[0].
Property Description 0 – shown 1 – hidden A timestamp indicating the last time the configuration of the type translator rule was updated. This timestamp uses the following format: YYYY-MM-DDTHH:MM:SSZ The name of the file containing the configuration web page for the Type Translator Rule on the SmartServer flash disk, absolute or relative to /web/user/echelon. This property is #8000010128000000[4].UFPTtypeTranslator_Rule_Cfg.htm by default.
13.3.2.1 Creating a Case Structure You can create case structures for each Type Translator Rule that defines the set of operations that will be performed when a type translation is made with that rule. Each case structure includes several global elements, and a series of case rules. The case rules are signified by a list of elements. You can use these rules to establish the value that will be assigned to the data point that the Type Translator Rule generates as output.
Property Description The index number of the case structure.
input data point is not equal to that of the compare data point. FN_NUL Null. Returns True for all values of the input. Use this if you want the case rules for a structure to be used each time there is a translation. The value of the input data point, or input data point field, selected for the case structure will be compared to the compare value using the selected comparison function. If the result of this comparison is True, the case rules defined for the case structure will be used.
2 0 DataPointFormat[UCPTnickName="nviScene"] scene_number DataPointFormat[UCPTnickName="nvoSwitch"] FN_NUL 0 100.0 1 Each case rule is defined by a element.
Property Description as the input data point or field selected for the case rule. The following table lists and describes the comparison functions you can use to fill in the property. FN_GT Greater than. Returns True if the value of the input data point is greater than that of the compare data point. FN_LT Less than. Returns True if the value of the input data point is less than that of the compare data point. FN_GE Greater than or equal to.
Property Description If the output data point or field takes an enumeration as its value type, enter the enumeration the output data point is to be assigned when the comparison for the case rule evaluates to True. If the output data point or field takes a numeric value as its value type, enter a numeric value here. The Type Translator will add this to the value of the input data point (or data point field) and store the resulting sum in the output data point (field).
0 DataPointFormat[UCPTnickName="nviSwitch"] DataPointFormat[UCPTnickName="nvoHVACmode"] FN_NUL 0 HVAC_COOL 1 DataPointFormat[UCPTnickName="nviSwitch"] FN
14 LONWORKS Driver The following chapter describes how to manage the networks, channels, devices, functional blocks, and data points on the LONWORKS driver on the SmartServer. Note that the functions and properties listed in this chapter are applicable for both the Web service on the SmartServer and the LNS Proxy Web service. 14.1 LONWORKS Networks The following section describes how to use the List, Get, Set, and Delete functions on LONWORKS networks. 14.1.
Response 0 - MyNetwork iLonNS;xsi:type="LON_Network_Cfg" 0 2008-03-20T15:26:55.610-07:00 LON_Network_Cfg.
Property Description interface. This property may have the following values: 0 – shown 1 – hidden A timestamp indicating the last time the configuration of the network was updated. This timestamp uses the ISO 8601 format, which is as follows: YYYY-MM-DDTHH:MM:SS.sssZPhh:mm The first segment of the time stamp (YYYY-MM-DD) represents the date the configuration of the Data Point was last updated. The second segment (after the T): HH:MM:SS.
Property Description Specifies the network management service used to manage the network. This property can be one of the following values: • SYNC_STANDALONE. The SmartServer is the network manager. It transmits all network management commands to the devices attached to its channel, and network configuration changes are stored in the internal SmartServer database. In standalone mode, the network functions as a master-slave system, where the SmartServer is the master to the slave devices.
Property Description Specifies when network configuration changes are propagated over the network to devices. This property can be one of the following values: • LCA_ONNET. Changes are sent immediately to the devices on the network. Use LCA_ONNET if you are installing an engineered network, or if you are designing and installing an ad-hoc network at the same time. • LCA_OFFNET.
SmartServer and get its property. If you don’t specify the of the current network, you will receive a response message with the following fault structure: 8 It's not allowed to set more then one network. Request (using the SmartServer Web service, select an existing LNS network database to which the SmartServer will automatically be synchronized) PAGE 207synchronization), you can perform a manual synchronization to update the LNS network database with network configuration changes made with the SmartServer. Even if is set to SYNC_LNS (LNS Auto; automatic synchronization), you may still want to periodically synchronize the SmartServer to update the SmartServer with changes made to the LNS network database by the LonMaker tool or other LNS application.
• The following example demonstrates how to synchronize the two devices on the network and their child functional blocks and data points to the LNS network database: PAGE 20914.1.3.2 Issuing Network Scan Commands to Discover Devices You can use the InvokeCmd function to discover all the uncommissioned devices on a LONWORKS network. When you send this command, a message is broadcast to the devices on the network that triggers the devices to identify themselves by their Neuron IDs. The network scan automatically generates a Data Log named “/#DeviceDiscovery” that includes entries for each uncommissioned device discovered by the network scan.
Option Description STATUS_CANCEL STATUS_PENDING STATUS_DONE STATUS_FAIL STATUS_INVOKE When this property is STATUS_PENDING, the network scan is ongoing. When this property is STATUS_DONE, the network scan is finished. See Checking the Network Scan Status for more information. An E_LonString type with a LonFormat attribute that must be set to <”UCPTscan”>. This property must be set to NST_ILON_DOMAIN. 14.1.3.2.
Read response and store it in the property of the subsequent Read request to avoid missing entries or receiving duplicate entries. This is the approach used by the SmartServer Web interface. Alternatively, you can wait until the network scan has been completed to read the uncommissioned devices in the data log all at once. This approach requires you to wait for the scan to be completed, but is much simpler to program.
- Net/LON IP IP;xsi:type="LON_Channel_Cfg" 1
The List function returns a list of - elements for each LONWORKS channel defined on the SmartServer or each LONWORKS channel defined in a specific LNS network database. You could use the list of
- elements returned by this function as input for the Get function.
Property Description property to which the channel is to be renamed. The type of channel and its xsi type, which is LON_Channel_Cfg. This determines the icon used to represent the channel in the SmartServer Web interface. A flag indicating whether the channel is hidden or shown in the navigation pane on the left side of the SmartServer Web interface.
Property Description is a power line channel that uses the Enhanced LonTalk® Proxy Protocol to transmit network messages from the SmartServer to the devices attached to the channel. For more information on the Enhanced LonTalk Proxy Protocol and power line repeating, see the i.LON SmartServer Power Line Repeating Network Management Guide. The transceiver ID of the channel. To create a new channel with the Set function, you must include this property.
Property Description is accomplished by assigning each priority device a time (priority) slot where it can transmit before all other lower priority and non-priority devices. These time slots consume network bandwidth; therefore, priority messaging should only be used for critical devices and data. The expected longest round-trip time (in milliseconds) of a message (for example, message and response).
Property Description Web service should be set to DDT_DYNAMIC. You cannot use the Set function to modify this property 14.2.3 Using the Set Function on a LONWORKS Channel You can use the Set function to overwrite the configuration of a channel, or to create a new channel. The input parameters you supply to the function will include one or more - elements. Each
- element includes a property that specifies a unique channel to be created or modified.
Response 0 - MyOldNetwork/MyOldChannel
14.3 LONWORKS Devices The following section describes how to use the List, Get, Set, and Delete functions on LONWORKS devices. Note: Section 21.1.4, Creating and Installing a LonWorks Device in Visual Basic.
Response 0 4.
14.3.2 Using the Get Function on a LONWORKS Device You can use the Get function to retrieve the configuration of a LONWORKS device defined on the SmartServer or in a specific LNS network database. The input parameters you supply to this function will include one or more - elements with a LON_Device_Cfg type. Each
- element will include the of each device whose configuration is to be returned by this function, as shown in the example below.
//Item[@xsi:type="LON_Device_Cfg"] [UCPTitemStatus="IS_UNCONFIGURED”] Request (use an xSelect statement return any devices that are offline) //Item[@xsi:type="LON_Device_Cfg"] [UCPTitemStatus="IS_APP_STOPPED”] Request (use an xSelect statement to return all devices from a specific manufacturer using the program ID) PAGE 221
The Get function returns an - element for each device referenced in the input parameters you supplied to the function. The properties included within each
- element are initially defined when the device is added to the SmartServer or LNS network database. You can write to these device properties with the Set function. The following table describes these properties. Property Description The name of the device in the following format: .
Property Description represents the time of day the configuration of the Data Point was last updated, in UTC (Coordinated Universal Time). UTC is the current term for what was commonly referred to as Greenwich Meridian Time (GMT). Zero (0) hours UTC is midnight in Greenwich England, which lies on the zero longitudinal meridian. Universal time is based on a 24 hour clock; therefore, an afternoon hour such as 4 pm UTC would be expressed as 16:00 UTC.
Property Description pre-loaded on a device. Devices that support dynamic functional blocks include controllers that do not have a static interface. For example, the v40 SmartServer XIF, which has a dynamic interface, supports a maximum of 500 dynamic functional blocks. The maximum number of dynamic network variables/data points that you can add to the device. A dynamic network variable/data point can be added to a functional block after the device has been commissioned.
Property Description • APP_RUNNING. Online. • APP_STOPPED. Offline. Indicates the current device configuration, which can be one of the following values: • COMSTATE_NUL. Never reached. • COMMISSIONED. Configured. • UNCOMMISSIONED. Unconfigured. The full path on the SmartServer flash disk of an application image to be downloaded to the device by the SmartServer.
Property Description Lists the network management and debugging commands issued for the device and their statuses. You can issue network management commands (ChangeApplicationStatus, ChangeCommissionStatus, ImageDownload, GetTemplate, Wink, and FetchProgID) in a Set function. You can issue debugging commands (QueryStatus and ClearStatus) with the Invoke_Cmd function. Note that these commands require the Item type of LON_Device_Command_Invoke.
14.3.3 Using the Set Function on a LONWORKS Device You can use the Set function to overwrite the configuration of a device, or to create a new device. The input parameters you supply to the function will include one or more - elements. Each
- element includes a property that specifies a unique device to be created or modified. Each
- element may also include a series of properties that define the configuration of the new (or modified) device.
To issue a network management command, you need to provide one or more - elements with a LON_Device_Cfg type. Each
- element needs to include the , , , and properties of the device upon which network management commands are to be issued. In addition, you should provide any other properties whose values are to be preserved (if you do not provide a property, the current value stored in it is erased).
STATUS_REQUEST ImageDownload You can use the ImageDownload command to download an application image file (.apb extension) stored on the SmartServer flash disk to the device. When using the ImageDownload command, you must specify the desired of the application image file to be downloaded to the device.
Reset You can use the Reset command to stop a device application, terminate all incoming and outgoing messages, set all temporary settings to their initial values, and then restart the device application. The following example demonstrates how to reset a device. PAGE 23014.3.3.2 Issuing Debugging Commands You can use the InvokeCmd function to issue debugging commands on LONWORKS devices. The debugging commands consist of QueryStatus, ClearStatus, and SendServicePin. You can use the QueryStatus debugging command to test the performance of a device and diagnose any problems. You can use the ClearStatus debugging command to clear the device statistics returned by the QueryStatus command.
Transaction timeouts occur when an acknowledged message times out after the last retry without the receiving device sending a confirmation that the message was delivered. Transaction full errors occur when the device’s transaction database, which is used to detect duplicate message packets, overflows. This may indicate excessive network traffic or transaction timers that are set too high.
You can use the ClearStatus debugging command to clear the device statistics returned by the QueryStatus command. The following example demonstrates how to use this command: PAGE 233• The property is Router. • The property is LON_Device_Router_Cfg.htm. Note that LON_Device_Router_Cfg has three additional properties: The network path of the channel attached to the far side of the router in the following format: //. • This property specifies one of the following seven router types: • LCA_CONFIGURED_ROUTER. The router determines which packets to forward based on internal routing tables.
bridges. You can use permanent bridges to preserve subnet IDs. • LCA_NUL. The SmartServer automatically select the appropriate router type. The port on the SmartServer used for receiving messages from the IP-852 Configuration Server. The default port is 1628. 14.5 Remote Network Interface You can use the List, Get, Set, and Delete functions on a remote network interface (RNI) as described in the previous section, LONWORKS Devices.
14.6.1 Using the List Function on a LONWORKS Functional Block You can use the List function to retrieve a list of functional blocks on the SmartServer or to retrieve a list of functional blocks in a specific LNS network database via the LNS Proxy Web service. The List function takes an element that has an xSelect statement with a LON_Fb_Cfg type as its input, as shown in the example below.
- Building 2/Channel 1/DIO-5/Digital Output[1] #8000010000000000[3].UFPTDigitalOutput;xsi:type="LON_Fb_Cfg" 0
14.6.2 Using the Get Function on a LONWORKS Functional Block You can use the Get function to retrieve the configuration of a functional block defined on the SmartServer or in a specific LNS network database.
0 2008-03-31T12:33:54.133-07:00 LON_Fb_Cfg.htm 2 #8000010000000000[3].UFPTDigitalCounter DDT_STATIC The Get function returns an - element for each functional block referenced in the input parameters you supplied to the function.
Property Description was last updated, in UTC (Coordinated Universal Time). UTC is the current term for what was commonly referred to as Greenwich Meridian Time (GMT). Zero (0) hours UTC is midnight in Greenwich England, which lies on the zero longitudinal meridian. Universal time is based on a 24 hour clock; therefore, an afternoon hour such as 4 pm UTC would be expressed as 16:00 UTC. The Z appended to the timestamp indicates that it is in UTC. It can be left out.
Property Description values: • 0. Standard functional profile defined in the standard resource file set. • 3. User-defined functional profile, defined in a manufacturer-specific resource file set. • 4. User-defined functional profile, defined in a manufacturer and device class specific resource file set. • 5. User-defined functional profile, defined in a manufacturer and device class/subclass specific resource file set. 6.
0 - Building 2/Channel 1/DIO-5/Digital Counter[0]
14.6.4 Using the Delete Function on a LONWORKS Functional Block You can use the Delete function to delete a functional block on the SmartServer, or in an LNS network database via the LNS Proxy Web service. The Delete function takes an - element with a LON_Fb_Cfg type as its input.
//Item[@xsi:type="LON_Dp_Cfg"][starts-with(UCPTname,"Building 2/Channel 1/DIO-5/Digital Output[0]")] Request (use an xSelect statement to return all the network variables that were updated after a specific time) PAGE 242 Response 0 - Building 2/Channel 1/DIO-5/Digital Output[0]/DO_Digital_1 Dp_In;xsi:type="LON_Dp_Cfg" 0 2008-03-31T12:34:28.483-07:00 Digital value to output LON_Dp_Cfg.
Property Description was last updated, in UTC (Coordinated Universal Time). UTC is the current term for what was commonly referred to as Greenwich Meridian Time (GMT). Zero (0) hours UTC is midnight in Greenwich England, which lies on the zero longitudinal meridian. Universal time is based on a 24 hour clock; therefore, an afternoon hour such as 4 pm UTC would be expressed as 16:00 UTC. The Z appended to the timestamp indicates that it is in UTC. It can be left out.
Property Description property. This property is a string up to 227 characters long that describes the units the value in which a network variable is measured. It is based on the data type assigned to the network variable. A default value will be assigned to this property if a unit for the network variable type chosen for the data point exists in the resource files on the SmartServer.
Property Description The frequency in which the SmartServer’s internal data server polls the network variable. The recommended minimum poll rate is 30 seconds; the maximum poll rate is 1 second. The default poll rate for network variables is 600 seconds. You should set poll rates for the data points of the external devices that are connected to the SmartServer.
a LON_Dp_Cfg type as its input. The - element only needs to include the network variable’s property in the Delete Request as demonstrated in the following code sample: Request
- MyOldNetwork/MyOldChannel/MyOldDevice/MyOldFb/MyOldNv
Response PAGE 247 The device must be disabled for the configuration property value to be changed. The device must be offline for the configuration property value to be changed. The device is reset after the configuration property value is changed. This property is applicable to configuration property files only (LON_Cp_File_Cfg). The offset in the file with the given index where the configuration property begins.
o ST_LON_UNACK (Unacknowledged). The sending device sends out the network variable update only once and does not expect any confirmation from the receiving device. This message service type consumes the least amount of resources, but is the least reliable. o ST_NUL (Unknown). The SmartServer selects the service type.
Transaction Timer Calculated based on topology and service type. Broadcast Options Broadcast addressing is not used. Alias Options Network variable aliases are used to resolve selector conflicts. i.LON SmartServer 2.
15 Modbus Driver The following chapter describes how to manage Modbus channels, devices, and data points on the SmartServer. 15.1 Modbus Channels The following section describes how to use the List, Get, Set, and Delete functions on Modbus channels. 15.1.1 Using the List Function on Modbus Channels You can use the List function to retrieve a list of Modbus channels on the SmartServer.
RS232 0 2008-04-02T11:07:27.860-07:00 MOD_Channel_Cfg.
Property Description 10:13:13 AM on August 15, 2002. If it is not UTC, time shift has to be defined: 2008-02-28T09:59:53.660+01:00 A user-defined description of the channel. This can be a maximum of 201 characters long. The name of the file on the SmartServer flash disk containing the configuration of the Modbus channel. This property is always MOD_Channel_Cfg.htm. The handle assigned to the Modbus channel assigned by the SmartServer.
Property Description This element contains the following options for Modbus channels attached to the RS-232 or RS-485 serial ports on the SmartServer ( is CT_RS485_MASTER or CT_RS232 _MASTER): • • • • . The baud rate at which the SmartServer communicates with the Modbus devices on the channel. The default value is MS_9600.
Property Description The transmission mode used by the SmartServer for communicating with Modbus devices. The default transmission mode is MM_RTU. You have the following two choices: • MM_RTU. Data is sent as two 4-bit, hexadecimal characters. RTU mode provides a higher throughput than ASCII mode at equivalent baud rates. • MM_ASCII. Data is sent as two ASCII characters.
• If you are creating a new Modbus channel, you only need to specify the property; all other properties are optional. • If you are modifying an existing Modbus channel, you must specify the channel’s . If you do not specify the handle, a new channel is created. All other properties must be filled; otherwise the values stored in them are erased. The previous section, Using the Get Function on Modbus Channels, details the properties you can include in the Set function.
15.2 Modbus Devices The following section describes how to use the List, Get, Set, and Delete functions on Modbus devices. 15.2.1 Using the List Function on Modbus Devices You can use the List function to retrieve a list of Modbus devices on the SmartServer. The List function takes an element that has an xSelect statement with a MOD_Device_Cfg type as its input, as shown in the example below. Request PAGE 257
The Get function returns an - element for each device referenced in the input parameters you supplied to the function. The properties included within each
- element are initially defined when the device is added to the SmartServer. You can write to these device properties with the Set function. The following table describes these properties. Property Description The name of the Modbus device in the following format: .
Property Description The name of the file on the SmartServer flash disk containing the configuration of the Modbus device. This property is always MOD_Device_Cfg.htm. The handle assigned to the Modbus device assigned by the SmartServer. When you use the Set function to modify the configuration of an existing Modbus device, you must specify the device’s handle. If you do not specify the handle, a new Modbus device is created.
15.2.4 Using the Delete Function on Modbus Devices You can use the Delete function to delete a Modbus device on the SmartServer. The Delete function takes an - element with a MOD_Device_Cfg type as its input. The
- element only needs to include the device’s property in the Delete Request as demonstrated in the following code sample: Request PAGE 260
15.4.1 Using the List Function on Modbus Data Points You can use the List function to retrieve a list of Modbus data points on the SmartServer. The List function takes an element that has an xSelect statement with a MOD_Dp_Cfg type as its input, as shown in the example below. Request (use an xSelect statement to return all the Modbus data points on the SmartServer) PAGE 26115.4.2 Using the Get Function on Modbus Data Points You can use the Get function to retrieve the configuration of Modbus data points defined on the SmartServer. The input parameters you supply to this function will include one or more - elements with a MOD_Dp_Cfg type. Each
- element will include the of each Modbus data point whose configuration is to be returned by this function, as shown in the example below.
Property Description rename a Modbus data point by providing its and specifying the new property to which the Modbus data point is to be renamed. The type of Modbus data point, which is Dp_In_Out by default. This determines the icon used to represent the Modbus data point in the SmartServer Web interface. A flag indicating whether the Modbus data point is hidden or shown in the navigation pane on the left side of the SmartServer Web interface.
Property Description including the type of values it takes and its base type. If you do not set this property, it is set to RAW_HEX and the Modbus data point uses raw hex values. Specifies the size (in bytes) of the Modbus data point. This property is a string up to 227 characters long that describes the units the value in which a Modbus data point is measured. It is based on the data type assigned to the Modbus data point.
Property Description states (on/off). • MTT_C_MO [Coil Functions (Functions 1 & 15 multi-write)]. For multiple coils. Single bit, read-write data that has two states (on/off). • MTT_DI [Discrete Input (Function 2)]. Single bit, read-only data that has two states (on/off). • MTT_IR [Input Register (Function 4)]. 16-bit read-only data that can be interpreted as a numeric value, a bit map, or an ASCII character. • MTT_HR [Hold Register (Functions 3 & 6 single-write)].
Property Description • DO_WORD_SWAP. Data is first arranged from highest to lowest order, but every pair of 16-bit words is swapped. For example, consider a device that uses an unsigned 32-bit integer to report runtime accumulation. Selecting the data ordering scheme is required because the Modbus protocol leaves the interpretation of 32-bit integers to the discretion of the implementer.
You can set multiple Modbus data points with a single Set message. However, you should not attempt to create or write to more than 100 Modbus data points with a single call to the Set function. The following example demonstrates how to create a new Modbus data point. Request (add a Modbus data point to a Modbus device) PAGE 267i.LON SmartServer 2.
16 M-Bus Driver The following chapter describes how to manage M-Bus channels, devices, and data points on the SmartServer. 16.1 M-Bus Channels The following section describes how to use the List, Get, Set, and Delete functions on M-Bus channels. 16.1.1 Using the List Function on M-Bus Channels You can use the List function to retrieve a list of M-Bus channels on the SmartServer.
0 2008-04-02T13:06:24.430-07:00 MBS_Channel_Cfg.
Property Description If it is not UTC, time shift has to be defined: 2008-02-28T09:59:53.660+01:00 A user-defined description of the channel. This can be a maximum of 201 characters long. The name of the file on the SmartServer flash disk containing the configuration of the M-Bus channel. This property is always MBS_Channel_Cfg.htm. The handle assigned to the M-Bus channel assigned by the SmartServer.
Property Description the M-Bus network. A parity bit is an extra bit used to check for errors in groups of data bits transferred between devices. The default parity size is P_EVEN. This property may be one of the following values: • P_NONE P_ODD P_EVEN . The number of stop bits used on the M-Bus network. The default value is SB_1. This property may be one of the following values: SB_1 SB_2 This property is not available for TCP/IP M-Bus channels.
• If you are creating a new M-Bus channel, you only need to specify the property; all other properties are optional. • If you are modifying an existing channel, you must specify the channel’s . If you do not specify the handle, a new channel is created. All other properties must be filled; otherwise the values stored in them are erased. The previous section, Using the Get Function on M-Bus Channels, details the properties you can include in the Set function.
16.2 M-Bus Devices The following section describes how to use the List, Get, Set, and Delete functions on M-Bus devices. 16.2.1 Using the List Function on M-Bus Devices You can use the List function to retrieve a list of M-Bus devices on the SmartServer. The List function takes an element that has an xSelect statement with an MBS_Device_Cfg type as its input, as shown in the example below. Request PAGE 274MED_NUL ff
AT_SECONDARY 0 00000000
The Get function returns an - element for each device referenced in the input parameters you supplied to the function.
Property Description 10:13:13 AM on August 15, 2002. If it is not UTC, time shift has to be defined: 2008-02-28T09:59:53.660+01:00 A user-defined description of the M-Bus device. This can be a maximum of 201 characters long. The name of the file on the SmartServer flash disk containing the configuration of the M-Bus device. This property is always MBS_Device_Cfg.htm. The handle assigned to the M-Bus device assigned by the SmartServer.
Property Description received from the device. The device answers to a REQ_UD-request with toggled FCB-Bit with a set FCV-bit from the SmartServer with a RSP_UD containing the data telegram section of a multi-telegram answer. Notes: An M-Bus device with a single RSP_UD-telegram may ignore the FCB in the REQ_UD2-telegram and always send the same (single) telegram.
Property Description (AT_SECONDARY) addressing. Primary addressing is preferred because it makes replacing M-Bus devices more transparent. Each of these addressing methods is described as follows: Primary. The primary address is assigned by the network management tool used to install the M-Bus device (analogous to a LONWORKS subnet/icon address). Secondary. The secondary address is burned into the device at the factory (analogous to a LONWORKS Neuron ID). • .
16.2.4 Using the Delete Function on M-Bus Devices You can use the Delete function to delete an M-Bus device on the SmartServer. The Delete function takes an - element with an MBS_Device_Cfg type as its input. The
- element only needs to include the device’s property in the Delete Request as demonstrated in the following code sample: Request PAGE 279
16.4.1 Using the List Function on M-Bus Data Points You can use the List function to retrieve a list of M-Bus data points on the SmartServer. The List function takes an element that has an xSelect statement with an MBS_Dp_Cfg type as its input, as shown in the example below. Request (return all the M-Bus data points on the SmartServer) PAGE 280
Alternatively, you can specify one or more M-Bus data point properties in the xSelect statement to filter the items returned by the Get function, including the to filter data points based on their parent device. Request (use an xSelect statement return all the M-Bus data points on a specific device) PAGE 281Property Description YYYY-MM-DDTHH:MM:SS.sssZPhh:mm The first segment of the time stamp (YYYY-MM-DD) represents the date the configuration of the Data Point was last updated. The second segment (after the T): HH:MM:SS.sss represents the time of day the configuration of the Data Point was last updated, in UTC (Coordinated Universal Time). UTC is the current term for what was commonly referred to as Greenwich Meridian Time (GMT).
Property Description The frequency in which the SmartServer’s internal data server polls the M-Bus data point. The recommended minimum poll rate is 30 seconds; the maximum poll rate is 1 second. The default poll rate for M-Bus data points is 10 seconds. Note: The actual poll rate is determined by calculating the least common denominator of all the poll rates set for the data point from the applications to which it has been added.
16.4.4 Using the Delete Function on M-Bus Data Points You can use the Delete function to delete an M-Bus data point on the SmartServer. The Delete function takes an - element with an MBS_Dp_Cfg type as its input. The
- element only needs to include the M-Bus data point’s property in the Delete Request as demonstrated in the following code sample: Request PAGE 284
17 Virtual Driver The virtual channel is the SmartServer's internal channel. It is used as a gateway for system information that is used by the data points on the SmartServer. The Virtual driver contains data points representing the SmartServer's free RAM, free disk space, CPU usage, software version number, last received service pin message, and other information. The following chapter describes how to manage virtual channels, and devices and data points on the virtual channel. 17.
0 - Net/Virtual Channel VirtualChannel 0 2008-04-02T17:05:45.270-07:00 Virtual_Channel_Cfg.
Property Description A user-defined description of the channel. This can be a maximum of 201 characters long. The name of the file on the SmartServer flash disk containing the configuration of the Virtual channel. This property is always Virtual_Channel_Cfg.htm. The handle assigned to the Virtual channel assigned by the SmartServer. When you use the Set function to modify the configuration of an existing Virtual channel, you must specify the channel’s handle.
17.1.4 Using the Delete Function on a Virtual Channel You can use the Delete function to delete a Virtual channel on the SmartServer. The Delete function takes an - element with a Virtual_Channel_Cfg type as its input. The
- element only needs to include the Virtual channel’s property in the Delete Request as demonstrated in the following code sample: Request PAGE 288
elements with a Virtual_Device_Cfg type. Each - element will include the of each device whose configuration is to be returned by this function, as shown in the example below. Request
- Net/VirtCh/iLON System
Response PAGE 289Property Description represents the time of day the configuration of the Data Point was last updated, in UTC (Coordinated Universal Time). UTC is the current term for what was commonly referred to as Greenwich Meridian Time (GMT). Zero (0) hours UTC is midnight in Greenwich England, which lies on the zero longitudinal meridian. Universal time is based on a 24 hour clock; therefore, an afternoon hour such as 4 pm UTC would be expressed as 16:00 UTC.
Net/Virtual Channel/Virtual Device Response 0 - Net/Virtual Channel/Virtual Device
17.2.4 Using the Delete Function on Virtual Devices You can use the Delete function to delete a Virtual device on the SmartServer.
17.4 Virtual Data Points The following section describes how to use the List, Get, Set, and Delete functions on Virtual data points. For information on reading and writing values to Virtual data points, see Chapter 4, Using the SmartServer Data Server. 17.4.1 Using the List Function on Virtual Data Points You can use the List function to retrieve a list of Virtual data points on the SmartServer.
- Net/VirtCh/iLON System/VirtFb/CMdialInIp Dp_Out;xsi:type="Virtual_Dp_Cfg" 0
17.4.2 Using the Get Function on Virtual Data Points You can use the Get function to retrieve the configuration of Virtual data points defined on the SmartServer. The input parameters you supply to this function will include one or more - elements with a Virtual_Dp_Cfg type.
Property Description . You can rename a Virtual data point by providing its and specifying the new property to which the Virtual data point is to be renamed. The type of Virtual data point, which may be Dp_In, Dp_Out, or Dp_In_Out (undefined). This determines the icon used to represent the Virtual data point in the SmartServer Web interface.
Property Description #[scope selector].[#format] . This determines many factors about the Virtual data point, including the type of values it takes and its base type. If you do not set this property, it is set to RAW_HEX and the Virtual data point uses raw hex values. Specifies the size (in bytes) of the Virtual data point.
Dp_Out #0000000000000000[0].SNVT_switch DIR_OUT 1.0 Response 0 - Net/VirtCh/iLON System/VirtFb/virt_switch
17.4.
18 File System Data You can use the List, Read, Write, and Delete functions to download, upload, and delete the data logs, alarm logs, the eventlog.txt file on the root directory of the SmartServer flash disk, and other user-defined .txt and .csv files under the web/user directory on the SmartServer flash disk. 18.1 Using the List Function on File System Data You can use the List function to return a list of directories containing .txt or .csv files on the SmartServer.
//*[@xsi:type="FileSystem"][UCPTname="/eventlog.txt"][UCPTfileFormat="text"] Request (return the data in a Data Logger) //*[@xsi:type="FileSystem"][UCPTname="/root/data/Net/LON/iLON App/Data Logger[1].csv"][UCPTfileFormat="text"] Response PAGE 298returns the following data: Hello World ! 18.3 Using the Write Function on File System Data You can use the Write function to upload a new alarm log, data log, or other user-defined file to the SmartServer or to overwrite an existing file. The Write function takes an - element with a FileSystem_Data type as its input. You can specify the format (text or hex) of the file in the property.
ilonWebRef.Item_Coll wrteResp = ilon.Write(itemDataColl); 18.4 Using the Delete Function on File System Data You can use the Delete function to delete an alarm log, data log, or other user-defined file on the SmartServer. The Delete function takes an - element with a FileSystem_Data type as its input. The
- element only needs to include the file’s property in the Delete request as demonstrated in the following code sample: Request PAGE 300
i.LON SmartServer 2.
19 System Information Methods You can use the SystemService_Read_Info and SystemService_Write_Info functions in the iLON100_System.wsdl to read system information about the SmartServer and modify the SmartServer’s configuration. You can use the SystemService_Test function to test connections to various host devices such as SMTP mail servers, SNTP time servers, and remote SmartServers and read the results of the tests. Note: To use the system information methods, you must reference the iLON100_System.
• Time of last refresh. SI_MAIL E-mail (SMTP) server settings. SI_RTR IP-852 router settings. SI_RTR_STAT (read-only) Network performance statistics for the SmartServer as an IP-852 router. SI_LSPA LonScanner Protocol Analyzer settings. The SystemService_Read_Info function returns a string listing all the system information provided by the property specified in the request message.
Auto false The SystemService_Read_Info function returns one item. The following table lists and describes the properties of the item. You can use the SystemService_Write_Info function to configure those properties that are marked (r/w). Properties that are read-only are marked with an (r).
Property Description R/W address prior to a reboot. The SmartServer’s current configured IPv4 mask. This property does not reflect changes made to the IPv4 mask prior to a reboot. r The SmartServer’s current configured IPv4 gateway. This property does not reflect changes made to the IPv4 gateway prior to a reboot.
Response
Response PAGE 307Property Description R/W A flag indicating whether the SmartServer can be rebooted remotely via the Setup - Reboot Web page.
true true 4.01.112 TP_FT_10 4.01.
Property Description R/W used to accommodate block failures. The recommended minimum number of spare flash blocks (8 blocks). If a flash block on the SmartServer fails and there are no spare blocks remaining, the flash disk may become unreliable. The SmartServer should be replaced before this happens. r The maximum rate of erases/minute of the SmartServer flash disk.
1440 0 The SystemService_Read_Info function returns one item. The following table lists and describes the properties of the < REAL_TIME> item. Note that all of the item’s properties are read-only. Property Description R/W A timestamp indicating the time that the real-time system information was returned.
Property Description R/W The number of free blocks of RAM on the SmartServer. r The number of blocks of RAM that have been allocated on the SmartServer. r An array of that indicate the rate and number of data point message failures over the last 2 minutes, 10 minutes, 60 minutes, and 24 hours (1440 minutes).
Property Description R/W The user name for logging in to an SMTP server that requires authentication. The SmartServer and the SMTP server will automatically negotiate the authentication mechanism to be used (PLAIN, LOGIN, or CRAM-MD5). The SmartServer does not support the POP before SMTP authentication mechanism. r/w ` The password used for logging in to an SMTP server that requires authentication. r/w 19.1.
Property Description R/W on which devices are attached to be determined automatically. Configured routers also support the use of redundant routers (multiple routers connecting two channels), which provide for redundant message paths and greater system reliability. • Learning. Like a configured router, the router determines which packets to forward based on internal routing tables.
Property Description R/W The domain, subnet, node address of the IP-852 router on the LonTalk channel connected to the SmartServer. r 19.1.8 IP-852 Router Statistics You can use the SystemService_Read_Info function to get network performance statistics for the SmartServer’s internal IP-852 router.
Property Description R/W IP-852 Configuration Server on the IP-852 channel. Packets received by the SmartServer's IP-852 router from the IP-852 Configuration Server on the IP-852 channel. R 19.1.9 LonScanner Protocol Analyzer You can use the SystemService_Read_Info function to get the SmartServer’s LonScanner Protocol Analyzer (LSPA) settings.
Property Description R/W This property enables packets directly transmitted to the internal devices on the SmartServer to be viewed with the LonScanner Protocol Analyzer tool. These packets will still not be sent on the physical network. r/w To enable packets sent by the internal devices on the SmartServer to be viewed with the LonScanner Protocol Analyzer tool, set this property to “true”. To disable this feature, set this property to “false”. 19.1.
This property specifies whether to start a test or get the current status of the test. This property may be set to one of the following values: • ST_BEGIN. Starts the test. • ST_STATUS. Returns the status of the test. Required A string specifying the e-mail address to where the test e-mail will be sent. Optional A string specifying the originator of the e-mail message.
Response SMTP_TEST 2008-04-10T15:40:37.488-07:00 IDLE 0 0 2008-04-10T15:36:44.
• SS_SENDING_MAIL • SS_BUSY A flag indicating whether there was an error with the test. A string that displays the last SMTP error received from either the server or client. This may be implementation specific between SMTP servers, so the entire string is copied to this parameter. An array of connection log entries . Each entry has the following properties: • . The index value assigned to the log entry.
Request (check the status of the test) CONFIG_SERVER_TEST ST_STATUS Response PAGE 321Required/ Optional Property Description Enumeration that defines the type of test to perform. This property must be set to CONNECTION_TEST. Required This property specifies whether to start a test or get the current status of the test. This property may be set to one of the following values: Required • ST_BEGIN. Starts the test. • ST_STATUS. Returns the status of the test.
0 2008-04-10T16:18:25.550-07:00 Create socket 0 10.2.124.82:80 1 2008-04-10T16:18:25.560-07:00 Connect socket 0 10.2.124.
20 Using the SOAP Interface as a Web Service This chapter assumes that you have some familiarity with Web services programming, and that you are using the Microsoft Visual Studio .NET development environment. All sample code in this chapter is written in Visual Basic .NET and Visual C# .NET using Microsoft Visual Studio 2008. However, you can use any development tool that is able to call standard Web services with the SmartServer SOAP/XML interface. 20.
4. Add a service reference to the version 4.0 WSDL to your project. To do this, follow these steps: a. Click Project and then click Add Service Reference. b. The Add Service Reference dialog opens. i.LON SmartServer 2.
c. In the URL or Address box, enter the following address: http://SmartServer IP address/WSDL/v4.0/iLON100.WSDL SmartServer IP address represents the IP address of the SmartServer your application is to reference. If you are using the system information methods to read system information and modify the SmartServer’s configuration, enter the following address in the URL or Address box: http://SmartServer IP address/WSDL/v4.0/iLON100_System.
e. In the Namespace box, enter a name for the service reference. You will use this name when you instantiate the Web services object because it becomes a name for the proxy class that is generated automatically by Visual Studio .NET. This is described in more detail in the next section. The name used for the service reference in this example is “iLON_SmartServer”. i.LON SmartServer 2.
f. Click OK. The new service reference appears in the list of references in the Solution Explorer pane. 5. Click Project, and then click Add Class. 6. The Add New Item dialog opens. i.LON SmartServer 2.
7. In the Name box, enter “iLON_SoapCalls” and then click Add. 8. You should now use the iLON_SoapCalls class to instantiate the SmartServer Web service as described in the section 20.2.1, Instantiating the Web Service Client in Visual C# .NET 3.5 or section 20.2.3, Instantiating the Web Service Client in Visual Basic .NET 3.5. 20.1.2 Referencing and Inheriting from the WSDL Using .NET 2.0 Framework The following procedure describes how to use Visual Studio 2008 .NET Framework 2.
3. Enter a name, location, and project type for the project, and then click OK. 4. Add a Web reference to the version 4.0 WSDL to your project. To do this, follow these steps: a. Click Project and then click Add Web Reference. The Add Web Reference dialog opens. i.LON SmartServer 2.
b. In the URL or Address box, enter the following address: http://SmartServer IP address/WSDL/v4.0/iLON100.WSDL SmartServer IP address represents the IP address of the SmartServer your application is to reference. Note: All examples in this section can also be applied to LNS Proxy Web service. The LNS Proxy supports the same WSDL as the SmartServer Web service; therefore, the same programming model can be applied to program a LNS network database in a transparent manner.
e. Click Add Reference. The new Web reference appears in the list of references in the Solution Explorer pane. i.LON SmartServer 2.
5. A .NET 2.0 client must turn off the keep-alive attribute to communicate with the SmartServer without exceptions being generated. To turn off the keep-alive attribute, the generated web reference class must be inherited, and the GetWebRequest method must be overridden, where the KeepAlive flag can be turned off. The following procedure describes how to do so. a. Click Project, and then click Add Class. The Add New Item dialog opens. b. In the Name box, enter “iLON_WebService” and then click Add. c.
class iLON_WebService : iLON_SmartServer.iLON100 // iLON_SmartServer refers to the name of the Web reference created in step 4 { protected override WebRequest GetWebRequest(Uri uri) { HttpWebRequest res = (HttpWebRequest)base.GetWebRequest(uri); res.KeepAlive = false; return res; } } 6. You should now use the iLON_WebService class to instantiate the SmartServer Web reference as described in section 20.2.2, Instantiating the Web Service Client in Visual C# .NET 2.0. 20.
namespace SmartServerConsoleExample { class iLON_SoapCalls { // your SmartServer's IpAddress public static string _iLonEndpointIpAddress = ""; // your SmartServer’s Web service reference static public iLON_SmartServer.iLON100portTypeClient _iLON = null; /// /// Instantiates the SmartServer Web service for /// .NET 3.5 /// static public void BindClientToSmartServer() { // Specify the binding to be used for the client.
20.2.2 Instantiating the Web Service Client in Visual C# .NET 2.0 using System; using System.Collections.Generic; using System.Text; namespace CodeExample { class iLON_SoapCalls { // your SmartServer's Web service reference static public iLON_WebService _iLON = null; /// /// Instantiates the SmartServer Web service for .NET 2.0 /// static public void BindClientToSmartServer(string _iLonEndpointIpAddress) { _iLON = new iLON_WebService(); String strOrigUrl = _iLON.Url; _iLON.
20.2.3 Instantiating the Web Service Client in Visual Basic .NET 3.5 The following example shows how to instantiate the Web service in Visual Basic. NET: Imports Imports Imports Imports Imports System System.Collections.Generic System.Linq System.Text System.
Note: The following examples assume that you are using a SmartServer that has been set to its factory default settings. This prevents compilation errors based on mismatching properties of the objects in the LONWORKS network hierarchy (network/channel/device/functional block/data point). 20.3.1 Reading and Writing Data Point Values in Visual C# .NET 3.5 The following Visual C# .NET 3.
// -------------- WRITING A DATA POINT VALUE -------------// reset the DP priority (see section 4.3.6 for more information) iLON_SmartServer.Item_Coll itemCollInvoke = new iLON_SmartServer.Item_Coll(); itemCollInvoke.Item = new iLON_SmartServer.Item[1]; itemCollInvoke.Item[0] = new iLON_SmartServer.Dp_ResetPrio_Invoke(); ((iLON_SmartServer.Dp_ResetPrio_Invoke)(itemCollInvoke.Item[0])).UCPTname = "Net/LON/iLON App/Digital Output 1/nviClaValue_1"; ((iLON_SmartServer.Dp_ResetPrio_Invoke)(itemCollInvoke.
after you have completed section 20.2.1, Referencing and Inheriting from the WSDL Using .NET 2.0 Framework, and section 20.2.2, Instantiating the Web Service Client in Visual C# .NET 2.0. using using using using System; System.Collections.Generic; System.Linq; System.Text; namespace SmartServerConsoleExample { class Program { // your SmartServer's IpAddress public static string _iLonEndpointIpAddress = ""; static void Main(string[] args) { iLON_SoapCalls.
"Net/LON/iLON App/Digital Output 1/nviClaValue_1"; ((iLON_SmartServer.Dp_ResetPrio_Invoke)(itemCollInvoke.Item[0])).UCPTpriority = 200; ((iLON_SmartServer.Dp_ResetPrio_Invoke)(itemCollInvoke.Item[0])).UCPTprioritySpecified = true; SmartServer.InvokeCmd(ref itemCollInvoke); // set the DP priority to 200 (see section 4.3.7 for more information) ((iLON_SmartServer.Dp_Data)dataColl.Item[0]).UCPTpriority = 200; ((iLON_SmartServer.Dp_Data)dataColl.Item[0]).UCPTprioritySpecified = true; // set 100.
20.3.3 Reading and Writing Data Point Values in Visual Basic .NET 3.5 The following Visual Basic .NET 3.5 example reads the value of the Net/LON/iLON App/Digital Output 1/nviClaValue_1 data point on the SmartServer, and then writes a value of “100.0 1” to it. This SNVT_switch data point is one of the relay outputs on the SmartServer. You can execute this code after you have completed section 20.1.1, Referencing and Inheriting from the WSDL Using .NET 3.5 Framework, and section 20.2.
SmartServer._iLON.InvokeCmd(itemCollInvoke) ' set the DP priority to 200 (see section 4.3.7 for more information) DirectCast(dataColl.Item(0), iLON_SmartServer.Dp_Data).UCPTpriority = 200 DirectCast(dataColl.Item(0), iLON_SmartServer.Dp_Data).UCPTprioritySpecified = True ' set 100.0 1 as the value DirectCast(dataColl.Item(0), iLON_SmartServer.Dp_Data).UCPTvalue = New iLON_SmartServer.E_LonString(0) {} DirectCast(dataColl.Item(0), iLON_SmartServer.Dp_Data).UCPTvalue(0) = New iLON_SmartServer.
a. Open a Command Prompt window to the following folder on your computer: C:\Program Files\Microsoft SDKs\Windows\v6.0A\bin folder. b. Enter the following command (in one line): wsdl.exe /language:CS /serverInterface /protocol:SOAP /n:iLon100e4 /u: /p:< SmartServer password> “http:///WSDL/V4.0/iLON100.wsdl” /out: “
4. Add a reference to the Microsoft.Web.Services2.dll component. To do this, click Project and then select Add References. The Add References dialog opens. Click the Browse tab, browse to the C:\Program Files\Microsoft WSE\v2.0 folder on your computer, click the Microsoft.Web.Services2.dll file, and then click OK. 5. Add the iLON100.cs proxy class to the project (you can copy the file to the same folder used to store your source code).
7. Write the code for web service. You can simply copy and paste the following code snippet into the public class Service1 : System.Web.Services.WebService. using using using using using using using using using using using System; System.Collections; System.ComponentModel; System.Data; System.Linq; System.Web; System.Web.Services; System.Web.Services.Protocols; System.Xml.Linq; iLon100e4; Microsoft.Web.
// create the response object Item_Coll itemColl_resp = new Item_Coll(); itemColl_resp.Item = new Item[] { new Item() }; itemColl_resp.Item[0].UCPTname = iLonItem.Item[0].UCPTname; // is the Item of the expected type? if (!(iLonItem.Item[0] is Dp_Data)) { System.Diagnostics.Trace.WriteLine("ERROR, unexpected object type"); ++itemColl_resp.UCPTfaultCount; itemColl_resp.UCPTfaultCountSpecified = true; itemColl_resp.Item[0].fault = new E_Fault(); itemColl_resp.Item[0].fault.
PAGE 348a. Right-click the LAN icon or a dial-out connection icon, point to Add Host, and then click Server (LNS, E-mail, Time, IP 852 Config, WebTarget) on the shortcut menu, or if are you adding the WebBinder Target to an existing server on the LAN, skip to step 4. b. The Setup – Host Web page opens, and a server icon is added one level below the LAN icon at the bottom of the navigation pane or one level below the dial-out connection icon. c.
f. Configure the following properties for the WebBinder Target server: i.LON SmartServer Property SOAP Path Enter the path on the WebBinder Target server to which SOAP messages should be transmitted. This is typically the location of the WSDL or ASMX file on the WebBinder target where it receives SOAP messages. For example, if you are exposing your Web service with the namespace of “WebBinder/Service1.asmx”, then enter the following text in the SOAP Path box: /WebBinder/Service1.asmx.
hexadecimal format. Maximum Age Specify the maximum age (in seconds) to be written to the target data points on the WebBinder destination when the local SmartServer sends updated values to them. If the WebBinder destination cannot communicate with the parent device of the target data point, the WebBinder destination caches the updated value it received from the local SmartServer.
d. Click Submit. 13. Return to your .NET project, put a break point on the first line in Write function, and run the project in debug mode. When you change the value of the source data point you selected in step 12, your server-side code’s break point should be hit. 14. Attach a text based file attachment such as event log to the Web connection, and run the server-side code in debug mode again.
i.LON SmartServer 2.
21 Programming Examples This chapter includes programming examples, written in Visual C# (.NET 3.5 and .NET 2.0 Frameworks) and Visual Basic with Microsoft Visual Studio 2008, that demonstrate how to use the SmartServer’s SOAP API to create custom applications. These programming examples create simple console applications that do the following: • • • • • • • Read and write data point values. Create and read a data logger. Create a scheduler and a calendar.
try { // See Section 20.2.1 (NET 3.5) or 20.2.2 (NET 2.0)for more information on iLON_SoapCalls class SmartServerConsoleExample.iLON_SmartServer.E_xSelect xSelect = new SmartServerConsoleExample.iLON_SmartServer.E_xSelect(); xSelect.xSelect = "//Item[@xsi:type=\"Dp_Cfg\"][contains(UCPTaliasName,\"nviClaValue\")]"; iLON_SmartServer.Item_Coll ItemColl = SmartServer.List(xSelect); iLON_SmartServer.Item_DataColl ItemDataColl = SmartServer.Read(ItemColl); if (ItemColl.UCPTfaultCount > 0) { Console.Out.
21.1.2.1 Creating a Data Logger The following C# console example creates a new data logger from an existing uninstantiated (hidden) data logger on the SmartServer, specifies the type, format, and size of the new data logger, and then specifies that the data logger record both of the SmartServer’s digital relay outputs every minute (the Net/LON/iLON App/Digital Output 1/nviClaValue_1 and Net/LON/iLON App/Digital Output 2/nviClaValue_2 data points).
// -------------- CREATING A DATA LOGGER -------------//Create an xSelect object and then specify the filter to be used iLON_SmartServer.E_xSelect xSelect = new iLON_SmartServer.E_xSelect(); xSelect.xSelect = "//Item[@xsi:type=\"LON_Fb_Cfg\"][contains(UCPTname,\"Log\")][UCPThidden = \"1\"]"; //Create an ItemColl that stores objects returned by List()function that takes an xSelect object iLON_SmartServer.Item_Coll ItemColl = SmartServer.
dataPointRef2.UCPTpollRate = 60; dataPointRef2.dpType = "Input"; //store data points in DP reference array myDataLogger.DataPoint[0] = dataPointRef1; myDataLogger.DataPoint[1] = dataPointRef2; //call Set function iLON_SmartServer.Item_CfgColl itemCfgColl = new iLON_SmartServer.Item_CfgColl(); itemCfgColl.Item = new iLON_SmartServer.Item_Cfg[1]; itemCfgColl.Item[0] = myDataLogger; iLON_SmartServer.Item_Coll ItemColl_Set_DataLogger_Return = SmartServer.Set(itemCfgColl); if (ItemColl_Set_DataLogger_Return.
Console.Out.WriteLine("Item: " + ItemColl.Item[j].UCPTname + ", fault code: " + ItemColl.Item[j].fault.faultcode + ", fault string: " + ItemColl.Item[j].fault.faultstring); } } } static void Main(string[] args) { iLON_SoapCalls.BindClientToSmartServer(); // If you are using NET 2.0 Framework, comment out the previous line of code, and then // uncomment the following line of code // iLON_SoapCalls.BindClientToSmartServer(_iLonEndpointIpAddress); iLON_SmartServer.
Console.ReadLine(); } finally { iLON_SoapCalls.CloseBindingToSmartServer(); } } } } 21.1.3 Creating a Scheduler and Calendar in Visual C# .NET This C# console example creates a Scheduler and Calendar for hypothetically controlling the lighting and heating of a store. You can execute this code after you have referenced and inherited from the SmartServer WSDL as described in section 20.1, and instantiated and initialized the Web service client as described in section 20.2.
Console.Out.WriteLine("Item: " + ItemCfgColl.Item[j].UCPTname + ", fault code: " + ItemCfgColl.Item[j].fault.faultcode + ", fault string: " + ItemCfgColl.Item[j].fault.faultstring); } } } static void PrintGetError(iLON_SmartServer.Item_Coll ItemColl) { // print out error and exit Console.Out.WriteLine("An error occurred:"); for (int j = 0; j < ItemColl.Item.Length; j++) { if (ItemColl.Item[j].fault != null) { Console.Out.WriteLine("Item: " + ItemColl.Item[j].UCPTname + ", fault code: " + ItemColl.Item[j].
myScheduler.UCPTname = "Net/LON/iLON App/myScheduler"; myScheduler.UCPTannotation = "#8000010128000000[4].UFPTscheduler"; //create DP reference array to store data points controlled by new Scheduler myScheduler.DataPoint = new iLON_SmartServer.E_DpRef[2]; //speficy data points to be controlled by new Scheduler iLON_SmartServer.UFPTscheduler_DpRef dataPointRef1 = new iLON_SmartServer.UFPTscheduler_DpRef(); dataPointRef1.UCPTname = "Net/LON/iLON App/Digital Output 1/nviClaValue_1"; dataPointRef1.
offEvent.UCPTvalue[0].Value = "OFF"; offEvent.UCPTvalue[0].LonFormat = "UCPTvalueDef"; dayBasedSchedule_weekdays.Event[1] = offEvent; //set Monday--Friday as the days in this daily schedule iLON_SmartServer.UFPTscheduler_CfgDayBasedWeekdays mon_to_fri = new iLON_SmartServer.UFPTscheduler_CfgDayBasedWeekdays(); mon_to_fri.UCPTmonday = 1; mon_to_fri.UCPTtuesday = 1; mon_to_fri.UCPTwednesday = 1; mon_to_fri.UCPTthursday = 1; mon_to_fri.UCPTfriday = 1; mon_to_fri.UCPTsaturday = 0; mon_to_fri.
sat.UCPTwednesday = 0; sat.UCPTthursday = 0; sat.UCPTfriday = 0; dayBasedSchedule_Sat.Weekdays = sat; //create daily schedule for Sundays iLON_SmartServer.UFPTscheduler_CfgDayBased dayBasedSchedule_Sun = new iLON_SmartServer.UFPTscheduler_CfgDayBased(); dayBasedSchedule_Sun.UCPTindex = 2; dayBasedSchedule_Sun.UCPTindexSpecified = true; dayBasedSchedule_Sun.UCPTdescription = "Sunday"; dayBasedSchedule_Sun.UCPTpriority = 255; //create events for Sunday Schedule dayBasedSchedule_Sun.
myScheduler.DayBased[2] = new iLON_SmartServer.UFPTscheduler_CfgDayBased(); myScheduler.DayBased[2] = dayBasedSchedule_Sun; //create a date-based schedule (an exception) for some American Holidays //*** NOTE: You must use Calendar application to specify the dates in which this //alterntate schedule is applicable*** iLON_SmartServer.UFPTscheduler_CfgDateBased holidays = new iLON_SmartServer.UFPTscheduler_CfgDateBased(); holidays.UCPTindex = 0; holidays.UCPTindexSpecified = true; holidays.
//create Exception item holidays.Exception = new iLON_SmartServer.UFPTscheduler_CfgDateBasedException[1]; holidays.Exception[0] = new iLON_SmartServer.UFPTscheduler_CfgDateBasedException(); holidays.Exception[0].UCPTexceptionName = "Holidays"; holidays.Exception[0].UCPTindex = 0; holidays.Exception[0].UCPTindexSpecified = true; //store date-based (exception) schedule we created in a DateBased[] myScheduler.DateBased = new iLON_SmartServer.UFPTscheduler_CfgDateBased[1]; myScheduler.
//create exception dates myCalendar.Exception[0].Schedule = myCalendar.Exception[0].Schedule[0] myCalendar.Exception[0].Schedule[1] myCalendar.Exception[0].Schedule[2] myCalendar.Exception[0].Schedule[3] new iLON_SmartServer.UFPTcalendar_CfgExceptionSchedule[4]; = new iLON_SmartServer.UFPTcalendar_CfgExceptionSchedule(); = new iLON_SmartServer.UFPTcalendar_CfgExceptionSchedule(); = new iLON_SmartServer.UFPTcalendar_CfgExceptionSchedule(); = new iLON_SmartServer.
myCalendar.Exception[0].Schedule[3].UCPTschedDay = new iLON_SmartServer.E_LonString(); myCalendar.Exception[0].Schedule[3].UCPTschedDay.LonFormat = "UCPTschedDay"; myCalendar.Exception[0].Schedule[3].UCPTschedDay.Value = "DM_DAY_25"; //set start date myCalendar.Exception[0].Schedule[3].StartDate = new iLON_SmartServer.UFPTcalendar_CfgESDate(); myCalendar.Exception[0].Schedule[3].StartDate.UCPTdate = new DateTime(2009, 6, 8); //set end date myCalendar.Exception[0].Schedule[3].EndDate = new iLON_SmartServer.
class Program { //Function required for converting device Neuron IDs and program IDs to a byte[] static public byte[] HexStringToArray(string str) { int nLen = str.Length / 2; byte[] arr = new byte[nLen]; for (int i = 0; i < nLen; i++) { string strByte = str.Substring(i * 2, 2); arr[i] = Byte.Parse(strByte, System.Globalization.NumberStyles.HexNumber); } return arr; } static void Main(string[] args) { iLON_SoapCalls.BindClientToSmartServer(); iLON_SmartServer.
my_LON_Device1.Command[1].UCPTstatus.Value = "STATUS_REQUEST"; //get the device template to show FBs and DPs in Web UI my_LON_Device1.Command[2] = new iLON_SmartServer.LON_Device_CfgCommand(); my_LON_Device1.Command[2].UCPTcommand = new iLON_SmartServer.LON_Device_eCommand(); my_LON_Device1.Command[2].UCPTcommand = iLON_SmartServer.LON_Device_eCommand.GetTemplate; my_LON_Device1.Command[2].UCPTstatus = new ConsoleApplication_LON_Device.iLON_SmartServer.E_LonString(); my_LON_Device1.Command[2].UCPTstatus.
", fault string: " + Device_Return_ItemColl.Item[j].fault.faultstring); } } } else { ItemCfgColl = SmartServer.Get(Device_Return_ItemColl); for (int j = 0; j < ItemCfgColl.Item.Length; j++) { iLON_SmartServer.LON_Device_Cfg newDevice = (iLON_SmartServer.LON_Device_Cfg)ItemCfgColl.Item[j]; Console.WriteLine("New Device Created = " + newDevice.UCPTname + ". Status = " + newDevice.UCPTcommissionStatus.Value + " and " + newDevice.UCPTapplicationStatus.Value + ".\r"); } } Console.
// If you are using NET 2.0 Framework, uncomment the following line of code to enter your // SmartServer’s IP Address // public static string _iLonEndpointIpAddress = ""; static void Main(string[] args) { iLON_SoapCalls.BindClientToSmartServer(); // If you are using NET 2.0 Framework, comment out the previous line of code, and then // uncomment the following line of code // iLON_SoapCalls.BindClientToSmartServer(_iLonEndpointIpAddress); iLON_SmartServer.
deviceItems.Command[0].UCPTcommand = iLON_SmartServer.LON_Device_eCommand.ChangeApplicationStatus; deviceItems.Command[0].UCPTstatus.Value = "STATUS_REQUEST"; deviceItems.Command[1].UCPTcommand = iLON_SmartServer.LON_Device_eCommand.ChangeCommissionStatus; deviceItems.Command[1].UCPTstatus.Value = "STATUS_REQUEST"; deviceItems.Command[2].UCPTcommand = iLON_SmartServer.LON_Device_eCommand.Reset; deviceItems.Command[2].UCPTstatus.Value = "STATUS_REQUEST"; Console.Out.
Console.Out.WriteLine(deviceItemsCheck.UCPTname + "RESET REQUEST STATUS = " + deviceItemsCheck.Command[2].UCPTstatus.Value); if (bOnlineFail && deviceItemsCheck.Command[2].fault != null) { Console.Out.WriteLine("Error string: " + deviceItemsCheck.Command[2].fault.faultstring + ", Error Code" + deviceItemsCheck.Command[2].fault.
{ int nLen = str.Length / 2; byte[] arr = new byte[nLen]; for (int i = 0; i < nLen; i++) { string strByte = str.Substring(i * 2, 2); arr[i] = Byte.Parse(strByte, System.Globalization.NumberStyles.HexNumber); } return arr; } static void Main(string[] args) { iLON_SoapCalls.BindClientToSmartServer(); iLON_SmartServer.iLON100portTypeClient SmartServer = iLON_SoapCalls._iLON; try { //create LONNetworkScanCommandInvoke item and ScanCommand attribute iLON_SmartServer.
//Check scan status bool scanDone = false; while (!scanDone) { SmartServer.InvokeCmd(ref itemColl_Check); iLON_SmartServer.InvokeCmdResponse scanCheck_Response = new iLON_SmartServer.InvokeCmdResponse(); scanCheck_Response.iLonItem = itemColl_Check; iLON_SmartServer.LON_Network_ScanCommand_Invoke scanStatusCheck = (iLON_SmartServer.LON_Network_ScanCommand_Invoke)scanCheck_Response.iLonItem.Item[0]; //if the scan is done set scanDone flag to true if (scanStatusCheck.Command[0].UCPTstatus.
Console.WriteLine("Neuron ID = " + NID); String PID = NID_PID.Substring(13, 16); Console.WriteLine("Program ID = " + PID); //set Neuron ID, which is a byte[] my_LON_Device.UCPTuniqueId = (HexStringToArray(NID)); //set Program ID, which is a byte[] my_LON_Device.UCPTprogramId = (HexStringToArray(PID)); //set template iLON_SmartServer.E_xSelect xSelect = new iLON_SmartServer.E_xSelect(); xSelect.
iLON_SmartServer.LON_Device_eCommand.ChangeCommissionStatus; my_LON_Device.Command[0].UCPTstatus = new iLON_SmartServer.E_LonString(); my_LON_Device.Command[0].UCPTstatus.LonFormat = "UCPTstatus"; my_LON_Device.Command[0].UCPTstatus.Value = "STATUS_REQUEST"; //run device application my_LON_Device.Command[1] = new iLON_SmartServer.LON_Device_CfgCommand(); my_LON_Device.Command[1].UCPTcommand = new iLON_SmartServer.LON_Device_eCommand(); my_LON_Device.Command[1].UCPTcommand = iLON_SmartServer.
finally { iLON_SoapCalls.CloseBindingToSmartServer(); } } } } 21.1.7 Configuring the SmartServer in Visual C# .NET This console example uses the system information methods in the SmartServer’s system WSDL (iLON100_System.wsdl) to check the SmartServer's current time and system information and then sets a new time. Note that the iLON_SoapCalls class references the iLON100_System Web service instead of the iLON100 Web service. The instantiation of the iLON100_System Web service for the NET 3.5 and NET 2.
iLON_SmartServer_System.messageProperties_system systemInfo = new iLON_SmartServer_System.messageProperties_system(); string staticData = "SI_STATIC"; string staticResult = SmartServer.SystemService_Read_Info(ref systemInfo, staticData); Console.Out.WriteLine(staticResult); Console.Out.WriteLine("\r\n Changing the SmartServer's System Time\r\n"); iLON_SmartServer_System.
{ // Specify the binding to be used for the client. BasicHttpBinding binding = new BasicHttpBinding(); // Initialize the namespace binding.Namespace = "http://wsdl.echelon.com/web_services_ns/ilon100/v4.0/message/"; // Obtain the URL of the Web service on the SmartServer. System.ServiceModel.EndpointAddress endpointAddress = new System.ServiceModel.EndpointAddress("http://" + _iLonEndpointIpAddress + "/WSDL/iLON100_System.wsdl"); // Instantiate the i.LON web service object with this address and binding.
// // _iLON.Credentials = new System.Net.NetworkCredential("ilon", "ilon"); _iLON.PreAuthenticate = true; } } } i.LON SmartServer 2.
21.2 Visual Basic.NET Examples 21.2.1 Reading and Writing Data Point Values in Visual Basic.NET This VB console example toggles the SmartServer’s digital relay outputs when run. It demonstrates how to use an xSelect statement to filter items returned by a List() method, and it demonstrates how to write to data points using values and presets. You can execute this code after you have referenced and inherited from the SmartServer WSDL as described in section 20.
Next Dim ItemWriteDpValues As ILON_SmartServer.Item_Coll = SmartServer._iLON.Write(ItemDataColl) 'check that there are obejcts in the ItemWriteDpValues If (ItemWriteDpValues.UCPTfaultCount > 0) Then Console.Out.WriteLine("you've got errors") Else Console.Out.WriteLine(vbNewLine + "Reading Updated Data Point Values" + vbNewLine) For j As Integer = 0 To ItemWriteDpValues.Item.Length - 1 ' we allocate a Item-Data array object to read DP values, which should all be 100.0 1 Dim dpItems As iLON_SmartServer.
Dim SmartServer As iLON_SoapCalls = New iLON_SoapCalls SmartServer.BindClientToSmartServer() Try ' -------------- CREATING A DATA LOGGER -------------'Create an xSelect object and then specify the filter to be used Dim xSelect As New iLON_SmartServer.E_xSelect() xSelect.xSelect = "//Item[@xsi:type=""LON_Fb_Cfg""][contains(UCPTname,""Data Logger"")][UCPThidden = ""1""]" 'Create an ItemColl that stores objects returned by List()function that takes an xSelect object Dim ItemColl As iLON_SmartServer.
myDataLogger.DataPoint(1) = dataPointRef2 'call Set function Dim itemCfgColl__2 As New iLON_SmartServer.Item_CfgColl() itemCfgColl__2.Item = New iLON_SmartServer.Item_Cfg(0) {} itemCfgColl__2.Item(0) = myDataLogger Dim ItemColl_Set_DataLogger_Return As iLON_SmartServer.Item_Coll = SmartServer._iLON.Set(itemCfgColl__2) If ItemColl_Set_DataLogger_Return.UCPTfaultCount > 0 Then Exit Sub Else Dim newDataLogger As iLON_SmartServer.Item = ItemColl_Set_DataLogger_Return.Item(0) Console.
PrintGetError(ItemColl) Else Dim myDataLogger As iLON_SmartServer.Item = ItemColl.Item(0) Console.WriteLine("Data Logger = " & myDataLogger.UCPTname & vbCr & vbLf & vbCr & vbLf) End If 'we use an xSelect to read only the last 10 records in the Data Logger for one data point ItemColl.xSelect = "//Item[UCPTpointName=""Net/LON/iLON App/Digital Output 1/nviClaValue_1""][position()>=last()-10]" ' Read Data Logger Dim dataLogger As iLON_SmartServer.Item_DataColl = SmartServer._iLON.
' print out error and exit Console.Out.WriteLine("An error occurred:") For j As Integer = 0 To ItemCfgColl.Item.Length - 1 If ItemCfgColl.Item(j).fault IsNot Nothing Then Console.Out.WriteLine((("Item: " & ItemCfgColl.Item(j).UCPTname & ", fault code: ") + ItemCfgColl.Item(j).fault.faultcode.Value & ", fault string: ") + ItemCfgColl.Item(j).fault.faultstring) End If Next End Sub Private Sub PrintGetError(ByVal ItemColl As iLON_SmartServer.Item_Coll) ' print out error and exit Console.Out.
dataPointRef1.UCPTname = "Net/LON/iLON App/Digital Output 1/nviClaValue_1" dataPointRef1.UCPTformatDescription = "#0000000000000000[0].SNVT_switch" dataPointRef1.SCPTdelayTime = 0 dataPointRef1.SCPTdelayTimeSpecified = True dataPointRef1.dpType = "Output" Dim dataPointRef2 As New iLON_SmartServer.UFPTscheduler_DpRef() dataPointRef2.UCPTname = "Net/LON/iLON App/Digital Output 2/nviClaValue_2" dataPointRef2.UCPTformatDescription = "#0000000000000000[0].SNVT_switch" dataPointRef2.
mon_to_fri.UCPTsaturday = 0 mon_to_fri.UCPTsunday = 0 dayBasedSchedule_weekdays.Weekdays = mon_to_fri 'create daily schedule for Saturdays Dim dayBasedSchedule_Sat As New iLON_SmartServer.UFPTscheduler_CfgDayBased() dayBasedSchedule_Sat.UCPTindex = 1 dayBasedSchedule_Sat.UCPTindexSpecified = True dayBasedSchedule_Sat.UCPTdescription = "Saturday" dayBasedSchedule_Sat.UCPTpriority = 255 'create events for Saturday schedule dayBasedSchedule_Sat.[Event] = New iLON_SmartServer.
'---create ON event---Dim onEvent_Sun As New iLON_SmartServer.UFPTscheduler_CfgEvent() onEvent_Sun.UCPTindex = 0 onEvent_Sun.UCPTindexSpecified = True onEvent_Sun.UCPTtime = New DateTime(2009, 6, 8, 12, 0, 0) onEvent_Sun.UCPTvalue = New iLON_SmartServer.E_LonString(0) {} onEvent_Sun.UCPTvalue(0) = New iLON_SmartServer.E_LonString() onEvent_Sun.UCPTvalue(0).Value = "ON" onEvent_Sun.UCPTvalue(0).LonFormat = "UCPTvalueDef" dayBasedSchedule_Sun.
Dim lockEvent_holiday As New iLON_SmartServer.UFPTscheduler_CfgEvent() lockEvent_holiday.UCPTindex = 0 lockEvent_holiday.UCPTindexSpecified = True lockEvent_holiday.UCPTtime = New DateTime(2009, 6, 8, 0, 0, 0) lockEvent_holiday.UCPTeventType = New iLON_SmartServer.E_LonString() lockEvent_holiday.UCPTeventType.Value = "ET_LOCK" lockEvent_holiday.UCPTeventType.LonFormat = "UCPTeventType" holidays.[Event](0) = lockEvent_holiday 'create ON event for Holiday schedule Dim onEvent_holiday As New iLON_SmartServer.
Dim newScheduler As iLON_SmartServer.Item = ItemColl_Set_Scheduler_Return.Item(0) Console.WriteLine("New Scheduler = " & newScheduler.UCPTname) End If End If ' -------------- CREATING A CALENDAR -------------Create a new UFPTcalendar_Cfg item Dim myCalendar As New iLON_SmartServer.UFPTcalendar_Cfg() myCalendar.UCPTname = "Net/LON/iLON App/myCalendar" myCalendar.UCPTannotation = "#8000010128000000[4].UFPTcalendar" End Try 'Configure the Calendar Dim effectivePeriod_calendar As New iLON_SmartServer.
myCalendar.Exception(0).Schedule(1).UCPTschedMonth = New iLON_SmartServer.E_LonString() myCalendar.Exception(0).Schedule(1).UCPTschedMonth.LonFormat = "UCPTschedMonth" myCalendar.Exception(0).Schedule(1).UCPTschedMonth.Value = "MN_SEP" myCalendar.Exception(0).Schedule(1).UCPTschedDay = New iLON_SmartServer.E_LonString() myCalendar.Exception(0).Schedule(1).UCPTschedDay.LonFormat = "UCPTschedDay" myCalendar.Exception(0).Schedule(1).UCPTschedDay.Value = "DM_FIRST_MON" 'set start date myCalendar.Exception(0).
Console.ReadLine() Finally SmartServer.CloseBindingToSmartServer() End Try End Sub End Module 21.2.4 Creating and Installing a LONWORKS Device in Visual Basic.NET This VB console example creates two LONWORKS devices, and then it commissions the devices, starts the devices’ applications, and gets the devices’ templates (to display the devices’ functional blocks and data points in the SmartServer Web interface). The example then prints out the names and statuses of the devices that have been installed.
my_LON_Device1.UCPTprogramId = HexStringToArray("80000105288a0403") my_LON_Device1.UCPTurlTemplate = "/root/lonWorks/Import/Echelon/LonPoint/Version3/dio-10v3.XIF" my_LON_Device1.UCPTcommissionStatus = New iLON_SmartServer.E_LonString() my_LON_Device1.UCPTcommissionStatus.Value = "COMMISSIONED" my_LON_Device1.UCPTapplicationStatus = New iLON_SmartServer.E_LonString() my_LON_Device1.UCPTapplicationStatus.Value = "APP_RUNNING" 'create a command array to store device commands to be sent my_LON_Device1.
'get the device template to show FBs and DPs in Web UI my_LON_Device2.Command(2) = New iLON_SmartServer.LON_Device_CfgCommand() my_LON_Device2.Command(2).UCPTcommand = New iLON_SmartServer.LON_Device_eCommand() my_LON_Device2.Command(2).UCPTcommand = iLON_SmartServer.LON_Device_eCommand.GetTemplate my_LON_Device2.Command(2).UCPTstatus = New iLON_SmartServer.E_LonString() my_LON_Device2.Command(2).UCPTstatus.LonFormat = "UCPTstatus" my_LON_Device2.Command(2).UCPTstatus.
'we create an xSelect object and then specify the filter to be used Dim xSelect_Device As ILON_SmartServer.E_xSelect = New iLON_SmartServer.E_xSelect xSelect_Device.xSelect = "//Item[@xsi:type=""LON_Device_Cfg""][UCPTitemStatus=""IS_UNCONFIGURED""]" 'we create an ItemColl that stores the objects returned by a List() function that takes our 'xSelect object Dim ItemColl_Device As ILON_SmartServer.Item_Coll = SmartServer._iLON.
ItemColl_SetReturn.xSelect = "//Item[@xsi:type=""LON_Device_Cfg""]" Dim ItemCfgColl_SetReturn As ILON_SmartServer.Item_CfgColl = SmartServer._iLON.Get(ItemColl_SetReturn) If (ItemCfgColl_SetReturn.UCPTfaultCount > 0) Then Console.Out.WriteLine("you've got Get errors") Else For i As Integer = 0 To ItemCfgColl_SetReturn.Item.Length - 1 Console.Out.WriteLine(vbNewLine + "*INSTALLATION STATUS CHECK*" + vbNewLine + vbNewLine) Dim deviceItemsCheck As iLON_SmartServer.LON_Device_Cfg = ItemCfgColl_SetReturn.
21.2.6 Discovering and Installing External Devices in Visual Basic.NET This console example scans a LONWORKS network for uncommissioned devices, processes the Neuron ID and program ID data of the discovered devices, and then commissions the devices, starts the devices’ applications, and gets the devices’ templates (to display the devices’ functional blocks and data points in the SmartServer Web interface). The example then prints out the names and statuses of the devices that have been installed.
networkScan.UCPTscan(0) = domain 'send InvokeCmd Dim itemColl As New iLON_SmartServer.Item_Coll() itemColl.Item = New iLON_SmartServer.Item(0) {} itemColl.Item(0) = networkScan SmartServer._iLON.InvokeCmd(itemColl) Console.WriteLine("starting scan") 'send the GetScan command to check network scan progress Dim networkScan_Check As New iLON_SmartServer.LON_Network_ScanCommand_Invoke() networkScan_Check.ScanCommand = iLON_SmartServer.LON_Network_eScanCommand.GetScan networkScan_Check.
End If ' -------------- CREATING DISCOVERED LONWORKS DEVICES-------------'Create a new LON_Device_Cfg Item and add it to ItemCfgColl Dim my_LON_Device As New iLON_SmartServer.LON_Device_Cfg() itemCfgColl.Item(i - 1) = my_LON_Device 'subtract 1 for the metaData item in Data Logger 'parse Neuron ID and Program ID from Data Logger Dim NID_PID As [String] = dataLoggerData.UCPTvalue(0).Value Dim NID As [String] = NID_PID.Substring(0, 12) Console.WriteLine("Neuron ID = " & NID) Dim PID As [String] = NID_PID.
my_LON_Device.Command = New iLON_SmartServer.LON_Device_CfgCommand(2) {} 'commission device my_LON_Device.Command(0) = New iLON_SmartServer.LON_Device_CfgCommand() my_LON_Device.Command(0).UCPTcommand = New iLON_SmartServer.LON_Device_eCommand() my_LON_Device.Command(0).UCPTcommand = iLON_SmartServer.LON_Device_eCommand.ChangeCommissionStatus my_LON_Device.Command(0).UCPTstatus = New iLON_SmartServer.E_LonString() my_LON_Device.Command(0).UCPTstatus.LonFormat = "UCPTstatus" my_LON_Device.Command(0).
21.2.7 Configuring the SmartServer in Visual Basic.NET This console example uses the system information methods in the SmartServer’s system WSDL (iLON100_System.wsdl) to check the SmartServer's current time and system information and then sets a new time. Note that the iLON_SoapCalls class references the iLON100_System Web service instead of the iLON100 Web service. You can execute this code after you have referenced and inherited from the SmartServer WSDL as described in section 20.1.
vbNewLine) Thread.Sleep(10000) Dim newTime As New iLON_SmartServer_System.messageProperties_system() Dim newTimeData As String = "SI_TIME" Dim newTimeResult As String = SmartServer._iLON.SystemService_Read_Info(newTime, newTimeData) Console.Out.WriteLine(newTimeResult) Console.ReadLine() Finally SmartServer.
' Closing the client gracefully ' closes the connection and cleans up resources Try _iLON.Close() Finally _iLON = Nothing End Try End Sub End Class i.LON SmartServer 2.
22 Programming the SmartServer with Java You can write custom applications for the SmartServer in Java. The SmartServer supports the Java API for XML Web Services (JAX-WS 2.0 and 2.1), which is Java programming language API for creating web services. 22.1 Setting up the Java Programming Environment To setup your Java programming environment for the SmartServer, you need to download and install the following software: • • • • Echelon SmartServer JAX-ES programming example.
2. Download the Maven 2.2.1 .zip file. 3. Browse to the C:\eclipse\eclipse 3.5\ilon.ws.clients folder, and then create a new folder named tools. 4. Extract the .zip file to the C:\eclipse\eclipse 3.5\ilon.ws.clients\tools folder. 22.1.5 Setting System Environment Variables To add environment variables for the JDK and Maven 2.2.1, follow these steps: 1. Open the System Properties dialog for your computer. To access this dialog, open the Windows Control Panel, and then click System.
22.2 Creating a JAX-WS Client To create a JAX-WS client, follow these steps: 1. Create the java proxy classes for the SmartServer’s WSDL and create a sample Eclipse project for programming the SmartServer in Java. To do this, follow these steps: a. Browse to the C:\eclipse\eclipse 3.5\ilon.ws.clients\jax-ws\src\wsdl folder, open the iLON100.wsdl file with a text editor, change the IP address at the bottom of the file to the IP address of your SmartServer, and then save the file. b.
b. The Import dialog opens with the Select window. Expand General, click Existing Projects into Workspace, and then click Next. i.LON SmartServer 2.
c. 4. The Import window opens. In the Root Directory property, enter C:\eclipse\eclipse 3.5\ilon.ws.clients\jax-ws and then press ENTER or TAB, or click Browse and select the C:\eclipse\eclipse 3.5\ilon.ws.clients\jax-ws folder. Click Finish. Install Maven integration software following these steps: a. Click Help and then click Install New Software. i.LON SmartServer 2.
b. In the Work With property, enter http://m2eclipse.sonatype.org/update/. In the Type Filter Text property, enter Maven. c. Under Maven Integration, select the Maven Embedder and Maven Integration for Eclipse check boxes, click Next, and then click Finish. i.LON SmartServer 2.
d. 5. Restart Eclipse. To do this, click File and then click Restart. If the following warning dialog opens, click OK. Set Eclipse to the JDK you installed in the Installing the Java Development Kit section following these steps: a. Click Windows and then click Preferences. i.LON SmartServer 2.
b. The Preferences dialog opens. Expand JAVA and then click Installed JREs. c. Add the JDK that you installed in the Installing the Java Development Kit section. To do this click Add, click Next, enter C:\Sun\SDK\jdk in the JRE Home property or click Directory and browse to the C:\Sun\SDK\jdk folder, and then click Finish. i.LON SmartServer 2.
d. A jdk entry is listed under Installed JREs. e. Delete the existing jre6 entry. To do this, click jre6 and then click Remove. i.LON SmartServer 2.
f. Click OK. g. Browse to C:\WINDOWS\system32 and rename the java.exe, javaw.exe, javaws.exe files to java.exe_bak, javaw.exe_bak, javaws.exe_bak, respectively. This prevents Eclipse from being confused by these files. h. Restart Eclipse. i. Set the Java Build Path to the JDK you installed following these steps: • Open the Project Explorer view. To do this, click Window, point to Show View, and then click Project Explorer.
• In the Properties dialog, click Java Build Path and then click the Libraries tab. If there is a JRE System Library [JavaSE-1.6] entry listed, remove it. To remove it, click it and then click Remove. • Click Add Library, click the JRE System Library, click Next, and then click Finish. i.LON SmartServer 2.
6. • A JRE System Library [jdk] entry is listed • Click OK. Enable Maven to manage your Java project following these steps: i.LON SmartServer 2.
a. In the Project Explorer view, right-click the ilon-ws folder, point to Maven, and then click Enable Dependency Management. b. Browse to the C:\eclipse\eclipse 3.5\ilon.ws.clients\jax-ws folder, open the .classpath file with a text editor and change the following line: to the following: PAGE 4198. Enter the following command in the C:\eclipse\eclipse 3.5\ilon.ws.clients folder to generate the documentation for the example SmartServer Java project: mvn javadoc:javadoc This creates an index.html file in the C:\eclipse\eclipse 3.5\ilon.ws.clients\jaxws\target\site\apidocs folder that you can open to view the SmartServer’s API. i.LON SmartServer 2.
9. Enter the following command in the C:\eclipse\eclipse 3.5\ilon.ws.clients\jax-ws folder to generate the documentation for the project Web pages: mvn site This creates an index.html file in the C:\eclipse\eclipse 3.5\ilon.ws.clients\jax-ws\target\site folder that you can open to view the project Web pages. 10. Open the Client.java class. Observe the example code in the main() method. i.LON SmartServer 2.
11. Run the Client.java class. To do this, click Run and then click Run or Debug. i.LON SmartServer 2.
12. Observe the output in the Console view at the bottom of the development environment. 22.3 Java Programming Examples This section includes Java programming examples that demonstrate how to use the SmartServer’s SOAP API to create custom applications. These programming examples create simple console applications that do the following: • • • • Read and write data point values. Create and read a data logger.
package com.echelon.sample.client.ilon; import import import import import import com.echelon.wsdl.web_services_ns.ilon100.v4_0.message.DpData; com.echelon.wsdl.web_services_ns.ilon100.v4_0.message.EXSelect; com.echelon.wsdl.web_services_ns.ilon100.v4_0.message.ItemColl; com.echelon.wsdl.web_services_ns.ilon100.v4_0.message.ItemDataColl; com.echelon.wsdl.web_services_ns.ilon100.v4_0.wsdl.ILON100; com.echelon.wsdl.web_services_ns.ilon100.v4_0.wsdl.
} ItemColl writeResponse = SmartServer.write(itemDataColl); if(writeResponse.getUCPTfaultCount()> 0) { // print out error and exit System.out.println("An error occurred:"); for (int j = 0; j
import import import import com.echelon.wsdl.web_services_ns.ilon100.v4_0.message.UFPTdataLoggerCfg; com.echelon.wsdl.web_services_ns.ilon100.v4_0.message.UFPTdataLoggerDpRef; com.echelon.wsdl.web_services_ns.ilon100.v4_0.wsdl.ILON100; com.echelon.wsdl.web_services_ns.ilon100.v4_0.wsdl.
logFormat_LonString.setLonFormat("UCPTlogFormat"); myDataLogger.setUCPTlogFormat(logFormat_LonString); //specify two data points to be logged by new Data Logger UFPTdataLoggerDpRef dataPointRef1 = new UFPTdataLoggerDpRef(); dataPointRef1.setUCPTname("Net/LON/iLON App/Digital Output 1/nviClaValue_1"); dataPointRef1.setUCPTformatDescription ("0000000000000000[0].SNVT_switch"); dataPointRef1.setUCPTpollRate(60); dataPointRef1.
import com.echelon.wsdl.web_services_ns.ilon100.v4_0.wsdl.ILON100; import com.echelon.wsdl.web_services_ns.ilon100.v4_0.wsdl.ILON100PortType; public class Client_DpReadWrite { /** * @param args */ public static void main(String[] args) { ILON100 iLon100 = null; ILON100PortType SmartServer = null; try { iLon100 = new ILON100(); SmartServer = iLon100.getILON100HttpPort(); try { // _________________________ // Soap::List EXSelect xSelect = new EXSelect(); xSelect.
// print out error and exit System.out.println("An error occurred:"); for (int j = 0; j
/** * @param args */ public static byte[] hexStringToByteArray(String s) { int len = s.length(); byte[] data = new byte[len / 2]; for (int i = 0; i < len; i += 2) { data[i / 2] = (byte) ((Character.digit(s.charAt(i), 16) << 4) + Character.digit(s.charAt(i+1), 16)); } return data; } public static void main(String[] args) { ILON100 iLon100 = null; ILON100PortType SmartServer = null; try { iLon100 = new ILON100(); SmartServer = iLon100.
//run device application LONDeviceCfg.Command setOnline_my_LON_Device1 = new LONDeviceCfg.Command(); setOnline_my_LON_Device1.setUCPTcommand(LONDeviceECommand.CHANGE_APPLICATION_STATUS); ELonString my_LON_Device1_applicationStatus = new ELonString(); my_LON_Device1_applicationStatus.setLonFormat("UCPTstatus"); my_LON_Device1_applicationStatus.setValue("STATUS_REQUEST"); setOnline_my_LON_Device1.setUCPTstatus(my_LON_Device1_applicationStatus); my_LON_Device1.getCommand().
LONDeviceCfg.Command getTemplate_my_LON_Device2 = new LONDeviceCfg.Command(); getTemplate_my_LON_Device2.setUCPTcommand(LONDeviceECommand.GET_TEMPLATE); ELonString my_LON_Device2_templateStatus = new ELonString(); my_LON_Device2_templateStatus.setLonFormat("UCPTstatus"); my_LON_Device2_templateStatus.setValue("STATUS_REQUEST"); getTemplate_my_LON_Device2.setUCPTstatus(my_LON_Device2_templateStatus); my_LON_Device2.getCommand().
You can execute this code after you have setup the Java programming environment as described in section 22.1, and created the Web service client as described in section 22.2. You must also upload the device interface (XIF) files of the devices you are discovering and installing to the root/LonWorks/import folder on the SmartServer flash disk, or create device templates (XML files) for the devices. For more information on discovering uncommissioned LONWORKS devices, see section 14.1.3.
new LONNetworkScanCommandInvoke.Command(); scanFrequency.setUCPTcommand(LONDeviceIlonNiECommand.SCAN_ONCE); //b. set scan status ELonString scanStatus = new ELonString(); scanStatus.setLonFormat("UCPTstatus"); scanStatus.setValue("STATUS_REQUEST"); scanFrequency.setUCPTstatus(scanStatus); //c. add scan command to LONNetworkScanCommandInvoke item networkScan.getCommand().add(scanFrequency); //3. Set UCPTscan ELonString domain = new ELonString(); domain.setLonFormat("ucptScan"); domain.
// A "/#DeviceDiscovery" data logger is automatically created by the network scan // read the Data Logger and process the data of the discovered data UFPTdataLoggerData deviceDiscovered = new UFPTdataLoggerData(); deviceDiscovered.setUCPTname("Net/#DeviceDiscovery"); ItemColl itemColl_DataLog = new ItemColl(); itemColl_DataLog.setXSelect("//Item[@xsi:type=\"UFPTdataLogger_Data\"]"); itemColl_DataLog.getItem().add(deviceDiscovered); ItemDataColl dataLogger = SmartServer.
String xifName = templateName_justxif[templateNameLength-1]; System.out.println("XIF Name = " + xifName); //3. name device using channel name, /device [index], and xif name //("Net/LON/Device 1 (ai-10v3.xif)") String deviceName = channel.getUCPTname() + "/" + "Device " + i + " (" + xifName + ")"; System.out.println("Device Name = " + deviceName); System.out.println("============================================"); my_LON_Device.
newDevice.getUCPTapplicationStatus().getValue() + "."); } } } } catch (Exception e) { System.out.println(e.getMessage()); } } catch (Exception e) { System.out.println(e.getMessage()); } finally { iLon100 = null; SmartServer = null; } } } i.LON SmartServer 2.
Appendix A: SOAP Tester Example You can use the iLON SOAP Tester (version 2.0.3994) to perform functional testing of the SmartServer’s pre-defined SOAP functions and your user-defined SOAP functions. The SOAP Tester is an unsupported engineering-level tool provided by Echelon. You can download the SOAP Tester from the i.LON SmartServer Community Web site at http://ilonsmartserver.com/files. If you have a SmartServer 2.0 (Release 4.03), the SOAP Tester is also included on the i.LON SmartServer 2.
4. Click List. This calls the Data Server’s List function and returns all the data points on the SmartServer in the SOAP response. The upper pane of the SOAP Tester displays the SOAP header, and the lower displays the SOAP body of the SOAP response. 5. Click the left arrow in the upper-left hand corner. This returns you to the List request used in the previous SOAP call. i.LON SmartServer 2.
6. In this example, we want to read and write only to the SmartServer’s digital relay outputs; therefore, we need to modify the List function so that it returns the subject data points. To do this, change the xSelect statement from: //Item[@xsi:type="Dp_Cfg"] to the following: //Item[@xsi:type="Dp_Cfg"][contains(UCPTaliasName,"nviClaValue")] This means that the List function will return only those data points that have “nviClaValue” in their alias names.
7. Click List. This calls the Data Server’s List function and returns all the data points that meet criteria specified in the xSelect statement. In this case, the Net/LON/iLON App/Digital Output 1/nviClaValue_1 and Net/LON/iLON App/Digital Output 2/nviClaValue_2 data points are returned because they are the only data points that include “nviClaValue” in their alias names (by default). For more information on using the Data Server List function, see section 4.3.1, Using the List Function on the Data Server.
8. Click Read. This calls the Data Server’s Read function and returns the Dp_Data type for the subject data points, which includes their values, statuses, and their current priority levels. For more information on using the Data Server Read function, see section 4.3.4, Using the Read Function on the Data Server. i.LON SmartServer 2.
9. Toggle the values of the data points. By default, the subject data points have pre-defined ON (100.0 1) and OFF (0.0 0) presets, as specified in the root/config/template/lonworks/Dp/ #0000000000000000[0].SNVT_switch.xml file. These presets are specified in the property. Because these data points have presets defined for them, you can toggle their values in the following two ways: • Change the preset (the property) to ON or OFF.
www.echelon.
