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.
Neuron Chips and other OEM Products were not designed
for use in equipment or systems, which involve danger to
human health or safety, or a risk of property damage and
Echelon assumes no responsibility or liability for use of the
Neuron Chips in such applications.
Parts manufactured by vendors other than Echelon and
referenced in this document have been described for
illustrative purposes only, and may not have been tested
by Echelon. It is the responsibility of the customer to
determine the suitability of these parts for each
application.
ECHELON MAKES AND YOU RECEIVE NO WARRANTIES OR
CONDITIONS, EXPRESS, IMPLIED, STATUTORY OR IN ANY
COMMUNICATION WITH YOU, AND ECHELON SP ECIFICALLY
DISCLAIMS A N Y IMPLIED WARRA NT Y O F ME R C H ANTABILITY
OR FITNESS FOR A PARTICULAR PURPOSE.
No part of this publication may be reproduced, stored in a
retrieval s ystem, or transmitted, in any form or by any means,
electronic, mechanical, photocopying, recording, or
otherwise, without the prior written permission of Echelon
Corporation.
The Echelon LonBridge™ Server is a software tool that provides an interface
between a TCP/IP network and a network of L
installation (ISI) devices. This interface allows you to create a control
application, such as a graphical user interface (GUI), to manage devices on a
ONWORKS network from a device that is connected to a TCP/IP network.
L
This document describes the LonBridge Server, including how to install it,
configure it, and use the LonBridge application programming interface (API) to
manage and communicate with devices.
Audience
This document assumes that you have a good understanding of the LONWORKS
platform and microcontroller or microprocessor programming.
Related Documentation
The following manuals are available from the Echelon Web site
www.echelon.com) and provide additional information that can help you develop
(
LonBridge applications:
Introduction to the LONW
•
provides an introduction to the ISO 14908 (ANSI/CEA-709.1 and
EN14908) Control Networking Protocol, and provides a high-level
introduction to L
are used for developing, installing, operating, and maintaining them.
ONWORKS networks and the tools and components that
ORKS
System
ONWORKS
®
interoperable self-
(078-0183-01A). This manual
ISI Programmer's Guide
•
(078-0299-01F). Describes how you can use the
Interoperable Self-Installation (ISI) protocol to create networks of control
devices that interoperate, without requiring the use of an installation
tool. Also describes how to use Echelon's ISI Library to develop devices
that can be used in both self-installed as well as managed networks.
ISI Protocol Specification
•
(078-0300-01F). Describes the Interoperable
Self-Installation (ISI) protocol, which is a protocol used to create
networks of control devices without requiring the use of an installation
tool.
•
LONM
®
ARK
Application Layer Interoperability Guidelines.
describes design guidelines for developing applications for open
interoperable L
Web site,
ShortStack User’s Guide
•
to develop an application for a L
ShortStack
ONWORKS devices, and is available from the LONMARK
www.lonmark.org.
(078-0365-01A). This document describes how
®
2.1 Micro Server. It describes the architecture of a
ONWORKS device using Echelon’s
ShortStack device and how to develop a ShortStack device.
®
All of the Echelon documentation is available in Adobe
PDF format. To view the
PDF files, you must have a current version of the Adobe Reader
download from Adobe at:
Browse the XIF File to Determine Indices .......................................... 56
Complete Device Class File................................................................... 59
vi
1
Introduction
This chapter introduces the LonBridge Server and describes
how to install it.
LonBridge Server User’s Guide 1
Introduction
The Echelon LonBridge Server is a software tool that provides an interface
between a TCP/IP network and a network of L
installation (ISI) devices. This interface allows you to create a control
application, such as a graphical user interface (GUI), to manage devices on a
ONWORKS network from a device that is connected to a TCP/IP network.
L
ONWORKS interoperable self-
LonBridge Server also provides a client-independent application programming
interface (API) for managing these networks and devices. For Microsoft
®
Windows
platforms, the LonBridge Server requires a layer-5 network interface
®
that is compatible with the OpenLDV™ interface, such as the Echelon U20 USB
Network Interface, to manage communications with the L
®
For Linux
platforms, the LonBridge Server requires an Echelon ShortStack
ONWORKS network.
Micro Server (which uses the LDV interface) to manage communications with the
ONWORKS network.
L
Figure 1 on page 3 is a block diagram of a Windows or Linux host running the
LonBridge Server, and using the OpenLDV or equivalent interface to
communicate with the L
ONWORKS network. The LonBridge Server uses TCP/IP
sockets to communicate with LonBridge applications. The socket interface allows
the LonBridge Server to communicate with applications that are local to the
same host platform as the LonBridge Server and with applications that are
remote (connected by an Ethernet or similar network). This socket interface also
allows you to develop LonBridge client applications with any programming
language that supports TCP/IP socket interfaces.
2 Introduction
TCP Socket
TCP
Socket
Figure 1. LonBridge Server
The LonBridge Server provides the following key features:
• Supports networks of ISI devices
• Provides an easy-to-use programmatic interface that is independent of
any client operating system or processor
• Supports multiple, simultaneous clients
• Supports simple set-up for use with home user interface (UI) applications
• Runs on Windows Vista
®
, Windows XP, or Linux hosts
The LonBridge API provides a simple TCP/IP socket interface that you can use
directly as a bridge to a L
ONWORKS network. The LonBridge API supports
development of UI and controller applications that can run on Windows or Linux
platforms. The API consists of a simple set of extensible markup language (XML)
elements that describe L
ONWORKS devices and actions for those devices.
LonBridge Server User’s Guide 3
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.
Getting Started
The LonBridge Server software includes a Windows version and a Linux version.
Both versions are available from Echelon Support.
To use the LonBridge Server, perform the following steps:
1. Install the LonBridge Server. See
more information.
2. Configure the LonBridge Server. See Chapter
LonBridge Server
3. Create a device class file for your device. This file describes the interface
for each device that the LonBridge Server supports. See Chapter
, on page 9, for more information.
LonBridge Device Class File
4. Create a LonBridge application using the LonBridge API. See Chapter
LonBridge API
If you have an Echelon Lamp Module or Appliance Module, you can run the
LonBridge Server after step 2. For the Windows version, you can use the
LonHome™ Display Example application to view and manage the Lamp Module
or Appliance Module; for the Linux version running on the Altera
Embedded Evaluation Kit, you can load the example application into the SD
Card and view and manage the Lamp Module or Appliance Module.
, on page 23, for more information.
Installing the LonBridge Server
, on page 33, for more information.
Installing the LonBridge Server
Echelon delivers source code for the LonBridge Server to LonBridge Server
licensees. You can port this source code to any platform. The LonBridge Server
has been ported to, and tested with, the following operating system
environments:
2,
Configuring the
®
Nios® II
for
5,
4,
• Microsoft Windows XP
• Microsoft Windows Vista
• μClinux™ for the Altera Nios II Embedded Evaluation Kit (NEEK)
Installation for Windows
To install the LonBridge Server on a Windows platform, perform the following
steps:
1. Contact Echelon Support to request a license for the LonBridge Server.
2. Download the LonBridge Server from the address supplied by Echelon
Support.
4 Introduction
3. Double click the LonBridge140
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.4 Driver
•
and applications with a unified Windows software interface for sending
and receiving LonTalk
interfaces.
LonBridge Control Utility
•
start, and stop the LonBridge Server. This utility is not required to
operate the LonBridge Server, but is useful for setting it up. See
– A Windows driver that provides LONWORKS tools
®
messages through Echelon's family of network
LonBridge Control Utility
utility.
LonHome Display Example
•
uses the LonBridge Server.
The Microsoft .NET Framework 3.5 SP1
•
environment for the LonBridge Control utility. The .NET Framework is
not installed if your PC already has version 3.5 SP1 or later installed.
xxx
Setup.exe file that you downloaded (the
– An application that you can use to configure,
The
on page 10 for more information about this
– An example user interface application that
– The required operating
You can embed the Windows installer for LonBridge Server into your own
product’s installation program, using a silent installation of the LonBridge
Server. Silent installation does not install the OpenLDV driver, the LonHome
Display Example application, the .NET Framework, or the LonBridge
documentation. To perform silent installation, use the /S command-line switch:
LonBridgeSetup.exe /S
The LonBridge Server is installed as a Windows Service. You can set the startup
type for the Service by running the LonBridge Control utility, by modifying the
config.xml file, or from the Windows Services window. See Chapter
Configuring the LonBridge Server
configuring the LonBridge Server.
Installation for Linux
To install the LonBridge Server on a Linux platform, perform the following steps:
1. Contact Echelon Support to request a license for the LonBridge Server.
2. Download the LonBridge Server from the address supplied by Echelon
Support.
3. Decompress the LonBridge140
xxx
(the
LonBridge Server).
4. For a μClinux environment, modify the make file (as needed) and run it
to build the LonBridge Server application. For other Linux distribution
in the file name represents the current build number for the
2,
, on page 9 for more information about
xxx
Source.zip file that you downloaded
LonBridge Server User’s Guide 5
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
2,
service to start manually (see Chapter
9, for more information about configuring the LonBridge Server).
page
For either Windows or Linux platforms, you can start the LonBridge Server from
the command line.
Configuring the LonBridge Server
Command Line Usage for Windows
To start the LonBridge Server, if it is not already running as a service:
1. From the Windows command prompt, change directories to the
for a listing of the available command-line switches
, on
Command Line Usage for Linux
To start the LonBridge Server:
1. From the Linux command prompt, change directories to the LonBridge
directory.
2. Enter the lonbridge command.
See
Command Line Switches
for the lonbridge command.
for a listing of the available command-line switches
Command Line Switches
Table 1 lists the available command-line switches for the Windows LonBridge
command and the Linux lonbridge command.
The switches for the Windows LonBridge command are not case sensitive; you
can use either lower or upper case. However, the switches for the Linux
lonbridge command are case sensitive.
Table 1. Command-Line Switches for the LonBridge Command
Windows
Switch
/C -c Enables console logging; copies all logged events to the
Linux Switch Description
console.
You can use this option to watch log events in real-time
during development and debugging of your application or of
the LonBridge Server.
6 Introduction
Windows
Switch
/D -d Enables debug logging; logs events tracing the internal
/E -e Enables error logging; includes only error events in the log
/G -g Enables general logging; logs general events, such as device
Linux Switch Description
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.
file.
Mutually exclusive with the /D, /G, /N, and /V (-d, -g, -n, and
-v) switches.
discovery and startup events in the log file. Also enables
error logging.
The LonBridge Server uses this logging level as the default
unless you specify a different level with one of the log-level
command-line switches, or in the LonBridge configuration
file.
Mutually exclusive with the /D, /E, /N, and /V (-d, -e, -n, and
-v) switches.
/N -n Disables all event logging.
Mutually exclusive with the /D, /E, /G, and /V (-d, -e, -g, and v) switches.
/S Starts the LonBridge Server standalone so that it is not
running as a Windows service.
The LonBridge Server service must be stopped when the
LonBridge Server is run standalone. Running standalone
can be useful during development if you are enhancing the
Windows version of the LonBridge Server.
There is no Linux switch for this option.
/V -v Enables verbose logging; logs detailed events for messages
sent to and received by the LonBridge Server. Also enables
debug, error, and general logging.
You can use this option when porting or enhancing the
LonBridge Server software, especially if you are modifying
the network driver interface.
Mutually exclusive with the /D, /E, /G, and /N (-d, -e, -g, and
-n) switches.
LonBridge Server User’s Guide 7
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
information about this file.
The config.xml File
on page 11 for
8 Introduction
Configuring the LonBridge Server
This chapter describes how you can configure the LonBridge Server.
2
LonBridge Server User’s Guide 9
Configuring the LonBridge Server
For the LonBridge Server, you can specify the following configuration
information:
• The L
• The LAN Internet protocol (IP) address
• The LAN IP port
• The L
• The event logging level for the LonBridge Server
This information configures the communications for the LonBridge Server to be
able to communicate with the L
also configures L
You can specify this basic configuration information for the LonBridge Server
either by:
• Running the LonBridge Control utility – for Windows platforms only
• Modifying the LonBridge configuration file (config.xml) – for both
All configuration values have default values, so if you do not specify a configured
value, the LonBridge Server uses the default values described in
on page 11.
File
ONWORKS network interface
ONWORKS network variable polling interval
ONWORKS network and the TCP/IP network. It
ONWORKS polling and event logging.
(available only for accounts that are part of the administrators group)
Windows and Linux platforms
The LonBridge Control Utility
The config.xml
The LonBridge Control utility, shown in Figure 2 on page 11, is a Windows
application program that allows you to specify certain configuration and
operating parameters for the LonBridge Server software and control the
Windows service for the LonBridge Server. The LonBridge Control utility
maintains its settings in the LonBridge configuration file (config.xml).
Important: The LonBridge Control utility is available for Windows platforms
only. In addition, the LonBridge Control utility is a C# application and requires
the Microsoft .NET Framework 3.5 SP1. The Windows installer for the
LonBridge Server automatically installs the necessary .NET Framework.
10 Configuring the LonBridge Server
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.xml file while the LonBridge Server is
running, you must stop and restart the server for the changes to take effect.
For a standard installation, this file is in the Windows common application data
directory or the Linux configuration directory:
•For Windows XP: C:\Documents and Settings\All Users\Application
Data\Echelon\LonBridge
• For Windows Vista: C:\Program Data\Echelon\LonBridge
• For Linux: /etc/lonbridge
The default config.xml file contains the following information:
The <bridge> element defines the configuration, and is the top-most element
within the config.xml file.
The <bridge> element is required if any of the other child elements are
included, and only one <bridge> element is allowed per configuration file.
<autostart>
The <autostart> element specifies whether the service for the LonBridge
Server starts automatically when the operating system starts. Valid values
are true and false. The default value is true, which enables autostart.
This element applies only to the Windows platform.
<interface>
The <interface> element specifies the name of the network interface that the
LonBridge Server uses to communicate with the L
LonBridge Server uses LON1 as the default L
ONWORKS network. The
ONWORKS network interface.
This element applies only to the Windows platform.
For Linux platforms, the LonBridge Server uses a serial device name (such as
/dev/ttyS0) rather than a L
ONWORKS network interface.
<ip>
The <ip> element specifies the IP address for the LonBridge Server. By
default, the LonBridge Server uses the default IP address (0.0.0.0). This
default address enables the server to listen for IP connections on all IP
addresses for the server’s host computer.
If you specify a specific address (rather than the default), all LonBridge
remote clients must use the same address to communicate with the
LonBridge Server. However, if you specify the default address or 0.0.0.0,
remote clients can use any valid address for the host computer that is
running the LonBridge Server. Local clients can use the 127.0.0.1 loop-back
address.
<pollrate>
The <pollrate> element specifies the number of seconds between polls for
ONWORKS network variables. The LonBridge Server periodically polls the
L
network variables that are defined within the network. Valid values are
between 0 and 60. By default, the LonBridge Server uses a polling interval of
10 seconds.
Example: If the polling interval is 5 seconds per poll and there are 20
network variables to be polled, one network variable will be polled every 5
seconds, and it will take 100 seconds to poll all 20 network variables.
12 Configuring the LonBridge Server
<port>
The <port> element specifies the IP port for the LonBridge Server. By
default, the LonBridge Server uses the default IP port (3050).
<logging>
The <logging> 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. Also enables error
logging.
The LonBridge Server uses this logging level as the default unless
you specify a different level with one of the log-level command-line
switches, or in the LonBridge configuration file.
•Debug – 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.
•Verbose – Enables verbose logging; logs detailed events for messages
sent to and received by the LonBridge Server. Also enables debug,
error, and general logging.
You can use this option when porting or enhancing the LonBridge
Server software, especially if you are modifying the network driver
interface.
By default, the LonBridge Server uses general logging. However, if you start
the LonBridge Server from the command line and specify any of the event
logging switches (/D, /E, /G, /N, or /V for Windows, -d, -e, -g, -n, or -v for
Linux), the LonBridge Server uses the specified event logging level,
regardless of the event logging level specified in the configuration file.
The event log is named LonBridge.log. This file is created in the Windows
common application data directory or the Linux configuration directory.
In addition to the data within the LonBridge configuration file, the LonBridge
Server also provides two directories of XML files that describe L
devices that the LonBridge Server can manage: the Classes directory and the
Instances directory. You can find these directories in the same Windows common
application data directory or the Linux user directory as the config.xml file.
Classes Directory
The Classes directory contains XML files that describe the inputs and outputs for
specific classes of devices (such as Echelon Lamp Modules or Appliance Modules).
When the LonBridge Server discovers a new device, the LonBridge Server reads
ONWORKS
LonBridge Server User’s Guide 13
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
Each class file describes the device interface for a specific program ID, similar to
a LONWORKS device external interface (XIF) file. However, unlike XIF files, the
class files are XML files that identify only those network variables that the
LonBridge Server monitors or controls. That is, the class files do not necessarily
include all of the network variables that are available on the device. In addition,
the class files specify whether a network variable should be polled by or bound to
the LonBridge Server.
Instances Directory
on page 16).
A standard installation includes the class files listed in