LNS DDE Server User’s Guide Version 2.
Echelon, LON, LONWORKS, LNS, LonTalk, Neuron, LONMARK, 3120, 3150, the LonUsers logo, the Echelon logo, and the LONMARK logo are registered trademarks of Echelon Corporation. LonPoint, LonMaker, and LonSupport are trademarks of Echelon Corporation. Other brand and product names are trademarks or registered trademarks of their respective holders.
Contents 1 LNS DDE Server Overview New Feature in Release 2.11 New Features in Release 2.
Service Run as a Windows NT Service Write Messages to the Event Log Message Logging Settings Display Information Messages Display Warning Messages Display Error Messages Display Trace Messages Max Number of Lines Scrolling Rate (ms) Circular Log File Max Log File Size Log to WWLogger LNS Object Server Settings Format and Typefile Catalog Path Setting Global Database Path Setting Remote Settings Remote Operation Network Interface Database Settings Single User Mode Trace Options DDE Toolkit Client Connection
Serial Number Generate PC Key Creating an Unlimited Mode License Transferring Licenses Network Settings Network Name Database Path Authentication Key Network Interface Network Attached Network Interface Name Attach to Network when Exploring Set Management Mode OnNet Network Event Subscription Default Data Reporting Settings Polling Interval (1/10 sec) Refresh Rate (1/10 sec) Use Bound Updates Use Priority Messages Number of Retries Reply Timeout (1/10 sec) Exclusive Mode (TCP/IP) Host Message Owner Point Re
5 Reading and Writing Network Variables Specifying a Network Variable Specifying a Network Variable Topic Specifying a Network Variable Item Network Variable Formats Requesting a One-Time Network Variable Update Requesting a One-Time Network Variable Update Using Excel Requesting a One-Time Network Variable Update Using InTouch Receiving Ongoing Network Variable Updates Event Driven Updates versus Polling Monitoring Polled Output Network Variables Receiving Ongoing Updates Using Excel Receiving Ongoing Upd
Point Properties Appendix A Resource Files LONMARK Resource Files Type File Format File Alternate Formats Language File Functional Profile Template File Appendix B Installing the PCLTA-10/20 and PCC-10 Drivers PCLTA-10, PCLTA-20, and PCC-10 Adapter Installation PCLTA-10, PCLTA-20, and PCC-10 Software Installation Procedure Hardware Installation Procedure PCLTA-10 Adapter Hardware Installation Procedure PCLTA-20 Adapter Hardware Installation Procedure PCC-10 Card Hardware Installation Procedure PCLTA-10,
viii Table of Contents
1 LNS DDE Server Overview This chapter defines the main concepts for a LONWORKS® network, the role of a network management tool in setting up a network, and the role of the LNS DDE Server in monitoring and controlling the network. It also provides a brief overview of DDE and a summary of the new features in Releases 2.1 and 2.11. Additional terms are defined in the Glossary.
New Features in Release 2.11 Release 2.l1 (release 2.1 with Service Pack 1 applied) of the LNS DDE Server includes adds date stamping to the log pane. New Features in Release 2.1 Release 2.
single network interface, or through multiple network interfaces. To open multiple remote networks, you must configure the LNS DDE Server as a lightweight client. See Remote Settings in Chapter 3, Using the LNS DDE Server. • Updated Network Drivers - New drivers are included for the PCC-10, PCLTA-10, and PCLTA-20 cards.
Monitoring and Controlling a LONWORKS Network Due to their high reliability, low cost, and flexibility, LONWORKS networks are used in many ways. For example, they can be used to instrument relay-controlled systems, saving the time, complexity, and cost associated with running wire from each point back to the monitoring station. They can also be used in conjunction with a central controller or PLC, for example, to provide a subsystem of smart sensors.
Configuration parameters are stored in files on the device, and may be accessed using the LONWORKS file transfer protocol, or by direct memory read/write for Neuron Chip hosted devices. Configuration properties may be properties of the device, a LONMARK object, or a network variable. The data representation and interpretation of a configuration property is defined by its type. The type may either be a user defined configuration property type (UCPT), or a standard configuration property type (SCPT).
That is, the application can observe the values of network variables, configuration properties, and application and foreign frame messages, and can change the values of them to affect the operation of the network(s). The LNS DDE Server uses the naming, addressing, and timing information stored in an LNS Server by a network tool such as the LonMaker Integration Tool. There are many tools available for installing LONWORKS networks. Some of these are legacy tools that are not LNS compatible.
Once a conversation is established, the client can send and receive data from the server on the DDE channel. For example, an Excel spreadsheet (the client) may ask the LNS DDE Server (the server) for the current fuel consumption from a flow sensor for use in an automated billing system. Or, an InTouch operator interface (the client) may tell the LNS DDE Server (the server) to change the state of a valve in a LONWORKS network in response to a request issued by the operator.
1-8 [Pause] Temporarily stops the LNS DDE Server from sending updates to devices on the LONWORKS network, both updates to network variables and network variable polls. When paused, however, it will still receive network variable update messages from application devices and pass those to the client. [Resume] Reenables polling and outgoing update messages.
2 Getting Started This chapter explains how to install the LNS DDE Server, and how to start it with an existing network.
Requirements The LNS DDE Server requires a PC that meets the following requirements: • • • • • • Microsoft Windows XP, Windows 2000, Windows Me, Windows 98, or Windows NT 4.
In the lower part of all the dialogs you will find navigation buttons. Use these buttons to go forward to the next dialog, go back to the previous dialog, or cancel the whole installation. 3 Click Next to continue with the next step. The License dialog is displayed. 4 Read the license in its entirety, and if you accept it, click I Agree. If you don’t accept it click I Do Not Agree to terminate the installation without installing the LNS DDE Server.
6 Select the LNS DDE Server components to be installed. The installation program automatically preselects some of the components based in part on what it finds already installed on your system. Some components may not be available for installation. When selecting or clearing components, the disk usage for the currently selected files is shown in the lower part of the window. Following is a description of each of the options: • • • • • • 2-4 LNS DDE Server.
Select the components to be installed and click Next. The Select Destination Directory window appears. 7 Choose a LONWORKS folder where you want the LNS DDE Server software installed. The software will be installed in an LNSDDE folder below the LONWORKS folder that you specify. If you have installed other LONWORKS software on this computer, be sure to use the same LONWORKS folder.
download the latest LNS 3 service pack from www.echelon.com/lns. Follow the instructions provided with the LNS service pack to install it. 17 If you selected a network driver in step 6, configure the network driver as described in Installing and Configuring a Network Driver, later in this chapter. If you have not installed an application key for the LNS DDE Server, the LNS DDE Server will run for 30 days.
Using the LNS DDE Server When you start the LNS DDE Server, a main window similar to the following figure appears (you may see a different set of networks under the Networks folder and different messages at the bottom of the screen): The main window is divided into three panes. On the left side there is a folder pane, on the right side there is a detail pane, and along the bottom a log pane. A menu bar is displayed across the top. The three panes and the menu bar are described in the following sections.
associated with the selected network will be listed in the detail pane on the right side of the window. You can simultaneously open any number of the networks listed in this pane. Detail Pane The detail pane lists the objects that are associated with the currently selected folder on the folder pane.
Menu Bar The menu bar contains six menus. These are described in the following table: File Save Log File Exit Saves the contents of the log file. Terminates the LNS DDE Server. Edit Copy Link Copy link information for the currently selected object in the folder or detail pane to the clipboard.
Log Display/ Errors Log Display/ Trace Log Display/ Freeze Log Display/ Go to Top Log Display/ Go to Bottom Log Display/ Clear Log File/ Log to File Log File/ Clear Log to WWLogger Toggles displaying of error events. Activates the tracing option. Stops automatic scrolling of the log. Go to the top of the log. Go to the bottom of the log. Clear the contents of the log. When enabled causes all log and trace messages to be written to a file on disk. Clears the active log file.
Bottom of Log Scrolls to the bottom of the log. Top of Log Scrolls to the top of the log. Freeze Stops automatic scrolling of the log. Clear Message Display Clears the log display. Display Information This setting controls filtering of information messages for the log. Click this setting to display information messages in the log. The default setting is On. This setting controls filtering of warning messages for the log. Click this setting to display warning messages in the log pane.
The LNS DDE Test example includes 5 application devices and a router, which matches the hardware in a LonPoint Demo Kit. If you do not have LonPoint devices to use with the examples, you can still open the examples in engineered mode to see Excel and InTouch usage examples for the LNS DDE Server. Following is a list of the 5 application devices defined in the LNS DDE Test example: • • • • • AI- 1. A LonPoint AI-10 Analog Input Interface Module.
variables are connected as shown on the LonMaker drawing. The following list summarizes the Sequence of Operations for the LNS DDE Test example. Sequence of Operation 1. Inputs 3 and 4 to DI- 1 are configured to toggle. 2. Inputs 1-3 of the DI- 1 device are used to sequence the system mode normally generated by the SCH-10. As the inputs are asserted, the highest ON input determines the system mode. If all inputs are OFF, the mode is HVAC_OFF.
4. Click the Browse button. The Select Backup File dialog opens. 5. Browse to the LNS DDE Test V2.zip or LNS DDE Test V3.zip file in the LONWORKS LNSDde folder and click Open, then click OK. The Confirm Restore dialog opens. 6. Confirm the folders for the drawing and database files. To change the folders, click the Change Directory button. Once you have specified the desired folders, click OK. A dialog confirming that you want to open the restored drawing is displayed. 7.
5. Click Yes to start the LNS DDE Server. 6. If a blank spreadsheet opens over the Excel example spreadsheet, close the blank speadsheet. 7. Excel may time out while the LNS DDE Server starts. If it does, click on cell A7 (the Analog value), click anywhere within the cell formula in the formula bar, and press the Enter key. This will cause Excel to refresh all links. The Excel example demonstrates monitoring for a number of analog and digital points, and one mode output.
2-16 Installing the LNS DDE Software
3 Configuring the LNS DDE Server This chapter discusses how to configure the LNS DDE Server.
Configuration Overview When the LNS DDE Server starts up the first time, it will run using its initial default configuration settings. The LNS Server determines some of these settings, so the initial defaults may have been modified if you have previously used other LNS applications. The LNS DDE Server will automatically detect and use LNS network interfaces and LNS networks on the local PC. The following sections describe the LNS DDE Server configuration settings.
DDE Server Settings Application Name This setting specifies the DDE Application Name of the LNS DDE Server. This is not the filename on disk of the server. It is the name that DDE client applications need to use in order to be able to access the LNS DDE Server. The default setting is “LNSDDE”. If this item is changed, the server will need to be stopped and restarted in order for the change to have an effect. A series of dialogs will help you through the restart process.
Network Server Response Timeout (sec) This setting controls how long a time the LNS DDE Server will wait for a response from the LNS Network Server application. The LNS Network Server application runs in the background as a separate process and handles the communication between the LNS DDE Server and the LNS network database. Some operations, particularly opening the network database and going OnNet, may take more than a few seconds to complete.
applications, for example Microsoft Excel, this means prepending the computer name to the application name as in the example, =\\MYCOMPUTER\LNSDDE|'MyNet.Subsystem 1.DevNV'!'MyDev.NV2'. Always specify the computer name when the LNS DDE Server is running as a service. While the LNS DDE Server is running as a service, it is not possible to start the LNS DDE Server as a normal desktop application. You also cannot start the LNS DDE Server as a service if it is already running as a desktop application.
Message Logging Settings Display Information Messages This setting controls filtering of information messages for the log. Click this setting to display information messages in the log. The default setting is On. Display Warning Messages This setting controls filtering of warning messages for the log. Click this setting to display warning messages in the log pane. This setting should always be enabled. The default setting is On.
Max Log File Size The log file size is user configurable, in kilobytes. The default log behavior is to stop logging messages when the maximum log size is reached. The minimum log size is 10KB, the maximum is 100,000KB. Log to WWLogger This setting controls if log messages displayed in the log pane will be forwarded to the Wonderware WWLogger application if it is installed and running.
To select another folder, either enter it manually or use the Browse button to search for one. The server validates the path entered when you press the Apply or OK buttons. Use the Edit button to start the LNS Resource File Catalog Utility. This utility can be used to edit the catalog file. Folders containing format and other resource files may be added or removed from the catalog. You can combine changing the folder and editing the catalog.
hosts the LNS Server. When running as a remote full client, network variable values are not read from or written to the LNS Server, instead, they are read from and written directly to the devices with the network variables. Configuration property updates are always managed through the LNS Server. You will typically see better performances with remote full clients on LONWORKS /IP channels then remote lightweight clients on LNS/IP channels.
Network Interface This property can only be set if the Remote Operation option is set. If the Remote Operation option is set, this field contains a list of all available network interfaces and a TCP/IP selection. If you are connecting to the LNS DDE Server as a Full Client, select the LNS Network Interface you will use.
DDE Toolkit This section of the trace options concerns the interaction between the LNS DDE Server and the Wonderware I/O Server Toolkit (formerly the Wonderware DDE Server toolkit), which is the component of the LNS DDE Server that handles the DDE messaging between the client applications and the DDE Server. Many of these trace options produce output that is difficult to interpret without knowledge of the Wonderware I/O Server toolkit API.
when a point is created. This option will generate a message for each point that is accessed. The server will not start reading the point until it has been activated. Point Activation This option generates a message containing the internal names of the topic and point when a point is activated, and the result of the operation (typically “True”). The server does not start to read a point until it has been activated.
Format Files This option generates a message each time a format file is opened. The full path of the format file is included in the message. The server normally opens all registered format files during startup. Type Files This option generates a message each time a type file is opened. The full path of the type file is included in the message. The server normally opens all registered type files during startup. Format Errors This option generates a message when a format error occurs.
One instance of the LNS Network Server runs for each network that is open. One additional instance is used by the server to list the available networks. Launching This option prints additional information during startup of an LNS Network Server process. The information may be useful when there is a problem starting the LNS Network Server. In most cases, however, normal error reporting should be sufficient to determine the cause of a startup problem. LNS Errors This option is not used.
If this option is disabled, a summary message will be generated when a service pin message is received. The message contains only the device path (subsystem path and device name) if available or the Neuron ID of the device which sent the service pin message. Attachments Attachment events are generated for devices that have ping enabled. You can use an LNS tool such as the LonMaker Integration Tool to enable and disable ping for a given device.
The LNS DDE Server has three licensing modes. The first is Temporary Mode. If there is no license installed on a PC, a Temporary Mode license is generated when the LNS DDE Server is first started. In Temporary Mode the LNS DDE Server will run on an otherwise unlimited basis for 30 days. You must acquire an application key as described in Register Application Key later in this chapter to continue to use the LNS DDE Server after the Temporary Mode license expires. The second licensing mode is Demo Mode.
Temporary Mode, this field will show the restriction placed on the license. The restrictions that can be placed on a license include duration and number of runs. If the license is restricted by duration, this field will say how many days that remain on the license. If an unrestricted license is installed this field will say None. Serial Number This field holds the serial number specified during installation of the LNS DDE Server. This number must be used when ordering a license.
LONWORKS/IP, LNS/IP, NetDDE or other networking protocol. You may transfer an application key to a new PC as described in the next section. If you lose an application key due to a hardware or software failure, you may order a replacement key at no charge. If you have installed and licensed a previous version of the LNS DDE Server, you may order an upgrade application key. An upgrade application key is purchased in an identical method to a standard application key, but at a lower cost.
Edition), or if this is a replacement for a lost key, fill in the appropriate fields, and enter 0 as the price. 8. Email the form to the license administrator address at the top of the form, or if you do not have access to email, fax the form to the license administrator fax number at the top of the form. If you are ordering the application key through a distributor, the distributor may provide you with an alternate mailing address or fax number for the license administrator.
select the tab corresponding to the network to be configured. In either case, the following dialog appears with one tab for each LNS Network Database on your PC: The Network interface name and Set management mode OnNet settings can affect other LNS applications when you open those applications; all other settings apply only to the LNS DDE Server. Click the OK or Apply buttons to enable your settings. The Cancel button allows you to void your changes.
Authentication Key This field allows you to enter the authentication key for the LNS network. This is required if you are accessing the network as a remote Full or remote Lightweight client and the network uses authentication. The authentication key is a hexadecimal value of 12 characters, for example "a327ff27ba24". Network Interface Network Attached Select this setting if the PC is attached to the physical network and you want to communicate with the physical devices.
If you are communicating as a Lightweight client over an LNS/IP Channel (see Remote Settings, earlier in this Chapter), this option will not be available. Network Event Subscription This setting controls how the LNS DDE Server subscribes to network variable address and connection change events. This can be set to one of the following: None The LNS DDE Server subscribes to no change events. If event subscription is disabled, LNS DDE Server startup is faster as no change events are subscribed to.
The network topology, type of network interface, and LNS DDE Server host PC performance will all affect the maximum number of points that can be polled per second. In early tests of the LNS DDE Server, version 2.1, a 600 MHz PC on a LONWORKS/IP channel connected to six TP/XF-1250 channels was able to poll over 600 points per second. Adjust polling intervals to ensure that you do not exceed the maximum throughput of your configuration.
acknowledgements are not an indicator of reliable delivery should the LNS DDE Server and attached client applications not be running. • If a network variable that is already connected to another device is monitored using bound updates, a group is created on the host. If unsuccessful in a creating a bound connection, the LNS DDE Server will automatically revert to polling the network variable. No errors or warnings are generated if the connection is not successful.
• Control the update rate of bound network variables. Network variables should generally only be bound if they will change infrequently. If there is a possibility that several network variables bound to the host will begin rapidly changing, slow the update rate to avoid saturating the network. For example, the update rate can be limited on many devices using the minimum send time standard configuration property type (SCPTminSendTime). The default setting for Use Bound Updates is off.
Exclusive Mode (Lightweight Clients) This option is disabled for version 2.1 of the LNS DDE Server. Host Message Owner This option is disabled for version 2.1 of the LNS DDE Server. Point Recovery Strategy This setting determines the behavior when a device with one or more points loses communication the LNS DDE Server.
Bound Update Persistent Once the DDE Server shuts down, all temporary network variables and connections created when using bound updates are removed automatically when the point is deleted. To keep the temporary network variables and connections active, select this setting. Selecting this setting improves shut-down and start-up performance if you are using temporary network variables. The default setting is Off. See Use Bound Updates, earlier in this chapter, for more information.
To create a custom topic, open the Configure menu, point to Topics, then select Create New. Alternatively, you can right-click a subsystem in the folder or detail pane and select Associate Topic from the shortcut menu. The following dialog opens: The settings in this dialog are described in the following sections. Topic Name This setting specifies the name for the custom topic.
Click Apply to save the specified topic and specify additional topics. Click OK to save the specified topic and close the dialog.
3-30 Using the LNS DDE Server
4 Addressing DDE Messages This chapter describes how a DDE client specifies an address for a DDE message.
Address Components When a DDE client sends out a request to begin a DDE conversation, all DDE servers running on the PC see the message. In order to direct the message to a specified point on a particular server, the client addresses the message using a three-part DDE address with application, topic, and item components. Application The name of the server to which the message is directed. For example, to address a message to the LNS DDE Server, the client may specify LNSDDE as the application.
Standard Topic Format The standard topic format specifies a network, subsystem, and topic type. Ose this format except when you are using custom topics as described in the next section. To use a standard topic format, specify a topic with the following three components: Network_name.Subsystem_path.Topic_type Each component is separated from the other by a single period ("."). The Subsystem_path component may consist of multiple subsystems, each also separated by a period.
Custom Topic Format The custom topic format specifies a custom topic name and a topic type. Use this format with custom topics that you define. To use a custom topic format, specify a topic with the following two components: Topic_name.Topic_type Each component is separated from the other by a single period (.). Following is a description of the two components (both components must be specified): Topic_name The custom topic name that you have defined.
Category Topic Type Description Network Variable LMNV Network variables belonging to a LONMARK object. Use this type to access network variables belonging to a specific LONMARK object. The item name must specify both the device name and the LONMARK object name. See Chapter 5 for more information. DevNV Network variables on a device. This type accesses network variables on a device that are not configuration properties and not members of a LONMARK object. See Chapter 5 for more information.
Device Dev Devices. Used to access a device’s or router’s properties. See Chapter 8 for more information. System System System properties. For the System type no subsystem is specified. See Chapter 8 for more information. Topic Types and the Folder Pane The example folder pane on the right illustrates how topic types are displayed by the LNS DDE Server.
Items The Item is the last component of a DDE address. The topic type as described in the previous section determines the format of the item. The item format consists of one or more of the following components: Device_name Device name, as defined in the LNS database. LMO_name LONMARK Object name, as defined in the LNS database. NV_name Network variable name. See Chapter 5 for more information. CP_name Configuration property name. See Chapter 6 for more information.
Examples Below are a few examples of correctly formatted items: Type Netvar DevNVCP LMNVCP LM Dev MT 4-8 Item AI-1.nviTemp –i 100 AI-1.AS_Analog_1.SCPTovrValue AI-1.AS-1.AS_Analog_1.UCPTobjectType AI-1.AS-1.Request.Override AI-1.NeuronId lamp.msg_in.
5 Reading and Writing Network Variables This chapter describes how to read and write network variables.
Specifying a Network Variable Monitoring and control applications will typically monitor input or output network variable values and allow an operator to update input network variable values. Network variables may be identified either by member name within a LONMARK object, or by name for a device. Devices with LONMARK objects may have multiple network variables with the same name, so using the LONMARK object name/member name is a more reliable way to access network variables on LONMARK-compatible devices.
Each component of the Item format has the following meaning: device_name Required. The name of a device, as defined in the LNS database. lm_name Required if the LMNV topic is used. The name of the LONMARK Object as defined in the LNS database. nv_name Required. The name of the network variable on the device, as defined in the LNS database. array_index Required if the network variable is an element in an array of network variables, array_index is the array index in square brackets. Optional.
-p bool For a variable monitored by polling, this option specifies whether the poll messages should be sent with priority service. May be set to True or False. The default is the setting specified for the network in the Network Configuration dialog. -r nn Specifies the retry count to be used for request/response service used to poll network variables, where nn is a number between 0 to 15. The default is the setting specified for the network and is tool dependant.
Format command. Once the extended form is assigned to the network variable, the DDE client application does not need to specify the format type in the item name. To override the default format, use the –t parameter described in the previous section. You may either specify a standard format, or specify a user format from the format file described in Appendix A, Resource Files, using the following syntax: #[].
The Al- 1.Node Object 0.Node_Directory item would be reformatted as a UNVT_u_long, by using the -t option as follows: Al- 1. Node Object 0.Node_Directory –t#8011223344556677[1].UNVT_u_long This item specifies the AI- 1 device, the Node Object 0 LONMARK object, and the Node_Directory network variable member of the LONMARK object. The format is specified as the format defined for program ID 8011223344556677, with a selector of 1, and a format name of UNVT_u_long.
Channel = DDEInitiate(Application, Topic) Value = DDERequest(Channel, Item) DDETerminate (Channel) Following is a description of the parameters: Application Channel Item Topic Value The DDE application as a string. By default, this is “LNSDDE” for the LNS DDE Server. A DDE channel number created by the DDEInitiate() function, as a long. A DDE item as a string, as described in Specifying a Network Variable earlier in this chapter. A DDE topic as a string.
3. On the target window, drag the control to the size you want. 4. To set the properties for the button, double-click the button. 5. To add an action script to the button, click the Action button. 6. Select On Key Down as the Condition Type. 7. Enter the following code: StatusTag = WWRequest(Application, Topic, Item, Value) Following is a description of the parameters: StatusTag Application Topic Item Value A tag containing the return value from the WWRequest function.
by exception strategy; a new value is reported only upon changes in the variable's value. If the LNS DDE Server is bound to an output network variable on a device and the LNS DDE Server has not yet received an update message from the variable, the LNS DDE Server polls the variable to get an initial value and then waits for event-driven updates for future values. The LNS DDE Server attempts to pass all these updates to your application as soon as the update arrives.
variable that is driven by multiple output network variables (network variable fanin) is a typical example of how bound monitoring is not applicable. Polling is also useful when you want to control the rate and volume of data being sent to your monitoring application. Monitoring Polled Output Network Variables Device manufacturers can optionally specify network-related characteristics of the device’s network variables.
1 In the LNS DDE Server folder pane, navigate from the top level down through the hierarchy to the network variable level. 2 Right-click the network variable that you want to monitor, and choose Copy Link from the shortcut menu. 3 In InTouch WindowMaker, click the Wizards icon on the toolbar. Select I/O Analog Display from the Value Displays category, and click OK. 4 Place the object on the window and then double-click it. Select Paste Link In in the dialog and then click OK.
timer expires, this property remains at 0 until explicitly reset to another value. Setting this property prevents a separate network variable update being sent on the network for each field updated. Set this property to a value such that all fields will be changed before the update is sent. Sending a Network Variable Update Using Excel Three separate functions are required to send a network variable update using Excel. They are the Excel DDEInitiate(), DDEPoke(), and DDETerminate() functions.
Value The value to be written to the network variable, as a worksheet cell reference. 8. To return to Excel from the VBA editor, select Close and Return to Microsoft Excel on the File menu. 9. To exit design mode and enable the ActiveX control, click Exit Design Mode on the Control Toolbox. Note: If your Visual Basic application expects to update other network variables using the same channel, do not terminate the channel until the updates are received.
StatusTag Application Topic Item Value 8 A tag containing the return value from the WWRequest function. The value is 1 for a successful update, 0 if the application is busy, and –1 for an error. The DDE application as a string or an InTouch tag. By default, this is “LNSDDE” for the LNS DDE Server. A DDE topic as a string or an InTouch tag. For network variables, this will be an LMNV, DevNV, or NV topic as described in Topics in Chapter 4 and in Specifying a Network Variable earlier in this chapter.
LNS DDE Server User's Guide 5-15
6 Reading and Writing Configuration Properties This chapter describes how to work with configuration properties.
Specifying a Configuration Property Configuration properties may be associated with a device, LONMARK object, or network variable. For example, a configuration property associated with a LONMARK object for a sensor may define the processing for the sensor data; a configuration property associated with an output network variable may specify the override value for the network variable.
Where each component has the following meaning: device_name Required. The name of a device, as defined in the LNS database. lm_name Required if the LMCP or LMNVCP topic is used. The LONMARK Object name as defined in the LNS database. nv_name Required if the DevNVCP or LMNVCP topic is used. The name of the network variable on the device, as defined in the LNS database. array_index Required if the DevNVCP or LMNVCP topic is used and the network variable is an element in an array of network variables.
-t type_name Specifies a format name to use for formatting the configuration property as described in the next section. If this option is not specified, a format is selected by LNS. Use this option and specify a format name to change the format. The format name can be one of the five built-in formats (INTEGER, DISCRETE, REAL, STRING, or RAW), a format name from the standard resource file (for SNVTs and SCPTs), or a format name from any user resource file.
Selector Index 1 2 3 4 5 6 Selector DEVICE_CLASS DEVICE_CLASS and SUB_CLASS MANUFACTURER MANUFACTURER and DEVICE_CLASS MANUFACTURER and DEVICE_CLASS and SUB_CLASS MANUFACTURER and DEVICE_CLASS and SUB_CLASS and MODEL The scope selector does not have to match the selector used by the functional profile template defining the LonMark object(s) on the device. format type The format type name specified in the format file.
Receiving Ongoing Configuration Property Updates Receiving ongoing configuration property updates is similar to receiving network variables as described in Chapter 5. However, for configuration properties, you need to specify the topic and item as described in Specifying a Configuration Property earlier in this chapter. See Receiving Ongoing Updates in Chapter 5 for an explanation.
7 Receiving and Sending Application and Foreign Frame Messages This chapter describes how to send and receive application and foreign frame messages.
Specifying an Incoming Message Item Application and foreign frame messages are typically used for proprietary, noninteroperable interfaces to LONWORKS devices. To receive application or foreign from messages from a device, use the MT topic and specify the item as follows: [device_name.]msg_in[.msg_code] [parameters] Each component of the item format has the following meaning: device_name Optional. Specifies the name of an application device, as defined in the LNS database.
-t type_name Specifies a format name to use for formatting the message data as described in the next section. If this option is not specified, a format is selected by LNS. Use this option and specify a format name to change the format. The format name can be one of the five built-in formats (INTEGER, DISCRETE, REAL, STRING, or RAW), a format name from the standard resource file, or a format name from any user resource file. If the format name is RAW, data will be returned in raw format.
Msg_code Optional. Specifies monitoring of responses with the given message code, in decimal. If a message code is specified, then the data returned by the LNS DDE Server does not contain the code. If a message code is not specified, then the first byte of the data returned by the LNS DDE Server contains the received response code. Parameters Optional.
Note: To receive a response, you must establish an automatic link on resp_in in the DDE Client before sending the request on msg_out (i.e. the response message must be automatically forwarded to the client). Otherwise, the response will be discarded. Specifying a Message Completion Event Completion events are used to determine the success or failure of outgoing messages sent by the LNS DDE Server. Completion events are not generated for messages sent using unacknowledged or repeated service.
The parameter options are: as follows -n bool Specifies whether the client will receive message response items from the LNS DDE Server even if the data has not changed from the last time this response was received from the network. May be set to True or False. If False, data is reported to the client only if it has changed. If True, a byte containing an incrementing counter will be appended to each incoming response.
response message must be automatically forwarded to the client). Otherwise, the completion will be discarded. See Example 3 in Requesting a One-Time Update later in this chapter for an example of a request using this specification. Specifying an Outgoing Application Message The LNS DDE Server uses the following item format for sending application and foreign frame messages: [device_name.]msg_out[.
-r nn Specifies the retry count to be used for acknowledged and request/response service or the repeat count to be used for repeated service, where nn is a number between 0 to 15. If not specified, the default value specified in the Messaging Options configuration dialog is used. -s service Specifies the service type to use when sending the message. May be set to ACKD (acknowledged), UNACKD (unacknowledged), UNACKD_RPT (repeated) or REQUEST (request/response).
bcast_d.msg_out[.msg_code][parameters] Where each component has the following meaning: bcast_d Required. bcast_d is a keyword, not a user-defined name. This keyword is case insensitive. msg_out Required. msg_out is a keyword, not a user-defined name. This keyword is case insensitive. msg_code Optional. Specifies sending messages with the given message code, in decimal. Application message codes are from 0 to 62. Foreign frame message codes are from 64 to 78.
-t format_name Specifies a format name to use for formatting the data in the outgoing message. For response messages, the LNS DDE Server does not automatically determine the format. The format name can be one of the five built-in formats (INTEGER, DISCRETE, REAL, STRING, or RAW), a format name from the standard resource file, or a format name from any user resource file. If the format name is RAW, data will be returned in raw format.
Example 1: Application Topic Item LNSDDE AppMsg Test.subsystem 1.MT msg_in –t SNVT_count Example 2: Application Topic Item LNSDDE AppMsg Test.subsystem 1.MT switch.msg_in Example 3: Application Topic Item LNSDDE AppMsg Test.subsystem 1.MT switch.msg_in.1 See Requesting a One-Time Update in Excel and Requesting a One-Time Update Using InTouch in Chapter 5, for a description of how to request a one-time update.
Example 1: Application Topic Item LNSDDE AppMsg Test.subsystem 1.MT msg_in –t SNVT_count Example 2: Application Topic Item LNSDDE AppMsg Test.subsystem 1.MT switch.msg_in Example 3: Application Topic Item LNSDDE AppMsg Test.subsystem 1.MT switch.msg_in.1 See Requesting a One-Time Update in Excel and Requesting a One-Time Using InTouch in Chapter 5, for a description of how to request a one-time update.
8 Using Properties This chapter describes the properties available for the different topic types.
Properties The LNS DDE Server provides access to additional properties besides the network variable, configuration property, and message values described in Chapters 5, 6, and 7. The available properties are dependent on the DDE topic. The following sections describe these properties. Specifying a Property A property topic is specified using the standard or custom topic format described in Chapter 4. The topic specifies a category of properties, and the item includes the property name.
Point.InError R Number of points that cannot be read in the network. Point.WriteCount R Number of write requests issued for this point. The number of writes issued may not exactly match the aggregate count of updates issued by all clients for a point. The server will fold together all currently queued write requests for a single point.
device with the same name exists in the same subsystem, the value of the property for the application device will be returned. Change the name of either the router or application device to receive properties for each one. Properties Available in both Application Devices and Routers Reset Test W R/W Issues a reset command to the device or router. Tests an application device or router.
the device has not yet been commissioned. 11 Program ID mismatch. The ID of the program in the device does not match the program ID in the network image. 12 Unable to verify domain/subnet/node configuration. Succeeded in communicating with the device using Neuron ID addressing, but could not communicate with the device using subnet/node addressing.
Properties Available only in Application Devices Wink W Winks the device, if supported by the device's application. SelfDocumentation R The self-documentation string of a device. The length of this string may be up to 1024 characters. However, the server limits the length to about 170 characters. R Point.Active Number of points currently being accessed. R Number of points that cannot be read. Point.WriteCount R/W Number of writes issued to this device. Point.
DetailInfo.ModelNumber R The type of protocol processor in the device. If the protocol processor is a Neuron Chip, this will be one of the following values: 0 Model 3150 8 Model 3120 9 Model 3120E1 10 Model 3120E2 11 Model 3120E3 12 Model 3120A20 13 Model 3120E5 A value of 128 or greater indicates a non-Neuron Chip protocol processor, such as a microcontroller running the Adept implementation of the LONWORKS protocol. DetailInfo.Reset Cause R The cause for the last reset on the device.
Request.Enable R/W Set to 1 to Enable object. Set to 0 to Disable it. Request.RemoveOverride R/W Set to 1 to remove the Override condition of an object. Set to 0 to place the object in Override. Point Properties The point properties provide access to values that apply to individual network variables, configuration properties, and message tags. Some properties are not meaningful for configuration properties. These properties are maintained entirely inside the LNS DDE Server.
Appendix A Resource Files This chapter discusses LONMARK resource files and how to use the Resource File Catalog Utility to add new resource files to the resource catalog.
LONMARK Resource Files The LNS DDE Server supports LONMARK resource files that define standard and user-defined network variable types, configuration property types, and functional profile templates (definitions of LONMARK object types). The LNS DDE Server is compatible with resource files that comply with version 3.2 of the LonMark Application Layer Interoperability Guidelines. Standard network variable types (SNVTs) and standard configuration property types (SCPTs) are defined in the STANDARD.TYP file.
For each network variable and configuration property type, the type file supplies the following information: • The name of the type and the names for any fields within the type. These names are all programmatic names defined by the application developer. • Indices to language-dependent strings for language-dependent names, comments, and units for the type, and any fields within the type. • A minimum and maximum for each field in the type.
2. US = United States measurement system format. These formats will be automatically selected if the operating system is configured to use United States units. 3. LO = operating system (e.g. Microsoft Windows) locale-specific format. This will cause the data type to be displayed as configured in the operating system. For example, the operating system could display the date in MM/DD/YYYY format or DD.MM.YYYY format.
LNS DDE Server User’s Guide A-5
Appendix B Installing the PCLTA-10/20 and PCC-10 Drivers This appendix explains how to install the PCLTA-10, PCLTA-20, and PCC-10 cards to function as an LNS network interface for the LNS DDE Server.
PCLTA-10, PCLTA-20, and PCC-10 Adapter Installation The PCLTA-10, PCLTA-20, and PCC-10 installation software installs the files required by the Windows XP, Windows 2000, Windows NT 4.0, Windows Me, or Windows 98 operating systems to recognize the PCLTA-10, PCLTA-20, and PCC10 adapters. Therefore, installation of the software must precede insertion of the adapter into a PC ISA (PCLTA-10), PCI (PCLTA-20), or PCMCIA PC Card (PCC-10) slot.
3. Select the language you want to install and click Next. 4. A welcome window appears. Read the information on the welcome window and click Next. The software licensing agreement window appears. 5. If you agree with the terms of the agreement, click Yes.
6. Choose the destination folder where you want to install the PCLTA-10, PCLTA-20, and PCC-10 drivers. You must choose the same folder you selected for the LNS DDE Server. 7. The installation program installs the software, then a dialog appears asking you if you want to modify your CONFIG.SYS file. This allows 16-bit Windows Applications to access the network interface. Click Yes or No. Select No if you not using any legacy 16-bit applications.
5. Reinsert the power cord and then restart the PC. A New Hardware Found window will be displayed briefly when the operating system recognizes the PCLTA-10 adapter. PCLTA-20 Adapter Hardware Installation Procedure ! ESD Warning This product contains devices which are sensitive to static electricity. Before installing or removing the PCLTA-20 adapter or the network cables, discharge any static electricity which may have accumulated to earth ground. 1. Turn off the PC and remove the power cord. 2.
If the computer was rebooted after installation of the software, insert the PCC-10 card into an open PC Card slot. Otherwise, reboot the computer before insertion. The device driver for the PCC-10 card is not loaded until the first PCC-10 card is discovered. Likewise, when the last PCC-10 card is removed, the device driver is unloaded, thus freeing any system resources it was using.
PCC10L7 is selected in the NI Application list. Click Apply whether or not you change the value. 5. Click the Diagnostics button. If the PCLTA-10/20 and PCC-10 software and hardware installation has proceeded correctly, the following dialog appears: 6. Refer to the PCLTA-10, PCLTA-20, or PCC-10 online help in the Echelon Drivers program folder if this dialog does not appear. 7. Click the Test button.
9. Click the OK button. The control panel enters a receive-ready state and displays the following message while waiting for a service pin message from another device on the network: Now waiting for a service pin message. 10. Press the service pin on any device that can communicate with the network interface card. The control panel sends a diagnostic message to the device originating the service pin message using Neuron ID addressing.
Appendix C Wonderware InTouch Client Example Wonderware's InTouch HMI development tool is an one of the HMI development tools that supports the LNS DDE Server. The example described in this appendix is provided as a starting point to understand the basics about how to monitor and control various kinds of LONWORKS data using the InTouch software with the LNS DDE Server.
Introduction The InTouch example provides an overview of how to use the InTouch software with the LNS DDE Server. See Using the InTouch Example in Chapter 2 for a description of the requirements for using the example, and for installation instructions. The following section provides a brief description of InTouch. You can skip this section if you are an experienced InTouch user. Intouch Overview Wonderware’s InTouch 7.
InTouch tags fall into three main category types. Memory tags are primarily data variables local to the PC running the InTouch WindowViewer application. I/O tags act as ports that move data to and from I/O servers and the running WindowViewer application. The LNS DDE server can be an I/O server for InTouch. Indirect tags are used to perform pointer-like operations to re-map tag data sources.
3. The following dialog opens: This dialog is associated with setting up NetDDE which is not used in this example. 4. Click the Done button without modifying any fields in this dialog.
5. Select the Monitoring NVs window. Click OK. InTouch starts the WindowMaker application with the Monitor NVs window open for modification. The following dialog opens: 6. Double-click the IO_Message tag label to show the animation link assigned to this object.
7. Select the String option to animate the label with a string value. 8.
9. Double-click the tag name in the Expression: edit box to see how this tag is defined. The following Tagname Dictionary dialog opens: Click the Type button to the right of the Tagname to see the first key piece of information that is required to define the tag. In this case the tag is defined as an I/O Message. Once a tag is assigned a type (Discrete, Integer, Real, or Message), it will remain restricted to these foundation types.
handle for the Subsystem containing the targeted function block or device, and is the topic type supported by the LNS DDE server. 11. Select LNS5LMNV and click the Modify button to review the definition of the Access Name using the following dialog: In this dialog you define the Application and Topic portions of the DDE link. The LNS DDE Server only supports DDE as a protocol. The default, ‘Advise only active items’ option is selected.
1. From the WindowMaker tool, double-click the LED to the right of SW- 1. The following dialog opens: This object is an InTouch Light Wizard. Wizards are higher level objects that support only a predefined set of animation links. As seen in the figure 10, this object supports a discrete expression that is driven by the value of the SW_1State tag. 2.
Changing the Default Format Two views of the mode output of the mode simulator value are shown under LonPoint Index Type in the main window of the example (see step 5 under InTouch Animation and I/O Tags). The first form of the value uses the default format where the mode is reported as a string spelling out the enumerated value. The InTouch tag is declared as an I/O Message type, and the item description of the I/O tag is declared as follows: DI-1.Mode Simulator.
4. Modify the item to add the -tSNVT_temp_f#US option as shown in the following figure: Substitute #SI for #US to force SI units. 5. Save changes and close the open dialogs. 6. Click Runtime! to review the results. Using the InTouch DDE Link Wizards The LNS DDE server supports copy/paste DDE link operations to speed the definition of I/O tags targeting the LNS DDE server. InTouch includes two wizards to support DDE copy/paste link operations.
To open the I/O Message Display wizard, select the Text Displays category on the left. 3. Double-click the I/O Analog Display or I/O Message Display wizard. Click once at the desired position in the Monitor NV window. This will show a text object with a string ‘0.00’ for the I/O Analog Display wizard or an 'I/O message' string for the I/O Message Display wizard.
4.
5. Navigate to the OA Temp device Analog output value, right-click the Analog output, and select Copy Link from the shortcut menu as shown in the following figure: 6. Click the InTouch button on the Windows taskbar to return to the wizard. 7. Click the Paste Link button. This will automatically fill in the Application, Topic, and Item portions of the link definition. The wizard defines a default tag name.
is contained in Action animation links attached to buttons placed in the window. Descriptions of other windows in the example HMI application. Application Window Point of Interest Device Topic Test From this window you can issue test commands, monitor several device topic items, and cause Wink commands to be issued to the devices. This window shows control of a tag item definition using action scripts and the IOSetItem( ) function in InTouch.
C-16 WonderWare InTouch Example
Appendix D License Order Form This appendix provides a printed copy of the order form for LNS DDE Server credits. See Chapter 3 for information on using and adding credits, and instructions for using this order form. The order form in this appendix is only for use when you cannot automatically generate an email or printed form as described in Chapter 3. Note: Your version of the LNS DDE Server may use an alternate order form, or your LNS DDE Server license administrator may provide an alternate form.
TO: Echelon License Administrator Email: credits@echelon.com Fax: +1-408-328-3802 (please use email if available) (the fax number may change July 2001) FROM: Name: Company: Phone: Fax: Email: SUBJECT: Order for LNS(tm) DDE Server Application Key (Form 2.
The following serial number and PC key values are filled in automatically by the LNS DDE Server when you generate an application key order as described in the LNS DDE Server User's Guide. You should always use the order form generated by the software and send the form by email (or fax if email is not available) to ensure that there are no errors in transcribing the serial number and key values. When you use the software to generate the order form, you will have 30 days of unrestricted use of the software.
Description of how the original application key was lost: [ ] No charge backup key. By submitting an order for a backup key, you agree that you will use the key solely to replace an LNS DDE Server Application Key that was lost due to a bitwise copy of a disk image with the LNS DDE Server software to a backup disk or PC. Limited to a single backup PC per licensed copy of the LNS DDE Server software.
Appendix E LNS DDE Server Software License Agreement This appendix provides a printed copy of the LNS DDE Server Software License Agreement.
Notice This is a legal agreement between you and Echelon Corporation ("Echelon"). YOU MUST READ AND AGREE TO THE TERMS OF THIS SOFTWARE LICENSE AGREEMENT BEFORE ANY SOFTWARE CAN BE DOWNLOADED OR INSTALLED OR USED. BY CLICKING ON THE "I AGREE" OR "ACCEPT" BUTTON OF THIS SOFTWARE LICENSE AGREEMENT, OR DOWNLOADING LICENSED SOFTWARE, OR INSTALLING LICENSED SOFTWARE, OR USING LICENSED SOFTWARE, YOU ARE AGREEING TO BE BOUND BY THE TERMS AND CONDITIONS OF THIS SOFTWARE LICENSE AGREEMENT.
Application Key for the Licensed Software for the server computer and every remote client computer, (d) physically transfer an Application Key from one computer to another, provided that the Application Key is removed from the computer on which it was previously used and the Application Key is used on only one computer at a time, (e) copy the licensed software as necessary for the uses expressly permitted above, (f) transfer your rights under this Agreement to an end user of the Licensed Software; provided
LIMITED WARRANTY AND DISCLAIMER Echelon warrants that, for a period of ninety (90) days from the date of delivery or transmission and installation of an Application Key to you, the Licensed Software under normal use will perform substantially in accordance with the Licensed Software specifications contained in the documentation accompanying the Licensed Software.
APPROVALS, AS APPLICABLE.
E-6 Software License Agreement
Appendix F LNS DDE Server Software License Transfer Agreement This appendix provides a printed copy of the Software License Transfer Agreement.
Software License Transfer Agreement THIS SOFTWARE LICENSE TRANSFER AGREEMENT is entered into as of [insert [insert date], by and between company name of original purchaser] ("Assignor") and [insert name of company purchasing the software] ("Assignee") for the [insert name of software product being transferred] (“Software”). 1. Software License Agreement.
Glossary This glossary defines LONWORKS terms that you may encounter when using the LNS DDE Server.
Application Device The individual sensor, actuator, and controller devices that make up a network. Application devices contain an application program developed by the device manufacturer or system integrator. Typically, device manufacturers develop application programs using a LonBuilder Developer's Kit or NodeBuilder Development Tool. Some application devices use a LONWORKS network interface, and execute their application programs on a host processor.
changes; the server only sends the item's value when requested by the client. The originator of a DDE conversation. A DDE client application sends requests for information to a DDE server. Manual DDE Client DDE Conversation An exchange of information between two applications using DDE. DDE Execute A request from a DDE client to a DDE server to perform a command. DDE Initiate A request to start a new DDE conversation.
international organization that develops guidelines and certification procedures for LONWORKS products. Devices that carry the LONMARK logo are able to interoperate even if they are made by different manufacturers. Only devices that adhere to the LONMARK guidelines and have passed a conformance review may carry the LONMARK logo. Gl-4 LONWORKS Message Application data contained within a LonWorks packet. LonWorks messages are used to exchange data between application devices on a LONWORKS network.
LonTalk Adapter play compatible interface card that connects to a LONWORKS network. It has an on-board twisted-pair transceiver of one of the following types: TP/XF-78, TP/XF1250, or TP/FT-10. PCLTA-20 PC LonTalk Adapter The PCLTA-20 is a high performance PCI plug-n-play compatible interface card that connects to a LONWORKS network. It has an on-board twisted-pair transceiver of one of the following types: TP/XF-78, TP/XF-1250, or TP/FT-10.
Gl-6 Glossary
