OpenLDV Programmer’s Guide 078-0275-01D
Echelon, i.LON, LonMaker, LONMARK, 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.
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® Windows® operating systems that enables Windows applications to 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.
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.
Table of Contents Welcome ......................................................................................................... iii Audience ........................................................................................................ iii Examples ....................................................................................................... iv Related Documentation ................................................................................ iv Chapter 1. Introduction...........
LdvCombineFlags Enumeration........................................................... 39 LdvDeviceCaps Enumeration ............................................................... 40 Structures and Enumerations for the Driver API ..................................... 42 LDVDriverInfo Structure ...................................................................... 42 LdvDriverID Enumeration ................................................................... 43 LdvDriverType Enumeration ......................
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 ...................................................
GetEncryptionType Method ................................................................ 170 GetLNSNetworkName Method .......................................................... 170 GetNextAuthenticationKey Method ................................................... 171 GetSessionControlObjectID Method .................................................. 171 GetUplinkKey Method ........................................................................ 172 SetAdditionalDownlinkPacketHeader Method ................
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.
Introduction to OpenLDV Networking The OpenLDV driver allows a Windows application to communicate with a LONWORKS network through a locally attached network interface or a remote network interface.
Client Applications OpenLDV applications, such as the LNS Server and the LonScanner Protocol Analyzer, use the OpenLDV application programming interface (API) to communicate with LONWORKS network interfaces. Echelon’s LNS software provides a high-level interface to LONWORKS networks that simplifies managing network interfaces.
Network Interfaces 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.
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.
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.
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.
Table 1. NI Application Settings Network Interface NI Application Setting for Layer 2 Image NI Application Setting for Layer 5 Image 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.
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.
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 74981).
the seven layers of the OSI Model and which OSI layers a Layer 2 or Layer 5 network interface handles. Application Layer Presentation Layer Session Layer Transport Layer Layer 5 Network Interface Network Layer Data Link Layer Physical Layer Layer 2 Network Interface Figure 3.
OpenLDV Application Application Layer Presentation Layer OpenLDV Application OpenLDV API OpenLDV Driver (Ldv32.dll) SLTA Link Layer SLTA-10 PCC Link Layer PCLTA Link Layer PCLTA-10 PCLTA-20 PCC-10 USB Link Layer U10 U20 OpenLDV Interface and Driver Software xDriver Link Layer SmartServer i.LON Interfaces Compatible with OpenLDV API LONWORKS Network Figure 4.
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.
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++®, Visual C#®, and Visual Basic® components. To develop an applicatikon with the OpenLDV API, first install the OpenLDV driver and the OpenLDV SDK.
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 Function Description Added in OpenLDV Version ldv_close() Closes an open session. 1.
Added in OpenLDV Version Function Description ldv_read() Reads a message from an open session. 1.0 ldv_register_event() Registers a Windows Event object to receive notification of the availability of new messages. 1.0 ldv_set_device_info() Creates or modifies the information about a LONWORKS interface device. 2.0 ldv_set_driver_info() Creates or modifies the information about a LONWORKS interface device driver class. 2.0 ldv_write() Writes a message to an open session. 1.
• 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.
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.
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() 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.
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.
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.
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.
Remarks This function returns a string for the version number of the OpenLDV driver being used: • OpenLDV 1.0 5.308.09 • OpenLDV/LNS 5.320.122 • OpenLDV 2.0 5.321.034 • OpenLDV 2.1 5.322.002 • OpenLDV 3.3 5.330.036 • OpenLDV 3.4 5.340.016 • OpenLDV 4.0 5.400.102 ldv_locate_sicb() Call this function to locate the serial interface control block (SICB) portion of the data within an LdvEx (or SICB) formatted message, if present.
along with other data, such as timestamp data, that could be useful for some applications). See Application Buffer Structure on page 58 for a description of the SICB and LdvEx formats. This function returns LDV_OK if the SICB data could be located and returned. If an LdvEx packet does not contain an SICB message, the error LDV_NOT_FOUND is returned. If the packet is not well formed (for example, too short), the error LDV_INVALID_DATA_FORMAT is returned.
the network interface enters an initial quiet mode (flush state) after a reset. To start using such a network interface, the OpenLDV application must cancel the quiet mode with the niFLUSH_CANCEL immediate network interface command. For more information about immediate commands, see Immediate Commands on page 77. The OpenLDV API clears old data from internal buffers during processing of the ldv_open() function before retrieving new data. Thus, your application does not need to perform this task.
Table 13. ldv_open_cap() Parameters Parameter Direction Description szDevice Input The network interface with which to establish communication. For example, “LON1” could be used to identify a U10, PCLTA-10, or PCLTA-21 network interface. Or, “X.Default.1MainStreet” could be used to identify a SmartServer that will be opened through xDriver. pHandle Output A pointer to a variable that you can use to identify the network interface with the other OpenLDV functions.
For local network interfaces, after the ldv_open_cap() function returns the LDV_OK success code, the network interface device has been initialized (see below for information about remote network interfaces). For some network interface types, the network interface enters an initial quiet mode (flush state) after reset. To start using the network interface, the OpenLDV application must cancel the quiet mode with the niFLUSH_CANCEL immediate network interface command.
Table 14. ldv_read() Parameters Parameter Direction Description handle Input The network interface device to be read. 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()). msg_p Output A pointer to a buffer allocated by your application that will receive the next uplink message. You must provide a sufficiently large buffer to receive each message.
format, the maximum length of a message is 257 bytes, and so you should use a buffer length of at least 257 bytes to guarantee that any message can be buffered. If your device uses the LdvEx format, you must allocate additional buffer space. If the handle parameter is not valid, the LDV_INVALID_DEVICE_ID code is returned. If the network interface referenced by the handle parameter has not been opened by your process, then the LDV_NOT_OPEN code is returned if the handle references a local network interface.
To de-register a current event and register a new event, call ldv_register_event()with a new event parameter. You can also call the ldv_register_event() function and specify NULL as the event parameter to disable event notifications for a network interface. If the handle parameter is not valid, the LDV_INVALID_DEVICE_ID code is returned. If the network interface referenced by the handle parameter is not open, then the LDV_NOT_OPEN code is returned.
specify the Windows device path, for example, \\.\MYLON1.0. See Appendix A, Custom Network Interfaces, on page147, for more information about custom network interfaces. • Set the desc field to the description of the new device, or set it to NULL or an empty string if the device description is not to be modified. • Set the caps and capsMask fields according to the capabilities of the device. • Set the transId field to the transceiver ID for the device.
Table 17. ldv_set_driver_info() Parameters Parameter Direction Description nDriverId Input The driver ID of the driver that you are creating or modifying. pDriverInfo Input A pointer to an LDVDriverInfo structure that contains the information for the created or modified driver. Remarks Use this function to create or modify information for a LONWORKS interface device driver. This function returns LDV_OK if the driver information is successfully updated.
Table 18. ldv_write() Parameters Parameter Direction Description handle Input The LONWORKS interface device to be written. 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()). msg_p Input A pointer to a buffer that contains the message to be written to the network interface.
Syntax LDVCode ldv_xlate_device_name( LPCSTR device_name, LPSTR driver_name, int* driver_name_len ) Table 19. ldv_xlate_device_name() Parameters Parameter Direction Description device_name Input The name of the network interface. driver_name Output A pointer to a buffer to receive the physical name. driver_name_len Input A pointer to the length of the buffer that will receive the physical name. Output On return, set to the length of the returned name.
Table 20. ldvx_open() Parameters Parameter Direction Description id Input The LONWORKS interface device with which to establish communication. For example, “LON1” could be used to identify a U10, PCLTA-10, or PCLTA-21 network interface. Or, “X.Default.1MainStreet” could be used to identify a SmartServer that will be opened through xDriver. handle Output A pointer to a variable that you can use to identify the network interface with the other OpenLDV functions.
information. If you do not specify a valid network interface name as the id parameter when you call this function, or if the network interface referenced by the id parameter cannot be found, the LDV_INVALID_DEVICE_ID or LDVX_INVALID_XDRIVER return code is returned. Each network interface can only be part of one OpenLDV session at a time on a particular computer.
Parameter Direction Description tag Input Correlates notification messages with sessions. This tag is supplied as the LPARAM parameter of all session state change messages. Remarks Use this function to register a Windows HWND object for receiving session change notifications. This handle is the same as that passed to one of the open functions (ldv_open(), ldv_open_cap(), or ldvx_open()). ldvx_shutdown() Call this function to cleanly shut down the OpenLDV driver before exiting your application.
/* (read-only) */ typedef const LDVDeviceInfo* LDVDeviceInfoPtr; The LDVDeviceInfo structure contains information that describes a specific LONWORKS interface device (identified by its name). Table 22 describes the LDVDeviceInfo structure’s fields. Table 22. LDVDeviceInfo Structure Field Description size The size (in bytes) of this structure. This field must be set before calling any of the set functions that pass this structure as a parameter.
typedef struct LDVDevices { DWORD nInfos; LDVDeviceInfoPtr* pInfos; } LDVDevices; The LDVDevices structure contains information that describes a set of LONWORKS interface devices. Table 23 describes the LDVDevices structure’s fields. Table 23. LDVDevices Structure Field Description nInfos The number of Device Info pointers in the array. pInfos An array of Device Info pointers. See LDVDeviceInfo Structure on page 37 for information about the LDVDeviceInfo structure.
1. Set the nCaps to LDV_DEVCAP_PA to specify protocol analyzer capability. 2. Set nCombine to LDV_COMBINE_DEFINITELY_ALL (or LDV_COMBINE_DEFINITELY_ANY) to specify that the function should return all devices that definitely are defined as protocol analyzers. If you want the function to return all devices that are definitely protocol analyzers along with devices that might be protocol analyzers (devices with multiple capabilities), specify LDV_COMBINE_POSSIBLY_ALL (or LDV_COMBINE_POSSIBLY_ANY). 3.
Device Capability Numeric Value LDV_DEVCAP_XDRIVER 0x00000040 Description The device is an xDriver-based device. The network interface is physically remote from the host computer. LDV_DEVCAP_SICB 0x00000100 The device uses SICBformatted packets. LDV_DEVCAP_LDVEX 0x00000200 The device uses LdvExformatted packets. LDV_DEVCAP_NOSTATUS 0x00000800 The device does not support the niSTATUS command.
Device Capability Numeric Value LDV_DEVCAP_CURRENTLY_AVAILABLE 0x40000000 Description The device is currently not in use by any process on this computer. If it is not is use by another computer, the device is available for use. Structures and Enumerations for the Driver API This section describes the structure and enumerations defined for the OpenLDV driver API.
See the following functions for their use of this structure: ldv_get_driver_info() on page 21, ldv_set_driver_info() on page 31, and ldv_free_driver_info() on page 19. LdvDriverID Enumeration Table 27 describes the enumerated values for the LdvDriverID driver identifier (ID). The driver ID describes the driver class of an associated network interface. LdvDriverID enumeration values less than 127 define Echelon network interfaces.
LdvDriverType Enumeration Table 28 describes the enumerated values for the LdvDriverType driver type. The driver type describes the driver type of an associated network interface. LdvDriverType enumeration values less than 127 define types of Echelon network interface drivers. To define your own network interface type, use an enumeration value greater than 128. Table 28.
OpenLDV API Return Codes Table 30 describes the return codes that can be returned by the OpenLDV API functions. These codes are defined in the LDVCode enumeration. Table 30. OpenLDV Return Codes Return Code Numeric Value LDV_OK 0 The operation completed successfully.
Return Code Numeric Value LDV_DEVICE_ERR 4 This code is returned if a function fails to execute as a result of a failure to communicate with the network driver. Call ldv_close() to close the network interface and release the resources assigned to the network driver. Then, re-open the network interface with one of the open functions.
Return Code Numeric Value LDV_NO_RESOURCES 8 No resources are available. This code is returned if the OpenLDV API has assigned too many session handles, or if the computer running your application has memory allocation problems. Close any non-essential processes running on your computer and try the operation again.
Return Code Numeric Value LDVX_OPEN_FAILED 12 The remote network interface (RNI) could not be opened. LDVX_CLOSE_FAILED 13 The remote network interface (RNI) could not be closed. LDVX_READ_FAILED 14 The application failed to read the message as a result of a generic failure during the call to ldv_read(). If you encounter this return code persistently, close the current session and start a new one, because the current session might have failed.
Return Code Numeric Value LDVX_INVALID_XDRIVER 17 Description This code is returned if you attempt to open an xDriver LONWORKS interface device with the ldv_open() function, and the xDriver lookup extension component fails to find that network interface. For devices that use the default profile, use the LONWORKS Interfaces application in the Windows Control Panel to verify that the network interface referenced by the id parameter exists.
Return Code Numeric Value LDV_CAPABILITY_NOT_SUPPORTED 22 The capability specified for the ldv_open_cap() function is not supported by the device. LDV_INVALID_DRIVER_INFO 23 The driver information specified for the ldv_set_driver_info() function is not valid. LDV_INVALID_DEVICE_INFO 24 The device information specified for the ldv_set_device_info() function is not valid. LDV_DEVICE_IN_USE 25 The device is in use and cannot be opened with any of the open functions.
Return Code Numeric Value LDV_DEVICE_UPDATE_FAILED 33 The device information specified for the ldv_set_device_info() function could not be updated. LDV_STD_DRIVER_TYPE_READ_ONLY 34 The driver information specified for the ldv_set_driver_info() function could not be updated because the driver type is read only. LDV_OUTPUT_BUFFER_SIZE_MISMATCH 40 Output buffer sizes (for both priority and non-priority buffers) must be the same. Description Applies to APP/NET buffers on the network interface.
Return Code Numeric Value LDV_BUFFER_CONFIGURATION_TOO_LARGE 45 Description The specified buffer configuration is too large to fit in the available space. Applies to APP/NET buffers on the network interface. LDV_WARNING_APP_BUFFER_SIZE_MISMATCH 46 Warning message that the buffer size mismatch might cause problems. Applies to APP/NET buffers on the network interface.
// Include the header file from the OpenLDV API Example // (contains definitions for ExpMsgHdr, ExpAppBuffer, niNTQ, niNETMGMT) #include "OpenLdvDefinitions.h" // Define Network Management commands // from ISO/IEC 14908 Control Networking Protocol spec #define LonNdQueryStatus 0x51 // Query Status command #define LonNdQueryStatusSuccess 0x31 // Success Response for Query Status // // Variable Definitions // // Handle for Windows event calls HANDLE hEvent = NULL; // Return code for ldv_* calls.
if (ldvCmdOk) { // Build message to send to NI m_msgOut.ni_hdr.q.queue = niNTQ; m_msgOut.ni_hdr.q.q_cmd = niNETMGMT; m_msgOut.ni_hdr.q.length = sizeof(ExpMsgHdr) + sizeof(ExplicitAddr) + msgSize; m_msgOut.msg_hdr.exp.tag = 1; // Assume message tag 1 m_msgOut.msg_hdr.exp.auth = 0; m_msgOut.msg_hdr.exp.response = 1; // Make it a response m_msgOut.msg_hdr.exp.st = 3; // Make it a REQUEST m_msgOut.msg_hdr.exp.pool = 0; // Must be zero m_msgOut.msg_hdr.exp.alt_path = 0; // Use default path m_msgOut.msg_hdr.exp.
// Perform the following tasks regardless of ldvCmdOk value: // Deregister event for NI ldv_register_event(m_OpenLdvHandle, NULL); // Close the network interface rc = ldv_close(m_OpenLdvHandle); if (rc != LDV_OK) { printf(“Could not close network interface.
3 Sending and Receiving Messages with the OpenLDV API This chapter describes the network interface message commands that your OpenLDV application can send and receive through a network interface, as well as the application buffer structure that each type of message requires.
Constructing Messages You can construct outgoing messages for OpenLDV application using application buffer structures, and send that data to the network interface using the ldv_write() function. Use the ldv_read() function to retrieve data from the network interface, using the same application buffer structures. The following section describes the application buffer structure. The OpenLDVdefinitions.
BF Packet Size Header Flags Extended Header Size Absolute Timestamp In Seconds Absolute Timestamp In Milliseconds Timestamps Differential Timestamp In Microseconds Command Queue Command NI Header SICB SICB Length N Data[0] Data[0] Data[1] Extended Header Extended Data Type Extended Data Version NI Header Length N Data Payload Data[1] Data[N-1] Data[N-1] Buffer Structure for Commands That Do Not Use a Message Queue Buffer Structure for Commands That Use a Message Queue Extension Ex
SICB application buffer structure is defined as a structure of type ExpAppBuffer in the OpenLDVdefinitions.h header file. Some immediate commands use only the first byte of the SICB buffer—the cmd field—of the application buffer, with no data payload. Other immediate commands also include a data payload. All other downlink and uplink message commands use the complete SICB application buffer structure, as shown in Figure 6. The following sections describe the application buffer structures.
Layer 2 Buffer Structure The following sections provide an overview of the Layer 2 buffer structure shown in Figure 6. Bit transmission order within a byte is “most significant first”, meaning that the most significant bit is transmitted first. Byte transmission order is also “most significant first”, meaning that the most significant byte of a field is transmitted first. A Layer 2 network interface uses the Layer 2 buffer structure for most messages.
• Domain length (2 bits) • Data (variable length, depending on the packet type and the data) CRC The cyclic redundancy check (CRC) is computed over the NPDU and the Layer 2 Header. The CRC is generated using the ITU-T (CCITT) CRC-16 standard polynomial.
• NetVarHdr — for sending and receiving network variables that are processed by the network interface ExpMsgHdr 7 6 msgtype service Priority Path 5 4 type auth compl code 3 2 1 0 pool resp tag addr mode alt path length msgtype The msgtype field is set to 0 for the ExpMsgHdr.
For an uplink message (read from a network interface), the tag field indicates the index into the receive transaction database for acknowledged, repeated and request messages. When an OpenLDV application generates a response to an uplink request message, it must save the tag value from the request, and set the same tag value in the downlink response message. priority The priority field is set to indicate a message delivered with priority media access, either uplink or downlink.
alternate path If the alternate path bit is set, the message is delivered on the path specified in the path bit, otherwise it is delivered on the default path. pool Set the pool bit to 0 for a downlink message. response Set the response bit to 1 for a downlink response message, and 0 otherwise. If it is set for an uplink message, the message is a response to a previously sent request. length The length field in the message header is distinct from the length field in the application layer header.
and request messages. When the OpenLDV application generates a response to an uplink request message, it must save the tag value from the request, and return the same tag value in the downlink response message. priority The priority field is set to indicate a message delivered with priority media access, either uplink or downlink. When the OpenLDV application generates a response to an uplink request message, it saves the priority attribute from the request, and returns the response with the same priority.
turnaround If the turnaround bit is set, the message is a turnaround message, that is, a message sent from one network variable to another network variable on the same device. pool Set the pool bit should 0 for a downlink message. response Set the response bit to 1 for a downlink response message, and 0 otherwise. If it is set for an uplink message, the message is a response to a previously sent request.
msb Format Destimation Address 0 lsb 0 0 0 0 0 1 1 Backlog Domain rpt_timer Retry tx_timer Subnet Reserved SendAddrDtl Destination Address For Broadcast Addressing msb Format Destimation Address lsb 1 Size Domain Member rpt_timer Retry tx_timer Group Reserved SendAddrDtl Destination Address For Group Addressing 68 Sending and Receiving Messages with the OpenLDV API
msb Format Destimation Address 0 lsb 0 0 0 Domain 0 0 0 1 Node Retry rpt_timer tx_timer Subnet Reserved SendAddrDtl Destination Address For Subnet/Node Addressing msb Format Destimation Address 0 lsb 0 0 0 0 0 1 0 Domain rpt_timer Retry tx_timer Subnet Neuron ID SendAddrDtl Destination Address For Neuron ID Addressing OpenLDV Programmer’s Guide 69
msb Format 0 lsb 1 1 1 1 1 1 1 Destination Address Reserved SendAddrDtl Destination Address For Local Addressing msb Format 0 lsb 1 1 1 1 1 1 0 msg_tag Destination Address Reserved SendAddrDtl Destination Address For Implicit Addressing RcvAddrDtl This structure is used for uplink messages addressed to the network interface and intended for the OpenLDV application.
msb Format Domain lsb flex_domain 0 0 0 0 0 0 Subnet Source Address Node Subnet Destination Address Reserved RcvAddrDtl Received Address For Broadcast Addressing msb Format Domain Source Address Destination Address lsb flex_domain 0 0 0 0 0 1 Subnet Node Group Reserved RcvAddrDtl Received Address For Group Addressing OpenLDV Programmer’s Guide 71
msb Format Domain lsb flex_domain 0 0 0 0 1 0 Subnet Source Address Node Subnet Destination Address Node Reserved RcvAddrDtl Received Address For Subnet/Node Addressing msb Format Domain Source Address Destination Address lsb flex_domain 0 0 0 0 1 1 Subnet Node Subnet Neuron ID Reserved RcvAddrDtl Received Address For Neuron ID Addressing RespAddrDtl This structure is used for an uplink message in response to a previous downlink request.
msb Format Source Address Domain lsb flex_domain Subnet 0 Node Subnet Destination Address Node Group Member Reserved RespAddrDtl Response Address For Group Addressing msb Format Source Address Destination Address Domain lsb flex_domain Subnet 1 Node Subnet 1 Node Reserved RespAddrDtl Response Address For Subnet/Node Addressing Message Data The data field contains the application data to be transferred within a message.
UnprocessedNV 7 6 1 dir 5 4 3 2 1 0 NV selector hi NV selector lo NV data Depending on the context, this form of the data field is used for network-variable update messages, poll messages, poll responses, or completion events. A network-variable update message or a poll response contains 1-31 bytes of network-variable data. A network-variable poll request message or a completion event contains no data, only the selector in the first two bytes.
Message Type Message Codes (Hex) Foreign responder offline 4F Network diagnostic message 50 .. 5F Network management message 60 .. 73 Router configuration message (not used by the network interface) 74 .. 7C Network management escape code 7D Router far side escape code (not used by the network interface) 7E Service pin message 7F Sending Messages to the Network Interface Some messages can be sent to the network interface itself.
Message Code Comments Set Node Mode 0x6C On-line and off-line only. OpenLDV application should send corresponding immediate command (niONLINE or niOFFLINE) to the network interface. Wink 0x70 OpenLDV application should indicate receipt of message to user, or handles a request to manage its self-documentation data. Query SI 0x72 OpenLDV application should respond with self-identification and self-documentation data. NV Fetch 0x73 OpenLDV application should respond with network variable data.
Uplink Commands An uplink command is a message read from a network interface by an OpenLDV application with the ldv_read() function: • The OpenLDV interface passes certain network management messages to the OpenLDV application for processing. • The network interface passes uplink application messages, network variable updates, and network variable poll requests to the OpenLDV interface when they are received from the network.
enumeration type definition NI_QueueCmd used in the field NI_Hdr.q.q_cmd of the application layer header, and the queue codes are defined by the enumeration type definition NI_Queue used in the field NI_Hdr.q.queue. The OpenLDV Developer Example contains a utility function, COpenLDVni::msgHdrInit(), that computes the correct value for the command/queue byte based on the address type (local or remote), the service type, and the priority attribute of the message.
Network Interface Command Value Direction Description niCOMM + niTQ_P 0x13 Downlink Used for downlink priority messages using acknowledged, request and repeated services. For Layer 2 devices, also used for unacknowledged messages. This command specifies niCOMM (for messages sent to and received from the network) as the queue value and niTQ_P as the command value. Applies to Layer 2 or Layer 5 devices. The command format is different for Layer 2 and Layer 5.
Network Interface Command Value Direction Description niCOMM + niINCOMING 0x18 Uplink Used for uplink messages received from the network or the network interface. This command specifies niCOMM (for messages sent to and received from the network) as the queue value and niINCOMING as the command value. niNETMGMT + niTQ 0x22 Downlink Used for downlink non-priority messages using acknowledged, request and repeated services.
Network Interface Command Value Direction Description niNETMGMT + niNTQ_P 0x25 Downlink Used for downlink priority messages using unacknowledged service, as well as responses. Also used for a Layer 2 network interface to issue a local network management command. This command specifies niNETMGMT (for messages sent to and received from the network interface) as the queue value and niNTQ_P as the command value. niNETMGMT + niRESPONSE 0x26 Uplink Used for uplink response messages and completion codes.
Network Interface Command Value Direction Description niL2_PRE_SHORT 0x34 Uplink Specifies a “Preamble Too Short” error condition for a Layer 2 network interface. niL2_PKT_SHORT 0x35 Uplink Specifies a “Packet Too Short” error condition for a Layer 2 network interface. niL2_FREQ_RPT 0x40 Uplink Specifies an incoming frequency report from a Layer 2 network interface. niRESET 0x50 Uplink Uplink: Specifies that the network interface has executed a hardware or software reset.
Network Interface Command Value Direction Description niONLINE 0x70 Downlink Requests that the network interface set its online flag and enter the online state. The OpenLDV application must send this command whenever it goes online. Generally, the OpenLDV application receives an uplink network management message from a network management tool or plug-in requesting that the application go online and send the niONLINE command.
Network Interface Command Value Direction Description niFLUSH 0x90 Downlink Requests that the network interface enter quiet mode (the FLUSH state), which causes it to send any pending downlink messages. After all pending downlink messages are completed, the network interface responds with the niFLUSH_COMPLETE command. No further downlink messages can be processed until the OpenLDV application cancels the flush state with the niFLUSH_CANCEL command. niFLUSH_IGN 0xA0 Downlink Obsolete.
Network Interface Command Value Direction Description niSERVICE 0xE6 Downlink Requests that the network interface send a service pin message. This command has the same effect as activating the device’s service pin. Some network interfaces might not support this command. niXDRVESC 0xEF Uplink Downlink This command applies to xDriver network interfaces only. This message must contain a data payload in addition to the command and length bytes.
Table 34. xDriver Specific Commands xDriver Command Description LDVX_NICMD_ENCRYPTION_ON_SEND=0x02 Use this command to enable RC4 encryption on the IP connection to the RNI for all subsequent messages sent to the network interface. All subsequent messages are encrypted until the LDVX_NICMD_ENCRYPTION_ OFF_SEND command is sent, or the session is terminated. This command is ignored if encryption has already been enabled. The xDriver subsystem determines if the network interface supports RC4 encryption.
xDriver Command Description LDVX_NICMD_ENCRYPTION_OFF_RECEIVE=0x05 Use this command to disable RC4 encryption on the IP connection to the RNI for all subsequent messages sent from the network interface. This command is ignored if encryption has already been disabled.
4 The OpenLDV Developer Example This chapter describes the OpenLDV Developer Example introduced with OpenLDV Release 2.1, and describes the various classes implemented in the example.
Overview The OpenLDV Developer Example is an example application that uses the OpenLDV API. The example application is available from the Examples & Tutorials folder in the Echelon OpenLDV 4.0 SDK program folder. The example application is also installed as a ZIP file in the LONWORKS \OpenLDV SDK\SourceArchive folder on your computer. The ZIP file is named LdvApiExamplesSource_vn.nn.nnn.ZIP, where the n.nn.nnn represents the version and build number for the OpenLDV release.
NiSendImmediate(), NiGetNextResponse(), NiSendResponse(), NiClose(), and NiEncryption(). The OpenLDVni.h header file contains details about this class and its usage. The COpenLDVni class also implements and controls a worker thread, COpenLDVmessagePump. This thread operates as a message pump, receiving and dispatching uplink messages from the COpenLDVapi class.
Developer Example Diagram Application-specific implementation and extensions Figure 7 shows the hierarchy of the classes described in this chapter. COpenLDVtools QueryDomain, LeaveDomain, ...
5 Using the xDriver Default Profile This chapter describes how to use the xDriver default profile. It also describes how to use the LONWORKS Interfaces application in the Windows Control Panel to configure an xDriver profile and build an xDriver database into the Windows Registry.
Configuring an xDriver Profile You can edit an xDriver profile to configure a number of parameters that impact how xDriver handles uplink and downlink sessions, including the automatic reconnection settings. Most applications will use the xDriver default profile. You can use the automatic reconnection feature to cause xDriver to attempt reconnection when sessions that use the default profile are terminated as a result of power outages, network interface failures, or other communications failures.
Figure 9. xDriver Profile General Tab You can edit the description of the xDriver profile by modifying the text in the Profile Description box in the General tab. You can also click Restore Default Values at any time to restore the default factory settings for the xDriver default profile. 3. Select the Downlink Sessions tab to configure how the profile manages downlink sessions, as shown in Figure 10 on page 96. A downlink session is an xDriver connection that is initiated by an OpenLDV application.
Figure 10. xDriver Profile Downlink Sessions Tab 4. Select the Uplink Sessions tab to configure how xDriver manages uplink sessions, as shown in Figure 11. An uplink session is an xDriver connection that is initiated when an RNI requests connection to the OpenLDV application. Figure 11.
For xDriver to receive these requests for connection, the xDriver Connection Broker must be running. For information about starting the Connection Broker, see Starting the Connection Broker on page 135. To enable uplink sessions, select the Enable Uplink Sessions checkbox, configure the rest of the fields on the tab, and click OK to save your changes. 5. Select the Protocol Options tab to configure protocol options for xDriver, as shown in Figure 12. Figure 12. xDriver Profile Protocol Options Tab 6.
Figure 13. xDriver Profile Recovery Options Tab You can configure xDriver to automatically attempt reconnection when xDriver sessions that are broken as a result of some unexpected communications failure. Select the Enable Recovery checkbox and configure the rest of the fields on the Recovery Options tab to enable the automatic reconnection feature. 7. Click OK to save the configuration changes and return to LONWORKS Interfaces application main window.
6 Extending xDriver You can extend xDriver by creating custom xDriver lookup extension components, and additional xDriver profiles. This chapter describes why you might need to extend xDriver, and how to extend it. Most OpenLDV developers will not need to extend xDriver.
Extending xDriver The OpenLDV driver software includes the LONWORKS Interfaces application, which you can use to create entries in the Windows Registry for each of your RNIs. Each entry stores the lookup information that xDriver requires to connect to one of your RNIs. The default xDriver lookup extension component supplies a COM method that xDriver calls to retrieve this information from the Windows Registry whenever an xDriver connection to an RNI is initiated.
of the downlink lookup key. Chapter 7, LNS Programming with xDriver, on page 137, provides programming samples that illustrate this behavior. Figure 14 shows the application flow for a downlink session. Database 3 User Application 2 1 xDriver Manager Lookup Extension 4 6 5 x.Profile.RNI Figure 14. Downlink Session The application flow for a downlink session includes the following steps (see Figure 14): 1.
Figure 15 on page 103 shows the flow of events that occur when a downlink session is initiated within the session-initiating LNS application and the lookup extension component.
Call ObjectServer.open() Typical Downlink Scenario Define network to be opened Does the network exist? No Add the network to the network collection Yes Open network in Local or serverIndependant mode? Indp. Get network from MyVNI network collection Call myNetwork.OpenIndependent() Local Get the network from Local network collection Call myNetwork.open() Set NetworkServiceDevice.NetworkInterface to desired xDriver networkInterface e.g. “x.[profileName].
The events shown in Figure 15 that occur within the LNS application represent a typical LNS application that opens a downlink session. Your application can vary from these steps. In addition, the events that occur within the lookup extension component in the flow chart represent the minimal tasks that a lookup extension component must perform during a downlink session. This flow chart refers to the methods that you can use when programming your custom lookup extension component.
identification message from the RNI that requested the uplink session. From this message, the Connection Broker obtains the uplink lookup key for the RNI. The SCO for the session is then initialized, and the uplink lookup key is inserted into the SCO. For RNIs that use a modem to connect to the LNS Server, you can create a listener application that uses the Windows Remote Access Service (RAS) to handle the modem communications with the RNI.
on page 142. You can also use the xDriver Profile Editor to specify a command to run each time that the listener port for that profile receives an uplink session. If you use an LNS Server as the OpenLDV application, the LNS Server provides an enhanced interface for LNS applications. 7.
Typical Uplink Scenario Call ObjectServer.open() Call BeginIncomingSessionEvents(myProfile) Uplink session event received, lookup extension launched. xDriver Lookup Extesnion Component Code ILdvxConfigure.SetInstance() to: return S_OK (This optional method is fired once in the lifetime of an Instance) Code ILdvxConfigure.SetOptions() to: return S_OK (This optional method is fired once in the lifetime of an Instance) Code ILdvxLookup.UplinkLookup() to: Call xSCO.
The events shown in Figure 17 that occur within the LNS application represent a typical LNS application that registers for uplink session event handling. Your application can vary from these steps. In addition, the events that occur within the lookup extension component in the flow chart represent the minimal tasks that a lookup extension component must perform during an uplink session. This flow chart refers to the methods that you can use when programming your custom lookup extension component.
Field Description Uplink Lookup Key The uplink lookup key is an ASCII string (105 characters maximum) passed to the lookup extension component by the RNI during an uplink session. It is used by the lookup extension to access the database record for the RNI that requested the uplink session, so that the lookup extension component can fill in the rest of the fields into the SCO. For a SmartServer or i.LON 600, the uplink lookup key uses the following naming convention: [Hostname].
Field Description Next Authentication Key This field represents the next authentication key to be used by the RNI. The next authentication key is usually the same as the current authentication key. The authentication key must be entered as a 32-character hexadecimal string representing a 128bit MD5 key. For example: 0102030405060708090A0B0C0D0E0F10 You can initiate a change to the authentication key used by the RNI by changing this field to a value different than the current authentication key.
Field Description Remote TCP Address The TCP/IP address of the RNI to which to connect. For an uplink session, this field is read-only. The remote TCP address must be specified in the form x.x.x.x, where x represents an integer between 0 and 255. A DNS-resolvable hostname can also be specified for this field. Remote TCP Port The port number that the RNI uses for incoming connections from the OpenLDV application. For an uplink session, this field is read-only. Valid port numbers are 1 to 65535.
unique, 32-character hexadecimal string representing the 128-bit MD5 key that is used by the RNI. The xDriver lookup interface includes the SetNextAuthenticationKey() method, which fills the next authentication key to be used by the RNI into the SCO. If no change the authentication key used by the RNI is desired, the next authentication key must be the same as the current authentication key. This field must be filled in immediately after the current authentication key is filled in.
Table 36. Changing Authentication Keys Phase One, Lookup Extension Component Is Called Initially, the current authentication key must match the authentication key configured into the RNI for the connection to be established.
Prerequisite: You must install the OpenLDV 4.0 SDK and Microsoft Visual Studio 2008 SP1 (or later). Important: If you use the sample project source files in your new project, you must rename the GUIDs in the .IDL and .RGS files. To create the framework for a custom lookup extension component using Microsoft Visual Studio 2008, perform the following tasks: 1. Start Microsoft Visual Studio 2. Create a new project using the Active Template Library (ATL) 3. Add a COM Object 4.
Figure 19. Visual Studio New Project Dialog In the New Project dialog: • Expand the C++ category and select ATL as the project template • Specify the version of the .NET Framework to use • Specify a name and location for the project • Specify a name and location for the solution You can use any project location for development. Install the completed custom lookup extension component in the LONWORKS \xDriver\Components \CompanyName\Lookup folder when you distribute the DLL for your application.
Figure 20. Visual Studio ATL Project Wizard Click Finish to close the ATL Project Wizard and create the project. Add a COM Object From the Visual Studio main window, select Project → Add Class to open the Add Class dialog, as shown in Figure 21 on page 117.
Figure 21. Visual Studio Add Class Dialog From the Add Class dialog, select the ATL category, select the ATL Simple Object template, and click Add to open the ATL Simple Object Wizard, as shown in Figure 22 on page 118.
Figure 22. Visual Studio ATL Simple Object Wizard – Names Page From the ATL Simple Object Wizard Names page, enter a name for the lookup extension component in the Short Name text box and fill in the rest of the fields as required. None of these fields should begin with “xDriver.” In addition, the short name should not match the project name (see Create a New Visual Studio Project on page 114). The COM interface is your automation interface, and is not used by xDriver.
From the ATL Simple Object Wizard, select the Options page, as shown in Figure 23. Figure 23. Visual Studio ATL Simple Object Wizard – Options Page For optimal performance, select Free as the threading model. This model requires that your extension be multithread safe, and allows your component to directly access other xDriver extension components. Click Finish to close the ATL Simple Object Wizard and create the object.
Figure 24. Visual Studio Implement Interface Wizard Within the Implement Interface wizard, select Echelon OpenLDV xDriver 1.0 Type Library from the Available type libraries dropdown listbox. For the Implement interface from radio button, specify either Registry or File. If you specify File, specify \LonWorks\bin\Ldvx.tlb for the Location. For your custom lookup extension component, implement the following interfaces: • ILdvxLookup • ILdvxConfigure (optional) Within the SampleLookupCsv.
} STDMETHOD(SetOptions)(BSTR options) { return E_NOTIMPL; } // ILdvxLookup Methods public: STDMETHOD(DownlinkLookup)(ILdvxSCO * xSCO) { return E_NOTIMPL; } STDMETHOD(UplinkLookup)(ILdvxSCO * xSCO) { return E_NOTIMPL; } STDMETHOD(UpdateLookup)(ILdvxSCO * xSCO) { return E_NOTIMPL; } }; Add the Extension to the Component Category To allow the OpenLDV xDriver Profile Wizard (and other xDriver-related tools) to display your custom lookup extension, you must register the lookup extension as belonging to the xDri
Project : error PRJ0050: Failed to register output. Please try enabling Per-user Redirection or register the component from a command prompt with elevated permissions. Start an elevated command shell (right-click the Visual Studio 2008 Command Prompt shortcut and select Run as administrator), change to the folder that contains your built DLL, and run the following command: REGSVR32 SampleLookup.
Figure 26. OpenLDV xDriver Profile Properties – General Tab 6. For the Lookup tab of the OpenLDV xDriver Profile Properties dialog for the new profile, select the newly built profile from the Extension Name dropdown listbox, as shown in Figure 27 on page 124.
Figure 27. OpenLDV xDriver Profile Properties – Lookup Tab 7. Make any other changes that are appropriate for your custom profile, and click OK to accept the changes and close the dialog. Test the Lookup Extension Create an RNI for your custom xDriver lookup extension, and give it a name like “X.Sample.DownlinkKey”.
interface ILdvxConfigure; // add to coclass SampleLookupCsv • Add additional private methods and properties to your ISampleLookupCsv interface, or remove it if it is not used. Creating a Custom Lookup Extension in Visual Basic This section describes the procedure for creating the framework for a custom lookup extension component in Visual Basic using Microsoft Visual Studio 2008. Use a similar procedure for Microsoft Visual Studio 2010, or later releases. Prerequisite: You must install the OpenLDV 4.
Figure 28. Visual Studio New Project Dialog In the New Project dialog: • Expand the Visual Basic category and select Class Library as the project template • Specify the version of the .NET Framework to use • Specify a name and location for the project • Specify a name and location for the solution You can use any project location for development.
Click OK to create the project. Add a Reference to the xDriver Type Library From the Visual Studio main window, select Project → Add Reference to open the Add Reference dialog. Select the COM tab, as shown in Figure 29. Figure 29. Visual Studio Add Reference Dialog From the COM tab, select Echelon OpenLDV xDriver 1.0 Type Library and click OK to add the reference.
Figure 30. Visual Studio Add New Item Dialog Select COM Class as the template. This template generates the proper GUIDs and the required New Sub method for your project. If you copy the sample files to use as a base for your project, you must change the GUIDs. Recommendation: Use the name Lookup[Database Type] as the name of the class, where [Database Type] represents the type of database management system you are using.
Figure 31. Delete Class1.vb Import xDriver Types to Your System Namespace Add the following lines to the beginning of your source code (LookupCSV.vb, in this example): Imports LdvxLib Imports LdvxLib.LdvxEncryption Imports LdvxLib.LdvxResult These statements add the properties, methods, and types of the Echelon OpenLDV xDriver 1.0 Type Library (see Add a Reference to the xDriver Type Library on page 127) to the System namespace of your project.
Figure 32. Visual Studio Object Browser View Your class must implement the DownlinkLookup, UpdateLookup, and UplinkLookup members of the ILdvxLookup interface. You can optionally also implement the SetIntance and SetOptions members of the ILdvxConfigure interface. You can now begin coding your lookup extension component. See Appendix C, Custom Lookup Extension Component Programming, on page 161, for more information about custom lookup extension component programming.
2. Click Add to open the New Profile dialog, as shown in Figure 33. Figure 33. xDriver Profile Editor New Profile Dialog 3. Enter a profile name (“Sample” for this example) in the Profile Name field. 4. Click OK to close the New Profile dialog. 5. For the General tab of the OpenLDV xDriver Profile Properties dialog for the new profile, enter a description in the Profile Description text box, as shown in Figure 34. Figure 34.
6. For the Lookup tab of the OpenLDV xDriver Profile Properties dialog for the new profile, select the newly built profile from the Extension Name dropdown listbox, as shown in Figure 35. Figure 35. OpenLDV xDriver Profile Properties – Lookup Tab 7. Make any other changes that are appropriate for your custom profile, and click OK to accept the changes and close the dialog. Test the Lookup Extension Create an RNI for your custom xDriver lookup extension, and give it a name like “X.Sample.DownlinkKey”.
• Windows Vista or Windows 7: \Users\Public\Documents \LonWorks\OpenLDV SDK\xDriver API Examples • Windows XP: \Documents and Settings\All Users\Documents \LonWorks\OpenLDV SDK\xDriver API Examples The example applications are also installed as a ZIP file in the LONWORKS \OpenLDV SDK\SourceArchive folder on your computer. The ZIP file is named xDriverApiExamplesSource_vn.nn.nnn.ZIP file (where n.nn.nnn represent the current version and build of the OpenLDV SDK).
these fields should only be updated from the UpdateLookup function. The database configuration interface that you create must update these fields in a guaranteed, safe manner. For more information about how the lookup extension component handles authentication key changes, see Authentication Key Handling on page 111.
installing the software does not return the default values to these profiles. However, the xDriver Profile Editor allows you to restore any profile to its default value. • Install your profiles with temporary Registry entries that are overwritten each time the software is installed. In this case, the default values would be restored each time the software is installed, and all changes that were configured by the user since the last installation would be lost.
Figure 36. Services Administrative Control Panel Applet 3. To start the Connection Broker, right-click Echelon xDriver Connection Broker and select Start. Important: You must have administrator privileges to start the Connection Broker. 4. To enable the Connection Broker service permanently, right-click Echelon xDriver Connection Broker and select Properties to open the Echelon xDriver Connection Broker Properties dialog. From this dialog, select Automatic from the Startup type dropdown listbox.
7 LNS Programming with xDriver This chapter describes sample programs to assist you when creating LNS applications to manage downlink and uplink xDriver sessions. Because LNS Server includes support for xDriver, you can review these sample programs to understand that support before creating your own LNS applications that use xDriver.
Downlink Sample Applications LNS applications that manage downlink sessions operate like any other type of network interface. However, the network interface name for an xDriver RNI must use the following naming convention: X.[Profile Name].[Downlink Lookup Key] where [Profile Name] represents the name of the xDriver profile to be used in this session and [Downlink Lookup Key] represents the downlink lookup key assigned to the RNI when it was added to the xDriver database.
lcaOS.Open 'Add a new network object and open the 'network database. “Network1” represents the name 'of the network and “c:\Network1” represents the path to the 'network database. Set ActiveNetwork = lcaOS.Networks.Add _ ("Network1", "c:\Network1", True) ActiveNetwork.Open 'Fetch the system from the network. Set ActiveSystem = ActiveNetwork.Systems.Item(1) 'Select a network interface. Note the use of the xDriver naming 'convention in this line: X.[Profile Name].[Downlink Lookup Key].
Figure 37. Downlink Application Form This application can open either of the two remote LONWORKS networks by clicking the Open Network A and Open Network B buttons. After either network has been opened, the applicable Close Network button becomes enabled, so that a user can close the network. When both networks are opened at the same time, each network is assigned its own xDriver network interface.
Set curRNI = NIs.Item("X.Default.RNI-0001") 'Set the variable curRNI as the 'network interface you want to open. Note the 'use of the xDriver naming convention here: 'X.[Profile Name].[Downlink Lookup Key]. Dim SysList As LcaSystems 'Set Syslist as the System objects collection. Set SysList = g_NetworkA.Systems 'Set g_SystemA as the System object for Set g_SystemA = SysList(1) 'the network to be opened. Dim SysNSD As LcaNetworkServiceDevice Set SysNSD = g_SystemA.NetworkServiceDevice Set SysNSD.
Private Sub CloseNetB_Click() OpenNetB.Enabled = True CloseNetB.Enabled = False g_SystemB.Close g_NetworkB.Close End Sub 'Private Sub Form_Load() is called when the form Load event occurs. Private Sub Form_Load() g_cOS.RemoteFlag = False 'Set the application access mode to local. g_cOS.SingleUserMode = False 'Allow multiple applications to access LNS 'server. g_cOS.Open 'Open the Object Server. CloseNetA.Enabled = False 'Disable the Close Network buttons, so that a CloseNetB.
be called from the Timer1_Timer() function after the next timer control interval expires. The StartButton_Click() function opens the network that requested connection in independent mode, and enables monitoring of the network variable monitor set for that network. It also calls the ReleasePendingUpdates method to release the monitor-point update events that have been withheld since the session began.
'local. 'Allow multiple applications to access 'the LNS Server. m_cOS.Open 'Open the LNS Server. m_cOS.BeginIncomingSessionEvents ("Default") 'Register the application 'for uplink session event handling. 'After this, each time the listener 'port assigned to default profile 'receives an uplink session request, 'the m_cOS_OnIncomingSessionEvent event 'will be fired. m_gbInMP = False 'Set the monitor point update event 'flag to False until a monitor point 'update event is received.
ByVal DataPoint As Object, ByVal srcaddr As Object) Dim src_addr As LcaSourceAddress Set src_addr = srcaddr 'Store the calling network address source in 'the variable src_addr. X1 = src_addr.NodeId 'Store the node ID reporting the event in the 'variable X1. X2 = src_addr.SubnetId 'Store the subnet ID in the variable X2. Set m_gMP = MonitorPoint 'Store the monitor point for the event in 'variable m_gMP. Set m_gDP = DataPoint 'Store the data point for the event in 'variable m_gDP.
m_gbInUplinkClose = True End Sub 'event and will now close the monitor points 'and the network. 'Set the uplink close flag to True. 'Private Sub StopButton_Click() closes all monitor points, monitor sets, and 'networks. It also re-enables the Exit button so that the user can close the 'application when he wants. Private Sub StopButton_Click() m_cMS.Close m_cCurNet.CloseIndependent ExitButton.Enabled = True End Sub 'Close monitor set. 'Close the open network.
A Custom Network Interfaces This appendix provides high-level guidance for working with a custom network interface that can work with the OpenLDV driver.
Overview Echelon and other manufacturers provide a wide selection of network interfaces for different LONWORKS channel types and for various computer requirements. You can also create a custom OpenLDV compatible network interface.
close calls. The OpenLDV driver calls these driver functions to interact with the custom network interface. You can create an OpenLDV application that manages the custom network interfaces supported by your custom Windows driver, similar to the Echelon LONWORKS Interfaces application. The OpenLDV application should perform the following basic tasks: 1. Create an LDVDriverInfo object: a. Set the size equal to the struct size. b. Set the id to any unused value > 127.
OR of the LDV_DEVCAP_L5 and LDV_DEVCAP_SICB enumeration values. g. Set the capsMask to suitable current capabilities of the device. When creating the device, you generally set this parameter to the same values as the caps parameter. h. Set the transId to the transceiver ID of the custom network interface, as appropriate. i. Set the driverId to the driver specified in the ldv_set_driver_info() function in step 2 on page 149.
for the custom network interface should be “MyCustomLON1”. The subkey for the device within the registry should also have the name “MyCustomLON1”. Figure 39 and Figure 40 show these example registry entries. Figure 39. The MyCustomLON1 Registry Key Figure 40.
B LNS Methods and Events for xDriver Support This appendix describes the methods and events that are included with LNS Server for use with xDriver. You use these methods and events when creating LNS applications to initiate and manage xDriver sessions.
xDriver Methods and Events This appendix describes the LNS methods and events you use when creating an application to manage xDriver sessions. To use these methods and events, you must install the LNS Application Developer’s Kit. Within a COM application, add a reference to the LNS Object Server. See Chapter 4, “Programming an LNS Application” in the LNS® Programmer’s Guide or the LNS Application Developer’s Kit help for more information.
automatically. The session establishment time for a profile can be configured using the xDriver Profile Editor. For more information, see xDriver Profiles on page 134. BeginIncomingSessionEvents Applies to: Object Server object This method is used to register for incoming session event handling. The application is then notified of incoming uplink session requests to the LNS Server. Syntax objServer.BeginIncomingSessionEvents xDriverProfileName Table 38.
Syntax objServer.EndIncomingSessionEvents xDriverProfileName Table 39. EndIncomingSessionEvents Parameters Element Description xDriverProfileName The name of the xDriver profile used in the call to BeginIncomingSessionEvents. Remarks Call this method for each profile for which the BeginIncomingSessionsEvent method was called before closing an application. NetworkInterfaces.
Element Description stringExpression A string type specifying the name of the object to retrieve. For xDriver network interfaces, the network interface name of the RNI can be a maximum of 128 characters long, and must be specified using the following naming convention: X.[ProfileName].
Element Description netName A string that represents the LNS network name of the network that requested the session. intfName A string that represents the network interface name of the network that requested the session. tag This value must be used when the AcceptIncomingSession method is called to accept or reject the session. Remarks After an uplink session request has been received and this event has fired, use the AcceptIncomingSession method to accept or reject the request.
Recommendation: Open the network in server-independent mode when you plan to use this method, because using this method in server-dependent mode could disrupt network management operations. If you are not operating in server-independent mode and you call this method, an exception is thrown. However, the monitor-point update events are released.
C Custom Lookup Extension Component Programming This appendix describes the interfaces and methods that your custom lookup extension component can use or must implement.
Overview This appendix describes the interfaces and methods that your custom lookup extension component can use or must implement: • Implement o • Use ILdvxConfigure (optional) o ILdvxLookup (required) o ILdvxSCO o o ILdvxSCO2 ILdvxSCO_TCP A lookup extension component must implement ILdvxLookup, and can optionally implement ILdvxConfigure. During its operation, the lookup extension component calls methods of the ILdvxSCO, ILdvxSCO2, and ILdvxSCO_TCP interfaces.
Syntax C++ STDMETHOD(SetInstance)(BSTR instance) Visual Basic Sub SetInstance(ByVal instance As String) Table 43. SetInstance Parameters Parameter Description instance Name of the lookup extension instance. Defaults to the profile name, if not configured in the profile. Returns Standard xDriver LdvxResult (HRESULT) describing the result of the call.
ILdvxLookup Interface The lookup interface is the primary interface implemented by an xDriver lookup extension component. It defines the methods that are used to look up session parameters in your xDriver database. DownlinkLookup Method Applies to: xDriver Lookup Extension Component This method is called by xDriver when a downlink session is initiated. It is passed a pointer to the xDriver Session Control Object (SCO) for the session. The SCO contains the downlink lookup key to be looked up.
E_HANDLE, LDVX_E_INVALID_DOWNLINK_KEY, or LDVX_E_LOOKUP_FAILURE. UpdateLookup Method Applies to: xDriver Lookup Extension Component This method is called by xDriver upon the completion of a change to a session authentication key by xDriver. The lookup extension component must implement an update to its database from this method, so that it stores the new values of the current authentication key and the next authentication key from the SCO. These fields can only be updated from the UpdateLookup method.
The ILdvxSCO interface provides methods that you can use to obtain the uplink lookup key and fill in the SCO fields. For more information, see ILdvxSCO Interface on page 166. Syntax C++ STDMETHOD(UplinkLookup)(ILdvxSCO * xSCO) Visual Basic Sub UplinkLookup(ByVal xSCO As LdvxLib.ILdvxSCO) Table 47. UplinkLookup Parameters Parameter Description xSCO Interface to the SCO object. This element contains the uplink key to be looked up. The UplinkLookup implementation must fill in the required SCO fields.
Called From Field Name DownlinkLookup UplinkLookup UpdateLookup Uplink Key Read/Write Read Only Read Only Current Authentication Key Read/Write Read/Write Read Only Next Authentication Key Read/Write Read/Write Read Only Additional Downlink Packet Header Read/Write Read/Write Read Only Additional Downlink Packet Trailer Read/Write Read/Write Read Only GetAdditionalDownlinkPacketHeader Method Applies to: Session Control Object This method obtains any additional bytes that are pre-pend
Syntax C++ STDMETHOD(GetAdditionalDownlinkPacketTrailer)(BSTR * hexBytes) Visual Basic Function GetAdditionalDownlinkPacketTrailer() As String Table 50. GetAdditionalDownlinkPacketHeader Parameters Parameter Description hexBytes String to contain returned bytes. Returns Hexadecimal string containing the bytes to be appended, two characters per byte.
Syntax C++ STDMETHOD(GetCurrentAuthenticationKey)(BSTR * authKey) Visual Basic Function GetCurrentAuthenticationKey() As String Table 52. GetCurrentAuthenticationKey Parameters Parameter Description authKey String variable that stores the return data. Returns Current authentication key for the RNI, as a 32-character hexadecimal string representing a 128-bit MD5 authentication key. GetDownlinkKey Method Applies to: Session Control Object This method obtains the downlink lookup key.
GetEncryptionType Method Applies to: Session Control Object This method obtains the type of encryption that the xDriver protocol engine is using when sending encrypted data packets for this session. Syntax C++ STDMETHOD(GetEncryptionType)(LdvxEncryption * nType) Visual Basic Function GetEncryptionType() As LdvxLib.LdvxEncryption Table 54. GetEncryptionType Parameters Parameter Description nType String variable that stores the return data. Returns Encryption type being used for the session.
GetNextAuthenticationKey Method Applies to: Session Control Object This method obtains the next xDriver authentication key. Syntax C++ STDMETHOD(GetNextAuthenticationKey)(BSTR * authKey) Visual Basic Function GetNextAuthenticationKey() As String Table 56. GetNextAuthenticationKey Parameters Parameter Description authKey String variable that stores the return data. Returns The next authentication key for the RNI, as a 32-character hexadecimal string representing a 128-bit MD5 authentication key.
GetUplinkKey Method Applies to: Session Control Object This method obtains the xDriver uplink lookup key. This key comes from the RNI identifier that is passed to xDriver during an uplink session, and is filled into the SCO automatically. It is the responsibility of the lookup extension component to map this key to the authentication and LNS network parameters to be used by the rest of the xDriver framework, and fill them into the SCO from the UplinkLookup function.
Table 59. SetAdditionalDownlinkPacketHeader Parameters Parameter Description hexBytes Hexadecimal string containing the bytes to be pre-pended, as pairs of hexadecimal digits. For example: 0B0C0D0E0F10. Returns Standard COM HRESULT describing the result of the call. Returns E_ACCESS_DENIED if field is presently read-only. Table 48 on page 166 lists each SCO field, along with when these fields are read-only.
For more information about how the xDriver lookup extension component handles authentication, see Authentication Key Handling on page 111. Syntax C++ STDMETHOD(SetAuthenticationFlag)(VARIANT_BOOL bAuth) Visual Basic Sub SetAuthenticationFlag(ByVal bAuth As Boolean) Table 61. SetAuthenticationFlag Parameters Parameter Description bAuth Authentication state as Boolean. If True, the xDriver protocol engine generates and validates link-level authentication.
Table 62. SetCurrentAuthenticationKey Parameters Parameter Description authKey xDriver authentication key for this session, as a 32-character hexadecimal string representing a 128-bit authentication key. The authentication key must be entered as a 32-character hexadecimal string representing a 128-bit MD5 key. For example: 0102030405060708090A0B0C0D0E0F10 Returns Standard COM HRESULT describing the result of the call. Returns E_ACCESS_DENIED if field is presently read-only.
must set this value appropriately depending on the RNI used. The default value is LDVX_ENCRYPTION_AUTO. Syntax C++ STDMETHOD(SetEncryptionType)(LdvxEncryption nType) Visual Basic Sub SetEncryptionType(ByVal nType As LdvxLib.LdvxEncryption) Table 64. SetEncryptionType Parameters Parameter Description nType Encryption type.
Table 65. SetLNSNetworkName Parameters Parameter Description lnsNetwork LNS network name as String (a maximum 85 characters). Returns Standard COM HRESULT describing the result of the call. Returns E_ACCESS_DENIED if field is currently read-only. Table 48 on page 166 lists each SCO field, along with when these fields are read-only. SetNextAuthenticationKey Method Applies to: Session Control Object This method specifies the next xDriver authentication key to be used for the session.
SetUplinkKey Method Applies to: Session Control Object This method sets the uplink lookup key. This unique key comes from the ASCII RNI identifier passed to xDriver during an uplink session and is filled into the SCO automatically. Therefore it is not required that you fill the uplink key into the SCO. Syntax C++ STDMETHOD(SetUplinkKey)(BSTR upKey) Visual Basic Sub SetUplinkKey(ByVal upKey As String) Table 67.
GetRemoteTCPAddress Method Applies to: Session Control Object This method obtains the remote TCP address of the RNI for the xDriver session. For an uplink session, the remote TCP address is filled into the SCO automatically. You could use this method to check that the remote TCP address filled into the SCO is valid by comparing the address that this method returns against the address stored in the database.
Table 70. GetRemoteTCPPort Parameters Parameter Description tcpPort Integer variable that stores the return data. Returns The remote TCP port number of the RNI as an Integer. SetRemoteTCPAddress Method Applies to: Session Control Object This method sets the remote TCP address of the RNI. For a downlink session, it is the responsibility of the xDriver lookup extension to map the downlink lookup key to the database, extract the TCP address from the database, and fill it into the SCO using this method.
This method sets the remote TCP port that the RNI at the other end of the connection uses to receive connections from the LNS Server. For a downlink session, it is the responsibility of the xDriver lookup extension to map the downlink lookup key to the database, extract the remote TCP port from the database, and fill it into the SCO using this method. Syntax C++ STDMETHOD(SetRemoteTCPPort)(short tcpPort) Visual Basic Function GetRemoteTCPPort() As Short Table 72.
Table 73. GetNeuronID Parameters Parameter Description nNeuronID String variable that stores the return data. Returns String representation of the 48-bit hexadecimal Neuron ID.
Index A AcceptIncomingSession, 154 ANSI/CEA 709.1-B, 10 API devices and drivers, 16 enumerations, 37, 42 example application, 52 functions.
GetRemoteTCPPort, 179 GetSessionControlObjectID, 171 GetUplinkKey, 172 H hardware requirements, 5 header file (ldv32.
N NetVarHdr, 65 network address, 67 network interface application settings, 7 command interface, 76 custom, 148 receiving messages from, 75 sending messages to, 75 network interface command, 77 Network Protocol Data Unit (NPDU), 61 NetworkInterfaces.Item( ), 156 NPDU, 61 O OnIncomingSessionEvent, 157 OpenLDV API, 15 OpenLDV Developer Example, 90 OSI Model, 10 P presentation layer, 13 processes, multiple, 14 profile, 94, 134 property, NetworkInterfaces.
www.echelon.
