Echelon OpenLDV User Manual
OpenLDV
Programmer’s Guide
078-0275-01D
Echelon, i.LON, LonMaker, LONMAR K, LonTalk, LONWORKS, LNS,
Neuron, NodeBuilder, 3120, 3150, and the Echelon logo are
trademarks of Echelon Corporation registered in the United
States and other countries. LonScanner and OpenLDV are
trademarks of the Echelon Corporation.
Other brand and product names are trademarks or
registered trademarks of their respective holders.
Smart Transceivers, Neuron Chips, and other OEM Products
were not designed for use in equipment or systems, which
involve danger to human health or safety, or a risk of
property damage and Echelon assumes no responsibility or
liability for use of the Smart Transceivers or Neuron Chips in
such applications.
Parts manufactured by vendors other than Echelon and
referenced in this document have been described for
illustrative purposes only, and may not have been tested
by Echelon. It is the responsibility of the customer to
determine the suitability of these parts for each
application.
ECHELON MAKES AND YOU RECEIVE NO WARRANTIES OR
CONDITIONS, EXPRESS, IMPLIED, STATUTORY OR IN ANY
COMMUNICATION WITH YOU, AND ECHELON SPECIFICALLY
DISCLAIMS ANY IMPLIED WARRANTY OF MERCHANTABILITY
OR FITNESS FOR A PARTICULAR PURPOSE.
No part of this publication may be reproduced, stored in a
retrieval system, or transmitted, in any form or by any means,
electronic, mechanical, photocopying, recording, or
otherwise, without the prior written permission of Echelon
Corporation.
Printed in the United States of America.
Copyright © 2004, 2011 Echelon Corporation.
Echelon Corporation
www.echelon.com
Welcome
This document describes Echelon’s OpenLDV™ Release 4.0 Network Driver and
Software Development Kit (SDK). The OpenLDV driver is an open driver for
Microsoft
send and receive low-level ISO/IEC 14908-1 messages through compatible
Echelon and third-party network interfaces. The OpenLDV SDK provides
example source code that demonstrates how to use the OpenLDV driver.
Supported network interfaces include local network interfaces (such as the
Echelon U10 or U20 USB Network Interface, PCC-10 PC Card, PCLTA-21 PC
LonTalk
Echelon SmartServer and i.LON
The OpenLDV driver includes an extensible remote network interface (RNI)
component, called xDriver. The OpenLDV driver uses xDriver to connect an
OpenLDV application, such as an LNS
This document describes how to configure and extend xDriver, including
descriptions of the software tools that you use to configure and extend xDriver,
and provides programming samples.
The OpenLDV SDK provides a low-level application programming interface (API)
for network applications. For most L
Echelon’s LNS Network Operating System software provides an interface to the
OpenLDV driver that is easier to use and that significantly reduces the time
required to develop L
Network tools that use LNS software generally have much higher performance
than those that use only the OpenLDV API. You can find out more about LNS
software on Echelon’s Web site at www.echelon.com/lns
at www.echelon.com/sales if you would like assistance in determining whether
you should develop your network tools with LNS software or with the OpenLDV
API.
®
Windows® operating systems that enables Windows applications to
®
Adapter), and Internet-enabled network interfaces (such as the
ONWORKS applications and tools for Windows environments.
®
600 IP-852 Router).
®
Server, to remote LONWORKS® networks.
ONWORKS application developers, using
. Contact Echelon Sales
Programming with the OpenLDV API requires knowledge of the ISO/IEC 149081 Control Network Protocol. Echelon’s implementation of the ISO/IEC 14908
Control Network Protocol is called the LonTalk protocol. Echelon has
implementations of the LonTalk protocol in several product offerings, including
the Neuron firmware, LNS Server, i.LON 600 IP-852 Router, and SmartServer
Energy Managers. This document refers to the ISO/IEC 14908 Control Network
Protocol as the “LonTalk protocol”, although other interoperable implementations
exist.
Audience
This guide is intended for software developers creating OpenLDV applications for
use with OpenLDV compatible network interface products. Readers of this guide
should be familiar with L
This guide is also intended for software developers creating xDriver extensions.
Programming samples in this document are written in C++ and Microsoft
®
Basic
.NET. However, extensions for xDriver can be written in any language
that supports Component Object Model (COM) components or ActiveX
Developers of xDriver extensions should have programming experience in such a
language, as well as familiarity with L
OpenLDV Programmer’s Guide iii
ONWORKS technology.
ONWORKS technology and COM concepts.
®
Visual
®
controls.
Examples
Throughout this guide, C++, Visual Basic, and other language programming
samples are used to illustrate concepts. To make these samples more easily
understood, they have been simplified. Error checking has generally been
removed, and in some cases, the examples are only fragments that might not
compile without errors or warnings.
Related Documentation
The following manuals are available from the Echelon Web site
(www.echelon.com
LONWORKS and LNS applications:
• Introduction to the LONWORKS Platform (078-0391-01B). This manual
provides an introduction to the ISO/IEC 14908 (ANSI/CEA-709.1 and
EN14908) Control Network Protocol, and provides a high-level
introduction to L
are used for developing, installing, operating, and maintaining them.
• LNS Programmer's Guide (078-0177-01F). This manual describes how to
write powerful LNS applications, and how to get those applications to
market quickly.
All of the Echelon documentation is available in Adobe
PDF files, you must have a current version of the Adobe Reader
download from Adobe at: get.adobe.com/reader
) and provide additional information that can help you develop
ONWORKS networks and the tools and components that
.
PDF format. To view the
, which you can
In addition to the Echelon documentation, the following specification can help
you develop L
• International Organization for Standardization (ISO) and International
You can purchase copies of ISO standards from the Information Handling
Services (IHS) Global page at: global.ihs.com
ONWORKS and LNS applications:
Electrotechnical Commission (IEC) standard ISO/IEC 14908 Control
Network Protocol
.
iv
Table of Contents
Welcome ......................................................................................................... iii
Audience ........................................................................................................ iii
Examples ....................................................................................................... iv
Related Documentation ................................................................................ iv
Chapter 1. Introduction ................................................................................... 1
Introduction to OpenLDV Networking ......................................................... 2
Client Applications .................................................................................. 3
OpenLDV Driver ...................................................................................... 3
Network Interfaces .................................................................................. 4
Installing the OpenLDV Software ................................................................ 5
Hardware and Software Requirements.................................................. 5
Downloading the OpenLDV Software .................................................... 5
Installing the OpenLDV Driver .............................................................. 6
Installing the OpenLDV SDK ................................................................. 6
Getting Started with the OpenLDV Driver .................................................. 7
Getting Started with the xDriver Component ............................................. 8
Chapter 2. Using the OpenLDV API ............................................................. 9
Introduction to OpenLDV Programming .................................................... 10
OpenLDV Application Architecture ............................................................ 11
Application Layer .................................................................................. 12
Presentation Layer ................................................................................ 13
Overview of the OpenLDV API ................................................................... 13
Referencing the OpenLDV Component ................................................ 14
Using Multiple Threads or Multiple Processes ................................... 14
The OpenLDV API ....................................................................................... 15
Working with Devices and Drivers ....................................................... 16
Using the OpenLDV API ....................................................................... 17
ldv_close() ............................................................................................... 18
ldv_free_device_info() ............................................................................ 18
ldv_free_driver_info() ............................................................................ 19
ldv_free_matching_devices() ................................................................. 20
ldv_get_device_info() ............................................................................. 20
ldv_get_driver_info() .............................................................................. 21
ldv_get_matching_devices() .................................................................. 22
ldv_get_version ...................................................................................... 22
ldv_locate_sicb() ..................................................................................... 23
ldv_open() ............................................................................................... 24
ldv_open_cap()........................................................................................ 25
ldv_read() ............................................................................................... 27
ldv_register_event() ............................................................................... 29
ldv_set_device_info() .............................................................................. 30
ldv_set_driver_info() .............................................................................. 31
ldv_write() .............................................................................................. 32
ldv_xlate_device_name() ....................................................................... 33
ldvx_open() ............................................................................................. 34
ldvx_register_window() ......................................................................... 36
ldvx_shutdown() ..................................................................................... 37
Structures and Enumerations for the Device API ..................................... 37
LDVDeviceInfo Structure ..................................................................... 37
LDVDevices Structure........................................................................... 38
OpenLDV Programmer’s Guide v
LdvCombineFlags Enumeration ........................................................... 39
LdvDeviceCaps Enumeration ............................................................... 40
Structures and Enumerations for the Driver API ..................................... 42
LDVDriverInfo Structure ...................................................................... 42
LdvDriverID Enumeration ................................................................... 43
LdvDriverType Enumeration ............................................................... 44
Windows Messages for Session Notifications ............................................. 44
OpenLDV API Return Codes ....................................................................... 45
Example: A Simple OpenLDV Application ................................................ 52
Chapter 3. Sending/Receiving Messages with the OpenLDV API ....... 57
Constructing Messages ................................................................................ 58
Application Buffer Structure ....................................................................... 58
Layer 2 Buffer Structure ....................................................................... 61
Application Layer Header .............................................................. 61
Layer 2 Header ................................................................................ 61
NPDU ............................................................................................... 61
CRC .................................................................................................. 62
Layer 5 Buffer Structure ....................................................................... 62
Application Layer Header .............................................................. 62
Message Header .............................................................................. 62
Network Address ............................................................................. 67
Message Data .................................................................................. 73
Sending Messages to the Network Interface ....................................... 75
Receiving Messages from the Network Interface ................................ 75
Using the Network Interface Command Interface .................................... 76
Downlink Commands ............................................................................ 76
Uplink Commands ................................................................................. 77
Immediate Commands .......................................................................... 77
Network Interface Commands .............................................................. 77
Chapter 4. The OpenLDV Developer Example ........................................ 89
Overview ....................................................................................................... 90
Common Definitions .................................................................................... 90
COpenLDVapi and COpenLDVtrace .......................................................... 90
COpenLDVni, Message Pumps, and Message Dispatchers ...................... 90
Toolkits and User Interface ......................................................................... 91
Developer Example Diagram ...................................................................... 92
Chapter 5. Using the xDriver Default Profile .......................................... 93
Configuring an xDriver Profile.................................................................... 94
LNS Applications for xDriver ...................................................................... 98
Chapter 6. Extending xDriver ...................................................................... 99
Extending xDriver ...................................................................................... 100
xDriver Sessions ......................................................................................... 100
Downlink Sessions ............................................................................... 100
Uplink Sessions ................................................................................... 104
Session Control Object ........................................................................ 108
Authentication Key Handling ................................................................... 111
Setting the Current Authentication Key ........................................... 111
Changing the Current Authentication Key ....................................... 112
Creating a Custom Lookup Extension in C++ ......................................... 113
Create a New Visual Studio Project ................................................... 114
Add a COM Object ............................................................................... 116
vi
Implement the ILdvxLookup Interface .............................................. 119
Add the Extension to the Component Category ................................ 121
Build and Register the COM Server .................................................. 121
Create a Custom xDriver Profile ........................................................ 122
Test the Lookup Extension ................................................................. 124
Optional Steps ..................................................................................... 124
Creating a Custom Lookup Extension in Visual Basic ............................ 125
Create a New Visual Studio Project ................................................... 125
Add a Reference to the xDriver Type Library ................................... 127
Add a COM Class ................................................................................. 127
Delete the Project Default Class ......................................................... 128
Import xDriver Types to Your System Namespace ........................... 129
Implement the ILdvxLookup Interface .............................................. 129
Build and Register the Lookup Extension ......................................... 130
Create a Custom xDriver Profile ........................................................ 130
Test the Lookup Extension ................................................................. 132
Sample Lookup Extension Component ..................................................... 132
xDriver Profiles .......................................................................................... 134
Starting the Connection Broker ......................................................... 135
Chapter 7. LNS Programming with xDriver .......................................... 137
Downlink Sample Applications ................................................................. 138
Opening a Single Remote Network With xDriver ............................. 138
Opening Multiple Remote Networks for Downlink ........................... 139
Uplink Sample Application ....................................................................... 142
Appendix A. Custom Network Interfaces................................................ 147
Overview ..................................................................................................... 148
Working with a Custom Network Interface ............................................. 148
Windows Registry Entries ......................................................................... 150
Appendix B. LNS Methods and Events for xDriver Support ............. 153
xDriver Methods and Events ..................................................................... 154
AcceptIncomingSession ....................................................................... 154
BeginIncomingSessionEvents ............................................................. 155
EndIncomingSessionEvents................................................................ 155
NetworkInterfaces.Item( ) ................................................................... 156
OnIncomingSessionEvent ................................................................... 157
ReleasePendingUpdates ...................................................................... 158
Appendix C. Custom Lookup Extension Programming ...................... 161
Overview ..................................................................................................... 162
ILdvxConfigure Interface .......................................................................... 162
SetInstance Method ............................................................................. 162
SetOptions Method .............................................................................. 163
ILdvxLookup Interface .............................................................................. 164
DownlinkLookup Method .................................................................... 164
UpdateLookup Method ........................................................................ 165
UplinkLookup Method ........................................................................ 165
ILdvxSCO Interface ................................................................................... 166
GetAdditionalDownlinkPacketHeader Method ................................. 167
GetAdditionalDownlinkPacketTrailer Method ................................. 167
GetAuthenticationFlag Method .......................................................... 168
GetCurrentAuthenticationKey Method ............................................. 168
GetDownlinkKey Method .................................................................... 169
OpenLDV Programmer’s Guide vii
GetEncryptionType Method ................................................................ 170
GetLNSNetworkName Method .......................................................... 170
GetNextAuthenticationKey Method ................................................... 171
GetSessionControlObjectID Method .................................................. 171
GetUplinkKey Method ........................................................................ 172
SetAdditionalDownlinkPacketHeader Method ................................. 172
SetAdditionalDownlinkPacketTrailer Method .................................. 173
SetAuthenticationFlag Method .......................................................... 173
SetCurrentAuthenticationKey Method .............................................. 174
SetDownlinkKey Method .................................................................... 175
SetEncryptionType Method ................................................................ 175
SetLNSNetworkName Method ........................................................... 176
SetNextAuthenticationKey Method ................................................... 177
SetUplinkKey Method ......................................................................... 178
ILdvxSCO_TCP Interface .......................................................................... 178
GetRemoteTCPAddress Method ......................................................... 179
GetRemoteTCPPort Method ............................................................... 179
SetRemoteTCPAddress Method ......................................................... 180
SetRemoteTCPPort Method ................................................................ 180
ILdvxSCO2 Interface ................................................................................. 181
GetNeuronID Method .......................................................................... 181
Index ................................................................................................................. 183
viii
1
Introduction
This chapter introduces the OpenLDV driver and how you
can use it to send and receive LonTalk messages through
any OpenLDV compatible network interface.
This chapter also introduces the xDriver component.
OpenLDV Programmer’s Guide 1
Introduction to OpenLDV Networking
OpenLDV Driver
Your
LNS
Application
Your
OpenLDV
Application
LonScanner
Protocol
Analyzer
Windows
Device
Drivers
OpenLDV Client Applications
Using the OpenLDV API
SLTA
PCC-10 PCLTA-22
U10 or U20
xDriver
Component
i.LON 10
i.LON 100 i.LON 600
SmartServer
Remote
Network Interfaces
Local
Network Interfaces
The OpenLDV driver allows a Windows application to communicate with a
ONWORKS network through a locally attached network interface or a remote
L
network interface. Figure 1 shows the basic components for communicating
with a L
ONWORKS network:
• One or more OpenLDV client applications (for example, an LNS Server
with one or more LNS clients, the Echelon LonScanner™ Protocol
Analyzer, or some other client that does not use an LNS Server), which
use the OpenLDV API
• The OpenLDV driver
• One or more local network interfaces, which use a Windows device driver
provided with the network interface
• One or more remote network interfaces (usually Internet enabled), which
use the xDriver component of the OpenLDV driver
2 Introduction
Figure 1. OpenLDV Programming Model
Client Applications
OpenLDV applications, such as the LNS Server and the LonScanner Protocol
Analyzer, use the OpenLDV application programming interface (API) to
communicate with L
ONWORKS network interfaces.
Echelon’s LNS software provides a high-level interface to L
that simplifies managing network interfaces. The LNS software is a powerful,
flexible network management platform you can use with high-performance
Layer-2 or Layer-5 network interfaces, as well as with IP-852 routers (such as
the i.LON 600 or SmartServer). The LNS Server provides a wide variety of
network management and monitor and control services, and allows multiple
client access to the same network interface.
For most customers, choosing the LNS software platform will result in a highquality application that can be developed more quickly, requiring less knowledge
of low-level details, than with other network management platforms, including
the OpenLDV platform. However, the OpenLDV API provides a low-level
interface for writing Windows based L
ONWORKS network interfaces.
L
You can use the OpenLDV API to write your own application that sends and
receives messages through L
LonTalk Layer 2 or Layer 5 interface. These messages can initialize and
terminate communications with the network interface, retrieve incoming
messages, or transmit outgoing messages. See Chapter 2, Using the OpenLDV
API, on page 9, and Chapter 3, Sending and Receiving Messages with the
OpenLDV API, on page 57, for information about these topics.
OpenLDV Driver
ONWORKS networks
ONWORKS software for use with
ONWORKS network interfaces, using either a
You can use the OpenLDV runtime with network management or monitoring and
control applications. For example, for a self-installed system with fixed network
addresses, you can use the OpenLDV API to create an application that sends
messages to test the devices on your network. This diagnostic application could
periodically send request messages to devices in the system to check their status.
You can also use the OpenLDV API to create a data logging application to
monitor and retrieve network variable values from the various devices on your
network.
The OpenLDV 4.0 driver and API are backward-compatible with previous
versions of the driver and the API (but see Hardware and Software Requirements
on page 5 for the OpenLDV 4.0 requirements, which differ from those of prior
releases).
To develop an OpenLDV application, you must understand LonTalk message
formats and network interface state management. You also need to be able to
manage low-level LonTalk messaging details, such as LonTalk reference IDs.
Chapters 3 and 4 of this document describe some of the LonTalk message formats
that you can use with the OpenLDV API. In addition, the section Message
Header on page 62 includes some discussion of LonTalk reference IDs. See the
ISO/IEC 14908 Control Network Protocol specification for detailed information
about the LonTalk protocol.
OpenLDV Programmer’s Guide 3
Network Interfaces
TCP/IP
LonWorks Channel
LonWorks Channel
LonWorks Devices
LonWorks Devices
OpenLDV Application
with xDriver
A local network interface (one that is physically connected to the computer
running the OpenLDV driver) uses its own Windows device driver. Echelon and
third parties provide a number of network interface products; see the specific
documentation about the network interface for more information.
You can also develop your own custom OpenLDV compatible local network
interface. To make your network interface compatible with the OpenLDV driver,
you must also develop a Windows device driver for it; see Appendix A, Custom
Network Interfaces, on page 147, for additional information about working with a
custom network interface.
A remote network interface (one that is connected to the computer through an IP
network, typically the Internet) uses the xDriver component of the OpenLDV
driver as a virtual device driver. The xDriver component is an extensible
network driver that uses IP to establish connections between OpenLDV
applications and network interfaces (such as an Echelon SmartServer).
xDriver can provide authenticated connections from an OpenLDV application to
hundreds or even thousands of remote L
(such as a SmartServer). As shown in Figure 2, the OpenLDV application
accesses the SmartServer, and the L
connected to, through an IP connection.
ONWORKS networks through RNI devices
ONWORKS channel that the SmartServer is
Figure 2. An OpenLDV Application Using xDriver to Manage LonWorks Devices
You configure the xDrvier component with an xDriver profile. An xDriver profile
is a set of configuration parameters that determines how xDriver manages
4 Introduction
connections with a group of remote networks. For example, you could have
hundreds of remote networks, each of which has a SmartServer attached. At
your service center, your monitoring tool could use the OpenLDV driver to listen
for session requests from these networks and send messages to remote devices.
The OpenLDV driver includes a default xDriver profile. You can use the default
xDriver profile for your OpenLDV applications, or you can use the xDriver Profile
Editor to create a custom xDriver profile for your OpenLDV applications; see
Chapter 5, Using the xDriver Default Profile, on page 93.
You can configure each xDriver profile to provide your application with
information identifying the network interface that has requested a network
session. Thus, you can program your application to quickly identify the source of
the session request, and respond to a variety of different alarm conditions. See
Configuring an xDriver Profile on page 94 for more information about the xDriver
profile.
Installing the OpenLDV Software
The following sections describe the requirements for downloading the OpenLDV
software, installing it, and using the OpenLDV software.
Hardware and Software Requirements
To install and use the OpenLDV 4.0 software, your computer must meet the
following minimum requirements, in addition to those imposed by your operating
system:
• 512 MB RAM (or the Windows operating system minimum requirement)
• Microsoft Windows 7 (32-bit or 64-bit), Windows Server 2008 R2 (64-bit),
Windows Vista
SP3
• Microsoft .NET Framework 3.5 SP1
• 50 MB of available hard-disk space
• 1024x768 screen resolution
®
(32-bit), Windows Server 2003 (32-bit), or Windows XP
Downloading the OpenLDV Software
You can download the OpenLDV driver and SDK from Echelon’s Web site at
www.echelon.com/downloads
The OpenLDV driver installer (OpenLDV400.exe) installs the OpenLDV driver,
ONWORKS Interfaces application in the Windows Control Panel, and the
the L
xDriver Profile Editor.
You can incorporate the OpenLDV driver installer into your OpenLDV
application’s installation, either as a standalone component that your end-users
will install, or as a component that your overall software installer will install.
The OpenLDV runtime installer is based on Microsoft Installer 3.1. If the
computer onto which you are installing the OpenLDV driver uses an older
version of Microsoft Installer, the OpenLDV driver installation will update the
computer to use version 3.1.
.
OpenLDV Programmer’s Guide 5
See the OpenLDV 4.0 ReadMe document for updates to the OpenLDV driver
documentation.
To develop an OpenLDV application or xDriver extension, install the OpenLDV
SDK (OpenLDV400-SDK.exe) in addition to the OpenLDV driver. The
OpenLDV SDK contains documentation, source files, and several examples,
which you can use when developing your own OpenLDV application or xDriver
extension.
See the OpenLDV SDK 4.0 ReadMe document for updates to the OpenLDV SDK
documentation.
Installing the OpenLDV Driver
To install and use the OpenLDV driver, perform the following steps:
1. Download the OpenLDV Driver OpenLDV400.exe file from Echelon’s
Web site at www.echelon.com/downloads
2. Double-click the OpenLDV400.exe file to begin the OpenLDV driver
installation. The OpenLDV driver installer window opens.
3. Follow the installation dialogs to install the OpenLDV driver onto your
computer.
If you are using a SmartServer or i.LON network interface:
.
1. Use the L
to specify the IP network addresses of the SmartServer or i.LON network
interface. See the online help for the L
for information about how to use it.
2. If you are using a SmartServer or i.LON network interface and you are
developing a custom xDriver profile, use the xDriver Profile Editor in the
OpenLDV program folder to configure an xDriver profile for use with
your OpenLDV application. For more information on the xDriver Profile
Editor, see Chapter 5, Using the xDriver Default Profile, on page 93.
3. See the installation instructions for your network interface for any
additional instructions for configuring the network interface.
ONWORKS Interfaces application in the Windows Control Panel
Installing the OpenLDV SDK
To install and use the OpenLDV SDK, perform the following steps:
1. Download and install the OpenLDV driver, as described in Installing the
OpenLDV Driver.
2. Download the OpenLDV SDK OpenLDV400-SDK.exe file from
Echelon’s Web site at www.echelon.com/downloads
3. Double-click the OpenLDV400-SDK.exe file to begin the OpenLDV SDK
installation. The OpenLDV SDK installer window opens.
ONWORKS Interfaces application
.
4. Follow the installation dialogs to install the OpenLDV SDK onto your
computer.
5. You can now use the OpenLDV SDK to write applications that use the
OpenLDV API or create xDriver extensions. For information about the
OpenLDV API, see Chapter 2, Using the OpenLDV API, on page 9. For
6 Introduction
information about xDriver extensions, see Chapter 6, Extending xDriver,
on page 99.
Getting Started with the OpenLDV Driver
An OpenLDV application can use a Layer 2 network interface or a Layer 5
network interface:
• Layer 2 Network Interface – A network interface that communicates at
Layer 2 of the LonTalk protocol. This type of interface transports
LonTalk packets without processing them, and does not filter by network
address. It is typically used for applications that implement layers 3
through 7 of the LonTalk protocol, such as an LNS Server, and is also
used for protocol analyzers that log and display network traffic.
Implementing layers 3 through 7 on a Windows computer, rather than in
the Neuron core or other processor of a local network interface, can
provide significantly higher performance. For example, the LNS Server
includes an implementation of layers 3 through 7 that provides
significantly higher performance when used with a Layer 2 network
interface.
• Layer 5 Network Interface – A network interface that communicates at
Layer 5 of the LonTalk protocol. This type of interface transports
incoming LonTalk packets that are addressed to the network interface,
and transports outgoing packets that are addressed to other devices. It is
typically used for remote network interfaces (such as a SmartServer or an
i.LON network interface) because these interfaces typically implement
layers 3 through 5 on a high performance processor within the network
interface, and it allows an uplink session to be initiated when the host
receives a particular message addressed to it. This type of interface
requires handling of NI resources, such as reference IDs, at a software
layer above the OpenLDV layer. For example, the LNS Server manages
NI resources when used with a Layer 5 network interface.
A typical OpenLDV application uses Layer 5 interfaces so that it need not
implement layer 3-5.
You can use the L
to determine if your network interface provides a Layer 2 or Layer 5 image or
supports switching between Layer 2 and Layer 5:
• Echelon U10 and U20 USB Network Interfaces can operate as either a
Layer 2 or Layer 5 interface, switchable within an OpenLDV application
• Remote Network Interfaces (SmartServer or i.LON) can be configured to
operate as a Layer 5 interface or as a read-only Layer 2 interface (for use
with protocol analyzers, such as the LonScanner Protocol Analyzer)
• IP-852 devices always operate as Layer 2 interfaces, as defined by the
ISO/IEC 14908-4 standard
For PCC-10, PCLTA-20, or PCLTA-21 network interfaces, Table 1 on page 8 lists
the application image that you can select to operate at either Layer 2 or Layer 5,
as needed. See the documentation for your network interface for additional
information.
OpenLDV Programmer’s Guide 7
ONWORKS Interfaces application in the Windows Control Panel
Table 1. NI Application Settings
Network
Interface
PCC-10 PCC10VNI NSIPCC
PCLTA-20 PCL10VNI NSIPCLTA
PCLTA-21 PCLTA21VNI PCLTA21NSI
The LONWORKS Interfaces application is installed with the OpenLDV driver.
For additional information about developing an OpenLDV application, see the
following chapters:
• Chapter 2, Using the OpenLDV API, on page 9. This chapter describes
each function that is included in the OpenLDV API. It also defines
guidelines for writing applications that use the OpenLDV API to access
multiple network interfaces.
• Chapter 3, Sending and Receiving Messages with the OpenLDV API, on
page 57. You can use the ldv_write() and ldv_read() functions
described in Chapter 2 to send and receive message commands through a
network interface. This chapter describes the various network interface
commands that your OpenLDV application can send and receive with
these functions, as well as the application buffer structure for each type
of message.
NI Application Setting for
Layer 2 Image
NI Application Setting for
Layer 5 Image
• Chapter 4, The OpenLDV Developer Example, on page 89. This chapter
introduces the OpenLDV Developer Example, which is installed with the
OpenLDV SDK. It describes various classes implemented in the
OpenLDV Developer Example. In addition to reviewing the code, you
should also review the code comments in the example.
Getting Started with the xDriver Component
The xDriver component is included with the OpenLDV driver. xDriver supports
scalable access to many network interfaces. The default xDriver implementation
uses a Lookup component that uses the Windows Registry to store a database
containing the information that it requires to connect to each device. For smallscale deployments, the Windows Registry is an efficient information store for the
xDriver database.
However, for larger deployments (more than 50 network interfaces), you can
improve performance by extending the default xDriver component to use a
database as your information store.
If you do not plan to extend the default xDriver component to use a database, you
can begin using the default xDriver component, as described in Chapter 5, Using
the xDriver Default Profile, on page 93.
If you plan to extend the default xDriver component, see Chapter 6, Extending
xDriver, on page 99. Most developers will not need to extend xDriver.
8 Introduction
2
Using the OpenLDV API
This chapter describes the OpenLDV API functions and types,
including the input and output parameters associated with each
function, and the return codes returned by each function.
OpenLDV Programmer’s Guide 9
Introduction to OpenLDV Programming
An application that uses the OpenLDV API is called an OpenLDV application.
The communications protocol used for OpenLDV applications is the ISO/IEC
14908-1 (ANSI/CEA 709.1-B and EN14908.1) Control Network Protocol. This
protocol is an international standard seven-layer protocol that has been
optimized for control applications, and is based on the Open Systems
Interconnection (OSI) Basic Reference Model (the OSI Model, ISO standard 7498-
1). The OSI Model describes computer network communications through the
seven abstract layers described in Table 2. The implementation of these layers
ONWORKS device provides standardized interconnectivity for devices within
in a L
ONWORKS network.
a L
Table 2. L
OSI Layer Purpose Services Provided
7 Application Application compatibility Network configuration, self-installation,
6 Presentation Data interpretation Network variables, application messages,
5 Session Control Request/response, authentication
4 Transport End-to-end
communication reliability
3 Network Destination addressing Unicast and multicast addressing,
2 Data Link Media access and framing Framing, data encoding, CRC error
ONWORKS Network Protocol Layers
network diagnostics, file transfer,
application configuration, application
specification, alarms, data logging,
scheduling
foreign frame transmission
Acknowledged and unacknowledged
message delivery, common ordering,
duplicate detection
routers
checking, predictive carrier sense
multiple access (CSMA), collision
avoidance, priority, collision detection
1 Physical Electrical interconnect Media-specific interfaces and modulation
schemes
Echelon’s implementation of the ISO/IEC 14908 Control Network Protocol is
called the LonTalk protocol. Echelon has implementations of the LonTalk
protocol in several product offerings, including the Neuron firmware, LNS
Server, SmartServers, and various network interfaces. This document refers to
the ISO/IEC 14908-1 Control Network Protocol as the “LonTalk protocol”,
although other interoperable implementations exist.
An OpenLDV application can work with Layer 2 network interfaces, Layer 5
network interfaces, or LonScanner Protocol Analyzer interfaces. Figure 3 shows
10 Using the OpenLDV API
Physical Layer
Data Link Layer
Network Layer
Transport Layer
Session Layer
Presentation Layer
Application Layer
Layer 5
Network
Interface
Layer 2
Network
Interface
the seven layers of the OSI Model and which OSI layers a Layer 2 or Layer 5
network interface handles.
Figure 3. Network Interfaces and the Seven Layers of the OSI Model
A Layer 2 network interface handles only the first two layers of the OSI Model,
and thus only sends and receives network packets; an application must
implement the rest of the ISO/IEC 14908-1 protocol to communicate with the
network.
A LonScanner Protocol Analyzer uses a Layer 2 network interface. The
LonScanner Protocol Analyzer implements the rest of the ISO/IEC 14908-1
protocol to communicate with and analyze the network.
A Layer 5 network interface handles the first five layers of the OSI Model, and
thus not only sends and receives network packets, but also implements layers 1
through 5 of the ISO/IEC 14908-1 protocol to communicate with the network.
Most OpenLDV applications use Layer 5 network interfaces so that they need not
implement Layers 3 to 5 of the ISO/IEC 14908-1 protocol.
OpenLDV Application Architecture
The OpenLDV application architecture also uses the OSI Model, and provides a
programming framework for communicating with the network, as shown in
Figure 4 on page 12.
OpenLDV Programmer’s Guide 11
Application Layer
OpenLDV API
Presentation Layer
OpenLDV Application
OpenLDV Driver (Ldv32.dll)
SLTA
Link Layer
PCLTA
Link Layer
PCC
Link Layer
USB
Link Layer
SLTA-10
PCLTA-10
PCLTA-20
PCC-10
U10
U20
LONW
ORKS
Network
xDriver
Link Layer
SmartServer
i.LON
Interfaces
Compatible
with
OpenLDV
API
OpenLDV
Interface
and Driver
Software
OpenLDV
Application
Figure 4. OpenLDV Application Architecture
An OpenLDV application implements the application and presentation layers,
and uses the OpenLDV API (with the OpenLDV driver, Ldv32.dll) as an
interface layer to communicate with a network interface. The network interfaces
communicate with the L
network interfaces, most third-party network interfaces can also use the
OpenLDV driver.
An OpenLDV application that uses the OpenLDV API can establish downlink
connections (session initiation from the application to the local or remote network
interface), and it can accept uplink session requests (session initiation from the
remote network interface, using the xDriver Broker service, to the application).
Application Layer
The application layer is responsible for sending data to the LONWORKS network
through output network variables and outgoing application messages, and
receiving L
ONWORKS network data through input network variables and
incoming application messages. Typically, the bulk of an OpenLDV application’s
code is at the application layer.
ONWORKS network. Although the figure shows Echelon
12 Using the OpenLDV API
The OpenLDV API does not include an application layer. However, the
OpenLDV Developer Example demonstrates how to integrate an application
layer (which dispatches incoming messages to an application-specific message
dispatcher) with the OpenLDV API. For more information about the OpenLDV
Developer Example and the message dispatcher it employs, see Chapter 4, The
OpenLDV Developer Example, on page 89.
Presentation Layer
The presentation layer is responsible for translating messages between the lower
layers, providing an easier-to-use presentation format used by the application
layer. For example, all incoming network variable update messages from a
network interface are recognized by this layer, updating the application’s
network variable values and notifying the application layer of the change.
The presentation layer can also manage network management messages and
diagnostics services, such as the responses to Query SI network management
commands (see Receiving Messages from the Network Interface on page 75).
The OpenLDV API does not include a presentation layer. However, the
OpenLDV Developer Example demonstrates how to integrate a presentation
layer with the OpenLDV API. The OpenLDV Developer Example also includes
code that handles several network management commands and diagnostics.
Overview of the OpenLDV API
The OpenLDV API is implemented by a 32-bit C DLL that is compatible with
both 64- and 32-bit versions of Windows. All data types defined for the API
assume a 32-bit compiler; for example, pointers reference 32-bit addresses, each
enum is a 32-bit type, size_t is an unsigned 32-bit type, and so on. The
OpenLDV header file, ldv32.h, includes the following type definitions for native
data types, rather than using compiler-dependent types:
typedef void* PVOID;
typedef short SHORT; /* signed 16-bit */
typedef long LONG; /* signed 32-bit */
typedef unsigned char BYTE; /* unsigned 8-bit */
typedef unsigned short WORD; /* unsigned 16-bit */
typedef unsigned long DWORD; /* unsigned 32-bit */
typedef char* LPSTR;
typedef const char* LPCSTR;
typedef void* HANDLE;
Each function of the OpenLDV API uses extern “C” and __stdcall calling
conventions.
An alternative to the OpenLDV API is the COpenLDVapi class provided with
the OpenLDV developer example described in Chapter 4. This class provides a
COM interface with thread-safe, synchronized, access to downlink messages
(ldv_write()). The same interface also implements a reader thread,
COpenLDVreader, which queries uplink messages (ldv_read()) and supplies
data to a protected queue. The COpenLDVapi::Read() function queries that
queue, thereby providing coordinated access to both uplink and downlink
messages.
OpenLDV Programmer’s Guide 13
Referencing the OpenLDV Component
You can develop applications that use the OpenLDV API with any Windows
application development environment that supports the use of standard Windows
DLL components and (for xDriver Extensions) COM components. Echelon has
tested the OpenLDV software with Microsoft Visual Studio 2008, using the
Microsoft Visual C++
To develop an applicatikon with the OpenLDV API, first install the OpenLDV
driver and the OpenLDV SDK. During the installation, the ldv32.h and
ldv32.lib files are copied to the L
\OpenLDV SDK\Lib folders.
To develop your OpenLDV application, include the ldv32.h header file in your
application and link it with the ldv32.lib library. See your development
environment’s documentation for information about linking to external libraries.
End users of your OpenLDV application do not need to install any of the files
included in the OpenLDV SDK; they need only install the OpenLDV driver.
The OpenLDV SDK includes the OpenLDV Developer Example, which uses many
of the functions described in this chapter. To compile and debug the OpenLDV
Developer Example, install Microsoft Visual Studio 2008 (or later), with the
Microsoft Visual C++ component. The example application is available from the
Examples & Tutorials folder in the Echelon OpenLDV 4.0 SDK program
folder; it is also installed as a ZIP file to the \LonWorks\OpenLDV
SDK\SourceArchive folder. The OpenLDV Developer Example contains
numerous helpful comments. See Chapter 4, The OpenLDV Developer Example,
on page 89, for a description of the architecture of the OpenLDV Developer
Example and of the different classes that it contains.
®
, Visual C#®, and Visual Basic® components.
ONWORKS \OpenLDV SDK\Include and
Using Multiple Threads or Multiple Processes
The OpenLDV software supports communication with multiple network
interfaces at the same time, with the following restrictions:
1. A single process can access multiple network interfaces simultaneously.
However, a single process should access a network interface with at most
one writer thread and one reader thread. You must program your
application to enforce this restriction, because it is not enforced by the
OpenLDV software. See the OpenLDV Developer Example for a
demonstration of the proper use of separate reader and writer threads.
2. Multiple processes cannot access the same network interface
simultaneously. Attempts to access the same network interface by more
than one process result in the LDVX_ACCESS_DENIED failure code
from the ldv_open() functions.
3. The SmartServer and i.LON network interfaces allow a single session at
a time. If you attempt to open such a network interface while another
session is active (usually from another computer), the call to ldv_open()
might initially appear to have succeeded (the connection is established in
the background). However, when you call ldv_read() or ldv_write() to
read or write a message to the network interface, the functions return the
LDVX_READ_FAILED or LDVX_WRITE_FAILED return codes,
which indicate that the session has failed. See ldv_open() on page 24 for
more information.
14 Using the OpenLDV API
The OpenLDV API
This section describes the functions included in the OpenLDV API. Table 3
summarizes these functions. See Structures and Enumerations for the Driver
API on page 42 for descriptions of the structures and enumerations used by the
OpenLDV API. See OpenLDV API Return Codes on page 44 for descriptions of
the return codes.
Table 3. OpenLDV API Functions
Added in
OpenLDV
Function Description
ldv_close() Closes an open session. 1.0
Version
ldv_free_device_info() Releases the resources allocated by a
call to ldv_get_device_info() or
ldv_get_matching_devices().
ldv_free_driver_info() Releases the resources allocated by a
call to ldv_get_driver_info().
ldv_free_matching_devices() Releases the resources allocated by a
call to
ldv_get_matching_devices().
ldv_get_device_info() Retrieves information about a
ONWORKS interface device.
L
ldv_get_driver_info() Retrieves information about a
ONWORKS interface device driver
L
class.
ldv_get_matching_devices() Retrieves information about the
ONWORKS interface devices that
L
match a set of capabilities.
ldv_get_version() Retrieves the version number of the
OpenLDV API.
2.0
2.0
2.0
2.0
2.0
2.0
1.0
ldv_locate_sicb() Locates the SICB portion of the data
within an LdvEx (or SICB)
formatted message, if present.
ldv_open() Opens a network interface device. 1.0
ldv_open_cap() An extended version of ldv_open()
and ldvx_open() that additionally
allows the caller to request specific
capabilities for the device.
OpenLDV Programmer’s Guide 15
2.0
2.0
Function Description
Added in
OpenLDV
Version
ldv_read() Reads a message from an open
session.
ldv_register_event() Registers a Windows Event object to
receive notification of the
availability of new messages.
ldv_set_device_info() Creates or modifies the information
about a L
ldv_set_driver_info() Creates or modifies the information
about a L
driver class.
ldv_write() Writes a message to an open session. 1.0
ldv_xlate_device_name() Translates a device’s logical name to
its physical name, that is, from the
device’s L
“LON1”) to its Windows device name
(such as “\\.\LON1.0”).
ldvx_open() Opens a network interface device,
registers a Windows HWND object
for receiving session change
notifications.
ONWORKS interface device.
ONWORKS interface device
ONWORKS name (such as
1.0
1.0
2.0
2.0
1.0
1.0
ldvx_register_window() Registers a Windows HWND object
for receiving session change
notifications.
ldvx_shutdown() Cleanly shuts down OpenLDV and
xDriver subsystem.
1.0
1.0
Working with Devices and Drivers
The OpenLDV API includes a number of functions that assist in working with
devices and device drivers, for example:
• The ldv_get_driver_info() function allows you to identify the device
driver for a particular device. With this function, an application could
display a list of devices associated with a specific device driver.
• The ldv_get_device_info() function allows you to retrieve device
information (such as the transceiver ID of the Smart Transceiver or
Neuron Chip). For example, the transceiver ID allows an application to
determine appropriate timer and channel settings for the device based on
the available hardware.
16 Using the OpenLDV API
• The ldv_set_device_info() function allows you to modify certain
information for a device.
• The ldv_get_matching_devices() function allows you retrieve a list of
devices that match a specified set of capabilities. For example, you can
determine which devices operate at Layer 2 or Layer 5, you can
determine which devices are IP-852 devices or channels, or you can
determine which devices are protocol analyzers.
• The ldv_free_device_info(), ldv_free_driver_info(), and
ldv_free_matching_devices() functions release resources allocated by
the ldv_get_device_info(), ldv_get_driver_info(), and
ldv_get_matching_devices() functions.
• The ldv_open_cap() function allows you to open a device with a specified
capability enabled, if the capability is supported by the device. For
example, you could open a U10 USB network interface with Layer 2
operation or with Layer 5 operation. However, only local devices and
static xDriver RNI devices that use the default xDriver lookup extension
can supply their device capabilities. xDriver RNIs that use a custom
lookup extension are either not available or report as having unknown
capabilities.
See The OpenLDV API on page 15 for a description of these functions and the
rest of the OpenLDV functions.
Using the OpenLDV API
The basic code flow for an OpenLDV application includes the following four
functions, which comprise the basis of all OpenLDV applications:
• ldv_open()
• ldv_read()
• ldv_write()
• ldv_close()
An application can call the ldv_read() and ldv_write() functions in any order,
and at any time after opening the network interface, but before closing the
network interface.
The following sections describe each of the API functions in detail. The syntax
for each function includes a table that describes the following information:
• Each parameter required for the function. The parameter data type does
not appear in the table, but is shown in the syntax for the function.
• The direction for each parameter:
o Input: Input parameters provide data to the OpenLDV function.
You must supply an appropriate value for each input parameter.
o Output: Output parameters provide data to your application
from the OpenLDV function. You must supply an appropriately
sized variable or buffer for each output parameter.
• A description of each parameter.
OpenLDV Programmer’s Guide 17
See Structures and Enumerations for the Driver API on page 42 for descriptions
of the structures and enumerations used by the OpenLDV API. See OpenLDV
API Return Codes on page 44 for descriptions of the return codes.
ldv_close()
Call this function to close a network interface that has been previously opened
with the ldv_open() function.
Syntax
LDVCode ldv_close(
LdvHandle handle
)
Table 4. ldv_close() Parameters
Parameter Direction Description
handle
Input The network interface to be closed. This value was returned
as the handle parameter when you opened the network
interface with one of the open functions (ldv_open(),
ldv_open_cap(), or ldvx_open()).
Remarks
Use this function to close an OpenLDV session and end communication between
your application and the network interface involved in the session. This function
also frees any resources assigned to the network interface and the handle
assigned to the session. This function returns LDV_OK if the network interface
is successfully closed; if so, other processes on your computer can access the
network interface.
Each successful ldv_open(), ldv_open_cap(), or ldvx_open() call (including
nested ones) must have a matching ldv_close() call. The OpenLDV driver does
not close a network interface until the last ldv_close() function is called. See
also ldvx_shutdown() on page 37.
If you attempt to close a network interface that has not been previously opened,
or has already been closed, the LDV_NOT_OPEN code is returned. If the
handle parameter is not valid, the LDV_INVALID_DEVICE_ID code is
returned.
Recommendation: Add a delay of at least one second before you call the
ldv_open() function after calling ldv_close() for a particular network interface.
ldv_free_device_info()
Call this function to release resources allocated by the ldv_get_device_info()
function.
18 Using the OpenLDV API
function) to be freed.
Syntax
LDVCode ldv_free_device_info(
const LDVDeviceInfo* pDeviceInfo
)
Table 5. ldv_free_device_info() Parameters
Parameter Direction Description
pDeviceInfo Input A pointer to an LDVDeviceInfo structure (that was
returned by the ldv_get_device_info()
Remarks
Use this function to release resources allocated by the ldv_get_driver_info()
function. This function returns LDV_OK if the resources are successfully
released.
See Structures and Enumerations for the Device API on page 37 for a description
of the LDVDeviceInfo structure.
ldv_free_driver_info()
Call this function to release resources allocated by the ldv_get_driver_info()
function.
Syntax
LDVCode ldv_free_driver_info(
LDVDriverInfo* pDriverInfo
)
Table 6. ldv_free_driver_info() Parameters
Parameter Direction Description
pDriverInfo Input A pointer to an LDVDriverInfo structure (that was
returned by the ldv_get_driver_info() function) to be freed.
Remarks
Use this function to release resources allocated by the ldv_get_driver_info()
function. This function returns LDV_OK if the resources are successfully
released.
See Structures and Enumerations for the Driver API on page 42 for a description
of the LDVDriverInfo structure.
OpenLDV Programmer’s Guide 19
ldv_free_matching_devices()
Call this function to release resources allocated by the
ldv_get_matching_devices() function.
Syntax
LDVCode ldv_free_matching_devices(
LDVDevices* pDevices
)
Table 7. ldv_free_matching_devices() Parameters
Parameter Direction Description
pDevices Input A pointer to an LDVDevices structure (that was returned
by the ldv_get_matching_devices() function) to be freed.
Remarks
Use this function to release resources allocated by the
ldv_get_matching_devices() function. This function returns LDV_OK if the
resources are successfully released.
See Structures and Enumerations for the Device API on page 37 for a description
of the LDVDevices structure.
ldv_get_device_info()
Call this function to retrieve device information about a LONWORKS interface
device.
Syntax
LDVCode ldv_get_device_info(
LPCSTR szDevice,
const LDVDeviceInfo** ppDeviceInfo
)
Table 8. ldv_get_device_info() Parameters
Parameter Direction Description
szDevice
ppDeviceInfo Output A pointer to an LDVDeviceInfo pointer that receives the
Input The name of the LONWORKS interface device for which you
are requesting information.
information of the requested device.
20 Using the OpenLDV API
Remarks
Use this function to retrieve device information about a LONWORKS interface
device. This function returns LDV_OK if the device information is successfully
retrieved. After you retrieve the device information and no longer need it, you
must free the device information resources by calling the
ldv_free_device_info() function.
The contents of the returned structure is constant (read-only) and cannot be
modified.
See Structures and Enumerations for the Device API on page 37 for a description
of the LDVDeviceInfo structure.
ldv_get_driver_info()
Call this function to retrieve driver information about a LONWORKS interface
device driver.
Syntax
LDVCode ldv_get_driver_info(
LDVDriverID nDriverId,
LDVDriverInfo** ppDriverInfo
)
Table 9. ldv_get_driver_info() Parameters
Parameter Direction Description
nDriverId Input The driver ID of the driver for which you are requesting
information.
ppDriverInfo Output A pointer to an LDVDriverInfo pointer that receives the
information of the requested driver.
Remarks
Use this function to retrieve driver information about a LONWORKS interface
device driver. This function returns LDV_OK if the driver information is
successfully retrieved. After you retrieve the driver information and no longer
need it, you must free the driver information resources by calling the
ldv_free_driver_info() function.
The contents of the returned structure should be treated as constant (read-only)
and cannot be modified.
See Structures and Enumerations for the Driver API on page 42 for a description
of the LDVDriverID enumeration values and the LDVDriverInfo structure.
OpenLDV Programmer’s Guide 21
ldv_get_matching_devices()
Call this function to retrieve information about all LONWORKS interface devices
that match a set of capabilities.
Syntax
LDVCode ldv_get_matching_devices(
LDVDeviceCaps nCaps,
LDVCombineFlags nCombine,
LDVDevices* pDevices
)
Table 10. ldv_get_matching_devices() Parameters
Parameter Direction Description
nCaps Input An LDVDeviceCaps value for the device capabilities to
match.
nCombine Input The criterion for how the match should be performed. The
criterion is a bitwise combination of one of the
LdvCombineFlags values.
pDevices Output A pointer to an LDVDevices structure for the devices whose
capabilities match those requested.
Remarks
Use this function to retrieve information about all LONWORKS interface devices
that match a specified set of device capabilities. This function returns LDV_OK
if the device information is successfully retrieved. After you retrieve the device
information, you must free the device information resources by calling the
ldv_free_matching_devices() function. Do not call the
ldv_free_device_info() function for each retrieved device.
The contents of the returned structure should be treated as constant (read-only)
and cannot be modified.
See Structures and Enumerations for the Device API on page 37 for a description
of the LDVDevices and LDVDeviceCaps structures and the
LdvCombineFlags enumeration.
ldv_get_version
Call this function to read the version number of the OpenLDV driver.
Syntax
LPCSTR ldv_get_version(
VOID
)
22 Using the OpenLDV API
Loading...