Transcription
FTXL User’s Guide 078-0363-01A
Echelon, LONWORKS, LONMARK, NodeBuilder, LonTalk, Neuron,3120, 3150, LNS, i.LON, ShortStack, LonMaker, and theEchelon logo are trademarks of Echelon Corporationregistered in the United States and other countries. 3190,FTXL, OpenLDV, Pyxos, and LonScanner are trademarks ofEchelon Corporation.Other brand and product names are trademarks orregistered trademarks of their respective holders.Neuron Chips and other OEM Products were not designedfor use in equipment or systems, which involve danger tohuman health or safety, or a risk of property damage andEchelon assumes no responsibility or liability for use of theNeuron Chips in such applications.Parts manufactured by vendors other than Echelon andreferenced in this document have been described forillustrative purposes only, and may not have been testedby Echelon. It is the responsibility of the customer todetermine the suitability of these parts for eachapplication.ECHELON MAKES AND YOU RECEIVE NO WARRANTIES ORCONDITIONS, EXPRESS, IMPLIED, STATUTORY OR IN ANYCOMMUNICATION WITH YOU, AND ECHELON SPECIFICALLYDISCLAIMS ANY IMPLIED WARRANTY OF MERCHANTABILITYOR FITNESS FOR A PARTICULAR PURPOSE.No part of this publication may be reproduced, stored in aretrieval system, or transmitted, in any form or by any means,electronic, mechanical, photocopying, recording, orotherwise, without the prior written permission of EchelonCorporation.Printed in the United States of America.Copyright 2001, 2008 Echelon Corporation.Echelon Corporationwww.echelon.com
WelcomeEchelon’s FTXL products enable any product that contains an Altera Nios IIprocessor to quickly and inexpensively become a networked smart device. AnFTXL device includes a complete ANSI/CEA 709.1-B (EN14908.1)implementation that runs on the Nios II embedded processor. Thus, the FTXL3190 Free Topology Smart Transceiver Chip provides a simple way to addLONWORKS networking to smart devices. The FTXL Transceiver is easy to usebecause it has a simple host application programming interface (API), a pre-builtlink-layer driver, a simple hardware interface, and comprehensive tool support.This document describes how to develop an application for a LONWORKS deviceusing Echelon’s FTXL Transceiver. It describes the architecture of an FTXLdevice and how to develop the software for an FTXL device. Development of aFTXL device includes creating a model file, running the LonTalk InterfaceDeveloper utility, and using the FTXL API functions to program your FTXLapplication for the Nios II processor.See the FTXL Hardware Guide for a description of the hardware interfaces for anFTXL device, the development boards for which the FTXL Developer’s Kitprovides reference designs, and FPGA design requirements for an FTXL device.AudienceThis document assumes that the reader has a good understanding of theLONWORKS platform and programming for the Altera Nios II processor.Related DocumentationIn addition to this manual and the FTXL Hardware Guide (078-0364-01A), theFTXL Developer’s Kit includes the following manuals: Neuron C Programmer’s Guide (078-0002-02G). This manual describesthe key concepts of programming using the Neuron C programminglanguage and describes how to develop a LONWORKS application. Neuron C Reference Guide (078-0140-02E). This manual providesreference information for writing programs that use the Neuron Clanguage. NodeBuilder Errors Guide (078-0193-01B). This manual describes errorcodes issued by the Neuron C compiler.The FTXL Developer’s Kit also includes the reference documentation for theFTXL LonTalk API, which is delivered as a set of HTML files.After you install the FTXL software, you can view these documents from theWindows 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 developapplications for an FTXL Transceiver:FTXL User’s Guideiii
Introduction to the LONWORKS System (078-0183-01A). This manualprovides an introduction to the ANSI/CEA-709.1 (EN14908) ControlNetworking Protocol, and provides a high-level introduction toLONWORKS networks and the tools and components that are used fordeveloping, installing, operating, and maintaining them. LONMARK Application Layer Interoperability Guidelines. This manual FT 3120 / FT 3150 Smart Transceiver Data Book (005-0139-01D). Thismanual provides detailed technical specifications on the electricalinterfaces, mechanical interfaces, and operating environmentcharacteristics for the FT 3120 , FT 3150 , and FTXL 3190 SmartTransceivers. LonMaker User's Guide (078-0333-01A). This manual describes how touse the Turbo edition of the LonMaker Integration Tool to design,commission, monitor and control, maintain, and manage a network.describes design guidelines for developing applications for openinteroperable LONWORKS devices, and is available from the LONMARKWeb site, www.lonmark.org.All of the FTXL documentation, and related product documentation, is availablein Adobe PDF format. To view the PDF files, you must have a current version ofthe Adobe Reader , which you can download from Adobe elated Altera Product DocumentationFor information about the Altera Nios II family of embedded processors andassociated tools, see the Altera Nios II Literature page:www.altera.com/literature/lit-nio2.jsp.Table 1 lists Altera product documents that are particularly useful for the FTXLDeveloper’s Kit.Table 1. Related Altera DocumentationProduct CategoryDocumentation TitlesQuartus II softwareIntroduction to Quartus II SoftwareQuartus II Quick Start GuideQuartus II Development Software Handbook v7.2iv
Product CategoryDocumentation TitlesNios II processorNios II Hardware Development TutorialNios II Software Development Tutorial (included in theonline help for the Nios II EDS integrated developmentenvironment)Nios II Flash Programmer User GuideNios II Processor Reference HandbookNios II Software Developer's HandbookCyclone II and Cyclone IIIFPGA and deviceconfigurationCyclone II Device HandbookCyclone III Device HandbookConfiguration HandbookUSB-Blaster downloadcableUSB-Blaster Download Cable User GuideSoftware licensingQuartus II Installation & Licensing for WindowsAN 340: Altera Software LicensingRelated devboards.de Product DocumentationThe FTXL Developer’s Kit uses the devboards.de DBC2C20 Altera Cyclone IIDevelopment Board for its examples and reference designs. For informationabout the DBC2C20 Altera Cyclone II Development Board, including the mostcurrent 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; seewww.ebv.com/en/products/development boards/dbc2c20.html.FTXL User’s Guidev
vi
Table of ContentsWelcome .iiiAudience .iiiRelated Documentation .iiiRelated Altera Product Documentation . ivRelated devboards.de Product Documentation. vIntroduction to FTXL . 1Overview . 2A LONWORKS Device with a Single Processor Chip . 3A LONWORKS Device with Two Processor Chips . 4LonTalk Platform for ShortStack Micro Servers . 5LonTalk Platform for FTXL Transceivers. 6Comparing Neuron-Hosted, ShortStack, and FTXL Devices . 8Requirements and Restrictions for FTXL . 10Development Tools for FTXL . 11FTXL Architecture . 11The FTXL Developer’s Kit . 13Overview of the FTXL Development Process . 13Getting Started with FTXL . 17FTXL Developer’s Kit Overview. 18Installing the FTXL Developer’s Kit. 18Hardware Requirements. 19Software Requirements. 19DBC2C20 Software. 20Installing the FTXL Developer’s Kit . 20FTXL API Files . 20LonTalk Interface Developer. 21Example FTXL Applications . 21Creating a Model File . 23Model File Overview . 24Defining the Device Interface. 25Defining the Interface for an FTXL Application . 25Choosing the Data Type . 26Defining a Functional Block . 27Declaring a Functional Block . 28Defining a Network Variable. 28Defining a Changeable-Type Network Variable . 30Defining a Configuration Property. 32Declaring a Configuration Property . 32Responding to Configuration Property Value Changes. 34Defining a Configuration Property Array . 34Sharing a Configuration Property . 37Inheriting a Configuration Property Type . 38Declaring a Message Tag . 40Defining a Resource File . 40Implementation-Specific Scope Rules. 42Writing Acceptable Neuron C Code . 43Anonymous Top-Level Types . 43Legacy Neuron C Constructs . 44Using Authentication for Network Variables . 44FTXL User’s Guidevii
Specifying the Authentication Key. 44How Authentication Works. 45Managing Memory . 46Address Table . 47Alias Table . 47Domain Table. 48Network Variable Configuration Table. 48Example Model files. 48Simple Network Variable Declarations . 48Network Variables Using Standard Types . 49Functional Blocks without Configuration Properties . 50Functional Blocks with Configuration Network Variables. 51Functional Blocks with Configuration Properties Implemented in a ConfigurationFile. 52Using the LonTalk Interface Developer Utility . 55Running the LonTalk Interface Developer. 56Specifying the Project File . 56Specifying the FTXL Transceiver Configuration. 57Specifying Service Pin Held Events . 57Configuring the FTXL LonTalk Protocol Stack. 57Configuring the Buffers . 58Configuring the Application. 58Configuring Support for Non-Volatile Data. 58Specifying the Device Program ID . 59Specifying the Model File. 60Specifying Neuron C Compiler Preferences. 60Specifying Code Generator Preferences . 61Compiling and Generating the Files . 61Using the LonTalk Interface Developer Files . 61Copied Files. 62LonNvTypes.h and LonCpTypes.h . 62FtxlDev.h. 63FtxlDev.c . 63project.xif and project.xfb. 63Using Types . 64Bit Field Members . 65Enumerations . 66Floating Point Variables . 66Network Variable and Configuration Property Declarations . 68Constant Configuration Properties. 70The Network Variable Table . 71Network Variable Attributes . 71The Message Tag Table . 72Developing an FTXL Application . 73Overview of an FTXL Application. 74Using the FTXL LonTalk API . 74Callbacks and Events . 76Integrating the Application with an Operating System . 76Providing Persistent Storage for Non-Volatile Data. 77Restoring Non-Volatile Data . 78Writing Non-Volatile Data . 79Tasks Performed by an FTXL Application . 80viii
Initializing the FTXL Device . 81Periodically Calling the Event Pump. 81Sending a Network Variable Update . 83Receiving a Network Variable Update from the Network . 85Handling a Network Variable Poll Request from the Network. 88Handling Changes to Changeable-Type Network Variables . 88Validating a Type Change . 89Processing a Type Change. 90Processing a Size Change . 91Rejecting a Type Change . 92Handling Dynamic Network Variables . 92Communicating with Other Devices Using Application Messages . 93Sending an Application Message to the Network . 94Receiving an Application Message from the Network. 94Handling Management Commands. 94Handling Local Network Management Tasks . 95Handling Reset Events. 95Querying the Error Log. 95Working with ECS Devices. 95Using Direct Memory Files. 96The DMF Memory Window. 97File Directory . 99Shutting Down the FTXL Device . 99Working with the Nios II Development Environment.101Development Tools. 102Using a Device Programmer for the FPGA Device . 103Setting up the Nios II IDE . 103Creating a New FTXL Application Project . 104Running the LonTalk Interface Developer Utility . 105Customizing the FTXL System Library. 105Specifying the Properties for the Application. 106Building the Application Image . 107Loading the Application Image into Persistent Memory . 107Running the Application. 108Debugging the Application . 109LonTalk Interface Developer Command Line Usage.111Overview . 112Command Usage . 112Command Switches. 113Specifying Buffers. 115Model File Compiler Directives .119Using Model File Compiler Directives. 120Acceptable Model File Compiler Directives. 120Neuron C Syntax for the Model File.125Functional Block Syntax. 126Keywords. 126Examples. 128Functional Block Properties Syntax . 129Keywords. 129Examples. 130Network Variable Syntax . 132FTXL User’s Guideix
Keywords. 132The Network Variable Modifier . 132The Network Variable Storage Class . 134The Network Variable Type . 134The Network Variable Connection Information . 135The Network Variable Initializer. 138The Network Variable Property List . 138Configuration Property Syntax . 139Keywords. 139The Configuration Property Type . 140The Configuration Property Modifiers . 140The Configuration Property Initializer . 142Declaring a Configuration Network Variable. 143Defining a Device Property List . 143Message Tag Syntax . 145Keywords. 145FTXL LonTalk API .147Introduction. 148The FTXL LonTalk API, Event Handler Functions, and Callback Handler Functions. 148FTXL LonTalk API Functions . 149Commonly Used FTXL LonTalk API Functions . 149Other FTXL LonTalk API Functions. 149Application Messaging API Functions . 150Non-Volatile Data API Functions . 151Extended API Functions. 151FTXL Event Handler Functions . 152Commonly Used Event Handler Functions. 152Dynamic Network Variable Event Handler Functions . 154Application Messaging Event Handler Functions . 154Non-Volatile Data Event Handler Functions. 155FTXL Callback Handler Functions . 155Commonly Used Callback Handler Functions . 155Direct Memory Files Callback Handler Functions . 156Non-Volatile Data Callback Handler Functions . 156The FTXL Operating System Abstraction Layer. 157Managing Critical Sections. 158Managing Binary Semaphores . 158Managing Operating System Events . 158Managing System Timing . 159Managing Operating System Tasks . 159Debugging Operating System Functions . 159Configuring the Operating System . 160Determining Resource Requirements. 160Specifying Task Priorities . 161Configuring the Micrium μC/OS-II Operating System . 165Maximum Number of Tasks. 165Lowest Assignable Task Priority . 166Maximum Number of Event Control Blocks . 167Other μC/OS-II Settings . 167The FTXL Hardware Abstraction Layer . 178Managing the FTXL Transceiver . 178Managing the Service Pin . 179x
Managing Interrupts . 179Determining Memory Usage for FTXL Applications .181Overview . 182Total Memory Use . 182Memory Use for Transactions. 183Memory Use for Buffers . 183Memory for LONWORKS Resources . 184Memory for Non-Volatile Data . 185Memory Usage Examples. 187Downloading an FTXL Application Over the Network.191Overview . 192Custom Application Download Protocol . 192Application Download Utility. 193Download Capability within the Application . 193Example FTXL Applications.195Overview of the Example Applications. 196Example Application Files . 196The Simple Example Application. 197Main Function. 198Application Task Function. 198Event Handler Function . 199Application-Specific Utility Functions . 200Callback Handler Function. 201Model File. 201The Dynamic Interface Example Application . 202Main Function. 203Application Task Function. 204Event Handler Functions. 205myNvUpdateOccurred(). 206myNvAdded(). 211myNvTypeChanged() . 211myNvDeleted() . 211myReset() . 212myOnline() . 212Application-Specific Utility Functions . 213Callback Handler Function. 213Model File. 214Setting up the Nios II IDE for the Example Applications. 215Creating a New FTXL Application Project . 215Running the LonTalk Interface Developer Utility . 217Building the Example Application Image . 218Building the Reference Design Hardware Image. 218Building the Example Software Image . 218Loading the Example Application Image into Flash . 219
Quartus II software Introduction to Quartus II Software Quartus II Quick Start Guide Quartus II Development Software Handbook v7.2 . FTXL User's Guide v Product Category Documentation Titles . USB-Blaster download cable USB-Blaster Download Cable User Guide Software licensing Quartus II Installation & Licensing for Windows AN 340 .
