Echelon SmartServer XMPP Client User Manual

SmartServer XMPP Client

Developer’s Guide

078-0471-01A

Echelon, LON, LONWORKS, LonTalk, Neuron, LONMARK, 3120,
3150, LNS, LonMaker, and the Echelon logo are trademarks
of Echelon Corporation registered in the United States and
other countries. LonPoint and LonSupport are trademarks of
Echelon Corporation.

Other brand and product names are trademarks or
registered trademarks of their respective holders.

Neuron

Chips, LonPoint Modules, 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 or LonPoint Modules 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 NO REPRESENTATION, WARRANTY, OR
CONDITION OF ANY KIND, EXPRESS, IMPLIED, STATUTORY, OR
OTHERWISE OR IN ANY COMMUNICATION WITH YOU,
INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OF
MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR ANY
PARTICULAR PURPOSE, NONINFRINGEMENT, AND THEIR
EQUIVALENTS.

No part of this publication may be reproduced, stored in a
retrieval system, or transmitted, in any form or by any means,
electronic, mechanical, photocopying, recording, or
otherwise, without the prior written permission of Echelon
Corporation.

Printed in the United States of America.
Copyright ©1997–2012 by Echelon Corporation.
Echelon Corporation
www.echelon.com

Table of Contents

Preface ..................................................................................................... v

Purpose .......................................................................................................... vi

Audience......................................................................................................... vi

Requirements ................................................................................................. vi

For More Information and Technical Support................................................. vi

1 Using SmartServer XMPP................................................................. 1

Introduction...................................................................................................... 2

Supported XMPP Protocol and Extensions .............................................. 2

BOSH ........................................................................................................ 3

Addressing ................................................................................................ 3

Creating an XMPP Solution............................................................................. 4

Step 1: Configuring an XMPP Server .......................................................4

Step 2: Configuring the SmartServer XMPP Client ..................................8

Step 3: Developing a Client Application.................................................. 12

XMPP Chat Client Example.............................................................. 12

SOAP/XMPP Example .....................................................................13

Getting More Information on XMPP Programming........................... 14

Step 4: Adding User Accounts to the XMPP Server ............................... 15

Step 5: Exchanging Data over XMPP ..................................................... 18

Running SmartServer-Pidgin XMPP Chat........................................ 18

Creating a Web Connection Over XMPP ......................................... 23

SmartServer XMPP Client Developer’s Guide iii

iv Preface

Preface

You can use the Extensible Messaging and Presence Protocol (XMPP) to enable

communication between SmartServers and client applications that reside behind

restrictive firewalls.

SmartServer XMPP Client Developer’s Guide v

Purpose

This document describes how to use XMPP to enable the SmartServer and client applications to
communicate bi-directionally when they are located behind firewalls.

Audience

This guide is intended for application developers creating SmartServer applications that run remotely
from the SmartServer, and that communicate with the SmartServer using SOAP over XMPP.

Requirements

Requirements for implementing a full XMPP solution are listed below:

• SmartServer 2.0 SP1 (Release 4.04.088) or newer.

• XMPP server. This document uses an ejabberd XMPP server, which is required if your

SmartServer’s firmware version is 4.04.088. You can use any XMPP compliant server if your
SmartServer’s firmware version is 4.04 .1 1 9 or newer .

• XMPP client application. This document is for software developers creating the XMPP client
application. The examples in this document use the Pidgin messaging client to demonstrate an
XMPP client application.

For More Information and Technical Support

If you have technical questions that are not answered by this document, you can contact technical
support. Free e-mail support is available or you can purchase phone support from Echelon or an
Echelon support partner. See
training services.

You can also view free online training or enroll in training classes at Echelon or an Echelon training
center to learn more about developing devices. You can find additional information about device
development training at

You can obtain technical support via phone, fax, or e-mail from your closest Echelon support center.
The contact information is as follows (check
information):

Region Languages Supported Contact Information
The Americas

www.echelon.com/support for more information on Echelon support and

www.echelon.com/training.

www.echelon.com/support for updates to this

English
Japanese

Echelon Corporation
Attn. Customer Support
550 Meridian Avenue
San Jose, CA 95126
Phone (toll-free):

1.800-258-4LON (258-4566)
Phone: [phone]
Fax: [phone]

[e-mail]

vi Preface

Region Languages Supported Contact Information
Europe

English
German
French
Italian

Echelon Europe Ltd.
Suite 12
Building 6
Croxley Green Business Park
Hatters Lane
Watford
Hertfordshire WD18 8YH
United Kingdom
Phone: [phone]
Fax: [phone]

[e-mail]

Japan

China

Other Regions

Japanese Echelon Japan

Holland Hills Mori Tower, 18F
5-11.2 Toranomon, Minato-ku
Tokyo 105-0001
Japan
Phone: [phone]
Fax: [phone]

[e-mail]

Chinese
English

Echelon Greater China
Rm. 1007-1008, IBM Tower
Pacific Century Place
2A Gong Ti Bei Lu
Chaoyang District
Beijing 100027, China
Phone: [phone]
Fax: [phone]

[e-mail]

English
Japanese

Phone: [phone]
Fax: [phone]

[e-mail]

SmartServer XMPP Client Developer’s Guide vii

viii Preface

1

Using SmartServer XMPP

This chapter summarizes how the SmartServer and client applications can exchange

data using XMPP.

SmartServer XMPP Client Developer’s Guide 1

Introduction

You can use the Extensible Messaging and Presence Protocol (XMPP) to enable SmartServers and
client applications to exchange data when firewalls prevent bi-directional communication. XMPP is an
open technology for real-time communication that provides a decentralized client-server architecture.
XMPP facilitates simple client-to-client communication where clients may reside behind different
firewalls, which are typically configured to allow outgoing connections, but block incoming
connections. With XMPP, SmartServers and client applications function as clients to a shared XMPP
server. In this case, the client-XMPP connections are outgoing and therefore allowed by firewalls—
without opening any ports or creating any special firewall configurations.

The SmartServer includes a built-in XMPP client that enables it communicate bi-directionally with a
client application. Client applications for the SmartServer are typically enterprise applications such as
energy management, demand response, or supervisory control applications. Both the SmartServer and
the client application may be behind different firewalls, and the firewalls only need to support
outbound access to the XMPP server. The XMPP server may be on the same server as the client site,
or it may be running on a separate server either at the same location or at a remote site. The following
figure illustrates a typical system using a SmartServer with XMPP to communicate with an
XMPP-enabled client application at a network operations center (NOC).

Supported XMPP Protocol and Extensions

XMPP is defined by base protocol and a number of optional protocol extensions for supporting
different types of clients and applications. The base protocol and the extensions supported by
the SmartServer are defined at the following locations:

xmpp.org/xmpp-protocols/xmpp-core/

•

xmpp.org/protocols/

•

xmpp.org/extensions/xep-0124.html

•

xmpp.org/extensions/xep-0206.html

•

xmpp.org/extensions/xep-0072.html

•

xmpp.org/extensions/xep-0060.html

•

Additional XMPP extensions are listed at the following location:

xmpp.org/xmpp-protocols/xmpp-extensions/

•

2 Using SmartServer XMPP

The SmartServer supports the following XMPP extensions:

Bidirectional-streams Over
Synchronous HTTP
(BOSH, XEP-0124)

XMPP over BOSH (XEP-

0206)
SOAP over XMPP (XEP-

0072)

Specifies how a binary stream of data can be carried on the HTTP
protocol. XMPP uses a connection method that does not require a
client to maintain a long-lived TCP connection.

BOSH emulates a bidirectional streams that are similar to TCP
binding, but implemented efficiently using multiple, synchronous
HTTP or HTTPS request/response pairs.

Specifies how XMPP can be implemented over a BOSH
connection.

Specifies how SOAP messaging can be performed over XMPP.
The SmartServer uses SOAP for communicating with client
applications.

BOSH

BOSH is used by both the SmartServer and client applications to exchange data. BOSH-based systems
are usually deployed with a special connection manager that acts as a proxy between a client and the
XMPP Server. If a client resides behind a restrictive firewall, it has to be configured to use a BOSH
connection manager. The BOSH connection manager may be implemented on the same server with
the XMPP server, and many XMPP server implementations include an embedded BOSH connection
manager.

The client starts an XMPP session with the XMPP server by sending an initial HTTP or HTTPS
request to the BOSH connection manager. The BOSH connection manager then opens a regular
XMPP connection to the XMPP server, forwards the request, and receives an XMPP reply, which it
forwards to the client in an HTTP or HTTPS response. The client then authenticates with the XMPP
server. After the client has successfully authenticated with the XMPP server, it is ready for
communication.

During the client’s initial request, BOSH properties are used to drive the communication with the
BOSH connection manager, including the number of HTTP connections to use and a request timeout.
The value of the timeout property is determined by the client. When the client does not send or receive
any XMPP message for longer than the timeout period, the BOSH connection manager sends
keep-alive messages to the client if the timeout period is about to expire. If the client does not have
anything to send to the XMPP server, then the client also sends a keep-alive message with the defined
timeout. The client and the BOSH connection manager keep sending these keep-alive messages every
timeout interval until either the BOSH connection manager receives data for the client and returns it in
the response’s body, or the client sends new data within the request’s body.

Addressing

Each XMPP client (SmartServer or client application) requires a unique address, called a
Jabber ID (JID), which has the following format: [<userName>]@<hostname>/[<resource>=].
The following table describes each components of the JID:

userName Identifies a user name registered with the XMPP server. XMPP

clients can use the user name of any user configured on the
XMPP server. For SmartServer clients, you can use the MAC
IDs as the userName to distinguish multiple SmartServer clients
more easily.

hostname The hostname of the XMPP server. This may be the same as

the domain name of the XMPP server host, or it may be a
different name specified in the XMPP server configuration.

resource Identifies a specific client belonging to the user (for example

SmartServer XMPP Client Developer’s Guide 3