OpenLDV™ Network Driver ReadMe
Release 4.0, August 2011
Copyright © 2003 – 2011 Echelon Corporation
All Rights Reserved
The OpenLDV Network Driver provides LONWORKS® tools and applications with an open and unified Windows® software interface for sending and receiving messages through LONWORKS network interfaces. The OpenLDV driver supports network interfaces from Echelon, and also supports compatible network interfaces available from other manufacturers. Echelon's family of network interfaces includes the following:
· SmartServer Energy Manager
· U10 and U20 USB Network Interfaces
· i.LON 600 IP-852 Router
· PCC-10 PC Card Network Interface
· PCLTA-20 and PCLTA-21 PCI Network Interfaces
When used in conjunction with the SmartServer and i.LON products, the OpenLDV driver provides outstanding security including RC4 encryption, MD5 authentication, and protection from replay attacks, as well as transparent, fault-tolerant session recovery when the IP connection or power to the SmartServer or i.LON network interface is interrupted. Support is provided for uplink connections, wherein a remote network initiates a call, either dial-up or broadband, into a service center. Uplink connections are commonly used in large remote access systems in which hundreds or thousands of sites report back to a single service center.
The OpenLDV installer installs all required drivers needed to access the i.LON 10, i.LON 100, i.LON 600, PCC-10, PCLTA-20, PCLTA-21, SmartServer, U10, and U20 network interfaces. The OpenLDV driver is compatible with the Echelon SLTA-10 Serial LonTalk Adapter, but requires separate installation of an SLTA driver.
For Windows developers, the development of network tools and applications for Windows will be simpler and less time-consuming using Echelon's LNS® Network Operating System. In addition, network tools and applications that use LNS will have higher performance levels than those that use OpenLDV directly. Contact Echelon Sales at www.echelon.com/sales if you would like assistance in determining whether you should develop your network tools with LNS plus the OpenLDV driver or just with the OpenLDV driver.
Network tool installer programs normally incorporate the OpenLDV installer; however, if the network tool does not include the OpenLDV installer, the end-user can download and install the OpenLDV driver separately.
If you are developing an application that requires OpenLDV, you can use the OpenLDV SDK to build support for the OpenLDV driver into your application. You can download the OpenLDV SDK from www.echelon.com/downloads.
This document contains important information about the OpenLDV driver. See the OpenLDV SDK ReadMe document for additional information on the OpenLDV SDK. Additional information and updates, including critical updates, may be available at www.echelon.com/downloads.
5 Repairing OpenLDV Installations
11.1 Certified PCLTA-20, PCLTA-21, and PCC-10 Drivers
12 Known Problems and Workarounds
12.1 Interaction with LNS 3, Service Pack 8, Update 1
12.2 Interaction with LNS 3.08
12.3 Some Windows 2000 Installations Require Reboot
12.4 LonWorks Interfaces Missing from Control Panel
12.5 Call to ldv_open() Sometimes Fails
12.7 .NET Framework 3.5 SP1 Requirement
12.8 .NET Framework 3.5 SP1 on Windows Server 2008 R2
12.9 Unknown Publisher Warning
12.11 32-bit Title on 64-bit Windows
12.12 OpenLDV 3.4 Example Failure
12.13 Missing U10/U20 Network Interface
12.14 PCC/PCLTA Image Not Reported Correctly by Test
12.15 PCC-10 and PCLTA Interface Name Limit
12.17 RNI Re-connect Problem with Restrictive Firewall Settings
· Microsoft .NET Framework 3.5 SP1
† Note: OpenLDV 4.0 runs as a 32-bit application on both 64-bit and 32-bit versions of Windows. It cannot be called from a 64-bit client application. In order to use OpenLDV on 64-bit Windows, the OpenLDV client application must be compiled as a 32-bit application. For unmanaged C++ applications built using Windows compilers, this means that the application must be build for the “Win32” platform, not the “x64” platform. For managed .NET applications (such as C#), this means that the application must be built for the “x86” platform, not the “x64” or “Any CPU” platforms.
You must have Administrative Privileges in order to install the OpenLDV driver.
If you are using the U10 or U20 USB Network Interface, install the OpenLDV driver before plugging the network interface into a USB port.
OpenLDV400.exe is available from www.echelon.com/downloads. Download the file and then double-click the OpenLDV installer (OpenLDV400.exe) to begin the OpenLDV installation. The Welcome to the InstallShield Wizard for Echelon OpenLDV 4.0 window appears. Click Next to continue. This opens the License Agreement window.
Read the terms of the license agreement and, if you agree to the terms, click I Accept to continue. This opens the Installing Echelon OpenLDV 4.0 window. The installer completes the OpenLDV driver installation.
Normally, you are not required to reboot your computer after installing the OpenLDV driver and no completion dialog appears when the installation completes successfully. If the OpenLDV driver is not installed successfully, a dialog appears to notify you of the problem.
If you are using an i.LON or SmartServer interface, you may need to modify the configuration (such as the IP address) for those devices by opening LonWorks Interfaces in the Windows Control Panel. Consult the LonWorks Interfaces online help for more information. Advanced users managing a large number of remote network interfaces from a single computer running OpenLDV may wish to create specialized connection profiles using the xDriver Profile Editor. For more information on the xDriver Profile Editor, see the OpenLDV Programmer’s Guide.
To develop OpenLDV applications or to create specialized connection profiles, install the OpenLDV SDK, available from www.echelon.com/downloads.
The OpenLDV driver 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 the OpenLDV driver 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:
This section lists the changes included in OpenLDV 4.0. Numbers in parentheses at the end of the fix descriptions are Echelon's internal problem tracking IDs.
The LonWorks® Plug n’ Play control panel application has been eliminated. All Echelon OpenLDV drivers are now managed through the updated LonWorks Interfaces control panel application. See the LonWorks Interfaces online help for details of the available configuration options.
The network interface device drivers have been recertified for the supported versions of Windows. These include:
The following problems have been fixed in OpenLDV 4.0:
The following problems have been fixed in OpenLDV 3.4:
The PCC10L7 image has been added back to the available images for the PCC and PCLTA cards. This image is not used by LNS applications, but some legacy applications require it. (42584)
In some cases, OpenLDV 3.3 installation can cause PCLTA-10, PCLTA-20 and PCC-10 card device driver entries to disappear after reboot. (42583)
The PCLTA-20 driver does not recognize the new RoHS-compliant PCLTA-20/SMX network interface card. (42396)
This section lists the changes included in OpenLDV 3.3.
The Echelon network interface cards formerly supported by a separate driver installation have been incorporated into the OpenLDV installation. The driver for these cards has been certified by Microsoft for compatibility with the Windows 2000, Windows XP, and Windows 2003 operating systems. The driver has not been certified for compatibility with Windows Vista. These interfaces are still defined and managed through the LonWorks® Plug n’ Play item in the Windows Control Panel.
The following problems have been fixed in OpenLDV 3.3:
The following are known OpenLDV problems and their workarounds. The numbers in parentheses at the end of the problem descriptions are Echelon's internal problem tracking IDs.
Echelon released a patch update to the LNS product in March 2003 named “LNS 3, Service Pack 8, Update 1” (LNS3SP8U1) that is not forward compatible with OpenLDV 3.3 and later releases.
This patch will cause problems for any computer with OpenLDV 4.0 installed, if it is installed after OpenLDV 4.0. It will overwrite the newer OpenLDV components, causing them to revert back to older versions. This will cause all functionality added in OpenLDV 3.3 through 4.0—such as USB network interface support—to be lost, and may cause programs that use new OpenLDV API calls (see ldv32.h in the OpenLDV 4.0 SDK) to completely fail to run.
The LNS3SP8U1 patch is included in some versions of the Echelon i.LON 10, i.LON 100 v1.1, and LonMaker® 3.13 product installations, and may also be embedded in installations from other companies that license and redistribute the LNS runtime. Although it is being phased out of product software, it may be encountered for some time to come. The OpenLDV 4.0 installation can be used as a replacement for LNS3SP8U1, as it corrects all of the problems corrected by that update, plus provides new USB functionality and bug fixes.
This problem will only manifest itself if LNS 3 is installed on the computer. If LNS Turbo or a later version is installed, this problem will not occur. (36682)
Workaround: If you suspect that you have encountered this problem, go through the procedure described in Repairing OpenLDV Installations. The OpenLDV 4.0 installation will then repair itself and function correctly. If this is not the problem, there is no harm in running the repair operation.
After installing OpenLDV 4.0 over LNS 3.08, uninstalling OpenLDV 4.0 will cause LNS 3.08 to become inoperable. OpenLDV 4.0 provides a partial upgrade to LNS 3.08 that may not be completely reversed by uninstalling. If your product installation embeds the OpenLDV 4.0 installation, do not attempt to uninstall it as part of your uninstallation process. Workaround: If LNS 3.08 has been inadvertently broken by uninstalling OpenLDV 4.0, reinstall OpenLDV 4.0. (36258)
On Windows 2000, the OpenLDV installation will require a reboot before LonWorks Interfaces appears in the Windows Control Panel or before the OpenLDV driver is accessible to all users.
On all Windows versions later than Windows 2000, if the OpenLDV driver is installed by one user, a reboot is necessary before logging onto another user and using OpenLDV. Logging off one user and onto another is not sufficient.
The installation does not always inform the user when a reboot is required. (32177, 32724)
Workaround: If some OpenLDV functionality is not working after installation, but before reboot, try again after rebooting your computer.
On a small number of Windows 2000 installations, LonWorks Interfaces may not appear in the Windows Control Panel, even after a reboot. This has been seen on a small number of computers that have been upgraded from earlier versions of Windows to Windows 2000. (41439)
Workaround: On Windows 2000, follow these steps:
When using the OpenLDV API, a call to ldv_open() immediately after a call to ldv_close() on the same network interface sometimes fails. Workaround: Insert a one-second delay between the ldv_close() call and the next call to ldv_open(). (37296)
The LNS DDE Server 2.11 software cannot handle RNI names longer than 22 characters, resulting in indeterminate behavior. RNI names, in the format x.Default.[User Defined Name], will extend beyond this limit if the user-defined portion of the name is over 12 characters long. Workaround: Limit user-defined names to 12 characters or less. (45752)
The .NET Framework 3.5 SP1 required by OpenLDV 4.0 is not a subset of the .NET Framework 4. From .NET 2 through .NET 3.5 SP1, all of the framework versions installed .NET 2 through the current version. The .NET Framework 4 does NOT do this. The fact that you have .NET 4 installed does not imply that you also have Framework 3.5 SP1 installed. The .NET 3.5 SP1 Framework installation had become huge (>200MB), and Microsoft apparently abandoned that scheme. (58841)
If you try to install .NET Framework 3.5 SP1 on a clean Windows Server 2008 R2 machine, the SP1 setup will halt with the message "You must use the Role Management Tool to install or configure Microsoft .NET Framework 3.5 SP1." That is kind of misleading, because when you find the Role Manager within the Server Manager tool, it does not say anything about .NET. (58841)
To install the .NET 3.5 SP1 Framework on Windows Server 2008 R2:
The OpenLDV 4.0 installation program is digitally signed to verify that it is software from Echelon Corporation. However, if you uninstall this program from the Add/Remove Programs on Windows Vista, it will display a UAC warning that the installation has an unknown publisher. This is a known Windows Vista problem, caused by Vista compression of the cached installation program used in the uninstall process – see http://kb.flexerasoftware.com/selfservice/viewContent.do?externalID=Q112476 for details. (59049)
Local network management commands directed at network interfaces will sometimes have the authentication bit set by the controlling software. In the responses to local request-response network management commands, the authentication bit is ignored. Various network interfaces either copy the original value of the bit in the response, or always reset it, but no significance should be attached to this. (45296)
On 64-bit versions of Windows, the title of the LonWorks Interfaces applet in the Windows Control Panel is shown as LonWorks Interfaces (32-bit). Workaround: This is normal and the control panel application will function normally in this environment. The name indicates that OpenLDV and its control panel application are 32-bit components, which run in 32-bit mode on 64-bit Windows. (59601)
After installing the OpenLDV 4.0 runtime, the OpenLDV 3.4 example may fail with the “This application has failed to start because MFC71.dll was not found. Reinstalling the application may fix this problem” error. This occurs because the OpenLDV 4.0 runtime update caused OpenLDV 3.4 and its components to be removed from the system. If no other application on the PC has installed the MFC71.dll component, it will no longer be present. Workaround: Install the OpenLDV 4.0 SDK to get updated examples that work with OpenLDV 4.0. (58688)
If an Echelon U10 or U20 USB device is plugged in before the OpenLDV 4.0 software is installed on a computer, the driver installation could partially fail in a way that makes the device invisible to the LonWorks Interfaces control panel applet. Workaround: Unplug the U10/U20 USB device. Uninstall the OpenLDV 4.0 runtime. Go to the Windows Device Manager and remove the USB device there. Re-install the OpenLDV 4.0 runtime. Plug the USB device back in. (59851)
When changing a PCC-10 or PCLTA’s “NI Application” image, the updated driver information is not shown on a subsequent Test command. Updated driver information will not be shown until the Test command is run two times or more. Workaround: Run the Test command again if the driver information seems out of date. (62182)
PCC-10 and PCLTA devices may only use device names in the range LON1 through LON9. If the “Starting Interface Name” for these types of devices is set to LON9, the system may only support one device of this type. Workaround: Set the Starting Interface Name to LON1 to support 9 LON interface devices. (62136)
When adding RNI and LonScanner interfaces, some invalid hostnames may be accepted, but later cause the “A non-recoverable error occurred during a database lookup” error message. Workaround: Enter a valid IP address or hostname in this field. (61672)
If the IP connection is disrupted between a computer running OpenLDV and an RNI and the OpenLDV computer is behind a firewall that only permits outbound connections based on the source-side port number, the reconnection may fail. Most firewalls are not this restrictive and will normally be configured to permit outbound connections based only on the target-side port number, allowing the source-side port number to be any value. Workaround: To communicate with RNI network interfaces in this scenario, modify the xDriver Profile on the client computer to specify a non-zero “TCP Local Port” on the “Downlink Sessions” tab.
With this configuration, if a session is closed or fails, it is not possible to re-connect to the same RNI for four minutes (until the connection leaves the TIME_WAIT state). Workaround: Either ensure that you won’t need to reconnect to the same RNI within four minutes; or create multiple xDriver Profiles (and duplicate RNI entries), each using a different permitted Local Port, and cycle among the profiles when connecting to the same RNI. (26579)
Since the OpenLDV driver is designed to be incorporated into third-party software products, the documentation required to use the OpenLDV driver is included with the third-party software product that includes the OpenLDV driver.
If you need to create Windows applications using the OpenLDV driver, download the OpenLDV SDK available from www.echelon.com/downloads.
The license that governs the use of the OpenLDV driver is available from the LonWorks OpenLDV directory in license_OpenLDV.htm.
The company that writes an application that uses the OpenLDV driver is required to provide technical support for their product. For technical support purely in relation to the OpenLDV driver apart from use of the OpenLDV driver by a client application, contact Echelon Support as described at www.echelon.com/support.