Echelon LonTal Stack User Manual

LonTalk® Stack Developer's Guide

078-0483-01A

Echelon, LONWORKS, LONMARK, NodeBuild er, LonTalk, Neuron, 3120, 3150, LNS,

ShortStack, and the Ec helon 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 SP ECIFICALLY DISCLAIMS A N Y IMPLIED WARR A N T Y OF M ER 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.

Echelon Corporation

www.echelon.com

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......................................................................................................

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 ..........................................................................

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 .........................................................................................

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

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

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....................................................................................................

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

193

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.........................................................................................

Introduction................................................................................................ 220

Error Messages........................................................................................... 220

Warning Codes ...........................................................................................226

Hint Codes .................................................................................................. 228

Appendix I Glossary ...................................................................................231

219

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 L 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

ONWORKS platform and programming for embedded processors.

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 L development solutions. It also describes attributes of a LonTalk Stack device, and the requirements and restrictions of the LonTalk Stack.

ONWORKS device

LonTalk Stack Developer’s Guide 1

Overview

Automation solutions for buildings, homes, utility, transportation, and industrial applications include sensors, actuators, and control systems. A L 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 L provides communications and complete access to control network data from any device in the network.

ONWORKS

ONWORKS network

The communications protocol used for L

ONWORKS 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 L devices within a L

ONWORKS device provides standardized interconnectivity for

ONWORKS 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

communication reliability

Acknowledged and unacknowledged 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

ONWORKS 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)

Physical layer

Transceiver and

wiring

LonTalk Stack Developer’s Guide 3

A L

ONWORKS 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 Tool or the Mini FX.

FX Development

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 L 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.

ONWORKS device that uses two processor chips is called a host-based device,

A L which means that the device includes an Echelon Smart Transceiver or Neuron Chip plus a host processor.

ONWORKS devices are implemented by adding a transceiver

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 L devices:

• ShortStack Developer’s Kit

• LonTalk Stack Developer’s Kit

ONWORKS

ShortStack Developer’s Kit

The ShortStack Developer’s Kit is a set of development tools, APIs, and firmware for developing host-based L and a ShortStack Micro Server.

ONWORKS devices that use the LonTalk Compact API

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 L

ONWORKS 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 L

ONWORKS 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 L

ONWORKS 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 L 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

ONWORKS devices that use the Echelon

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 L

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.

ONWORKS devices on the network.

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 L

ONWORKS devices.

Characteristic

Maximum number of network variables

Maximum number of aliases

Maximum number of addresses

Maximum number of dynamic network variables

Maximum number of receive transaction records

Neuron-Hosted Solution

254 254

254 127

15 15 32767

0 0 4096

16 16 32767

ShortStack FX

[1]

4096

[2]

8192

LonTalk Stack

Maximum number of transmit transaction records

Support for the LonTalk Extended Command Set

LonTalk Stack Developer’s Guide 7

2 2 32767

[3]

No No Yes

File access methods supported

FTP

[4]

, DMF FTP

[4]

, DMF FTP

[4]

, DMF

[5]

Link-layer type N/A 4- or 5-line

SCI or 6- or 7-line SPI

Typical host API runtime footprint

N/A 5-6 KB code

with 1 KB RAM (includes serial driver, but does not include optional API or ISI API)

2-line SCI

Native LonTalk protocol stack.

Includes LonTalk API, Linux Serial MIP driver, and the SimpleDevice example application.

IP-852 LonTalk protocol stack.

Includes LonTalk API, Linux Serial MIP driver, and the SimpleIp852Device example application.

Native LonTalk to IP-852 Router.

850 KB

955 KB

965 KB

Host processor type

Application development language

N/A Any 8-, 16-,

32-, or 64-bit microprocessor or microcontroller

Neuron C Any (typically

ANSI C)

Includes Linux Serial MIP driver, and the Ip852Router example application.

Any 32- or 64-bit microprocessor or microcontroller

ANSI C or C++ for the embedded processor

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 L

with the product.

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

Memory Files.

ONWORKS file transfer protocol (FTP) is not provided

Using Direct

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

ONWORKS and IP-852 channels. The ShortStack solution provides support for

L 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

ONWORKS file transfer protocol (FTP) or use the direct memory files (DMF)

L feature. See FTP or the DMF feature.

Using Direct Memory Files for more information about when to use

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

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 L 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.

Interface Developer utility for defining the interface for your

ONWORKS devices. See the OpenLNS Commissioning

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 L 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

• Various functions to initiate typical operations, such as the propagation

• Event handler functions to notify the application of events, such as the

• Functions to interface with the operating system.

ONWORKS network. The API code provides ANSI C interfaces for

processes messages pending in any of the data queues.

of network variable updates.

arrival of network variable data or an error in the propagation of an application message.

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 Developer’s Kit and become familiar with it

Load an application image file with the Neuron firmware and Layer 2 MIP onto an Echelon Smart Transceiver or Neuron Chip.

Create the hardware interface between your host processor and the Echelon Smart Transceiver or Neuron Chip.

Chapter 2,

Getting Started with the LonTalk Stack Developer’s Kit

Chapter 3,

Loading the Echelon Smart Transceiver or Neuron Chip

Chapter 4,

Designing the Serial I/O Hardware Interface

LonTalk Stack Developer’s Guide 13

Task Additional Considerations Reference

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.

Select a microprocessor, microcontroller, or embedded processor.

Integrate the LonTalk Stack application with your device hardware

Chapter 5,

Creating a LonTalk Stack Serial Driver

The LonTalk Stack application runs on any microprocessor, 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.

You integrate the Echelon Smart Transceiver or Neuron Chip with the device hardware. You can reuse many parts of a hardware design for different applications to create different LonTalk Stack devices.

Test and verify your hardware design

Select and define the functional profiles and resource types for your device using tools such as the NodeBuilder Resource Editor and the SNVT and SCPT Master List

You must ensure that the host processor and the Echelon Smart Transceiver or Neuron Chip can communicate using the serial interface.

You must select profiles and types for use in the device’s interoperable interface for each application that you plan to implement. This selection can include the definition of user-defined types for network variables, configuration properties or functional profiles. A large set of standard definitions is also available and is sufficient for many applications.

Chapter 6,

Creating a Model File

14 Introduction to the LonTalk Stack

Task Additional Considerations Reference

Structure the layout and interoperable interface of your LonTalk Stack device by creating a model file

Use the LonTalk Interface Developer utility to generate device interface data, device interface files, and a skeleton application framework

You must define the interoperable interface for your device in a model file, using the Neuron C (Version 2.1) 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.

You must execute this utility, a simple click-through wizard, whenever the model file changes or other preferences change. The utility generates the interface files (including 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.

Chapter 6,

Creating a Model File

Appendix C,

Neuron

C Syntax for the Model File

Chapter 7,

Using the LonTalk Interface Developer Utility

Complete the LonTalk API event handler functions and callback handler functions to process application-specific

ONWORKS events

Modify the Operating System Abstraction Layer (OSAL) files for your application’s operating system

Modify the non-volatile data (NVD) driver files

You must complete the event handler functions and callback handler functions for every application that you implement, because they provide input from network events to your application, and because they are part of your networked device’s control algorithm.

Depending on the type of non-volatile 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.

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 Reference

Modify your application to interface with a L

ONWORKS

network by using the LonTalk API function calls

Test, install, and integrate your LonTalk Stack device using a L

ONWORKS network

tool such as the OpenLNS Commissioning Tool

You must make these function calls for every application that you implement. These calls include, for example, calls to the LonPropagateNv() function that propagates an updated network variable value to the network. Together with the completion of the

Chapter 8,

Developing a LonTalk Stack Device Application

Appendix D, LonTalk API

event and callback handler functions, this task forms the core of your networked device’s control algorithm.

OpenLNS

Commissioning Tool User’s Guide

16 Introduction to the LonTalk Stack

LonTalk Stack Developer’s Guide 17

+ 217 hidden pages

Echelon LonTal Stack User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Table of Contents

Welcome

Audience

Related Documentation

Introduction to LonTalk Stack

Overview

A LONWORKS Device with a Single Processor Chip

A LONWORKS Device with Two Processor Chips

ShortStack Developer’s Kit

LonTalk Stack Developer’s Kit

Requirements and Restrictions for LonTalk Stack

Development Tools for LonTalk Stack

LonTalk Stack Architecture

Overview of the LonTalk Stack Development Process