LonBridge Server User’s Guide ® 078-0386-01A
Echelon, LONWORKS, LONMARK, LonTalk, Neuron, 3120, 3150, ShortStack, and the Echelon logo are trademarks of Echelon Corporation registered in the United States and other countries. 3170, LonBridge, and OpenLDV are trademarks of the Echelon Corporation. Other brand and product names are trademarks or registered trademarks of their respective holders.
Welcome The Echelon LonBridge™ Server is a software tool that provides an interface between a TCP/IP network and a network of LONWORKS® interoperable selfinstallation (ISI) devices. This interface allows you to create a control application, such as a graphical user interface (GUI), to manage devices on a LONWORKS network from a device that is connected to a TCP/IP network.
iv
Table of Contents Welcome .........................................................................................................iii Audience ........................................................................................................iii Related Documentation ................................................................................iii Introduction........................................................................................................ 1 Introduction.......................
Define Elements........................................................................... 46 Use the Resource Editor to Determine Attributes .............................. 47 Determining the Attributes for nvoPower..................................... 48 Determining the Attributes for nviValue and nvoValueFb ......... 50 Define Elements...................................................................... 53 Browse the XIF File to Determine Indices ..........................................
1 Introduction This chapter introduces the LonBridge Server and describes how to install it.
Introduction The Echelon LonBridge Server is a software tool that provides an interface between a TCP/IP network and a network of LONWORKS interoperable selfinstallation (ISI) devices. This interface allows you to create a control application, such as a graphical user interface (GUI), to manage devices on a LONWORKS network from a device that is connected to a TCP/IP network. LonBridge Server also provides a client-independent application programming interface (API) for managing these networks and devices.
TCP Socket TCP Socket Figure 1.
The LonBridge API supports up to 20 local or remote clients. Each client opens a TCP socket to the LonBridge Server. Clients call functions in the API by sending a request to the LonBridge Server. The request must be formatted as an XML string. The API returns a response as an XML string through the same TCP socket interface. Each client specifies an incoming port to receive event notifications for device discovery and network variable value changes. All clients receive all events.
3. Double click the LonBridge140xxxSetup.exe file that you downloaded (the xxx in the file name represents the current build number for the LonBridge Server). The Echelon LonBridge Server 1.4 main installer window opens. 4. Follow the installation dialogs to install the LonBridge Server onto your computer. By default the LonBridge Server is installed in the C:\Program Files\Echelon\LonBridge Server directory. In addition to the LonBridge Server, the installation program also installs: • OpenLDV 3.
environments, you must port the LonBridge Server to that Linux distribution (see the source code comments for more information). Starting the LonBridge Server For the Windows platform, the service for the LonBridge Server generally starts automatically when the operating system starts, although you can configure the service to start manually (see Chapter 2, Configuring the LonBridge Server, on page 9, for more information about configuring the LonBridge Server).
Windows Switch Linux Switch Description /D -d Enables debug logging; logs events tracing the internal operation of the LonBridge Server. Also enables error and general logging. You can use this option when porting or enhancing the LonBridge Server. Mutually exclusive with the /E, /G, /N, and /V (-e, -g, -n, and -v) switches. /E -e Enables error logging; includes only error events in the log file. Mutually exclusive with the /D, /G, /N, and /V (-d, -g, -n, and -v) switches.
The order of increased level of detail for the event logging switches is: 1. /E (-e) 2. /G (-g): Includes /E (-e) 3. /D (-d): Includes /E (-e) and /G (-g) 4. /V (-v): Includes /E (-e), /G (-g), and /D (-d) Specifying one of the event logging switches (/D, /E, /G, /N, or /V for Windows, -d, -e, -g, -n, or -v for Linux) overrides the event-logging value specified in the LonBridge configuration file (config.xml); see The config.xml File on page 11 for information about this file.
2 Configuring the LonBridge Server This chapter describes how you can configure the LonBridge Server.
Configuring the LonBridge Server For the LonBridge Server, you can specify the following configuration information: • The LONWORKS network interface • The LAN Internet protocol (IP) address • The LAN IP port • The LONWORKS network variable polling interval • The event logging level for the LonBridge Server This information configures the communications for the LonBridge Server to be able to communicate with the LONWORKS network and the TCP/IP network.
Figure 2. LonBridge Control Utility See the LonBridge Control utility online help for information about the utility’s fields and controls. The config.xml File The config.xml file contains XML elements that configure the LonBridge Server; these elements correspond to the GUI controls in the LonBridge Control utility. You can edit this file using any text editor (such as Windows Notepad or Linux vi). If you change any values within the config.
The element defines the configuration, and is the top-most element within the config.xml file. The element is required if any of the other child elements are included, and only one element is allowed per configuration file.
The element specifies the IP port for the LonBridge Server. By default, the LonBridge Server uses the default IP port (3050). The element specifies the event logging level for the LonBridge Server and the LonHome Display Example: • None – Disables all event logging. • Error – Enables error logging; includes only error events in the log file. • General – Enables general logging; logs general events, such as device discovery and startup events in the log file.
the program ID from the new device and then searches the device class files for a matching program ID. If the LonBridge Server finds a matching program ID, the LonBridge Server stores information about the discovered device in the devices.xml file in the Instances directory (see Instances Directory on page 16). Each class file describes the device interface for a specific program ID, similar to a LONWORKS device external interface (XIF) file.
Class File Application Program ID isilampmodule3.xml Echelon 3170 Lamp Module 90:00:01:1E:29:4F:11:03 isilampmodule4.xml Example Mini PL 3120 Lamp 9F:FF:FF:1E:29:41:11:03 isilampmodule5.xml Example Mini PL 3150 Lamp 9F:FF:FF:1E:29:4F:11:03 isilampmodule6.xml Echelon Mini FT 3150 Lamp 9F:FF:FF:1E:29:4F:04:03 isilight2.xml Echelon ISI Lamp Module 9F:FF:51:1E:00:4A:11:18 isioccupancy.xml Example Occupancy Sensor 9F:FF:FF:0A:3D:40:11:00 isioccupancy2.
To add a new device for the LonBridge Server to monitor or control, add an XML file for the device to the Classes directory. See Chapter 5, LonBridge Device Class File, on page 34, for information about the XML elements that describe devices and for an example class file. To modify which network variables the LonBridge Server monitors or controls for a device, edit the appropriate device class file with any text editor.
• • An indication of the device’s state within LonBridge (the active attribute); this attribute can have one of the following values: o active=true to specify that LonBridge can communicate with the device o active=pending to specify that LonBridge has not yet established communications with the device; this value is set during LonBridge startup, while it is establishing communications with all known devices o active=marginal to specify that LonBridge has temporarily lost communications with the devi
3 Using the LonBridge API This chapter describes the tasks performed by a LonBridge application and by the LonBridge Server. A LonBridge application uses the LonBridge API to manage and communicate with LONWORKS devices.
Tasks Performed by a LonBridge Application Using the LonBridge API, a LonBridge application can discover manage LONWORKS interoperable self-installation (ISI) devices on a LONWORKS network, communicate with the devices, and communicate with the LonBridge Server about the devices. Defining Device Classes The Classes directory contains device class files that describe classes of devices that the LonBridge Server supports.
The LonBridge Server reads the LonBridge configuration file to determine the name of the network interface (such as LON1) for a layer-5 MIP interface, or the serial device name (such as /dev/ttyS0) for a ShortStack interface. The LonBridge Server cannot share a network interface with other applications. If the network interface is already in use by another application, the LonBridge Server waits for the network interface to become available.
The monitoring method can be specified for each specified network variable. The method can be either passive monitoring (with a layer-5 MIP only) or polled updates: • For passive monitoring, the LonBridge Server silently joins connections for network variables that are enrolled in connections.
4 LonBridge API This chapter describes the LonBridge application programming interface (API) for input and output messages.
LonBridge API The communications between the LonBridge Server and various LonBridge applications uses the LonBridge API. This API consists of XML strings (commands) passed as messages between the LonBridge Server and a LonBridge application. Each message is a well-formed XML string with a element as the top-most element. Table 3 lists the commands that form the LonBridge API. Table 3.
retrieves the id attribute; you can also view the id attribute in the devices.xml file (see Instances Directory on page 16). Expressions Expressions are used in the where attribute of the message. The conditional operators include: • and • or • > • >= • == • != Operators are processed from left to right. However, you can use parentheses to group conditions.
Examples: Error deleting non-existing object: ... ... More complex error reporting: ... ...
posProperty--; } } LonBridge Commands for Input Messages The LonBridge Server sends messages to a LonBridge application for either of the following reasons: • In response to specific LonBridge command • To notify the LonBridge application of events, such as device discovery or a property update An application cannot send input messages.
can act on the change (for example, update a GUI window) without waiting for the response from the remote LONWORKS device. The message is usually followed by the message. The attributes for the message vary depending on the device and the original output message for which this message is the response. The reported attributes include a fixed set of attributes that identify the device, followed by the attributes defined within the element in the devices.xml file.
The element is required, and only one element is allowed per message. The message modifies one or more objects. The LonBridge Server stores the specified attribute values, and overwrites any existing attribute values. You cannot delete attributes from an object. Whenever a message causes any change to an object, the LonBridge Server broadcasts the message for that object, followed by the message when the device responds that the change is complete.
<
Example for the Message: ...
5 LonBridge Device Class File This chapter describes the XML elements for the LonBridge device class file and how to create a device class file.
LonBridge Device Class File Format A LonBridge device class file is an XML document that the LonBridge Server uses to define the interface for a device interface for a specified program ID. When a device is discovered, the LonBridge Server searches the Classes directory for a device class file with a matching program ID (see Classes Directory on page 13). Table 7 lists the XML elements that a device class file includes. Table 7.
Attribute Description Required? length Defines the length of an input network variable. Optional Example: For a network variable with a length of 2, the element maps attributes to bytes 0 and 1. name Defines the name for the attribute. Required scale Defines a percentage by which to scale the value.
Example: The element defines the fields within a network variable. Table 9 lists the attributes for the element. Table 9. Attributes for the Element Attribute Description Required? index Specifies the starting byte of the networkvariable. Index 0 is the first byte. Required length Defines the number of bytes within the input network variable.
Attribute Description Required? pid Defines the program ID for the device class. Required During device discovery, LonBridge Server maps the program ID of the class to the program ID of the discovered device. type Defines the type of the device. Required Example:
Attribute Description Required? output For an input network variable, defines the bytes to be put on the LONWORKS network for this byte. Optional For an output network variable, defines the LonBridge XML value used to set the device. value Defines the value of the byte, if any. Optional Example:
Attribute Description Required? type Specifies the type for the network variable. If the network variable is a configuration network variable (CPNV), the type can be a configuration property type. Optional If the type name is SCPTname1, SCPTname2, or SCPTname3, the LonBridge Server reads the network variable to get the device name for the device. If more than one name string is available, the LonBridge Server concatenates them.
XML Schema for Device Class Files To allow you to create well-formed XML documents for device class files, this section provides an XML Schema Definition (XSD) that defines the basic syntax for a LonBridge device class file. PAGE 47
energy peak use, and one for lowest energy use. These network variables are defined by the elements within the three structures.
PAGE 502. Define an element for each abstract attribute that the application requires. 3. Decide which network variables or fields within network variables the LonBridge application needs to access. The application can include a subset of the network variables or network variable fields that are defined for the LONWORKS device. Recommendation: If you define a subset, include any mandatory network variables. 4.
network output polled SNVT_power nvoPower nv_properties { cpPwrSendOnDelta }; network input const SCPTenergyCntInit cp cp_info(device_specific) cpEnergyCntInit; network output eeprom SNVT_elec_kwh nvoEnergyHi nv_properties { cpEnergyCntInit }; network output SNVT_elec_whr nvoEnergyLo; network output SNVT_multiplier_s nvoMultiplierFb = DEFAULT_MULTIPLIER; network input far const SCPTrunHrInit cp cp_info(device_specific) cpRunHrInit; network output SNVT_elapsed_tm nvoRunHours nv_properties { cpRunHrInit }; ne
network output polled SNVT_power nvoPower nv_properties { cpPwrSendOnDelta }; The first network variable, nviValue, defines the input state for the simplified Lamp Module, which the LonBridge application uses to set the lamp’s state. The second network variable, nvoValueFb, defines the output state for the simplified Lamp Module, which the lamp uses to report its current state to the LonBridge application and to the network.
... ... At this point, the element is missing important information, such as the network variable indexes, their lengths, and the byte indexes for fields within the network variable (if any).
To use the Resource Editor to determine the network variable attributes: 1. Start the Resource Editor. If you have a current version of the NodeBuilder Development Tool installed, select Start → Programs → Echelon NodeBuilder Software → NodeBuilder Resource Editor. The Resource Editor is also installed with the Echelon Mini EVK, and is available for LonMark members from the LonMark Web site. 2. Expand the entry for C:\LonWorks\Types. 3. Expand the entry for STANDARD (Scope 0: Standard). 4.
Figure 4. Attribute Information for the SNVT_power Type The first piece of information that you need about a network variable is its size. As the figure shows, the data type for the SNVT_power type is unsigned long, which the Neuron C language defines as a two-byte type. Thus, the size of the nvoPower network variable is 2. Because the SNVT_power type does not include any structures, there is only one network variable field: its index is 0 and its length is 2 (the size of the type).
Figure 5. The Scales Tab for the SNVT_power Type For a LonBridge application, you might want to show the power as whole units, so you can include a scale attribute of 10 to display whole values.
Figure 6. Attribute Information for the SNVT_switch_2 Type The first piece of information that you need about a network variable is its size. As the figure shows, the SNVT_switch_2 type is a structured type.
Figure 7. The Scales Tab for the SNVT_switch_2 Type For the enumeration value within the device class file to define the “on” state, you need to include a scale value of 200 to allow the LonBridge application to use simple values of 0 and 1 to specify “off” and “on” states. Thus, the elements for the state attribute within the device class file includes the following information: ...
The definition still lacks the network variable indices for the nviValue and nvoValueFb network variables; see Browse the XIF File to Determine Indices on page 56 to determine the indices. The next step is to define the enumerations for the state network variables. Define Elements The state network variables are structured network variables, and the example LonBridge application for the simplified Lamp Module requires access to the fields within these network variables.
Figure 8. Enumerations within the NodeBuilder Resource Editor Double-click the switch_state_t enumeration to display the enumeration values, as shown in Figure 9 on page 55.
Figure 9. The switch_state_t Enumeration For the nviValue network variable, a LonBridge application uses the SW_SET_OFF and SW_SET_ON values, which are enumeration values 0 and 1. For the nvoValueFb network variable, a LonBridge application receives the SW_REPORT_OFF and SW_REPORT_ON values, which are enumeration values 2 and 3.
The next step is to fill in the missing network variable indices.
0 1 63 1 0 1 0 1 0 0 0 0 0 "@0|6 13 * 1 2 0 0 0 0 VAR nvoEnergyLo 8 0 0 0 0 1 63 1 0 1 0 1 0 0 0 0 0 "@0|10 14 * 1 2 0 0 0 0 VAR nvoMultiplierFb 9 0 0 0 0 1 63 1 0 1 0 1 0 0 0 0 0 "@0|7 188 * 1 1 0 0 0 0 VAR cpRunHrInit 10 0 0 0 0 1 63 0 0 1 0 1 0 0 0 0 1 "&2,11,0\xA4,135 87 * 5 2 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 2 0 0 0 0 VAR nvoRunHours 11 0 0 0 0 1 63 1 0 1 0 1 0 0 0 0 0 "@0|8 87 * 5 2 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 2 0 0 0 0 VAR nvoConnSize 12 0 0 0 0 1 63 1 0 1 0 1 0 0 0 0 0 * 8 * 1 2 0 0 0
Neuron C Declaration XIF File Definition network output polled SNVT_switch_2 nvoValueFb VAR nvoValueFb 2 0 0 0 nv_properties { cpMinSendTime }; 0 1 63 1 0 1 0 1 0 0 0 0 0 "@0|2 189 * 3 1 0 0 1 0 4 0 1 0 0 1 0 0 0 0 network output polled SNVT_power nvoPower nv_properties { cpPwrSendOnDelta }; VAR nvoPower 5 0 0 0 0 1 63 1 0 1 0 1 0 0 0 0 0 "@0|4 27 * 1 2 0 0 0 0 For a device class file, you need the network variable index for each network variable.
... The next step is to ensure that the device class file is complete, and is not missing any important information.
60 LonBridge Device Class File
www.echelon.
