Echelon FTXL User Manual

FTXL User’s Guide

078-0363-01A

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

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

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

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

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

.LON, ShortStack, LonMaker, and the

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.

Echelon Corporation

www.echelon.com

Welcome

Echelon’s FTXL™ products enable any product that contains an Altera® Nios® II processor to quickly and inexpensively become a networked smart device. An FTXL device includes a complete ANSI/CEA 709.1-B (EN14908.1) implementation that runs on the Nios II embedded processor. Thus, the FTXL 3190™ Free Topology Smart Transceiver Chip provides a simple way to add

ONWORKS

L because it has a simple host application programming interface (API), a pre-built link-layer driver, a simple hardware interface, and comprehensive tool support.

networking to smart devices. The FTXL Transceiver is easy to use

This document describes how to develop an application for a L using Echelon’s FTXL Transceiver. It describes the architecture of an FTXL device and how to develop the software for an FTXL device. Development of a FTXL device includes creating a model file, running the LonTalk Developer utility, and using the FTXL API functions to program your FTXL application for the Nios II processor.

See the FTXL device, the development boards for which the FTXL Developer’s Kit provides reference designs, and FPGA design requirements for an FTXL device.

FTXL Hardware Guide

Audience

This document assumes that the reader has a good understanding of the

ONWORKS platform and programming for the Altera Nios II processor.

Related Documentation

In addition to this manual and the FTXL Developer’s Kit includes the following manuals:

Neuron C Programmer’s Guide

•

the key concepts of programming using the Neuron language and describes how to develop a L

ONWORKS device

Interface

for a description of the hardware interfaces for an

FTXL Hardware Guide

(078-0002-02G). This manual describes

ONWORKS application.

(078-0364-01A), the

C programming

Neuron C Reference Guide

•

reference information for writing programs that use the Neuron C language.

NodeBuilder Errors Guide

•

codes issued by the Neuron C compiler.

The FTXL Developer’s Kit also includes the reference documentation for the FTXL LonTalk API, which is delivered as a set of HTML files.

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

The following manuals are available from the Echelon Web site

www.echelon.com) and provide additional information that can help you develop

( applications for an FTXL Transceiver:

FTXL User’s Guide iii

(078-0140-02E). This manual provides

(078-0193-01B). This manual describes error

•

Introduction to the LONW

ORKS

System

(078-0183-01A). This manual provides an introduction to the ANSI/CEA-709.1 (EN14908) Control Networking Protocol, and provides a high-level introduction to

ONWORKS networks and the tools and components that are used for

L developing, installing, operating, and maintaining them.

•

LONM

ARK

Application Layer Interoperability Guidelines.

describes design guidelines for developing applications for open interoperable L Web site,

FT 3120 / FT 3150 Smart Transceiver Data Book

•

ONWORKS devices, and is available from the LONMARK

www.lonmark.org.

manual provides detailed technical specifications on the electrical interfaces, mechanical interfaces, and operating environment

characteristics for the FT 3120

, FT 3150®, and FTXL 3190 Smart

Transceivers.

LonMaker User's Guide

•

use the Turbo edition of the LonMaker

(078-0333-01A). This manual describes how to

Integration Tool to design,

commission, monitor and control, maintain, and manage a network.

All of the FTXL documentation, and related product documentation, is available in Adobe the Adobe Reader

PDF format. To view the PDF files, you must have a current version of

, which you can download from Adobe at:

www.adobe.com/products/acrobat/readstep2.html.

Related devboards.de Product Documentation

The FTXL Developer’s Kit uses the devboards.de DBC2C20 Altera Cyclone II Development Board for its examples and reference designs. For information about the DBC2C20 Altera Cyclone II Development Board, including the most current data sheet for the board, see the DBC2C20 page:

www.devboards.de/index.php?mode=products&kategorie=14.

The DBC2C20 development board is also available from EBV Elektronik; see

www.ebv.com/en/products/development_boards/dbc2c20.html.

FTXL User’s Guide v

vi FTXL User’s Guide vii

Table of Contents

Welcome.........................................................................................................iii

Audience ........................................................................................................iii

Related Documentation ................................................................................iii

Related Altera Product Documentation ................................................iv

Related devboards.de Product Documentation...................................... v

Introduction to FTXL......................................................................................... 1

Overview ......................................................................................................... 2

A LONWORKS Device with a Single Processor Chip ..............................3

A LONWORKS Device with Two Processor Chips ................................... 4

LonTalk Platform for ShortStack Micro Servers ............................ 5

LonTalk Platform for FTXL Transceivers....................................... 6

Comparing Neuron-Hosted, ShortStack, and FTXL Devices ...............8

Requirements and Restrictions for FTXL ..................................................10

Development Tools for FTXL ...................................................................... 11

FTXL Architecture ....................................................................................... 11

The FTXL Developer’s Kit ........................................................................... 13

Overview of the FTXL Development Process ............................................. 13

Getting Started with FTXL ............................................................................. 17

FTXL Developer’s Kit Overview.................................................................. 18

Installing the FTXL Developer’s Kit........................................................... 18

Hardware Requirements....................................................................... 19

Software Requirements......................................................................... 19

DBC2C20 Software................................................................................ 20

Installing the FTXL Developer’s Kit .................................................... 20

FTXL API Files ............................................................................................20

LonTalk Interface Developer....................................................................... 21

Example FTXL Applications ....................................................................... 21

Creating a Model File ...................................................................................... 23

Model File Overview .................................................................................... 24

Defining the Device Interface...................................................................... 25

Defining the Interface for an FTXL Application .................................25

Choosing the Data Type .................................................................26

Defining a Functional Block .................................................................27

Declaring a Functional Block ......................................................... 28

Defining a Network Variable................................................................ 28

Defining a Changeable-Type Network Variable ........................... 30

Defining a Configuration Property....................................................... 32

Declaring a Configuration Property ..............................................32

Responding to Configuration Property Value Changes................ 34

Defining a Configuration Property Array ..................................... 34

Sharing a Configuration Property .................................................37

Inheriting a Configuration Property Type ....................................38

Declaring a Message Tag ...................................................................... 40

Defining a Resource File ....................................................................... 40

Implementation-Specific Scope Rules............................................ 42

Writing Acceptable Neuron C Code ............................................................ 43

Anonymous Top-Level Types ................................................................ 43

Legacy Neuron C Constructs ................................................................ 44

Using Authentication for Network Variables ............................................ 44

Specifying the Authentication Key....................................................... 44

How Authentication Works................................................................... 45

Managing Memory ....................................................................................... 46

Address Table ........................................................................................47

Alias Table .............................................................................................47

Domain Table......................................................................................... 48

Network Variable Configuration Table................................................ 48

Example Model files..................................................................................... 48

Simple Network Variable Declarations ............................................... 48

Network Variables Using Standard Types .......................................... 49

Functional Blocks without Configuration Properties ......................... 50

Functional Blocks with Configuration Network Variables................. 51

Functional Blocks with Configuration Properties Implemented in a Configuration

File..........................................................................................................

Using the LonTalk Interface Developer Utility.............................................. 55

Running the LonTalk Interface Developer................................................. 56

Specifying the Project File ....................................................................56

Specifying the FTXL Transceiver Configuration................................. 57

Specifying Service Pin Held Events ..................................................... 57

Configuring the FTXL LonTalk Protocol Stack................................... 57

Configuring the Buffers ........................................................................ 58

Configuring the Application.................................................................. 58

Configuring Support for Non-Volatile Data......................................... 58

Specifying the Device Program ID ....................................................... 59

Specifying the Model File...................................................................... 60

Specifying Neuron C Compiler Preferences......................................... 60

Specifying Code Generator Preferences ............................................... 61

Compiling and Generating the Files .................................................... 61

Using the LonTalk Interface Developer Files ............................................ 61

Copied Files............................................................................................ 62

LonNvTypes.h and LonCpTypes.h ....................................................... 62

FtxlDev.h................................................................................................ 63

FtxlDev.c ................................................................................................ 63

project.xif and project.xfb...................................................................... 63

Using Types .................................................................................................. 64

Bit Field Members ................................................................................. 65

Enumerations ........................................................................................66

Floating Point Variables ....................................................................... 66

Network Variable and Configuration Property Declarations ...................68

Constant Configuration Properties............................................................. 70

The Network Variable Table ....................................................................... 71

Network Variable Attributes ................................................................ 71

The Message Tag Table ...............................................................................72

Developing an FTXL Application .................................................................... 73

Overview of an FTXL Application............................................................... 74

Using the FTXL LonTalk API .............................................................. 74

Callbacks and Events ............................................................................ 76

Integrating the Application with an Operating System ..................... 76

Providing Persistent Storage for Non-Volatile Data........................... 77

Restoring Non-Volatile Data .......................................................... 78

Writing Non-Volatile Data .............................................................79

Tasks Performed by an FTXL Application ................................................. 80

viii

Initializing the FTXL Device ................................................................ 81

Periodically Calling the Event Pump................................................... 81

Sending a Network Variable Update ...................................................83

Receiving a Network Variable Update from the Network .................. 85

Handling a Network Variable Poll Request from the Network.......... 88

Handling Changes to Changeable-Type Network Variables .............. 88

Validating a Type Change .............................................................. 89

Processing a Type Change.............................................................. 90

Processing a Size Change ............................................................... 91

Rejecting a Type Change ................................................................ 92

Handling Dynamic Network Variables ................................................ 92

Communicating with Other Devices Using Application Messages .... 93

Sending an Application Message to the Network ......................... 94

Receiving an Application Message from the Network.................. 94

Handling Management Commands...................................................... 94

Handling Local Network Management Tasks ..................................... 95

Handling Reset Events.......................................................................... 95

Querying the Error Log......................................................................... 95

Working with ECS Devices.......................................................................... 95

Using Direct Memory Files.......................................................................... 96

The DMF Memory Window................................................................... 97

File Directory ......................................................................................... 99

Shutting Down the FTXL Device ................................................................99

Working with the Nios II Development Environment...................................101

Development Tools ..................................................................................... 102

Using a Device Programmer for the FPGA Device .................................. 103

Setting up the Nios II IDE ........................................................................ 103

Creating a New FTXL Application Project ........................................ 104

Running the LonTalk Interface Developer Utility ............................ 105

Customizing the FTXL System Library............................................. 105

Specifying the Properties for the Application.................................... 106

Building the Application Image ................................................................ 107

Loading the Application Image into Persistent Memory ........................ 107

Running the Application............................................................................ 108

Debugging the Application ........................................................................ 109

LonTalk Interface Developer Command Line Usage.....................................111

Overview ..................................................................................................... 112

Command Usage ........................................................................................112

Command Switches.................................................................................... 113

Specifying Buffers................................................................................ 115

Model File Compiler Directives......................................................................119

Using Model File Compiler Directives...................................................... 120

Acceptable Model File Compiler Directives.............................................. 120

Neuron C Syntax for the Model File...............................................................125

Functional Block Syntax............................................................................ 126

Keywords.............................................................................................. 126

Examples.............................................................................................. 128

Functional Block Properties Syntax ......................................................... 129

Keywords.............................................................................................. 129

Examples.............................................................................................. 130

Network Variable Syntax .......................................................................... 132

FTXL User’s Guide ix

Keywords.............................................................................................. 132

The Network Variable Modifier ................................................... 132

The Network Variable Storage Class .......................................... 134

The Network Variable Type ......................................................... 134

The Network Variable Connection Information ......................... 135

The Network Variable Initializer................................................. 138

The Network Variable Property List ........................................... 138

Configuration Property Syntax ................................................................. 139

Keywords.............................................................................................. 139

The Configuration Property Type ................................................ 140

The Configuration Property Modifiers ........................................ 140

The Configuration Property Initializer ....................................... 142

Declaring a Configuration Network Variable.................................... 143

Defining a Device Property List .........................................................143

Message Tag Syntax ..................................................................................145

Keywords.............................................................................................. 145

FTXL LonTalk API .........................................................................................147

Introduction................................................................................................ 148

The FTXL LonTalk API, Event Handler Functions, and Callback Handler Functions

.....................................................................................................................

148

FTXL LonTalk API Functions ............................................................ 149

Commonly Used FTXL LonTalk API Functions ......................... 149

Other FTXL LonTalk API Functions........................................... 149

Application Messaging API Functions ........................................ 150

Non-Volatile Data API Functions ................................................ 151

Extended API Functions............................................................... 151

FTXL Event Handler Functions ......................................................... 152

Commonly Used Event Handler Functions................................. 152

Dynamic Network Variable Event Handler Functions ..............154

Application Messaging Event Handler Functions ...................... 154

Non-Volatile Data Event Handler Functions.............................. 155

FTXL Callback Handler Functions .................................................... 155

Commonly Used Callback Handler Functions ............................ 155

Direct Memory Files Callback Handler Functions ..................... 156

Non-Volatile Data Callback Handler Functions ......................... 156

The FTXL Operating System Abstraction Layer..................................... 157

Managing Critical Sections................................................................. 158

Managing Binary Semaphores ...........................................................158

Managing Operating System Events .................................................158

Managing System Timing ................................................................... 159

Managing Operating System Tasks ................................................... 159

Debugging Operating System Functions ........................................... 159

Configuring the Operating System ....................................................160

Determining Resource Requirements.......................................... 160

Specifying Task Priorities ............................................................161

Configuring the Micrium μC/OS-II Operating System ..................... 165

Maximum Number of Tasks......................................................... 165

Lowest Assignable Task Priority .................................................166

Maximum Number of Event Control Blocks ............................... 167

Other μC/OS-II Settings ............................................................... 167

The FTXL Hardware Abstraction Layer ..................................................178

Managing the FTXL Transceiver .......................................................178

Managing the Service Pin ................................................................... 179

Managing Interrupts........................................................................... 179

Determining Memory Usage for FTXL Applications.....................................181

Overview ..................................................................................................... 182

Total Memory Use ...............................................................................182

Memory Use for Transactions............................................................. 183

Memory Use for Buffers ...................................................................... 183

Memory for LONWORKS Resources ..................................................... 184

Memory for Non-Volatile Data ...........................................................185

Memory Usage Examples.................................................................... 187

Downloading an FTXL Application Over the Network..................................191

Overview ..................................................................................................... 192

Custom Application Download Protocol ...................................................192

Application Download Utility.................................................................... 193

Download Capability within the Application ........................................... 193

Example FTXL Applications...........................................................................195

Overview of the Example Applications..................................................... 196

Example Application Files ..................................................................196

The Simple Example Application.............................................................. 197

Main Function...................................................................................... 198

Application Task Function.................................................................. 198

Event Handler Function .....................................................................199

Application-Specific Utility Functions ............................................... 200

Callback Handler Function................................................................. 201

Model File............................................................................................. 201

The Dynamic Interface Example Application .......................................... 202

Main Function...................................................................................... 203

Application Task Function.................................................................. 204

Event Handler Functions.................................................................... 205

myNvUpdateOccurred()................................................................ 206

myNvAdded()................................................................................. 211

myNvTypeChanged() .................................................................... 211

myNvDeleted() ..............................................................................211

myReset()....................................................................................... 212

myOnline()..................................................................................... 212

Application-Specific Utility Functions ............................................... 213

Callback Handler Function................................................................. 213

Model File............................................................................................. 214

Setting up the Nios II IDE for the Example Applications....................... 215

Creating a New FTXL Application Project ........................................ 215

Running the LonTalk Interface Developer Utility ............................ 217

Building the Example Application Image ................................................218

Building the Reference Design Hardware Image.............................. 218

Building the Example Software Image .............................................. 218

Loading the Example Application Image into Flash ............................... 219

Running the Example Applications ..........................................................220

Running the Simple Example............................................................. 222

Running the Dynamic Interface Example .........................................222

Changing Network Variable Types.............................................. 222

Adding Dynamic Network Variables ........................................... 223

The Micrium Software License .................................................................227

FTXL User’s Guide xi

LonTalk Interface Developer Utility Error and Warning Messages.............229

Introduction................................................................................................ 230

Error Messages........................................................................................... 230

Warning codes ............................................................................................ 237

Hint codes ................................................................................................... 239

Glossary...........................................................................................................241

Index................................................................................................................245

xii

Introduction to FTXL

This chapter introduces the LonTalk Platform for FTXL Transceivers. It describes the architecture of an FTXL device, including a comparison with other L devices. It also describes attributes of an FTXL device, the requirements and restrictions of the FTXL LonTalk protocol stack, and the FTXL products that are available from Echelon.

ONWORKS

FTXL User’s Guide 1

Overview

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

LONW

ORKS

network

ONWORKS network provides communications and

is a peer-to-peer

The communications protocol used for L

ONWORKS networks is the ANSI/CEA

709.1-B (EN14908.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 the seven abstract layers described in The implementation of these layers in a L interconnectivity for devices within a L

Table 2. L

ONWORKS Network Protocol Layers

ONWORKS device provides standardized

ONWORKS network.

Table 2.

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 ANSI/CEA-709.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

.LON® servers, and the FTXL LonTalk protocol stack. This document refers to

Micro Server), LNS® Server, LNS remote client,

2 Introduction to FTXL

the ANSI/CEA-709.1 (EN14908-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 L

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, Echelon’s 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 Smart Transceiver runs the device’s application, implements the LonTalk protocol, and interfaces with the physical communications media through a transformer.

4 shows the seven-layer LonTalk protocol on a single Neuron Chip or Smart

page Transceiver.

A L

ONWORKS device that uses a single processor chip is called a

device, which means that the Neuron-based processor (the Smart Transceiver) runs both the application and the LonTalk protocol.

Figure 1 on

Neuron-hosted

FTXL User’s Guide 3

Figure 1. A Single-Chip L

For a Neuron-hosted device that uses a Neuron Chip or Smart Transceiver, the physical layer (layer 1) is handled by the Neuron Chip or 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 create the application program using the Neuron C programming language in either the NodeBuilder

Development Tool or the Mini EVK Evaluation Kit.

ONWORKS Device

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 Smart Transceiver can provide. Other L an existing processor and application. For these applications, the device uses two processor chips working together:

• An Echelon Smart Transceiver

• A microprocessor, microcontroller, or embedded processor in a field-

programmable gate array (FPGA) device, typically called the

processor

A L

ONWORKS device that uses two processor chips is called a

which means that the device includes a Smart Transceiver plus a host processor.

4 Introduction to FTXL

ONWORKS devices are implemented by adding a transceiver to

host

host-based

device,

Compared to the single-chip device, the Smart Transceiver implements only a subset of the LonTalk protocol layers. The host processor implements the remaining layers and runs the device’s application program. The Smart Transceiver and the host processor communicate with each other through a linklayer 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 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 Development Tool or the Mini EVK application, to develop the application.

LonTalk API

. In

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

• The LonTalk Platform for ShortStack Micro Servers

• The LonTalk Platform for FTXL Transceivers

ONWORKS

LonTalk Platform for ShortStack Micro Servers

The LonTalk Platform for ShortStack Micro Servers is a set of development tools, APIs, and firmware for developing host-based L LonTalk Compact API and a ShortStack Micro Server.

A ShortStack Micro Server is a Smart Transceiver with firmware, the

firmware

protocol, as shown in application layer (layer 7) and part of the presentation layer (layer 6).

The ShortStack firmware allows you to use almost any host processor for your device’s application and I/O. The Smart Transceiver implements layers 2 to 5 (and part of layer 6) of the LonTalk protocol and provides the physical interface for the L

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. Currently, example drivers are available for an Atmel processor.

For ShortStack device development, you use the C programming language use the Echelon LonTalk Interface Developer utility to create the application framework. Your application uses an ANSI C API, the Echelon LonTalk Compact API, to manage communications with the ShortStack Micro Server and devices on the L

, that implements layers 2 to 5 (and part of layer 6) of the LonTalk

Figure 2 on page 6. The host processor implements the

ONWORKS communications channel.

ARM7 microprocessor and an Altera Nios II embedded

ONWORKS network.

ONWORKS devices that use the

ShortStack

. You

For ShortStack device development, you could alternatively use 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.

FTXL User’s Guide 5

Using a ShortStack Micro Server makes it easy to add LONWORKS networks to any existing smart device.

ShortStack Device

Application in any suitable language

Link layer

Transceiver and

wiring

FT 3120, PL 3120,

FT 3150, or PL 3150

Smart Transceiver

SCI or SPI serial I/O link layer and driver software

Host Processor

Figure 2. The ShortStack Solution for a Host-Based L

ONWORKS Device

LonTalk Platform for FTXL Transceivers

The LonTalk Platform for FTXL Transceivers is a set of development tools, APIs, firmware, and chips for developing host-based L LonTalk API and an FTXL Transceiver.

An FTXL Transceiver is an FT 3190 Smart Transceiver with firmware that implements the data link layer (layer 2) of the LonTalk protocol, as shown in Figure 3 on page 8. The host processor implements the remaining layers (layers 3 to 7). Included with the FTXL development tools is the FTXL LonTalk protocol stack, which implements layers 3 to 6 of the LonTalk protocol and runs on the host processor. Your application implements the application layer (layer 7).

6 Introduction to FTXL

ONWORKS devices that use the

For an FTXL device, you use an Altera Nios II processor as the host processor for your device’s application and I/O. The Nios II processor runs on an Altera Cyclone II or Cyclone III FPGA device. The FTXL LonTalk protocol stack implements layers 3 to 6 of the LonTalk protocol, and the FTXL Transceiver implements layers 1 and 2, including the physical interface for the L

ONWORKS

communications channel.

The FTXL LonTalk protocol stack includes a communications interface driver for the parallel link layer that manages communications between the FTXL LonTalk protocol stack within the Nios II host processor and the FTXL Transceiver. You need to include the physical implementation of the parallel link layer in your FTXL device design. However, you do not need to provide the software implementation of the parallel interface driver because it is included with the FTXL LonTalk protocol stack, nor can you modify the Echelon-provided implementation.

For FTXL device development, you use a C or C++ compiler that supports the Nios II processor. As with ShortStack development, you use the Echelon LonTalk Interface Developer utility to create the application framework. Your application uses an ANSI C API, the Echelon LonTalk API, to manage communications with the FTXL LonTalk protocol stack, FTXL Transceiver, and devices on the L

ONWORKS network.

Using an FTXL Transceiver, it is easy to add L performance FPGA-based smart device.

ONWORKS networking to a high-

FTXL User’s Guide 7

FTXL Device

Application in C

Link layer

Transceiver and

wiring

FTXL 3190 Free

Topology Smart

Transceiver

Figure 3. An FTXL Device

11-pin parallel I/O link layer and driver software

Nios II

Host Processor

Comparing Neuron-Hosted, ShortStack, and FTXL Devices

Table 3 on page 9 compares some of the key characteristics of the Neuron-hosted and host-based solutions for L

ONWORKS devices.

8 Introduction to FTXL

Table 3. Comparing Neuron-Hosted and Host-Based Solutions for L

NeuronHosted

Characteristic

Maximum number of

Solution ShortStack Solution FTXL Solution

62 254

[1]

4096

network variables

Maximum number of

62 127

[2]

8192

aliases

Maximum number of

15 15 4096

addresses

Maximum number of

0 0 4096 dynamic network variables

Maximum number of

16 16 200 receive transaction records

Maximum number of

2 2 2500 transmit transaction records

ONWORKS Devices

Support for the

No No Yes LonTalk Extended Command Set

File access methods supported

FTP

DMF

[4]

FTP

[4]

, DMF FTP

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)

Host processor type N/A Any 8-, 16-, 32-, or 64-bit

microprocessor or microcontroller

Application

Neuron C Any (typically ANSI C) ANSI C or C++ for the development language

[3]

[4]

, DMF

11-line parallel I/O

[5]

[6]

540 KB (includes LonTalk protocol stack, but does not include the application or operating system)

Altera Nios II embedded processor

Nios II processor

FTXL User’s Guide 9

Notes:

1. ShortStack Micro Servers running on FT 3150 or PL 3150 Smart Transceivers support up to 254 network variables. ShortStack Micro Servers running on FT 3120 Smart Transceivers support up to 240 network variables, and ShortStack Micro Servers running on PL 3120 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 Smart Transceivers support up to 127 aliases. ShortStack Micro Servers running on FT 3120 Smart Transceivers support up to 120 aliases. ShortStack Micro Servers running on PL 3120 Smart Transceivers support up to 62 aliases. A custom Micro Server can support up to 127 aliases, depending on available resources.

3. See the more information about the extended command set (ECS) network management commands. This document is available from the IHS Standards Store:

global.ihs.com/doc_detail.cfm?item_s_key=00391891&item_key_date=971131&rid= CEA.

4. An implementation of the L with the product.

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

Memory Files

6. The FTXL parallel I/O link-layer driver is included with the FTXL LonTalk protocol stack.

LonTalk Control Network Protocol Specification

ONWORKS file transfer protocol (FTP) is not provided

on page 96.

The FTXL solution provides the best performance and highest network capacity, but is limited using to an Altera Nios II host processor and the TP/FT-10 channel. The ShortStack solution provides support for any host processor (with available examples for both an Atmel ARM7 host processor and an Altera Nios II host processor), and supports both the TP/FT-10 and PL-20 channels. The ShortStack solution supports fewer network variables and aliases that the FTXL solution, but more network variables and aliases than the Neuron-hosted solution.

Because the ShortStack and FTXL solutions are both built on the LonTalk platform, they share a very similar API (the FTXL LonTalk API and the ShortStack LonTalk Compact API). Thus, migrating applications from one solution to the other is fairly easy. In addition, you can create applications that share a common code base for devices that use both solutions.

, EIA/CEA 709.1-B-2002, for

Using Direct

Requirements and Restrictions for FTXL

The FTXL Developer’s Kit supports only the FTXL 3190 Free Topology Smart Transceiver. It does not support other transceiver types.

The FTXL LonTalk protocol stack requires that the FTXL application use an embedded operating system. The FTXL Developer’s Kit includes an example application that uses the Micrium μC/OS-II operating system, but you can use any embedded operating system that meets your application’s requirements. And although the μC/OS-II operating system is a real-time operating system, the FTXL LonTalk protocol stack does not require the operating system to be a realtime operating system.

10 Introduction to FTXL

The FTXL LonTalk protocol stack and API require about 540 KB of program memory on the Nios II host processor, not including the application program or the operating system. In addition, you must provide sufficient additional nonvolatile 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 when to use FTP or the DMF feature.

Using Direct Memory Files

on page 96 for more information about

Development Tools for FTXL

To develop an application for a device that uses an FTXL Transceiver, you need a development system for the Nios II processor. In addition, you need the FTXL Developer’s Kit, which includes:

• The FTXL LonTalk API

• The LonTalk

your FTXL device and generating the application framework

• Example FTXL applications

• A reference design for a Nios II processor and associated hardware for

the FPGA device

You also need a network management tool to install and test your FTXL device. You can use the LonMaker Integration Tool, or any other tool that can install and monitor L information on the LonMaker tool.

You do not need the NodeBuilder Development Tool to use the FTXL Developer's Kit; however, the NodeBuilder Code Wizard that is included with the NodeBuilder tool, version 3 or later, can help you develop your Neuron C model file. The model file is used to define the device’s interoperable interface.

ONWORKS devices. See the

Interface Developer utility for defining the interface for

FTXL Architecture

An FTXL device consists of the following components:

• The FTXL 3190 Free Topology Smart Transceiver running the FTXL

firmware

• A Nios II embedded processor running the following software:

• An FTXL host application that uses the FTXL LonTalk API

LonMaker User's Guide

for more

• The FTXL LonTalk protocol stack

• The FTXL hardware abstraction layer (HAL)

• The FTXL non-volatile data (NVD) driver

• The FTXL operating system abstraction layer (OSAL)

• An embedded operating system

• The Altera SOPC Builder hardware abstraction layer (HAL)

FTXL User’s Guide 11

Figure 4 shows the basic architecture of an FTXL device.

Figure 4. FTXL Architecture

The FTXL Developer's Kit includes the FTXL LonTalk API and a precompiled library that implements the FTXL LonTalk protocol stack. The kit also includes source code for additional operating system and hardware APIs that you compile and link with your application. The FTXL LonTalk API defines the functions that your application calls to communicate with other devices on a L network. The API code provides ANSI C interfaces for the host application.

12 Introduction to FTXL

ONWORKS

The FTXL LonTalk API consists of the following types of functions:

• Functions to initialize the FTXL 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.

The FTXL Developer’s Kit

The FTXL Developer’s Kit consists of two components: a hardware component and a software component. See the the hardware component of the FTXL Developer’s Kit.

The software component contains the software required to develop FTXL applications that use an FTXL Transceiver:

1. The FTXL LonTalk protocol stack library and FTXL LonTalk API

2. ANSI C source code for event handler functions.

FTXL Hardware Guide

for information about

3. Portable ANSI C source code for the reference implementations of the APIs for the operating system and hardware.

4. The LonTalk Interface Developer utility that you use to generate device interface data, device interface files, and a skeletal application framework.

5. Example applications that run on the reference design hardware.

The software component of the FTXL Developer’s Kit is available as a free download from the Echelon Web site: must acquire a licence from Echelon to use the FTXL Developer’s Kit.

www.echelon.com/downloads. You also

Overview of the FTXL Development Process

Figure 5 on page 14 shows a high-level overview of the development process for an FTXL application. The basic process includes the following steps:

1. Use the Altera Quartus II software and SOPC Builder tool, with input from FTXL hardware components and your FPGA design, to generate compiled hardware description files.

2. Use the LonTalk Interface Developer utility, with input from a model file that you create, to generate application framework files and interface files.

3. Use the Altera Nios II EDS IDE to create the FTXL application, with input from:

• The application framework files generated by the LonTalk Interface

Developer utility

FTXL User’s Guide 13

Source

FPGA

Hardware

Description

Files

FTXL Hardware

Components

• The FTXL hardware abstraction layer (HAL) files, which you might

need to modify

• The FTXL operating system abstraction layer (OSAL) files, which you

might need to modify

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

modify

• The FTXL LonTalk protocol stack

Because an FTXL device is comprised of both hardware and software components, 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.

Quartus II

Software and

SOPC Builder

Compiled

FPGA

Hardware

Description

Files

Nios II EDS

IDE

FTXL Application

Source

Model File

(*.nc)

LonTalk

Interface

Developer

Generated Application Framework

Files

FTXL HAL FTXL OSAL

FTXL NVD

Driver

FTXL LonTalk Protocol Stack

Interface Files

(*.xif and *.xfb)

Figure 5. Overview of the FTXL Development Process

For more information about hardware development for an FTXL device, see the

FTXL Hardware Guide

This manual describes the software development process for creating an FTXL device, which includes the general tasks listed in

Table 4.

Table 4. Tasks for Developing Software for an FTXL Device

Task Additional Considerations Reference

Install the FTXL Developer’s Kit and become familiar with it

Chapter

Started with FTXL

, on page 17

Getting

14 Introduction to FTXL

Task Additional Considerations Reference

Select an FPGA device and load it with Nios II processor and related hardware

Integrate the FTXL application with your device hardware

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

The FTXL application runs on a Nios II embedded processor, which is implemented on an FPGA device. You must meet the FTXL hardware and software requirements to ensure that the FTXL device has sufficient RAM and non-volatile memory.

You integrate the FTXL Transceiver with the device hardware. You can reuse many parts of a hardware design for different applications to create different FTXL devices.

You must ensure that the host processor and the FTXL Transceiver can communicate using the parallel interface. The FTXL Developer’s Kit includes a BringUp application to help test and verify the communications 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.

FTXL

The

Hardware Guide

FTXL

The

Hardware Guide

Chapter 6,

Working with the Nios II Development Environment

101

page

FTXL

The

Hardware Guide

Chapter

, on

Creating a Model

, on page 23

File

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

FTXL User’s Guide 15

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 or ShortStack application, or use the NodeBuilder Code Wizard included with the NodeBuilder Development Tool to create the required code using a graphical user interface.

Chapter

Creating a Model File

Appendix

Neuron C Syntax for the Model File

on page

, on page 23

125

Task Additional Considerations Reference

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

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

ONWORKS events

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

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.

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.

If you use the Micrium μC/OS-II operating system, you can use the OSAL files that are included with the FTXL Developer’s Kit.

Chapter

Using the LonTalk Interface Developer Utility

on page

Chapter

Developing an FTXL Application

147

FTXL

, on

on page

Appendix

LonTalk API

page

The FTXL Operating System Abstraction Layer

on page

157

Modify the non-volatile data (NVD) driver files

Modify your application to interface with a

ONWORKS network by

L using the FTXL LonTalk API function calls

Test, install, and integrate your FTXL device using a

ONWORKS network tool

L such as the LonMaker Integration Tool

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 FTXL Developer’s Kit, make minor modifications to one of these drivers, or implement your own driver.

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 event and callback handler functions, this task forms the core of your networked device’s control algorithm.

The

Providing Persistent Storage for Non-Volatile

on page 77

Data

Chapter

Developing an FTXL Application

147

FTXL

, on

on page

Appendix

LonTalk API

page

LonMaker

User's Guide

16 Introduction to FTXL

Getting Started with FTXL

This chapter describes the FTXL Developer’s Kit and how to install it.

FTXL User’s Guide 17

FTXL Developer’s Kit Overview

The FTXL Developer’s Kit is a development toolkit that contains the hardware designs, software designs, and documentation needed for developing applications that use an FTXL Transceiver. The kit includes the following components:

• Hardware and software design files for the FPGA design, including

Quartus II files, SOPC Builder files, and Nios IDE files

• Hardware component files for the FPGA development board

• The FTXL LonTalk protocol stack and FTXL LonTalk API, delivered as a

C object library

• Software source files for the FTXL LonTalk API

• A set of example programs that demonstrate how to use the FTXL

LonTalk API to communicate with a L

• The LonTalk Interface Developer utility, which defines parameters for

your FTXL host application program and generates required device interface data for your device

ONWORKS network

• Documentation, including this

, and HTML documentation for the FTXL API

Guide

The FTXL Developer’s Kit also refers to three hardware development boards that are available from devboards GmbH, can also obtain these boards from EBV Elektronik GmbH, FTXL Developer’s Kit uses these boards for its examples and reference designs. These boards are:

• The

Contact your Altera representative for information about acquiring a Nios II development license.

See the development boards and the reference designs for the FTXL Developer’s Kit.

The software for the FTXL Developer’s Kit is available as a free download from

www.echelon.com/ftxl.

DBC2C20 Altera Cyclone II Development Board

FPGA device and peripheral I/O

FTXL Adapter Board

between the DBC2C20 development board and the FTXL Transceiver Board

FTXL Transceiver Board

Transceiver Chip and a L

FTXL Hardware Guide

for more information about the hardware

FTXL User’s Guide

www.devboards.de. European customers

, which primarily provides voltage regulation

, which includes the FTXL 3190 Smart

ONWORKS network connector

, the

FTXL Hardware

www.ebv.com. The

, which provides the

Installing the FTXL Developer’s Kit

The FTXL Developer’s Kit requires the following software:

• Altera Quartus II software, Version 7.2 or later

• Altera Nios II EDS integrated development environment (IDE), Version

7.2 or later

18 Getting Started with FTXL

+ 231 hidden pages