Echelon LonTal Stack User Manual

LonTalk® Stack

Developer's Guide

078-0483-01A

Echelon, LONWORKS, LONMARK, NodeBuilder, LonTalk, Neuron, 3120, 3150, LNS, ShortStack, and the Echelon logo are trademarks of Echelon Corporation registered in the United States and other countries. OpenLDV and LonScanner are trademarks of Echelon Corporation.

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

Smart Transceivers, Neuron Chips, and other OEM Products were not designed for use in equipment or systems, which involve danger to human health or safety, or a risk of property damage and Echelon assumes no responsibility or liability for use of the Smart Transceivers, Neuron Chips, and other OEM Products in such applications.

Parts manufactured by vendors other than Echelon and referenced in this document have been described for illustrative purposes only, and may not have been tested by Echelon. It is the responsibility of the customer to determine the suitability of these parts for each application.

ECHELON MAKES AND YOU RECEIVE NO WARRANTIES OR CONDITIONS, EXPRESS, IMPLIED, STATUTORY OR IN ANY COMMUNICATION WITH YOU, AND ECHELON SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

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

Printed in the United States of America.

Copyright © 2012 Echelon Corporation.

Echelon Corporation www.echelon.com

Table of Contents
Welcome.........................................................................................................	ix
Audience ........................................................................................................	ix
Related Documentation ................................................................................	ix
1 Introduction to LonTalk Stack ...............................................................	1
Overview.........................................................................................................	2
A LONWORKS Device with a Single Processor Chip ..............................	3
A LONWORKS Device with Two Processor Chips ...................................	4
ShortStack Developer’s Kit ..............................................................	4
LonTalk Stack Developer’s Kit.........................................................	6
Comparing Neuron-Hosted, ShortStack, and LonTalk Stack
Devices......................................................................................................	7
Requirements and Restrictions for LonTalk Stack......................................	9
Development Tools for LonTalk Stack........................................................	10
LonTalk Stack Architecture ........................................................................	10
Overview of the LonTalk Stack Development Process ..............................	12
2 Getting Started with the LonTalk Stack Developer’s Kit ..............	19
LonTalk Stack Overview .............................................................................	20
Installing the LonTalk Stack Developer’s Kit............................................	20
Hardware Requirements.......................................................................	20
Software Requirements.........................................................................	20
Installing the LonTalk Stack Developer’s Kit .....................................	21
LonTalk Stack Files .....................................................................................	21
LonTalk Interface Developer.......................................................................	21
Example LonTalk Stack Applications ........................................................	22
3 Loading the Echelon Smart Transceiver or Neuron Chip .............	25
Loading Overview ........................................................................................	26
Integrating a Custom Network Interface...................................................	28
Defining Incoming Layer 2 Packet Buffers..........................................	29
Functions................................................................................................	29
4 Designing the Serial I/O Hardware Interface ...................................	31
Overview of the Hardware Interface ..........................................................	32
Reliability...............................................................................................	32
Serial Communication Lines ................................................................	32
The RESET~ Pin ...................................................................................	33
Selecting the Link-Layer Bit Rate........................................................	34
Host Latency Considerations................................................................	36
SCI Interface ................................................................................................	36
Performing an Initial Echelon Smart Transceiver Health Check ............	37
5 Creating a LonTalk Stack Serial MIP Driver....................................	39
Overview of the Link Layer Protocol ..........................................................	40
Code Packet Layout...............................................................................	40
Type Code Values............................................................................	42
Acknowledgment Rules ..................................................................	44
Sequence Number Cycling and Duplicate Detection ....................	45
Supported MIP Command Set..............................................................	45
Layer 2 / Layer 5 Modes........................................................................	46
Product Query Network Management .................................................	47

LonTalk Stack Developer’s Guide

iii

Serial MIP Driver Example.........................................................................	47
Serial MIP Driver API .................................................................................	47
Structures ..............................................................................................	47
Functions................................................................................................	48
6 Creating a Model File ..............................................................................	51
Model File Overview ....................................................................................	52
Defining the Device Interface......................................................................	53
Defining the Interface for a LonTalk Stack Application.....................	53
Choosing the Data Type .................................................................	54
Defining a Functional Block .................................................................	55
Declaring a Functional Block.........................................................	56
Defining a Network Variable................................................................	56
Defining a Changeable-Type Network Variable ...........................	58
Defining a Configuration Property.......................................................	59
Declaring a Configuration Property ..............................................	59
Responding to Configuration Property Value Changes................	62
Defining a Configuration Property Array .....................................	62
Sharing a Configuration Property .................................................	64
Inheriting a Configuration Property Type ....................................	66
Declaring a Message Tag ......................................................................	67
Defining a Resource File .......................................................................	68
Implementation-Specific Scope Rules............................................	70
Writing Acceptable Neuron C Code ............................................................	70
Anonymous Top-Level Types ................................................................	71
Legacy Neuron C Constructs ................................................................	71
Using Authentication for Network Variables ............................................	71
Specifying the Authentication Key.......................................................	72
How Authentication Works...................................................................	73
Managing Memory .......................................................................................	74
Address Table ........................................................................................	74
Alias Table .............................................................................................	75
Domain Table.........................................................................................	75
Network Variable Configuration Table................................................	76
Example Model files.....................................................................................	76
Simple Network Variable Declarations ...............................................	76
Network Variables Using Standard Types ..........................................	76
Functional Blocks without Configuration Properties .........................	77
Functional Blocks with Configuration Network Variables.................	78
Functional Blocks with Configuration Properties Implemented
in a Configuration File ..........................................................................	79
7 Using the LonTalk Interface Developer Utility................................	81
Running the LonTalk Interface Developer.................................................	82
Specifying the Project File ....................................................................	82
Specifying the Echelon Smart Transceiver or Neuron Chip
Configuration .........................................................................................	83
Configuring the LonTalk Stack ............................................................	84
Configuring the Buffers ........................................................................	85
Configuring the Application..................................................................	86
Configuring Support for Non-Volatile Data.........................................	87
Specifying the Device Program ID .......................................................	88
Specifying the Model File......................................................................	89
Specifying Neuron C Compiler Preferences.........................................	90

iv

Specifying Code Generator Preferences...............................................	91
Compiling and Generating the Files ....................................................	92
Using the LonTalk Interface Developer Files ............................................	93
Copied Files............................................................................................	94
LonNvTypes.h and LonCpTypes.h .......................................................	94
FtxlDev.h................................................................................................	95
FtxlDev.c ................................................................................................	95
project.xif and project.xfb......................................................................	95
Using Types..................................................................................................	95
Bit Field Members .................................................................................	97
Enumerations ........................................................................................	98
Floating Point Variables .......................................................................	98
Network Variable and Configuration Property Declarations .................	100
Constant Configuration Properties...........................................................	102
The Network Variable Table .....................................................................	103
Network Variable Attributes ..............................................................	103
The Message Tag Table .............................................................................	104
8 Developing a LonTalk Stack Device Application...........................	105
Overview of a LonTalk Stack Device Application....................................	106
Using the LonTalk API .......................................................................	106
Callbacks and Events..........................................................................	108
Integrating the Application with an Operating System ...................	108
Providing Persistent Storage for Non-Volatile Data.........................	109
Restoring Non-Volatile Data ........................................................	110
Writing Non-Volatile Data ...........................................................	111
Tasks Performed by a LonTalk Stack Application ..................................	112
Initializing the LonTalk Stack Device ...............................................	113
Periodically Calling the Event Pump.................................................	113
Sending a Network Variable Update .................................................	115
Receiving a Network Variable Update from the Network................	117
Handling a Network Variable Poll Request from the Network........	120
Handling Changes to Changeable-Type Network Variables............	120
Validating a Type Change ............................................................	121
Processing a Type Change............................................................	122
Processing a Size Change .............................................................	123
Rejecting a Type Change ..............................................................	124
Handling Dynamic Network Variables..............................................	124
Communicating with Other Devices Using Application
Messages ..............................................................................................	125
Sending an Application Message to the Network .......................	126
Receiving an Application Message from the Network................	126
Handling Management Commands....................................................	126
Handling Local Network Management Tasks ...................................	127
Handling Reset Events........................................................................	127
Querying the Error Log.......................................................................	127
Working with ECS Devices........................................................................	127
Using Direct Memory Files........................................................................	128
The DMF Memory Window.................................................................	129
File Directory .......................................................................................	130
Shutting Down the LonTalk Stack device................................................	131
9 Developing an IP-852 Router Application........................................	133
Developing an IP-852 Router Application ................................................	134

LonTalk Stack Developer’s Guide

v

	LtLogicalChannel ................................................................................	134
	LtIp852Router .....................................................................................	134
10	Porting a LonTalk Stack Application .........................................	137
	Porting Overview .......................................................................................	138
	OSAL ....................................................................................................	138
	LonLink Driver ....................................................................................	138
	Service LED .........................................................................................	139
	Socket Interfaces .................................................................................	139
	LonTalkStack Source Files .................................................................	139
	Application-Specific Files for LonTalk Stack Devices.......................	141
	Application-Specific Code for IP-852 Interfaces.......................................	141
	Selecting the Device Type..........................................................................	141
	File System Requirements ........................................................................	142
Appendix A LonTalk Interface Developer Command Line
Usage ................................................................................................................		143
	Overview.....................................................................................................	144
	Command Usage ........................................................................................	144
	Command Switches....................................................................................	145
	Specifying Buffers................................................................................	147
Appendix B Model File Compiler Directives .......................................		151
	Using Model File Compiler Directives......................................................	152
	Acceptable Model File Compiler Directives..............................................	152
Appendix C Neuron C Syntax for the Model File................................		157
	Functional Block Syntax............................................................................	158
	Keywords..............................................................................................	158
	Examples..............................................................................................	160
	Functional Block Properties Syntax .........................................................	161
	Keywords..............................................................................................	161
	Examples..............................................................................................	162
	Network Variable Syntax ..........................................................................	164
	Keywords..............................................................................................	164
	The Network Variable Modifier ...................................................	164
	The Network Variable Storage Class ..........................................	166
	The Network Variable Type .........................................................	166
	The Network Variable Connection Information .........................	167
	The Network Variable Initializer.................................................	170
	The Network Variable Property List ...........................................	170
	Configuration Property Syntax .................................................................	171
	Keywords..............................................................................................	171
	The Configuration Property Type ................................................	172
	The Configuration Property Modifiers ........................................	172
	The Configuration Property Initializer .......................................	174
	Declaring a Configuration Network Variable....................................	175
	Defining a Device Property List .........................................................	175
	Message Tag Syntax ..................................................................................	177
	Keywords..............................................................................................	177
Appendix D LonTalk API ..........................................................................		179
	Introduction................................................................................................	180
	The LonTalk API, Event Handler Functions, and Callback Handler
	Functions ....................................................................................................	180

vi

LonTalk API Functions.......................................................................	180
Commonly Used LonTalk API Functions....................................	181
Other LonTalk API Functions......................................................	181
Application Messaging API Functions ........................................	182
Non-Volatile Data API Functions ................................................	182
Extended API Functions...............................................................	183
Event Handler Functions....................................................................	184
Commonly Used Event Handler Functions.................................	184
Dynamic Network Variable Event Handler Functions ..............	185
Application Messaging Event Handler Functions ......................	186
Non-Volatile Data Event Handler Functions..............................	186
LonTalk Stack Callback Handler Functions .....................................	187
Commonly Used Callback Handler Functions ............................	187
Direct Memory Files Callback Handler Functions .....................	188
Non-Volatile Data Callback Handler Functions.........................	188
The Operating System Abstraction Layer................................................	189
Managing Critical Sections.................................................................	190
Managing Binary Semaphores ...........................................................	190
Managing Operating System Events .................................................	190
Managing System Timing ...................................................................	191
Managing Operating System Tasks ...................................................	191
Debugging Operating System Functions ...........................................	191
Appendix E Determining Memory Usage for LonTalk Stack
Applications....................................................................................................	193
Overview.....................................................................................................	194
Memory Use for Code ..........................................................................	194
Memory Use for Transactions.............................................................	194
Memory Use for Buffers ......................................................................	195
Memory for LONWORKS Resources .....................................................	195
Memory for Non-Volatile Data ...........................................................	196
Memory Usage Examples for Data.....................................................	198
Appendix F Downloading a LonTalk Stack Application Over
the Network....................................................................................................	201
Overview.....................................................................................................	202
Custom Application Download Protocol ...................................................	202
Application Download Utility....................................................................	203
Download Capability within the Application ...........................................	203
Appendix G Example LonTalk Stack Applications ............................	205
Overview of the Example Applications.....................................................	206
Building the Example Applications....................................................	207
Running the Examples........................................................................	207
Running the SimpleLtDevice Example .......................................	208
Running the SimpleIp852Device Example..................................	208
Running the Ip852Router Example.............................................	208
SimpleLtDevice and SimpleIp852Device Example Application
Details.........................................................................................................	208
Main Function......................................................................................	209
Application Task Function..................................................................	211
Event Handler Function .....................................................................	212
Application-Specific Utility Functions ...............................................	213
Callback Handler Function.................................................................	213

LonTalk Stack Developer’s Guide

vii

Model File.............................................................................................	214
Extending the SimpleLtDevice and SimpleIp852 Examples............	214
IP-852 Router Example Application Details ............................................	215
Appendix H LonTalk Interface Developer Utility Error and
Warning Messages.........................................................................................	219
Introduction................................................................................................	220
Error Messages...........................................................................................	220
Warning Codes ...........................................................................................	226
Hint Codes ..................................................................................................	228
Appendix I Glossary ...................................................................................	231

viii

Welcome

Echelon’s LonTalk® Stack enables you to add a high-performance ISO/IEC 14908-1 control networking interface to any product that contains a microprocessor, microcontroller, or embedded processor. The LonTalk Stack includes a simple host application programming interface (API), a complete ISO/IEC 14908-1 protocol stack implementation, a link-layer driver, a simple hardware interface, and comprehensive tool support.

This document describes how to port the LonTalk Stack to your processor and how to develop an application for a LONWORKS device using the LonTalk Stack. It describes the architecture of a LonTalk Stack device, and how to develop the device’s software. Software development of a LonTalk Stack device includes creating a model file, running the LonTalk Interface Developer utility, and using the LonTalk Stack API functions to program your LonTalk Stack application for the host processor.

Audience

This document assumes that the reader has a good understanding of the LONWORKS platform and programming for embedded processors.

Related Documentation

In addition to this manual, the LonTalk Stack documentation suite includes the following manuals:

•Neuron C Programmer’s Guide. This manual describes the key concepts of programming using the Neuron® C programming language and describes how to develop a LONWORKS application.

•Neuron C Reference Guide. This manual provides reference information for writing programs that use the Neuron C language.

•Neuron Tools Errors Guide. This manual describes error codes issued by the Neuron C compiler.

The LonTalk Stack also includes the reference documentation for the LonTalk API, which is delivered as a set of HTML files.

After you install the LonTalk Stack software, you can view these documents from the Windows Start menu: select Programs → Echelon LonTalk Stack Developer’s Kit, and then select the document that you want to view.

The following manuals are available from the Echelon Web site (www.echelon.com/docs) and provide additional information that can help you develop LONWORKS applications:

•Introduction to the LONWORKS Platform. This manual provides an introduction to the ISO/IEC 14908 1 Control Network Protocol, and provides a high-level introduction to LONWORKS networks and the tools and components that are used for developing, installing, operating, and maintaining them.

LonTalk Stack Developer’s Guide

ix

•LONMARK® Application Layer Interoperability Guidelines. This manual describes design guidelines for developing applications for open interoperable LONWORKS devices, and is available from the LONMARK Web site, www.lonmark.org.

•FT 3120 / FT 3150 Echelon Smart Transceiver Data Book. This manual provides detailed technical specifications on the electrical interfaces, mechanical interfaces, and operating environment characteristics for the FT 3120 and FT 3150® Echelon Smart Transceivers.

•PL 3120®/PL 3150®/PL 3170™ Power Line Smart Transceiver Data Book. Provides detailed technical specifications on the electrical interfaces, mechanical interfaces, and operating environment characteristics for the PL 3120®, PL 3150® and PL 3170™ Power Line Smart Transceivers. This data book also provides guidelines for migrating applications to the PL Smart Transceiver using the NodeBuilder® FX Development Tool, the Mini FX Evaluation Kit, or the ShortStack® Developer’s Kit.

•Series 5000 Chip Data Book. Provides detailed specifications on the electrical interfaces, mechanical interfaces, and operating environment characteristics for the FT 5000 Smart Transceiver and Neuron 5000 Processor.

•OpenLNS Commissioning Tool User’s User's Guide. This manual describes how to use the OpenLNS Commissioning Tool to design, commission, monitor and control, maintain, and manage a network.

All of the LonTalk Stack documentation, and related product documentation, is available in Adobe® PDF format. To view the PDF files, you must have a current version of the Adobe Reader®, which you can download from Adobe at: http://get.adobe.com/reader/.

x

LonTalk Stack Developer’s Guide

xi

1

Introduction to LonTalk Stack

This chapter introduces LonTalk Stack for embedded processors. It describes the architecture of a LonTalk Stack device, including a comparison with other LONWORKS device development solutions. It also describes attributes of a LonTalk Stack device, and the requirements and restrictions of the LonTalk Stack.

LonTalk Stack Developer’s Guide

1

Overview

Automation solutions for buildings, homes, utility, transportation, and industrial applications include sensors, actuators, and control systems. A LONWORKS network is a peer-to-peer network that uses an international-standard control network protocol for monitoring sensors, controlling actuators, communicating with devices, and managing network operation. In short, a LONWORKS network provides communications and complete access to control network data from any device in the network.

The communications protocol used for LONWORKS networks is the ISO/IEC 14908-1 Control Network Protocol. This protocol is an international standard seven-layer protocol that has been optimized for control applications and is based on the Open Systems Interconnection (OSI) Basic Reference Model (the OSI Model, ISO standard 7498-1). The OSI Model describes computer network communications through seven abstraction layers. The implementation of these seven layers in a LONWORKS device provides standardized interconnectivity for devices within a LONWORKS network. The following table summarizes the CNP layers.

OSI Layer		Purpose	Services Provided
7	Application	Application compatibility	Network configuration, self-installation,
			network diagnostics, file transfer,
			application configuration, application
			specification, alarms, data logging,
			scheduling
6	Presentation	Data interpretation	Network variables, application messages,
			foreign frame transmission
5	Session	Control	Request/response, authentication
4	Transport	End-to-end	Acknowledged and unacknowledged
		communication reliability	message delivery, common ordering,
			duplicate detection
3	Network	Destination addressing	Unicast and multicast addressing,
			routers
2	Data Link	Media access and framing	Framing, data encoding, CRC error
			checking, predictive carrier sense
			multiple access (CSMA), collision
			avoidance, priority, collision detection
1	Physical	Electrical interconnect	Media-specific interfaces and modulation
			schemes

Echelon’s implementation of the ISO/IEC 14908-1 Control Network Protocol is called the LonTalk protocol. Echelon has implementations of the LonTalk protocol in several product offerings, including the Neuron firmware (which is included in a ShortStack® Micro Server), OpenLNS Server, SmartServers, i.LON

2	Introduction to the LonTalk Stack

600 IP-852 Routers, and the LonTalk Stack. This document refers to the ISO/IEC 14908-1 Control Network Protocol as the LonTalk protocol, although other interoperable implementations exist.

A LONWORKS Device with a Single Processor Chip

A basic LONWORKS device consists of four primary components:

1.An application processor that implements the application layer, or both the application and presentation layers, of the LonTalk protocol.

2.A protocol engine that implements layers 2 through 5 (or 2 through 7) of the LonTalk protocol.

3.A network transceiver that provides the physical interface for the LONWORKS network communications media, and implements the physical layer of the LonTalk protocol.

4.Circuitry to implement the device I/O.

These components can be combined in a physical device. For example, an Echelon Smart Transceiver product can be used as a single-chip solution that combines all four components in a single chip. When used in this way, the Echelon Smart Transceiver runs the device’s application, implements the LonTalk protocol, and interfaces with the physical communications media through a transformer. The following figure shows the seven-layer LonTalk protocol on a single Neuron Chip or Echelon Smart Transceiver.

Traditional single-chip approach (Neuron Chip or Smart Transceiver)

Application layer

Presentation layer

Session layer

Transport layer

Network layer

Data link layer

Neuron C

Application

(NodeBuilder FX,

Mini Kit)

re a w m r i F n o r u e N

	Physical layer	Transceiver and
		wiring

LonTalk Stack Developer’s Guide

3

A LONWORKS device that uses a single processor chip is called a Neuron-hosted device, which means that the Neuron-based processor (the Echelon Smart Transceiver) runs both the application and the LonTalk protocol.

For a Neuron-hosted device that uses a Neuron Chip or Echelon Smart Transceiver, the physical layer (layer 1) is handled by the Neuron Chip or Echelon Smart Transceiver. The middle layers (layers 2 through 6) are handled by the Neuron firmware. The application layer (layer 7) is handled by your Neuron C application program. You can create the application program using the Neuron C programming language in either the NodeBuilder® FX Development Tool or the Mini FX.

A LONWORKS Device with Two Processor Chips

Some LONWORKS devices run applications that require more memory or processing capabilities than a single Neuron Chip or Echelon Smart Transceiver can provide. Other LONWORKS devices are implemented by adding a transceiver to an existing processor and application. For these applications, the device uses two processor chips working together:

•An Echelon Smart Transceiver or Neuron Chip.

•A microprocessor, microcontroller, or embedded processor. This is typically called the host processor.

A LONWORKS device that uses two processor chips is called a host-based device, which means that the device includes an Echelon Smart Transceiver or Neuron Chip plus a host processor.

Compared to the single-chip device, the Echelon Smart Transceiver or Neuron Chip implements only a subset of the LonTalk protocol layers. The host processor implements the remaining layers and runs the device’s application program. The Echelon Smart Transceiver or Neuron Chip and the host processor communicate with each other through a link-layer interface.

For a single-chip, Neuron-hosted, device you write the application program in Neuron C. For a host-based device, you write the application program in ANSI C, C++, or other high-level language, using a common application framework and application programming interface (API). This API is called the LonTalk API. In addition, for a host-based device, you select a suitable host processor and use the host processor’s application development environment, rather than the NodeBuilder FX Development Tool or the Mini FX application, to develop the application.

Echelon provides the following solutions for creating host-based LONWORKS devices:

•ShortStack Developer’s Kit

•LonTalk Stack Developer’s Kit

ShortStack Developer’s Kit

The ShortStack Developer’s Kit is a set of development tools, APIs, and firmware for developing host-based LONWORKS devices that use the LonTalk Compact API and a ShortStack Micro Server.

4	Introduction to the LonTalk Stack

A ShortStack Micro Server is an Echelon Smart Transceiver or Neuron Chip with ShortStack firmware that implements layers 2 to 5 (and part of layer 6) of the LonTalk protocol. The host processor implements the application layer (layer 7) and part of the presentation layer (layer 6). The Echelon Smart Transceiver or Neuron Chip provides the physical interface for the LONWORKS communications channel. The ShortStack firmware allows you to use almost any host processor for your device’s application and I/O. The following figure displays the ShortStack solution for a host-based LONWORKS device.

A simple serial communications interface provides communications between the ShortStack Micro Server and the host processor. Because a ShortStack Micro Server can work with any host processor, you must provide the serial driver implementation, although Echelon does provide the serial driver API and an example driver for some host processors. An example driver is available for an Atmel® ARM7 microprocessor.

Host Processor

Application

LonTalk API

ISO/IEC 14908-1

Layer 7

Serial I/O Driver

Smart Transceiver

ShortStack

ISO/IEC 14908-1

Layers 2 – 6

ISO/IEC 14908-2 or 3

Layer 1 PHY

Communications Channel

For ShortStack device development, you use the C or C++ programming language. Alternatively, you can develop ShortStack devices using any programming language supported by the host processor if you port the LonTalk Compact API and the application framework generated by the LonTalk Interface Developer utility to that language.

You use the Echelon LonTalk Interface Developer (LID) utility to create the application framework. Your application uses the Echelon LonTalk Compact

LonTalk Stack Developer’s Guide

5

API, which is an ANSI C API, to manage communications with the ShortStack Micro Server and devices on the LONWORKS network.

LonTalk Stack Developer’s Kit

The LonTalk Stack Developer’s Kit is a set of development tools, APIs, and firmware for developing host-based LONWORKS devices that use the Echelon Smart Transceiver or Neuron Chip, a Layer 2 Microprocessor Interface Program (MIP), and the LonTalk API. You can also use the LonTalk Stack to create controllers that are attached to IP-852 channels, and IP-852 routers that route packets between IP-852 and native LonTalk channels.

The Echelon Smart Transceiver or Neuron Chip includes Neuron firmware that implements the data link layer (layer 2) of the LonTalk protocol. The LonTalk Stack provides a Layer 2 MIP that transforms the Echelon Smart Transceiver or Neuron Chip into a network interface that can transmit and receive any packet from the host processor. The LonTalk Stack includes source code that implements layers 3 to 6 and part of layer 7 of the LonTalk protocol that you port to your host processor. The LonTalk Stack also includes a LonTalk API implementation that you port to your host processor that you integrate with your application. This solution enables you to develop high-performance controllers with up to 4,096 network variables and 32,767 address table entries.

Host Processor

Application

LonTalk API

ISO/IEC 14908-1

Layers 3 – 7

With ECS

Serial I/O Driver

Smart Transceiver

Layer 2 MIP

ISO/IEC 14908-1

Layer 2

ISO/IEC 14908-2 or 3

Layer 1 PHY

Communications Channel

To develop the application for your host processor, you use a C or C++ compiler that supports the embedded processor. You will use the Echelon LonTalk Interface Developer utility to create the application framework, and then you can

6	Introduction to the LonTalk Stack

develop your application using the Echelon LonTalk API to manage communications between the LonTalk Host stack, Echelon Smart Transceiver or Neuron Chip, and other LONWORKS devices on the network.

The LonTalk Stack includes an example communications interface driver for the serial link layer that manages communications between the LonTalk Host stack within the host processor and the Echelon Smart Transceiver or Neuron Chip with Layer 2 MIP. You need to include the physical implementation of the serial link layer in your LonTalk Stack device design, and you need to create the software implementation of the serial interface driver.

Comparing Neuron-Hosted, ShortStack, and LonTalk

Stack Devices

The following table compares some of the key characteristics of the

Neuron-hosted and host-based solutions for LONWORKS devices.

	Neuron-Hosted	ShortStack
Characteristic	Solution	FX	LonTalk Stack
Maximum	254	254 [1]	4096
number of
network
variables
Maximum	254	127 [2]	8192
number of aliases
Maximum	15	15	32767
number of
addresses
Maximum	0	0	4096
number of
dynamic network
variables
Maximum	16	16	32767
number of receive
transaction
records
Maximum	2	2	32767
number of
transmit
transaction
records
Support for the	No	No	Yes [3]
LonTalk
Extended
Command Set

LonTalk Stack Developer’s Guide

7

File access	FTP [4] , DMF	FTP [4], DMF	FTP [4], DMF [5]
methods
supported
Link-layer type	N/A	4- or 5-line		2-line SCI
		SCI
		or
		6- or 7-line SPI
Typical host API	N/A	5-6 KB code
runtime footprint		with 1 KB		Native LonTalk	850 KB
		RAM (includes		protocol stack.
		serial driver,		Includes LonTalk
		but does not
				API, Linux Serial
		include
				MIP driver, and the
		optional API
				SimpleDevice
		or ISI API)
				example application.
				IP-852 LonTalk
					955 KB
				protocol stack.
				Includes LonTalk
				API, Linux Serial
				MIP driver, and the
				SimpleIp852Device
				example application.
				Native LonTalk to
					965 KB
				IP-852 Router.
				Includes Linux Serial
				MIP driver, and the
				Ip852Router example
				application.
Host processor	N/A	Any 8-, 16-,		Any 32or 64-bit microprocessor or
type		32-, or 64-bit		microcontroller
		microprocessor
		or
		microcontroller
Application	Neuron C	Any (typically		ANSI C or C++ for the embedded
development		ANSI C)		processor
language

8	Introduction to the LonTalk Stack

Notes:

1.ShortStack Micro Servers running on FT 3150 or PL 3150 Echelon Smart Transceivers support up to 254 network variables. ShortStack Micro Servers running on FT 3120 Echelon Smart Transceivers support up to 240 network variables, and ShortStack Micro Servers running on PL 3120 Echelon Smart Transceivers support up to 62 network variables. A custom Micro Server can support up to 254 network variables, depending on available resources.

2.ShortStack Micro Servers running on FT 3150 or PL 3150 Echelon Smart Transceivers support up to 127 aliases. ShortStack Micro Servers running on FT 3120 Echelon Smart Transceivers support up to 120 aliases. ShortStack Micro Servers running on PL 3120 Echelon Smart Transceivers support up to 62 aliases. A custom Micro Server can support up to 127 aliases, depending on available resources.

3.See the ISO/IEC 14908-1 Control Network Protocol Specification for more information about the extended command set (ECS) network management commands. This document is available from ISO: www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=60203

4.An implementation of the LONWORKS file transfer protocol (FTP) is not provided with the product.

5.For more information about the direct memory files (DMF) feature, see Using Direct Memory Files.

The LonTalk Stack solution provides support for any host processor with the highest performance and highest network capacity, and it can be used on native LONWORKS and IP-852 channels. The ShortStack solution provides support for any host processor, and supports TP/FT-10 and PL-20 channels. The ShortStack solution supports fewer network variables and aliases that the LonTalk Stack solution.

Requirements and Restrictions for LonTalk Stack

The LonTalk Stack requires that the application on the host processor use either an embedded operating system or software that implements a minimum set of operating system services.

The LonTalk Stack require about 850 KB of program memory on the host processor, not including the application program or the operating system. In addition, you must provide sufficient additional non-volatile memory for device configuration data and any non-volatile data that you include in your application.

You can implement configuration properties as configuration network variables or in configuration files. To access configuration files, you can implement the LONWORKS file transfer protocol (FTP) or use the direct memory files (DMF) feature. See Using Direct Memory Files for more information about when to use FTP or the DMF feature.

LonTalk Stack Developer’s Guide

9

Development Tools for LonTalk Stack

To develop an application for a device that uses the LonTalk Stack, you need a development system for the host processor. In addition, you need the LonTalk Stack Developer’s Kit, which includes:

•LonTalk API

•LonTalk Host Stack

•LonTalk Interface Developer utility for defining the interface for your LonTalk Stack device and generating the application framework

•Example LonTalk Stack applications

If you are not using an FT 5000 Smart Transceiver with serial interface to your host, you will also need a NodeBuilder FX Development Tool or Mini FX Evaluation Kit to develop the MIP image for your network interface.

You also need a network management tool to install and test your LonTalk Stack device. You can use the OpenLNS Commissioning Tool, or any other tool that can install and monitor LONWORKS devices. See the OpenLNS Commissioning Tool User’s Guide for more information on the OpenLNS Commissioning Tool.

You can use NodeBuilder Code Wizard that is included with the NodeBuilder FX tool, version 3 or later, to help develop your Neuron C model file. The model file is used to define the device’s interoperable interface.

LonTalk Stack Architecture

A LonTalk Stack device consists of the following components:

•Echelon Smart Transceiver or Neuron Chip with a Layer 2 MIP.

•A microprocessor, microcontroller, or embedded processor running the following software:

•Host application that uses the LonTalk API.

•LonTalk API

•LonTalk host stack.

•Non-volatile data (NVD) driver.

•Operating system abstraction layer (OSAL).

•Embedded operating system.

•Serial I/O driver.

The following figure shows the basic architecture of a LonTalk Stack device.

10	Introduction to the LonTalk Stack

The LonTalk Stack includes source code for the LonTalk API and the LonTalk host stack. The kit also includes source code for additional operating system and hardware APIs that you compile and link with your application. The LonTalk API defines the functions that your application calls to communicate with other devices on a LONWORKS network. The API code provides ANSI C interfaces for the host application.

The LonTalk API consists of the following types of functions:

•Functions to initialize the host device after each reset.

•A function that the application must call periodically. This function processes messages pending in any of the data queues.

•Various functions to initiate typical operations, such as the propagation of network variable updates.

•Event handler functions to notify the application of events, such as the arrival of network variable data or an error in the propagation of an application message.

•Functions to interface with the operating system.

LonTalk Stack Developer’s Guide

11

Overview of the LonTalk Stack Development

Process

The development process for a LonTalk Stack application includes the following steps:

1.Load the Neuron firmware and the Layer 2 MIP on the Echelon Smart Transceiver or Neuron Chip.

2.Create the serial I/O hardware interface between your host processor and the Echelon Smart Transceiver or Neuron Chip.

3.Develop a LonTalk Stack serial driver for your host processor that manages the handshaking and data transfers between the host processor and the Echelon Smart Transceiver or Neuron Chip.

4.Create a model file that defines the interoperable interface of your LonTalk Stack device, including its network inputs and outputs.

5.Use the LonTalk Interface Developer utility to generate application framework files and interface files from the model file.

6.Use a C/C++ development tool to create the LonTalk Stack application, with input from:

•The application framework files generated by the LonTalk Interface Developer utility

•The operating system abstraction layer (OSAL) files, which you might need to modify

•The non-volatile data (NVD) driver files, which you might need to modify

•The LonTalk host stack

•The LonTalk API

A LonTalk Stack device is comprised of both hardware and software components; therefore, different people can be involved in the various steps, and these steps can occur in parallel or sequentially. The figure does not imply a required order of steps.

12	Introduction to the LonTalk Stack

This manual describes the software development process for creating a LonTalk Stack device, which includes the general tasks listed in the following table.

Task	Additional Considerations	Reference
Install the LonTalk		Chapter 2, Getting
Developer’s Kit and become		Started with the
familiar with it		LonTalk Stack
		Developer’s Kit
Load an application image		Chapter 3, Loading
file with the Neuron		the Echelon Smart
firmware and Layer 2 MIP		Transceiver or
onto an Echelon Smart		Neuron Chip
Transceiver or Neuron Chip.
Create the hardware		Chapter 4,
interface between your host		Designing the Serial
processor and the Echelon		I/O Hardware
Smart Transceiver or		Interface
Neuron Chip.

LonTalk Stack Developer’s Guide

13

Task	Additional Considerations	Reference
Develop a LonTalk Stack		Chapter 5, Creating
serial driver for your host		a LonTalk Stack
processor that manages the		Serial Driver
handshaking and data
transfers between the host
processor and the Echelon
Smart Transceiver or
Neuron Chip.
Select a microprocessor,	The LonTalk Stack application runs
microcontroller, or	on any microprocessor,
embedded processor.	microcontroller, or embedded
	processor. You must meet the
	LonTalk Stack hardware and software
	requirements to ensure that the
	LonTalk Stack device has sufficient
	RAM and non-volatile memory.
Integrate the LonTalk Stack	You integrate the Echelon Smart
application with your device	Transceiver or Neuron Chip with the
hardware	device hardware. You can reuse many
	parts of a hardware design for
	different applications to create
	different LonTalk Stack devices.
Test and verify your	You must ensure that the host
hardware design	processor and the Echelon Smart
	Transceiver or Neuron Chip can
	communicate using the serial
	interface.
Select and define the	You must select profiles and types for	Chapter 6, Creating
functional profiles and	use in the device’s interoperable	a Model File
resource types for your	interface for each application that you
device using tools such as	plan to implement. This selection can
the NodeBuilder Resource	include the definition of user-defined
Editor and the SNVT and	types for network variables,
SCPT Master List	configuration properties or functional
	profiles. A large set of standard
	definitions is also available and is
	sufficient for many applications.

14	Introduction to the LonTalk Stack

Task	Additional Considerations
Structure the layout and	You must define the interoperable
interoperable interface of	interface for your device in a model
your LonTalk Stack device	file, using the Neuron C (Version 2.1)
by creating a model file	language, for every application that
	you implement. You can write this
	code by hand, derive it from an
	existing Neuron C application, or use
	the NodeBuilder Code Wizard
	included with the NodeBuilder
	Development Tool to create the
	required code using a graphical user
	interface.
Use the LonTalk Interface	You must execute this utility, a simple
Developer utility to generate	click-through wizard, whenever the
device interface data, device	model file changes or other
interface files, and a	preferences change. The utility
skeleton application	generates the interface files (including
framework	the XIF file) and source code that you
	can compile and link with your
	application. This source code includes
	data that is required for initialization
	and for complete implementations of
	some aspects of your device.
Complete the LonTalk API	You must complete the event handler
event handler functions and	functions and callback handler
callback handler functions to	functions for every application that
process application-specific	you implement, because they provide
LONWORKS events	input from network events to your
	application, and because they are part
	of your networked device’s control
	algorithm.
Modify the Operating
System Abstraction Layer
(OSAL) files for your
application’s operating
system
Modify the non-volatile data	Depending on the type of non-volatile
(NVD) driver files	memory that your device uses, you
	can use one of the non-volatile data
	drivers provided with the LonTalk
	Stack, make minor modifications to
	one of these drivers, or implement
	your own driver.

Reference

Chapter 6, Creating a Model File

Appendix C, Neuron C Syntax for the Model File

Chapter 7, Using the

LonTalk Interface

Developer Utility

Chapter 8,

Developing a

LonTalk Stack

Device Application

Appendix D,

LonTalk API

Integrating the Application with an Operating System in Chapter 8,

Developing a

LonTalk Stack Device Application

Providing Persistent Storage for Non-Volatile Data in Chapter 8,

Developing a

LonTalk Stack Device Application

LonTalk Stack Developer’s Guide

15

Task	Additional Considerations
Modify your application to	You must make these function calls
interface with a LONWORKS	for every application that you
network by using the	implement. These calls include, for
LonTalk API function calls	example, calls to the
	LonPropagateNv() function that
	propagates an updated network
	variable value to the network.
	Together with the completion of the
	event and callback handler functions,
	this task forms the core of your
	networked device’s control algorithm.
Test, install, and integrate
your LonTalk Stack device
using a LONWORKS network
tool such as the OpenLNS
Commissioning Tool

Reference

Chapter 8,

Developing a

LonTalk Stack

Device Application

Appendix D,

LonTalk API

OpenLNS

Commissioning Tool

User’s Guide

16	Introduction to the LonTalk Stack

LonTalk Stack Developer’s Guide

17