EchelonÒ OpenLNS Server ReadMe
Release 4.00.184, January 2013
Copyright
© 2013 Echelon Corporation
All Rights Reserved
This document describes the known problems and workarounds for the OpenLNS Server. For additional information and updates (including critical updates), go to www.echelon.com/downloads. For answers to frequently asked questions, see Echelon’s Knowledge Base at www.echelon.com/support/kb. For the latest OpenLNS news, go to www.echelon.com/openlns.
5 Repairing an OpenLNS Server Installation
6 Known Problems and Workarounds
6.1 Application Download on PL-20 Channels
6.5 Moving Remote Full Clients
6.8 OpenLNS Remote Server Logging
6.10 Echelon IP-852 Configuration Server
6.11 Closing Remote Full Clients
6.12 LonWorks File Transfer Protocol Support
6.13 System.GetServiceStatus() on OpenLNS Lightweight Clients
6.14 NvMonitorPoint.Tag Property
6.22 LonMaker Functional Block Shapes
6.23 Event Timing with Multiple Remote Clients
6.24 OpenLNS xDriver Broker Service
6.25 NetworkVariable.DsIsDefaultFormat Property
6.26 LCA #51 Error Documentation
6.27 Traversing Lists with OpenLNS Clients
6.28 Swapped Near and Far Side Neuron IDs
6.29 Moving AppDevices Documentation
6.30 Database Validation and Repair
6.31 SntpClient Error after Upgrading from LNS 3.0
6.32 Installation Failure with EES
6.33 File Transfer Failure Error during Device Template Import
6.34 LNS Turbo Edition ADK Example
6.35 Network Databases on Mapped Drives
6.36 Unexpected F1 Help Behavior
6.37 Installation Interrupted on Windows XP or Windows Server 2003
6.38 OpenLNS Object Server Help Requires Acrobat Reader
6.39 Plug-in XFB Files Installed as Read-Only Files
This ReadMe document applies to the first release of the Echelon OpenLNS Server. You can verify that you have this release by starting the Programs and Features (or Add or Remove Programs on Windows XP) control panel, and checking the Version number of Echelon OpenLNS Server. For the first release of OpenLNS Server, the version number is 4.00.184.
The following section lists the system requirements for computers running the OpenLNS Server.
· MicrosoftÒ Windows 7 (64-bit and 32-bit), Windows Server 2008 SR2 (64‑bit), Windows Vista with Service Pack (SP) 1 (32-bit), or Windows XP with SP3 (32‑bit).
· Microsoft .NET Framework 3.5 SP1.
· 500MHz processor or faster (2 GHz or faster processor recommended).
· 2 GB or more of free disk space plus the minimum Windows requirements for the selected version of Windows. This does not account for the size of OpenLNS network databases.
· 512 MB RAM minimum (2 GB RAM minimum recommended) plus the minimum Windows requirements for the selected version of Windows. This may vary depending on the requirements of the OpenLNS Server and the OpenLNS applications running on the computer.
· 1,024 MB page file minimum (2,048 page file minimum recommended).
· Windows application development tool that supports the use of COM or .NET components. Echelon has tested and offers technical assistance on the following development environments:
o Microsoft Visual Studio 2010 Pro C++ (used with ATL or MFC), C#, or VB.NET
o Microsoft Visual Studio 2008 Pro C++ (used with ATL or MFC), C#, or VB.NET
· Adobe® Acrobat® Reader 6 or higher, for reading included PDF documents.
· 1,024 x 768 or higher resolution display with at least 256 colors.
· Mouse or compatible pointing device.
· Local, remote, or IP-852 OpenLDV 4.0 network interface.
o Compatible local network interfaces include the U10/U20 USB network interface; PCC‑10, PCLTA‑20, or PCLTA‑21 network interface cards; and the SLTA‑10 Serial LonTalk Adapter. The PCC/PCLTA and SLTA-10 network interfaces are compatible with 32‑bit versions of Windows only.
o Compatible remote network interfaces (RNIs) include the SmartServer, i.LON 100 Internet Server, and i.LON 600 LonWorks/IP-852 Router.
o Compatible IP-852 network interfaces include the SmartServer (with IP-852 routing option), i.LON 100 Internet Server (with IP-852 routing option), and i.LON 600 LonWorks/IP-852 Router.
Third-party network interfaces may also be compatible with OpenLNS Server, but Echelon does not test with or provide technical support for them.
OpenLNS Server is installed using Microsoft Windows Installer technology. Some components of this product were also present in earlier installations of Echelon products that did not follow the Windows Installer installation rules. As a result, installing some older Echelon products after installing this product may revert some files to obsolete versions. Workaround: If you experience software behavior changes as a result of another software installation, you can repair this product installation through the following procedure:
1. Open the Windows Control Panel.
2. Double-click Programs and Features (Windows Vista or Windows 7), or click Add or Remove Programs (Windows XP).
3. Click program to be repaired in the program list.
4. Right-click the program, and then click Repair (Windows Vista or Windows 7), or click the program, click Click Here for Support Information, and then click the Repair button (Windows XP).
5. Repeat steps 2 –4 for each program to be repaired in the program list. You may need to repair the following programs:
This section describes known problems and their workarounds for this release. Numbers in parentheses at the end of the descriptions are Echelon's internal problem tracking IDs.
An application download may fail on a PL-20 channel with default transport timers if monitoring is occurring at the same time as the application download. This problem occurs because the default PL-20 channel transport timers are optimized for typical application communication and monitoring traffic, not for monitoring combined with device application downloads. Workaround: Increase the channel delay to support simultaneous monitoring and application download. To determine the appropriate channel delay, collect a LonScanner™ protocol analyzer log of normal channel operations. In the protocol analyzer log, look for messages being sent from the Network Service Device being retried even though there are responses for those messages. Typically, in this case, the responses will be sent after all of the retries. However, due to transmission delays, some of the responses may be sent before the all of the retries have been sent. If there are a number of unexplained retries, increasing the channel cost will likely fix the problem. (43979)
If you have a device on the network, and you are monitoring it with a data point within a temporary monitor set when the device is deleted, you will not get an lcaMonitorEventTypeNvDelete event from OnNvMonitorPointEvent. Subsequent accesses to the stale point will return a “Data Server #374, object is not valid” exception. Workaround: Remove the monitor point or set prior to deleting the device. (34347)
The OpenLNS Remote Server will report a runtime error if the specified UDP port is already in use. Workaround: Specify an available UDP port to be used by the OpenLNS Remote Server as described in the OpenLNS Remote Server documentation.
You can use the Network.Replace() method to replace the current NetworkServiceDevice (NSD) with another NSD from the NetworkServiceDevices collection. This is possible even if the replacement NSD belongs to another full client which is running during the replacement. However, communication problems will occur if you replace the current NSD with another that is running. Workaround: Replace the current NSD with a new one or one that is not currently in use. (18451)
If a router configured as a repeater is defined between an OpenLNS Full Client and the server, and the client has not specified a channel prior to opening the system, the OpenLNS Server will not be able to determine the proper channel for that full client. A full client application cannot move its NSI to the correct channel—an attempt to do so will result in an "operation has been disabled, NS #91" error. It may be moved from an application running on the server machine. Workaround: If a remote client must be moved to another channel, initiate the move from a client local to the OpenLNS Server. (17220)
Microsoft TCP/IP Networking must be installed to use OpenLNS, or else a DB #-2524 error is reported when an OpenLNS database is opened. Workaround: Microsoft TCP/IP Networking is normally installed during operating system installation but it is an optional component if a network interface card (such as an Ethernet adapter) is not installed in the computer. Microsoft TCP/IP Networking is included on the Windows installation CD of all Windows operating systems that the OpenLNS Server runs on. Depending upon the Windows operating system that you are using, the Microsoft TCP/IP Networking component may be named slightly differently. See the Windows documentation for further information on how to install the Microsoft TCP/IP Networking component. (20485)
Providing MonitorPoint update events to a remote lightweight client puts a high load on the OpenLNS Remote Server. If too many MonitorPoint updates are received at the same time, the OpenLNS Remote Server cannot keep up with delivering the events and begins to exhaust available memory. The problem is compounded by the fact that once physical memory is used up, Windows starts doing memory page swaps, which further reduces real time performance and therefore worsens the situation. Ultimately the computer running the OpenLNS Remote Server will run out of memory, leading to a variety of problems. Workaround: Use remote full clients instead of remote lightweight clients, use a faster computer, install more physical memory in the computer, reduce the number of remote lightweight clients doing monitoring, reduce the number of points monitored by each client, change the throttle rate for the points being monitored, change the points to report only by exception, or some combination of the above.
The OpenLNS Remote Server application optionally produces an Access Log, an Error Log, and a Trace Log. The Access Log and Error Log generally produce few messages; however the Trace Log is designed for debugging only, and produces voluminous information, especially for a monitored network. The Trace Log slows down the OpenLNS Remote Server by up to 50%, and on a very heavily loaded OpenLNS Remote Server, the Trace Log can cause remote lightweight clients to be disconnected. Furthermore, the log file will grow until the hard disk space is exhausted. Workaround: Only use the Trace Log for debugging.
The Routers.RemoveEx() method allows you to specify the merge option even if the two channels connected by the router are of different transceiver types. The devices will not be able to communicate after this process due to incompatible transceivers. Workaround: Only merge compatible channels. (18415)
The Echelon IP-852 Configuration Server can run on the same computer as the OpenLNS Server or it can run on a different computer. When it runs on the same computer as the OpenLNS Server, the IP-852 Configuration Server and IP-852 network interface must have different IP port numbers. Port conflicts between the IP-852 network interface and the IP-852 Configuration Server cannot always be automatically detected, especially when channels and devices are defined before the OpenLNS VniServer process is loaded. When a port conflict is detected, the error reported is not always correct. Workaround: If you run the Echelon IP-852 Configuration Server and the OpenLNS Server on the same computer, configure them to use different IP port numbers. (17249)
If you close down the OpenLNS Remote Server while remote full clients are running, then close down the remote client, it can take a long time for the remote client to exit. This is due to the fact that there are relatively long timeouts associated with the client/server communication channel. It can take up to 4 minutes before the remote client completely exits. Workaround: Close remote clients before closing the OpenLNS Remote Server. (18198)
You can use the System.FileTransfer object to perform file transfers to and from devices that support the LonWorks File Transfer Protocol. OpenLNS applications can specify the number of bytes to transfer, and for devices supporting random access, the start address of the transfer. Large file transfers results in correspondingly large numbers of LonWorks messages, and this burst of network traffic may temporarily affect the network as any burst of network activity would. On a standard TP/FT-10 channel, it can take approximately 3 seconds to transfer 5000 bytes.
The File Transfer Protocol service is available to all OpenLNS applications regardless of where they execute. Lightweight clients are restricted to transferring up to 65000 bytes in one file transfer request. The transfer size limitation does not apply to other types of clients. An attempt by a lightweight client to read more than 65000 bytes from a device in one request will result in an exception, and no data will be returned to the OpenLNS application. An attempt to write more than 65000 bytes to a device in one request will result in an exception, and no data will have been written to the device.
Workaround: If you are using a lightweight client to do a LonWorks file transfer and the device to which the file transfer is being performed supports random access file transfer, transfer multiple blocks, each no larger than 65000 bytes.
System.GetServiceStatus() always returns zeros when invoked on an OpenLNS remote lightweight client. Workaround: Do not use System.GetServiceStatus() on an OpenLNS remote lightweight client. (19174)
If the NVMonitorPoint.Tag property is set after opening a monitor set, the OnNvMonitorPointUpdateEvent will return the pre-existing tag value. Workaround: Set the NvMonitorPoint.Tag property before opening the monitor set with NvMonitorSet.Open(). (20956)
Attempting to remove a network from the RemoteNetworks collection will result in an OpenLNS #8 error. Workaround: Remove the remote network from the VniNetworks collection instead. (33531)
The Subnets.Remove() method takes either a subnet name or index as an argument. The use of an index in this method will always result in an “OpenLNS #6: The object was not found.” exception. Workaround: When removing a subnet, remove it by name. (34708)
The following sequence of events can cause full clients on a network to get out of synch with the OpenLNS Server:
1. The network database is backed up.
2. A full client is added.
3. The network is restored from the backup.
4. Another computer joins the network as a full client.
The result of this sequence is that the OpenLNS Server may incorrectly assign the same network address to multiple clients. At this point, the duplicate clients will exhibit unpredictable behavior. Workaround: When restoring a backup network database, delete the ObjectServer.VniNetworks entry named “r_<Network Name>” on any computer that has been added as a full client since the backup was made. (35000)
If two or more OpenLNS clients are simultaneously reading and writing the value of a configuration property implemented in a configuration file, the read and write operations may fail with a combination of NS exceptions, including #99, #11 and #4038. Workaround: Surround CP access with OpenLNS transactions, serializing the access across multiple clients. (35144)
The Borland Delphi development environment incorrectly lists the ObjectServer.CurrentFormatLocale property as a protected member, meaning that only read access is allowed. Workaround: The following assignment code works in Delphi:
LcaObjectServer1.DefaultInterface.CurrentFormatLocale := ILcaFormatLocale(myLocale)
(35077)
The OpenLNS Database Validation tool, which is available in the Echelon OpenLNS Utilities program folder, creates an XML report file with database validation results. This report file is placed in the network database folder for the network database that is validated. If you create a network database, then remove it, the directory tree containing the network database would ordinarily be deleted, but it will not be deleted if any extra files are found in the network database folder tree. If you then try to create the same network again, the creation will fail because files are found in the target directory tree. Workaround: Delete the legacy network database directory tree if the Network.Create() method fails. (35159)
Using a mixture of remote full clients and remote lightweight clients on the same network may sometimes result in unexpected behavior. Workaround: Use the same type of remote clients within a network, either all remote full clients or remote lightweight clients. (34423)
LNS Turbo Edition added the Auto Scope Determination (ASD) feature for LonMarkObject objects. This feature automatically attempts to determine the scope (also known as mode) of each functional block on the device (during XIF import) by searching through LonMark resource files that match the device program ID at scope 6 first, then proceeding to the lower-numbered scopes. If the functional block is not found after ASD is run, the LonMarkObject.Mode will be set to lcaResourceScopeUnknown(-1).
This method of determining the LonMarkObject.Mode value supersedes the behavior of earlier LNS versions, which would set a scope of 0 or 3 based on whether the LonMarkObject type index was in the standard or user range, respectively. In most cases, this method does a better job of selecting the correct scope.
The OpenLNS Commissioning Tool (CT) and the LonMaker Integration Tool embed OpenLNS LonMarkObject.Mode information in Functional Block shapes, using it to match dropped Functional Block shapes with functional blocks that exist on network devices.
Devices that formerly set their LonMarkObject.Mode in a plug-in will not see any change in OpenLNS CT or LonMaker behavior. Devices that used the default 0 and 3 values may see a change in newly-imported devices with OpenLNS CT—Functional Block shapes that worked in LonMaker running earlier LNS versions may no longer work on OpenLNS CT.
Workaround: Modify the OpenLNS CT Functional Block shapes that no longer work to accept any number of values for the LonMarkObject.Mode property when looking for matching functional blocks on network devices. The new values introduced by ASD may include lcaResourceScopeUnknown if there are no resource files for the device or the resource files cannot be found by the OpenLNS Server. They may also include the true scope value if the resource files are newly found and included in the resource catalog. (34735)
If one OpenLNS remote client is making changes to the database within a lengthy transaction, and another remote client is subscribed to change events, the remote event listener may actually get notification of database changes before they are visible. New objects, for example, will only become visible to other remote clients after the transaction is committed. This is not a problem between remote and local clients; it is only a problem between multiple remote clients. Workaround: If you attempt to retrieve an object based on a database event, and get an “OpenLNS #6: The object was not found.” exception, wait and retry the operation. (35090)
If uplink sessions with a SmartServer, i.LON 100, or i.LON 600 are managed by an OpenLNS listener application, the uplink session handling will be disabled if the OpenLNS xDriver Broker service is stopped and restarted independently of the listener application. Workaround: Restart the listener application after the Broker service is restarted in order to restart uplink listening. (24687)
The NetworkVariable.DsIsDefaultFormat property does not work as documented in all cases. Workaround: You can determine whether a NetworkVariable object is using its default format—that is, NetworkVariable.DsFormatType has never been manually set—by saving the value of NetworkVariable.DsFormatType, setting it to the empty string, then reading it back. If it returns the original value, it is using the default format. If this method is used and the NetworkVariable object is not using its default format, be sure to restore the original value of NetworkVariable.DsFormatType when you are finished. (20412)
The current documentation describing an LCA #51 error is incomplete. The current error description is as follows: “The program ID from the DeviceTemplate object does not match the one found on the device during an attempt to commission the device.”
Workaround: Following is the updated documentation: The LCA #51 exception is now also thrown when importing an XIF file into an existing DeviceTemplate where the program ID in the XIF file does not match the program ID in the DeviceTemplate. (40967)
In chapter 4 of the OpenLNS Programmer’s Guide, the section entitled Using Transactions with Collections recommends surrounding list traversals with a transaction. While this will result in a consistent list every time, it may also result in a visible delay if multiple clients are in use and the listing client is put in queue, waiting for the current transaction. Workaround: If your application encounters excessive delays when traversing a list, traverse the list without an enclosing transaction, but retry with a transaction if your application encounters any of the concurrency errors described in this section. (45728)
The Router.MoveEx function causes the Neuron IDs of the Router near and far side to get swapped if the network interface is on an isolated channel with no paths to the Router. Workaround: Move the network interface to a channel with a path to the Router that you are going to move. (48540)
The OpenLNS documentation makes the following incorrect statement: “In networks that only contain configured routers, devices that do not use authentication can be physically moved at any time while OpenLNS is OnNet; OpenLNS will eventually detect the move and reconfigure the device.” Workaround: To move a device from one channel to another, always use the AppDevice.PreMove and AppDevice.PostMove methods, or the AppDevice.MoveEx method. (49736)
Database validation and repair operations must adhere to the following rules:
· Databases that are repaired must always be validated again after repair. Occasionally, database validation will detect additional repairable errors after a repair is done, as the first round of repairs can fix database object interconnections in such a way that other errors may subsequently be detected and repaired.
· Databases must always be backed up before validation and repair operations are attempted, in addition to normal periodic backups.
If you have previously installed LNS release 3.08 or earlier, and then install the OpenLNS Server without first upgrading to LNS Turbo Edition, you may see an error dialog each time the computer is rebooted or you log on to the computer, that contains the text “SntpClient.exe – Entry Point Not Found”. Workaround: You may close the dialog box and ignore the error. The SntpClient.exe is not required for the OpenLNS Server. To prevent this error message from appearing again, remove the "Echelon LNS SNTP Client" value from the following Windows registry key: “HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run”. (65834)
OpenLNS Server installation will fail if the Echelon Enterprise Services (EES) application included with the SmartServer Controller and i.LON 100 Internet Server is running. Workaround; Stop EES before installing the OpenLNS Server, in addition to stopping all OpenLNS applications and services. (57090)
When importing a device template, you may receive a File Transfer Failure Error (NS #103) if the folder containing the XIF file for the device template is not writable. The OpenLNS Server needs to rewrite the XFB and XFO files if they use an older format (for example, if the file were created with LNS). By default, all users can write to the LonWorks Import folder, but if the XIF, XFB, and XFO files are stored in a different folder, you may need to modify the permissions on that folder so that the files can be updated. (67514)
You may also encounter this error if you try to import a XIF file using only a relative path (for example, manf\prod\dt.xif). With the LNS Server, this path was interpreted relative to the current working directory of the process. With the OpenLNS Server, this path is interpreted relative to the path specified in the System.ImportDirectory property. (62283)
The LNS Network Management Example application from the LNS Turbo Edition ADK uses a VB6 tree view ActiveX Control; however, the OpenLNS Server no longer installs the VB6 runtime. Workaround: This example is no longer supported; however, you can download and install the VB6 runtime for your operating system from Microsoft. (63186)
By default, the OpenLNS Server runs an OpenLNS database server as a service running under the Network Service account. The OpenLNS database server is based on a FastObjects Server service. Generally, this improves system performance; however, if you try to use or add a network database that is located on a remote drive to the global database using a mapped drive (for example, X:\DB) or a UNC path (for example, \\SERVER\SHARE\DB), you may receive a database error (for example, DB #-2019 or #-2031). This is because mapped drives are user-specific and typically not available to services, and network sharing permissions may restrict access to the service account unless they are set correctly. Workaround: Change the FastObjects Server service to run under a user account that has appropriate access to the shared network resource. Alternatively, you can stop and disable the FastObjects Server service. If the FastObjects Server is stopped, it will be started as needed under the account of the currently logged in user. (63941)
When you click an object, property, or method in the OpenLNS Object Browser and then press F1 for the online help, Adobe Reader opens and displays the correct page of the OpenLNS Programmer’s Reference for the selected item. If you press F1 on another item in the Object Browser before closing Adobe Reader, the first instance of Adobe Reader is brought to the foreground, but the page does not change. Workaround: Close Adobe Reader before pressing F1 again, or use the Bookmarks pane or Find box to search for further information. (65684)
If you try to install OpenLNS Server on Windows XP or Windows Server 2003 by connecting to it using Remote Desktop, the installer will fail (“interrupted”) after activating the license. This problem is common to all installers that use chained installs. Workaround: If you are installing OpenLNS Server on Windows XP or Windowser Server 2003 using Remote Desktop, install OpenLNS Server from the console, or connect to the console session by specifying the /admin argument to the Remote Desktop command (for example, save an .RDP connection file and then run mstsc.exe /admin MYPC.RDP). (65890)
The OpenLNS Object Sever online help is provided as a PDF file. As a result, accessing the OpenLNS Object Sever online help requires Adobe Acrobat Reader. You can use other PDF viewers; however, they may not display the correct page when you open the help. Workaround: If you use another PDF viewer, also install the Adobe Acrobat Reader on your computer. (66738)
When importing an XIF file, a plug-in may fail with a "File transfer failed due to file open error" (NSS #103). This occurs if the OpenLNS Server tries to update the plug-in supplied XFB file, but the XFB file (and all other plug-in files) was installed under the C:\Program Files directory without a DACL, which left the files as read-only. Workaround: Make the folder containing the files writable. (67514)
Echelon, LNS, and LonMaker are registered trademarks of Echelon Corporation in the U.S. and other countries.