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.
i
.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.
Printed in the United States of America.
Copyright © 2001, 2008 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.
L
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 Altera Product Documentation
For information about the Altera Nios II family of embedded processors and
associated tools, see the Altera Nios II Literature page:
www.altera.com/literature/lit-nio2.jsp.
This manual
(005-0139-01D). This
Table 1 lists Altera product documents that are particularly useful for the FTXL
Developer’s Kit.
Table 1. Related Altera Documentation
Product Category Documentation Titles
Quartus® II software Introduction to Quartus II Software
Quartus II Quick Start Guide
Quartus II Development Software Handbook v7.2
iv
Product Category Documentation Titles
Nios II processor Nios II Hardware Development Tutorial
Nios II Software Development Tutorial (included in the
online help for the Nios II EDS integrated development
environment)
Nios II Flash Programmer User Guide
Nios II Processor Reference Handbook
Nios II Software Developer's Handbook
Cyclone® II and Cyclone III
FPGA and device
configuration
USB-Blaster™ download
cable
Software licensing Quartus II Installation & Licensing for Windows
Cyclone II Device Handbook
Cyclone III Device Handbook
Configuration Handbook
USB-Blaster Download Cable User Guide
AN 340: Altera Software Licensing
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..........................................................................................................
52
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
x
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
1
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
i
.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
re
wa
m
r
i
F
n
o
r
u
e
N
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
1
. You
1
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
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
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
2,
, 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
3,
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
3,
, on page 23
125
C,
,
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
L
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.
4,
Chapter
Using
the LonTalk
Interface
Developer Utility
on page
Chapter
55
5,
,
Developing an
FTXL Application
147
73
D,
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
5,
Developing an
FTXL Application
147
73
D,
FTXL
, on
on page
Appendix
LonTalk API
page
LonMaker
User's Guide
,
16 Introduction to FTXL
2
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
• The
• 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
Loading...