Echelon NodeBuilder FX User Manual

NodeBuilder

®

FX User’s Guide

®

0 7 8 - 0 4 0 5 - 0 1 A

Echelon, LON, LonWorks, Neuron, 3120, 3150, Digital
Home, i.LON, LNS, LonMaker, L

ONMARK, LonPoint,

LonTalk, NodeBuilder, ShortStack, and the Echelon logo
are trademarks of Echelon Corporation registered in the
United States and other countries. FTXL, LonScanner,
LonSupport, OpenLDV, and LNS Powered by Echelon
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 or LonPoint Modules

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 NO REPRESENTATION, WARRANTY, OR
CONDITION OF ANY KIND, EXPRESS, IMPLIED, STATUTORY,
OR OTHERWISE OR IN ANY COMMUNICATION WITH YOU,
INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED
WARRANTIES OF MERCHANTABILITY, SATISFACTORY
QUALITY, FITNESS FOR ANY PARTICULAR PURPOSE,
NONINFRINGEMENT, AND THEIR EQUIVALENTS.

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 ©1997–2009 by Echelon
Corporation.
Echelon Corporation
www.echelon.com

ii

Table of Contents

Preface .................................................................................................... ix

Purpose ........................................................................................................... x

Audience.......................................................................................................... x

Hardware Requirements.................................................................................. x

Content ........................................................................................................... xi

Related Manuals.............................................................................................xii

For More Information and Technical Support................................................xiii

1 Introduction .......................................................................................

Introduction to the NodeBuilder Tool............................................................... 2

New Features in the NodeBuilder FX Tool...................................................... 2

5000 Series Chip Support......................................................................... 2

Backwards Compatibility for Device Applications .............................. 3

Improved Memory Architecture .......................................................... 3

Faster System Clock ..........................................................................4

Improved Performance for Arithmetic Operations.............................. 4

User-Programmable Interrupts........................................................... 4

Additional I/O Model Support ............................................................. 5

FT 5000 EVB Evaluation Board ................................................................ 5

Increased Network Variable Support ........................................................ 5

Neuron C Version 2.2 Enhancements ......................................................6

Interrupt Support................................................................................. 6

Non-Constant Device-Specific Configuration Property Support......... 6

New and Enhanced Compiler Directives............................................ 6

Enhanced Hardware Template Editor....................................................... 6

Enhanced Code Wizard Framework Template......................................... 6

Neuron C Debugger.................................................................................. 7

LNS Plug-in Framework Developer’s Kit................................................... 7

Microsoft Windows Vista Support ............................................................. 7

What's Included with the NodeBuilder FX Tool ............................................... 7

NodeBuilder FX Development Tool CD .................................................... 8

Development Platforms............................................................................. 8

FT 5000 EVB Evaluation Board ......................................................... 8

LTM-10A Platform and NodeBuilder Gizmo 4 I/O Board ...................9

LTM-10A Platform...................................................................... 10

NodeBuilder Gizmo 4 I/O Board ................................................10

LonMaker Integration Tool CD................................................................11

LonScanner Protocol Analyzer CD ......................................................... 11

U10/U20 USB Network Interface ............................................................ 11

Introduction to NodeBuilder Device Development and LONWORKS

Networks........................................................................................................

Channels ................................................................................................. 12

Routers.................................................................................................... 13

Applications............................................................................................. 13

Program IDs ............................................................................................ 13

Network Variables ................................................................................... 14

Configuration Properties .........................................................................16

Functional Blocks .................................................................................... 16

Functional Profiles................................................................................... 16

Hardware Templates............................................................................... 17

Neuron C................................................................................................. 17

Device Templates ...................................................................................17

1

12

NodeBuilder FX User's Guide iii

Device Interface Files .............................................................................

Resource Files ........................................................................................ 18

Targets .................................................................................................... 18

2 Installing the NodeBuilder FX Development Tool ........................

Installing the NodeBuilder FX Development Tool.......................................... 20

Installing the NodeBuilder Software........................................................ 21

Connecting the NodeBuilder Hardware ..................................................26

Connecting the NodeBuilder FX/FT Hardware................................. 26

Connecting the NodeBuilder FX/PL Hardware................................. 29

3 NodeBuilder Quick-Start Exercise.................................................

NodeBuilder Quick-Start Exercise................................................................. 32

Step 1: Creating a NodeBuilder Project.................................................. 32

Step 2: Creating a NodeBuilder Device Template .................................. 36

Step 3: Defining the Device Interface and Creating its Neuron C

Application Framework ...........................................................................

Step 4: Developing the Device Application............................................. 46

FT 5000 Evaluation Boards.............................................................. 47

LTM-10A Platform and Gizmo 4 I/O Board ......................................48

Step 5: Compiling, Building, and Downloading the Application .............. 49

Step 6: Testing the Device Interface....................................................... 53

Step 7: Debugging the Device Application ............................................. 55

Step 8: Connecting and Testing the Device in a Network ......................61

Additional Device Development Steps.................................................... 67

Creating a LonMaker Stencil ............................................................ 67

Creating an LNS Device Plug-in....................................................... 71

Developing an HMI ........................................................................... 72

Creating a Device Installation Application ........................................ 72

Submitting a LONWORKS OEM License ............................................ 74

Applying for LONMARK Certification .................................................. 74

17

19

31

41

4 Creating and Opening NodeBuilder Projects ...............................

Introduction to the NodeBuilder Project Manager .........................................78

Using the Project Pane ...........................................................................79

Creating a NodeBuilder Project..................................................................... 80

Creating a NodeBuilder Project from the LonMaker Tool....................... 81

Creating a NodeBuilder Project from the NodeBuilder Project

Manager ..................................................................................................

Creating a NodeBuilder Project from the New Device Wizard ............... 84

Opening a NodeBuilder Project..................................................................... 86

Opening a NodeBuilder Project from the LonMaker Tool....................... 86

Opening a NodeBuilder Project from the NodeBuilder Project

Manager ..................................................................................................

Copying NodeBuilder Projects....................................................................... 89

Using the LonMaker Tool to Backup and Restore a NodeBuilder

Project .....................................................................................................

Manually Copying NodeBuilder Project Files.......................................... 92

Copying NodeBuilder Device Templates....................................................... 92

Copying User-Defined Resource Files .......................................................... 93

Viewing and Printing NodeBuilder XML Files................................................ 94

5 Creating and Using Device Templates ..........................................

Introduction to Device Templates.................................................................. 96

Creating Device Templates ........................................................................... 96

Starting the New Device Template Wizard ............................................. 96

77

81

88

89

95

iv Preface

Specifying the Device Template Name...................................................

Specifying the Program ID ...................................................................... 98

Specifying Target Platforms.................................................................. 103

Managing and Editing Device Templates....................................................105

Managing Device Templates ................................................................105

Viewing and Editing Device Templates................................................. 106

Viewing Device Template Components ................................................ 107

Managing Development and Release Targets .....................................109

Setting Device Template Target Properties: Compiler................... 110

Setting Device Template Target Properties: Linker ....................... 113

Setting Device Template Target Properties: Exporter.................... 114

Setting Device Template Target Properties: Configuration............ 116

Inserting a Library into a NodeBuilder Device Template ......................118

Using Hardware Templates ......................................................................... 121

Creating Hardware Templates .............................................................. 122

Editing Hardware Templates................................................................. 124

Setting Hardware Properties ..........................................................124

Setting Memory Properties............................................................. 127

5000 Series Chips.................................................................... 128

3150 Neuron Core ................................................................... 129

3120 and 3170 Neuron Core ...................................................129

Setting the Hardware Template Description................................... 129

6 Defining Device Interfaces and Creating their Neuron C

Application Framework.................................................................

Introduction to Device Interfaces................................................................. 132

Starting the Code Wizard...................................................................... 132

Using the Resource Pane............................................................... 133

Introduction to Resource File Sets...........................................134

Introduction to Resources ........................................................ 135

Using the NodeBuilder Resource Editor .................................. 137

Using the Program Interface Pane ................................................. 137

Defining the Device Interface................................................................ 139

Adding Functional Blocks ............................................................... 142

Using Large Functional Block Arrays....................................... 145

Editing Mandatory Network Variables ............................................ 145

Editing Mandatory Configuration Properties................................... 152

Implementing Optional Network Variables ..................................... 158

Implementing Optional Configuration Properties............................ 160

Adding Implementation-specific Network Variables ....................... 162

Adding Implementation-specific Configuration Properties ............. 164

Setting Initial Values for Network Variables and Configuration

Properties .......................................................................................

Setting Initial Values for Structured Data Types ...................... 168

Setting Initial Values for Enumerations.................................... 170

Setting Initial Values for Floating Point and s32 Data Types... 171

Using Changeable-Type Network Variables .................................. 172

Generating Code with the Code Wizard ...............................................173

Files Created by the Code Wizard .................................................173

Using Code Wizard Templates.................................................... 176

Version 3 Templates ................................................................ 176

Version 2 Templates ................................................................ 176

Version 1 Templates ................................................................ 177

Creating the Device Application ..................................................... 177

97

131

167

NodeBuilder FX User's Guide v

7 Developing Device Applications.................................................. 179

Introduction to Neuron C .............................................................................180

Unique Aspects of Neuron C ................................................................ 180

Neuron C Variables............................................................................... 182

Neuron C Variable Types ............................................................... 182

Neuron C Storage Classes............................................................. 182

Variable Initialization....................................................................... 183

Neuron C Declarations ................................................................... 183

Introduction to Neuron C Code Editing........................................................ 184

Modifying Neuron C Code Generated by the Code Wizard.................. 185

Code Commands............................................................................ 185

Code Guidelines ............................................................................. 186

Add I/O and Timer Declarations...............................................186

Add when-tasks Responding to I/O and Timer Events............ 187

Add interrupt-tasks Responding to Interrupt Requests............ 187

Add Code to when(nv_update_occurs(<nv>)) when-task of

Functional Blocks with Input NVs.............................................

Share Code with filexfer.nc when Handling Explicit

Messages on a Device Implementing FTP ..............................

Ignore NCC#310 and NC#463 Compiler Warnings................. 187

Implementing Changeable-Type Network Variables...................... 187

Neuron C Version 2 Features Not Supported by the Code

Wizard.............................................................................................

Message Tags.......................................................................... 189

I/O Models................................................................................189

Network Variables.................................................................... 189

Configuration Properties .......................................................... 189

when() clauses ......................................................................... 190

LONMARK Style ......................................................................... 190

Director Functions.................................................................... 190

Interrupt Tasks ......................................................................... 190

Using the NodeBuilder Editor ...................................................................... 190

Using Syntax Highlighting ..................................................................... 191

Searching Source Files......................................................................... 191

Searching a Single File for a String................................................ 191

Replacing Text................................................................................ 192

Searching Multiple Files for a String............................................... 192

Using Bookmarks .................................................................................. 195

Setting Editor Options ........................................................................... 195

187

187

189

8 Building and Downloading Device Applications........................

Introduction to Building and Downloading Applications .............................. 198

Building an Application Image ..................................................................... 198

Excluding Targets from a Build ............................................................. 203

Cleaning Build Output Files ..................................................................203

Viewing Build Status .............................................................................204

Setting Build Options............................................................................. 206

Downloading an Application Image ............................................................. 207

Programming 5000 Off-chip Memory.................................................... 208

Programming 5000 Series Chips In-Circuit .................................... 209

Programming 3150 Off-chip Memory.................................................... 214

Programming 3150 On-chip Memory.................................................... 215

Programming 3120 and 3170 On-chip Memory.................................... 216

Programming PL 3120 and PL 3170 Smart Transceiver

Parameters .....................................................................................

vi Preface

197

216

Upgrading Device Applications .............................................................

Adding and Managing Target Devices ........................................................ 217

Adding a Target Device with the LonMaker Tool..................................217

Adding a Target Device with the NodeBuilder Project Manager ..........221

Managing Target Devices ..................................................................... 223

Editing Target Device Settings.............................................................. 224

9 Testing a NodeBuilder Device Using the LonMaker Tool..........

Introduction to Testing NodeBuilder Devices .............................................. 230

Monitoring and Controlling NodeBuilder Devices ................................. 230

Using the Data Point Shape ........................................................... 230

Using the LonMaker Browser ......................................................... 232

Connecting NodeBuilder Devices ......................................................... 235

10 Debugging a Neuron C Application.............................................

Introduction to Debugging ...........................................................................242

Starting the NodeBuilder Debugger...................................................... 242

Using the Debugger Toolbar................................................................. 244

Stopping an Application ........................................................................ 245

Halting an Application.....................................................................246

Running to the Cursor ....................................................................246

Setting and Using Breakpoints ....................................................... 246

Stepping Through Applications............................................................. 247

Debugging Interrupts for 5000 Series chips ......................................... 247

Using Statement Expansion.................................................................. 247

Using the Watch List Pane.................................................................... 247

Using the Call Stack Pane ....................................................................251

Using the Debug Device Manager Pane............................................... 251

Peeking and Poking Memory ................................................................ 252

Executing Code in Development Targets Only..................................... 253

Using the Debug Error Log Tab ............................................................ 253

Setting Debugger Options..................................................................... 253

217

229

241

Appendix A Using the Command Line Project Make Facility ........

Appendix B Using Source Control With a NodeBuilder Project ....

Appendix C Glossary.........................................................................

Appendix D NodeBuilder Software License Agreement.................

257

261

265

279

NodeBuilder FX User's Guide vii

viii Preface

Preface

The NodeBuilder FX Development Tool is a complete hardware and software

platform that is used to develop applications for Neuron

Transceivers. The NodeBuilder tool lets you create, debug, test, and maintain

LONWORKS® devices. It includes a suite of device development software that you

can use to develop device applications, and hardware platforms that you can use to

build and test prototype and production devices.

®

Chips and Echelon® Smart

NodeBuilder FX User's Guide ix

Purpose

This document describes how to use the NodeBuilder tool to develop LONWORKS device applications
and build and test prototype and production L

ONWORKS devices.

Audience

This guide is intended for device and system designers with an understanding of control networks.

Hardware Requirements

Requirements for computers running the NodeBuilder tool are listed below:

• Microsoft

latest service pack available from Microsoft for your version of Windows.

• Intel® Pentium

requirements for the selected version of Windows.

• 300 to 550 megabytes (MB) free hard-disk space, plus the minimum Windows requirements for

the selected version of Windows.

®

Windows Vista or Microsoft Windows XP. Echelon recommends that you install the

®

III 600MHz processor or faster, and meeting the minimum Windows

o The NodeBuilder tool requires 100 MB of free space.

®

o The LonMaker

Integration Tool, which is included with the NodeBuilder software and is

required to install the NodeBuilder tool, requires 172 MB of free space.

o The LonScanner

™

Protocol Analyzer, which is included with the NodeBuilder software,

requires 26 MB of free space.

o Microsoft .NET Framework 3.5 SP1, which is required to run the NodeBuilder tool, requires

30 MB of free space.

®

o If you install Acrobat

Reader 9.1 from the NodeBuilder FX Development Tool CD, you

need an additional 204 MB of free space.

• 512 MB RAM minimum.

Note: Vista testing for the NodeBuilder tool has been performed on computers that have a
minimum of 2 GB of RAM. For complete Vista requirements, refer to

www.microsoft.com/windows/windows-vista/get/system-requirements.aspx. You can use

Microsoft’s Vista Upgrade Advisor to determine upgrade requirements for a particular computer.
To download this tool, go to the Microsoft Web site at

www.microsoft.com/windows/windows-vista/get/upgrade-advisor.aspx.

• CD-ROM drive.

• 1024x768 or higher-resolution display with at least 256 colors.

• Mouse or compatible pointing device.

• LNS

®

network interface or IP-852 router. If an LNS network interface is used, it may be a local or

remote interface.

o Compatible local network interfaces include the U10/U20 USB network interface (included

with the NodeBuilder FX/FT and FX/PL Development Kits); PCC-10, PCLTA-20, or
PCLTA-21 network interfaces; and the SLTA-10 Serial LonTalk Adapter.

®

o Compatible remote network interfaces include the i.LON

Internet Server, i.LON 600 L

ONWORKS-IP Server, or i.LON 10 Ethernet Adapter.

SmartServer, i.LON 100 e3

x Preface

o Compatible IP-852 routers include the i.LON SmartServer with IP-852 routing, i.LON 100 e3

Internet Server with IP-852 routing, or an i.LON 600 L
an IP-852 router, your computer must have an IP network interface such as an Ethernet card
or modem with PPP software. In addition, the i.LON software must be installed on your
computer, and the IP-852 channel must be configured using the L
Server application software.

The LonMaker tool, which is included with the NodeBuilder software, automatically installs
drivers for all local and remote network interfaces, except the SLTA-10 Serial LonTalk Adapter.
The LonMaker CD includes an option for installing the driver for the SLTA-10 Serial LonTalk
Adapter.

Note: You must run the NodeBuilder software on the same computer with the LNS Server which
is installed by the LonMaker installer. You cannot run the NodeBuilder tool as a remote client to
an LNS Server running on another computer.

Content

This guide includes the following content:

•

Introduction: Lists the new features in the NodeBuilder FX tool, summarizes the components
included with the NodeBuilder tool, and provides an overview of NodeBuilder device
development and L

ONWORKS networks.

ONWORKS-IP Server. If you are using

ONWORKS-IP Configuration

•

Installing the NodeBuilder FX Development Tool. Describes how to get started with your
NodeBuilder tool, including how to install the NodeBuilder software and connect the NodeBuilder
hardware.

NodeBuilder Quick-Start Exercise. Demonstrates how to create a LONWORKS device using the

•

NodeBuilder tool.

•

Creating and Opening NodeBuilder Projects. Describes how to create, open, and copy
NodeBuilder projects, and explains how to copy NodeBuilder projects and NodeBuilder device
templates to another computer.

Creating and Using Device Templates. Describes how to use the New Device Template wizard in

•

the NodeBuilder Project Manager to create, manage, and edit NodeBuilder device templates.
Explains how to manage development and release targets and insert libraries into a device
template. Describes how to use the Hardware Template Editor to create and edit hardware
templates.

Defining Device Interfaces and Creating their Neuron C Application Framework. Describes how

•

to use the NodeBuilder Code Wizard to define your device interface and generate Neuron C code
that implements it. Explains how to start the NodeBuilder Code Wizard, how to add functional
blocks, network variables, and configuration properties to your device template, and how to create
the Neuron C framework for your device interface.

Developing Device Applications. Provides an overview of the Neuron C Version 2.2

•

programming language. Describes how to edit the Neuron C source code generated by the
NodeBuilder Code Wizard to implement your device functionality. Explains how to use the
NodeBuilder Editor to edit, search, and bookmark Neuron C code.

Building and Downloading Device Applications. Describes how to compile Neuron C source

•

code, build an application image, and download the application image to a device. Explains how
to add target devices to a NodeBuilder project and how to manage them.

Testing a NodeBuilder Device Using the LonMaker Tool. Describes how to use the Data Point

•

shape and LonMaker Browser in the LonMaker tool to monitor and control your device. It
explains how to use the LonMaker tool to connect your NodeBuilder device to other L

ONWORKS

devices in a network.

NodeBuilder FX User's Guide xi

Debugging a Neuron C Application. Describes how the use the NodeBuilder debugger to

•

troubleshoot your Neuron C application.

• Appendices. Provides information for using the command line project make facility and managing

a NodeBuilder project using a source control application. Includes a glossary with definitions for
many terms commonly used with NodeBuilder device development, and it includes the
NodeBuilder Software License agreement.

Note: Screenshots in this document were taken during the development of the NodeBuilder FX tool;
therefore, some images may vary slightly from the release version of the user interface.

Related Manuals

The documentation related to the NodeBuilder tool is provided as Adobe® PDF files and online help
files. The PDF files are installed in the Echelon NodeBuilder program folder when you install the
NodeBuilder tool. You can download the latest NodeBuilder documentation, including the latest
version of this guide, from Echelon’s Web site at

The following manuals provide supplemental information to the material in this guide. You can
download these documents from Echelon’s Web site at

FT 5000 EVB Examples Guide Describes how to run the Neuron C example applications

www.echelon.com/docs.

www.echelon.com.

included with the NodeBuilder FX/FT Development tool on an
FT 5000 EVB.

FT 5000 EVB Hardware Guide Describes how to connect the FT 5000 EVBs, and describes the

Neuron core, I/O devices, service pin and reset buttons and
LEDs, and jumper settings on the FT 5000 EVB hardware.

One or two FT 5000 EVBs are included with the NodeBuilder
FX/FT Development Tool.

Gizmo 4 User’s Guide Describes how to use the I/O devices on the Gizmo 4 I/O Board,

and how to use the Gizmo 4 I/O Board to build your own I/O
hardware.

The Gizmo 4 I/O Board is included with the NodeBuilder FX/PL
Development Tool.

Introduction to the L
Platform

ONWORKS

®

Provides a high-level introduction to L

ONWORKS networks and

the tools and components that are used for developing, installing,
operating, and maintaining them.

®

Plug-in Programmer’s Guide

LNS

Describes how to write plug-ins using .NET programming
languages such as C# and Visual Basic .NET

LonMaker

L

ONMARK

®

User’s Guide

®

SNVT and SCPT Guide

Describes how to use the LonMaker Integration Tool to design,
commission, modify, and maintain L

ONWORKS networks.

Documents the standard network variable types (SNVTs),
standard configuration property types (SCPTs), and standard
enumeration types that you can declare in your applications.

LonScanner™ Protocol Analyzer
User’s Guide

Describes how to use the LonScanner Protocol Analyzer to
monitor, analyze, and diagnose ISO/IEC 14908-4,

ONWORKS/IP, and native ISO/IEC 14908-1 channels, and how

L
to interpret the data that the protocol analyzer collects.

xii Preface

ONWORKS

L

®

User’s Guide

USB Network Interface

Describes how to install and use the U10 and U20 USB Network
Interfaces, which are included with NodeBuilder FX/FT
Development Tool and NodeBuilder FX/PL Development Tool,
respectively.

LTM-10A User’s Guide Describes how to use the LTM-10A Platform for testing your

applications and I/O hardware prototypes. Also describes how
you can design the LTM-10A Flash Control Module into your
products.

The LTM-10A Platform is included with the NodeBuilder
FX/PL Development Tool.

Neuron

®

C Programmer’s Guide

Describes how to write programs using the Neuron

®

C Version

2.2 language.

Neuron

®

C Reference Guide

Provides reference information for writing programs using the
Neuron C language.

®

Neuron

Tools Error Guide

NodeBuilder

®

FX/PL Examples Guide

Provides reference information for Neuron tool errors.

Describes how to run the Neuron C example application included
with the NodeBuilder FX/PL Development tool on the
LTM-10A Platform/Gizmo 4 I/O Board.

NodeBuilder
Guide

®

Resource Editor User’s

Describes how to use the NodeBuilder Resource Editor to create
and edit resource file sets and resources such as functional
profile templates, network variable types, and configuration
property types.

For More Information and Technical Support

The NodeBuilder ReadMe file provides descriptions of known problems, if any, and their
workarounds. To view the NodeBuilder ReadMe, click Start, point to Programs, point to
NodeBuilder, and then select NodeBuilder ReadMe First. You can also find additional information
about the NodeBuilder tool at the NodeBuilder Web page at

If you have technical questions that are not answered by this document, the NodeBuilder online help,
or the NodeBuilder ReadMe file, you can contact technical support. To receive technical support from
Echelon, you must purchase support services from Echelon or an Echelon support partner. See

www.echelon.com/support for more information on Echelon support and training services.

You can also enroll in training classes at Echelon or an Echelon training center to learn more about
developing devices. You can find additional information about device development training at

www.echelon.com/training/.

You can obtain technical support via phone, fax, or e-mail from your closest Echelon support center.
The contact information is as follows:

Region Languages Supported Contact Information

The Americas

English
Japanese

www.echelon.com/nodebuilder.

Echelon Corporation
Attn. Customer Support
550 Meridian Avenue
San Jose, CA 95126
Phone (toll-free):
1-800-258-4LON (258-4566)
Phone: [phone]
Fax: [phone]

[e-mail]

NodeBuilder FX User's Guide xiii

Region Languages Supported Contact Information

Europe

English
German
French
Italian

Echelon Europe Ltd.
Suite 12
Building 6
Croxley Green Business Park
Hatters Lane
Watford
Hertfordshire WD18 8YH
United Kingdom
Phone: [phone]
Fax: [phone]

[e-mail]

Japan

China

Other Regions

Japanese Echelon Japan

Holland Hills Mori Tower, 18F
5-11-2 Toranomon, Minato-ku
Tokyo 105-0001
Japan
Phone: [phone]
Fax: [phone]

[e-mail]

Chinese
English

Echelon Greater China
Rm. 1007-1008, IBM Tower
Pacific Century Place
2A Gong Ti Bei Lu
Chaoyang District
Beijing 100027, China
Phone: [phone]
Fax: [phone]

[e-mail]

English
Japanese

Phone: [phone]
Fax: [phone]

[e-mail]

xiv Preface

1

Introduction

This chapter introduces the NodeBuilder Development Tool. It lists the new features

in the NodeBuilder FX tool, summarizes the components included with the

NodeBuilder tool, and provides an overview of NodeBuilder device development and

LONWORKS networks.

NodeBuilder FX User's Guide 1

Introduction to the NodeBuilder Tool

The NodeBuilder FX Development Tool is a complete hardware and software platform for developing,
debugging, testing, and maintaining L
5000 Smart Transceiver and all previous-generation 3100 Series chips. You can use the NodeBuilder
tool all to create many types of devices, including VAV controllers, thermostats, washing machines,
card-access readers, refrigerators, lighting ballasts, blinds, and pumps. You can use these devices in a
variety of systems including building and lighting controls, factory automation, energy management,
and transportation.

You can use the NodeBuilder tool to do the following:

• View standard resource file definitions for standard network variable types (SNVTs), standard

configuration property (SCPTs), and standard functional profile templates (SFPTs).

• Create your own resource files with user-defined network variable types (UNVTs), user-defined
configuration property (UCPTs), and user-defined functional profile templates (UFPTs).

• Automatically generate Neuron C code that implements your device’s interface and provides the
framework for your device application.

• Edit your Neuron C code to implement your device’s functionality.

• Compile, build, and download your application to a development platform or to your own devices.

ONWORKS devices based on the Neuron 5000 Processor and FT

• Test with prototype I/O hardware on either the FT 5000 EVB Evaluation Boards included with the
NodeBuilder FX/FT tool and available separately, or LTM-10A Platform and Gizmo 4 I/O Board
included with the NodeBuilder FX/PL tool and available separately, or use your own custom
device to build and test your own I/O hardware.

• Install your device into a L

ONWORKS devices.

L

ONWORKS network and test how your device interoperates with other

New Features in the NodeBuilder FX Tool

The NodeBuilder FX tool includes support for Echelon’s new 5000 Series chips (the term used to
collectively refer to the Neuron 5000 Processor and FT 5000 Smart Transceiver), support for
Echelon’s new FT 5000 EVB, and the following key features:

• Increased network variable support.

• Neuron C Version 2.2 Enhancements

• Enhanced Hardware Template Editor

• Enhanced Code Wizard Template

• Enhanced Neuron C debugger

• New LNS Plug-in Framework Developer’s Kit

• Microsoft Windows Vista support

The following sections describe these new features.

5000 Series Chip Support

The NodeBuilder FX tool supports Echelon’s new Neuron 5000 Processor and FT 5000 Smart
Transceiver, which are designed for the L
smaller, and cheaper that previous-generation chips, as they include the following new features and
functions.

• Backwards compatibility for device applications.

• Improved memory architecture.

• Faster system clock.

2 Introduction

ONWORKS 2.0 platform. The 5000 Series chips are faster,

• Improved performance for arithmetic operations.

• User-programmable interrupts.

• Additional I/O model support.

The following sections describe these new features and functions.

Backwards Compatibility for Device Applications

The 5000 Series chips are compatible with device applications written for 3150 and 3120 Neuron
Chips and Smart Transceivers. You can use the NodeBuilder tool to port your old application to a
5000 Series chip. To do this, you open the device’s NodeBuilder project, update the Neuron Chip
model used by the hardware template to the Neuron 5000 processor or FT 5000 Smart Transceiver, and
then re-build the device application. See
information on using the Hardware Template Editor.

You can also use the NodeBuilder tool to upgrade your existing device applications to the new Version
3 code templates when porting them to a 5000 Series chip. The version 3 code templates include
improved code size, speed, and compliance with interoperability guidelines. To upgrade existing
device applications to the version 3 templates, see

Notes:

The Neuron firmware contains the implementation of the ISO/IEC 14908-1 protocol stack, the
application scheduler, and many frequently used functions. The functions included in the Neuron
firmware vary between firmware versions and chip models; therefore, when you rebuild an existing
application for a FT 5000 Smart Transceiver, the application may have a smaller or larger memory
footprint, subject to the application’s use of library functions.

Editing Hardware Templates in Chapter 5 for more

Using Code Wizard Templates in Chapter 6.

The Neuron C Version 2.2 language includes the following new keywords: interrupt, __lock,
stretchedtriac, __slow, __fast, and __parity. Some of these keywords use a double underscore

prefix to avoid any naming collisions within existing device applications.

Improved Memory Architecture

The 5000 Series chips have a new memory architecture that speeds up the CPU operation and lowers
development and device costs. The 5000 Series chips have internal on-chip memory that includes 16
KB of ROM to store the Neuron firmware image and 64 KB of RAM (44 KB is available for
application code and data). The 5000 Series chips use external serial memory (EEPROM or flash) to
store your application code, configuration data, and an upgradable Neuron firmware image (the 5000
Series chips have no user-accessible on-chip non-volatile memory). The external serial EEPROM and
flash memory devices communicate with Neuron 5000 Core via a serial peripheral interface bus (SPI)
or Inter-Integrated Circuit (I
flash devices must use the SPI interface.

When a device is reset, the application code and configuration data are copied from the external
non-volatile memory into the internal on-chip RAM, and the device application is then executed. The
5000 Series chips require at least 2KB of off-chip EEPROM to store configuration data, and you can
use a larger capacity EEPROM device or an additional flash device (up to 64 KB) to store your
application code and an upgradable Neuron firmware image.

The 5000 Series chips also include a new interrupt processor (ISR) that handles user-programmable
interrupts, which improves chip performance.

Note: Many types of EEPROM devices are supported; however, Echelon currently supports and
provides drivers for three external flash devices: Atmel AT25F512AN, ST M25P05-AVMN6T, and
SST25VF512A. You can configure the external non-volatile memory used by a device in the
Hardware Template Editor. For more information on using the Hardware Template Editor, see
Hardware Templates in Chapter 5.

2

C) interface. EEPROM devices can use either the SPI or I2C interfaces;

Using

The following graphic illustrates the memory architecture of the 5000 Series chips. For more
information on the memory architecture of the 5000 Series chips, see the 5000 Series Chip Data Book.

NodeBuilder FX User's Guide 3

Faster System Clock

The 5000 Series chips support an internal system clock speed of up to 80 MHz (using an external 10
MHz crystal). This results in application processing power that equals a hypothetical FT 3150 Smart
Transceiver operating at an external clock speed of 160MHz. You can adjust the internal system clock
speed from 5 MHz to 80 MHz based on the device’s hardware template maintained by the
NodeBuilder Development Tool. For more information on configuring the system clock of the 5000
Series chips, see

Editing Hardware Templates in Chapter 5.

Improved Performance for Arithmetic Operations

The 5000 Series chips include 8-bit hardware multipliers and dividers, which are supported by new
Neuron assembly language instructions for multiplication and division. These instructions use
hardware multiply and divide functions to provide improved performance for 8-bit multiplication and
division. The older software multiplication and division system functions are still supported, but many
of these functions automatically benefit from these faster hardware multipliers and dividers.

User-Programmable Interrupts

The 5000 Series chips let you define user interrupts that can handle asynchronous I/O events,
timer/counter events, and a dedicated, high-resolution system timer. A hardware semaphore is
supplied to help you control access to data that is shared between the application (APP) and interrupt
(ISR) processors on the 5000 Series chips.

At higher system clock rates (20 MHz or greater), these interrupts can run in the dedicated interrupt
processor (ISR) on the chip. This improves the performance of the interrupt routines and your device
application. At lower system clock rates, these interrupts run in the same application processor (APP)
as the device application.

4 Introduction

Additional I/O Model Support

The 5000 Series chips include hardware support for the Serial Peripheral Interface (SPI) and Serial
Communication Interface (SCI) serial I/O models, which provide increased performance for devices
that use these interfaces. The UART on the 5000 Series chips includes an increased FIFO (16 bytes),
and supports software-configurable parity generation and validation (odd, even, none).

Overall, the 5000 Series chips support 35 I/O models, including all of the I/O models that were
previously only supported by the PL 3120, PL 3150, and PL 3170 Smart Transceivers. These I/O
models include the Infrared Pattern model, Magcard Bitstream model, SCI model, and SPI model.

In addition, the 5000 Series chips support the Stretched Triac model, which is a new I/O model that
improves performance for triac devices used with inductive loads.

FT 5000 EVB Evaluation Board

The FT 5000 EVB is a complete 5000 Series LONWORKS device that you can use to evaluate the

ONWORKS 2.0 platform and create LONWORKS devices. The FT 5000 EVB includes a FT 5000

L
Smart Transceiver with an external 10 MHz crystal (you can adjust the system’s internal clock speed
from 5MHz to 80MHz), an FT-X3 communication transformer, 64KB external serial EEPROM and
flash memory devices, and a 3.3V power source. The FT 5000 EVB features a compact design that
includes the following I/O devices that you can use to develop prototype and production devices and
test the FT 5000 EVB example applications:

• 4 x 20 character LCD

• 4-way joystick with center push button

• 2 push-button inputs

• 2 LED outputs

• Light-level sensor

• Temperature sensor

The FT 5000 EVB Evaluation Board also includes EIA-232/TIA-232 (formerly RS-232) and USB
interfaces that you can use to connect the board to your development computer and perform
application-level debugging. You can also use the EIA-232 interface for development with the
ShortStack

Note: You cannot run ShortStack 2.1 Micro Servers on the FT 5000 EVB.

Each FT 5000 EVB also features a flash in-circuit emulator (ICE) header that supports the SPI and I
interfaces for fast downloads when programming the external non-volatile memory of the FT 5000
Smart Transceiver on the board.

For more information on the FT 5000 EVB hardware, including detailed descriptions of its Neuron
core, I/O devices, service pin and reset buttons and LEDs, and jumper settings, see the FT 50000 EVB
Hardware Guide.

®

Developer’s Kit. Note that only one interface can be used at a time.

Increased Network Variable Support

Neuron chips that use version 16 firmware or greater can support up to 254 static network variables
and 127 network variable aliases for Neuron-hosted devices, subject to available system resources (for
example, RAM and EEPROM) and application requirements. The 5000 Series chips use the new
version 18 Neuron firmware and therefore support these increased network variable limits, subject to
resources.

2

C

You must build the device application with the NodeBuilder FX tool to take advantage of these
increased network variable limits. If you use a previous release of the NodeBuilder tool, your device
application is limited to 62 network variables.

NodeBuilder FX User's Guide 5

Neuron C Version 2.2 Enhancements

The new features in the Neuron C Version 2.2 programming language include interrupt support,
non-constant device-specific configuration properties, and new and enhanced compiler directives.
These new features are detailed in the Neuron C Programmer’s Guide and Neuron C Reference Guide.

Interrupt Support

The 5000 Series chips support hardware user interrupts in addition to the support provided through I/O
models. The Neuron C Version 2.2 language includes new keywords to manage hardware user
interrupts and a semaphore for application programs. The 5000 Series chips support the following
three types of interrupts: I/O interrupts, timer/counter driven interrupts, and periodic system interrupts.

When the 5000 Series chips are running at a system clock rate of 20 MHz or greater, these interrupts
execute in the separate interrupt processor on the chips, which improves the performance of the
interrupt and the device application.

Non-Constant Device-Specific Configuration Property Support

The Neuron C Version 2.2 language supports non-constant device-specific configuration properties.
Non-constant device-specific configuration properties have values that can be modified by the device
application, an LNS network tool such as the LonMaker tool, or another tool not based on LNS. For
example, a thermostat may include a user interface that allows the user to change the setpoint.

New and Enhanced Compiler Directives

The Neuron C Version 2.2 language includes new compiler directives and existing compiler directives
that have been enhanced to help you develop location-independent and modular code.

You can enable and disable specific errors and warnings using the new #error and #warning compiler
directives. You can use the new #pragma library directive to indicate custom library that is required.
You can use enhanced buffer control directives for statements of minimum or final requirements.

Compiler directives for control of the Neuron C Optimizer have been streamlined, and a new
optimization phase for generating more compact code has been added.

Enhanced Hardware Template Editor

The Hardware Template Editor in the NodeBuilder tool now supports hardware templates based on the
Neuron 5000 Processor or the FT 5000 Smart Transceiver, and is now available as a standalone tool.

For 5000 Series chips, you use the Hardware Template Editor to map external non-volatile memory
from 0x4000 to 0xE7FF in the Neuron address space (a maximum of 42 KB). The 5000 Series chips
support external serial EEPROM or serial flash devices for off-chip non-volatile memory. Echelon
currently supports and provides drivers for three flash devices (Atmel AT25F512AN, ST
M25P05-AVMN6T, and SST25VF512A).

For more information on using the Hardware Template Editor, see
Chapter 5.

Using Hardware Templates in

Enhanced Code Wizard Framework Template

The new Code Wizard Framework Version 3 Template supports large functional block and network
variable counts and includes fixes and improvements to code, code layout, and comments. New device
applications are automatically built using the Version 3 templates, and you can manually upgrade
existing applications to this version. The Code Wizard also supports continued maintenance of
applications based on Version 2 templates. For more information on upgrading existing device
applications to the new Code Wizard framework template, see
Chapter 6.

Using Code Wizard Templates in

6 Introduction

Neuron C Debugger

The NodeBuilder debugger provides an option to write all breakpoints to RAM and not have them
copied to the external non-volatile memory. This option lets you set breakpoints and single step
through the memory of a 5000 Series Chip, without causing excessive writes to the external
non-volatile memory that could cause the memory to fail. For more information on using breakpoints
while debugging, see

Setting and Using Breakpoints in Chapter 10.

LNS Plug-in Framework Developer’s Kit

You can use the new LNS Plug-in Framework Developer’s Kit to write LNS device plug-ins in .NET
programming languages such as C# and Visual Basic .NET. The LNS Plug-in Framework Developer’s
Kit allows plug-ins to function in the .NET environment and interface with director applications. It
includes the .NET components needed for interfacing with the COM-based LNS API in the .NET
environment. It provides a set of example software and framework assemblies that let you efficiently
develop plug-ins with the latest .NET programming tools and re-distribute your plug-ins.

The LNS Plug-in Framework Developer’s Kit is automatically installed on your computer when you
install the NodeBuilder FX Development Tool CD. For more information on writing LNS device
plug-ins and the LNS Plug-in API, see the LNS Plug-in Programmer’s Guide.

Note: The LNS Plug-in Wizard, which generated code for Microsoft Visual Basic 6.0, has been
removed from the NodeBuilder tool and is no longer supported. You can still download the LNS
Plug-in Wizard from the Echelon Web site at

www.echelon.comdownloads.

Microsoft Windows Vista Support

The NodeBuilder FX Development Tool and the NodeBuilder online help files are compatible with
Microsoft Windows Vista.

What's Included with the NodeBuilder FX Tool

There are four NodeBuilder FX products: the NodeBuilder FX/FT Development Tool, the NodeBuilder
FX/PL Development Tool, the NodeBuilder FX/FT Classroom Edition, and the NodeBuilder FX CD.

The NodeBuilder FX/FT Classroom Edition is for educational-use only. The NodeBuilder FX CD is
for developers who do not require development hardware such as NodeBuilder 3.1 users or Mini FX
users who want to upgrade from an evaluation kit to a development kit (the NodeBuilder FX/FT Tool
and Mini FX/FT Kit both include FT 5000 EVBs). The four NodeBuilder FX products consist of the
following components:

Component

NodeBuilder Development Tool CD

Development Platforms*

LonMaker Integration Tool
Professional Edition CD (includes
Microsoft Visio 2003 Professional)

FX/FT and

FX/PL Tools

5 5 5

5 5 

5  5

Classroom

Edition

CD

LonMaker Integration Tool Standard
Edition CD (includes Microsoft Visio
2003 Standard)

LonScanner Protocol Analyzer LNS

NodeBuilder FX User's Guide 7

 5 

5 5 5

Turbo Edition CD

U10/U20 USB Network Interface

* The NodeBuilder FX/FT Development Tool and NodeBuilder FX/FT Classroom Edition include two FT 5000 EVBs. The

NodeBuilder FX/PL Tool includes one LTM-10A Hardware Platform and one NodeBuilder Gizmo 4 I/O Board (for
development of PL devices).

The following sections describe each of the components.

5 5 

NodeBuilder FX Development Tool CD

The NodeBuilder Development Tool CD contains the software required to develop and debug Neuron
C applications for your L
can run on your development platform and use to further learn how to develop your own device
applications.

The NodeBuilder software includes the following components:

• NodeBuilder Resource Editor. View standard types and functional profiles, and create
user-defined types and profiles if the standard resource files do not include the resources you need.

• NodeBuilder Code Wizard. Use a drag-and-drop interface to create your device’s interface and
then automatically generate Neuron C source code that implements the device interface and
creates the framework for your device application.

• NodeBuilder Editor. Edit the Neuron C source code generated by the Code Wizard to create your
device’s application.

• NodeBuilder Debugger. Debug your application with a source-level view of your application code
as it executes.

ONWORKS devices, and it includes Neuron C example applications that you

• NodeBuilder Project Manager. Build and download your application image to your development
platform or to your own device hardware.

The NodeBuilder FX/FT Development tool and NodeBuilder FX/FT Classroom Edition include three
Neuron C example applications that you can run on your FT 5000 EVB, and the NodeBuilder FX/PL
Development tool includes one Neuron C example application that you can run on your LTM-10A
platform with Gizmo 4 I/O board. You can use these examples to test the I/O devices on the FT 5000
EVB or Gizmo 4 I/O board, and create simple L
code used in the example applications, and then create a new device application by modifying the
existing example applications or by developing the device application from scratch.

For more information on using the FT 5000 EVB example applications, see the FT 5000 EVB
Examples Guide. For more information on using the LTM-10A Platform–Gizmo 4 I/O Board example
application, see the NodeBuilder FX/PL Examples Guide.

ONWORKS networks. You can view the Neuron C

Development Platforms

The NodeBuilder FX/FT Development Tool includes two FT 5000 EVBs. The NodeBuilder FX/PL
Development Tool includes the LTM-10A Hardware Platform, a PLM-22 power line transceiver,
power line couplers for line-to-earth coupling and line-to-neutral coupling, and the NodeBuilder
Gizmo 4 I/O Board. The following sections describe these development platforms.

FT 5000 EVB Evaluation Board

The FT 5000 EVB is a complete 5000 Series LONWORKS device that you can use to evaluate the

ONWORKS 2.0 platform and create LONWORKS devices. The FT 5000 EVB includes an FT 5000

L
Smart Transceiver with an external 10 MHz crystal (you can adjust the system’s internal clock speed
from 5MHz to 80MHz), an FT-X3 communication transformer, 64KB external serial EEPROM and
flash memory devices, and a 3.3V power source. The FT 5000 EVB features a compact design that

8 Introduction

includes the following I/O devices that you can use to develop prototype and production devices and
test the FT 5000 EVB example applications:

• 4 x 20 character LCD

• 4-way joystick with center push button

• 2 push-button inputs

• 2 LED outputs

• Light-level sensor

• Temperature sensor

The FT 5000 EVB Evaluation Board also includes an EIA-232/TIA-232 (formerly RS-232) and USB
interfaces that you can use to connect the board to your development computer and perform
application-level debugging. You can also use the RS-232 interface for development with the
ShortStack

®

Developer’s Kit. Note that only one interface can be used at a time.

Note: You cannot run ShortStack 2.1 Micro Servers on the FT 5000 EVB.

2

Each FT 5000 EVB also features a flash ICE header that supports the SPI and I

C interfaces for fast
downloads when programming the external non-volatile memory of the FT 5000 Smart Transceiver on
the board.

For more information on the FT 5000 EVB hardware, including detailed descriptions of its Neuron
core, I/O devices, service pin and reset buttons and LEDs, and jumper settings, see the FT 50000 EVB
Hardware Guide.

LTM-10A Platform and NodeBuilder Gizmo 4 I/O Board

The NodeBuilder FX/PL Development Tool includes the LTM-10A Hardware Platform (right) and the
NodeBuilder Gizmo 4 I/O Board (left).

NodeBuilder FX User's Guide 9

LTM-10A Platform

The LTM-10A Platform is a complete LONWORKS device with downloadable flash memory and RAM
that you can use for testing your applications and I/O hardware prototypes.

The LTM-10A Platform includes an LTM-10A Flash Control Module (herein referred to as the
LTM-10A module) that you can design into your prototypes and products. The LTM-10A module
includes a Neuron Chip, 64 KB flash memory, 32 KB static RAM, 10 MHz crystal oscillator, and
custom Neuron firmware. The custom firmware allocates the memory to the Neuron Chip 64 KB
address space and automatically initializes the transceiver interface for standard transceivers. The
NodeBuilder tool can load your application image into the RAM or flash memory of the LTM-10A
module. An application image loaded into the flash memory is preserved when the module is powered
down. An application image loaded into the RAM is preserved when the module is reset, but not when
it is powered down. You can use the Neuron C Debugger to debug applications running in the RAM
or flash memory; however, you should debug your application running in RAM because extensive
debugging in the flash memory can cause the flash memory to fail.

The LTM-10A Platform also includes a PLM-22 power line transceiver with external power line
coupler for attaching the platform to a L

ONWORKS network. Two power line couplers are included,

one for line-to-earth coupling and one for line-to-neutral coupling.

For more information on the LTM-10A Platform and Flash Control Module, see the LTM-10A User’s
Guide.

NodeBuilder Gizmo 4 I/O Board

The NodeBuilder Gizmo 4 I/O Board is a collection of I/O devices that you can use with the LTM-10A
Platform for developing prototype devices and I/O circuits, developing special-purpose devices for
testing, or running the NodeBuilder examples. The Gizmo 4 includes the following I/O devices:

• 4 x 20 character LCD display

• 2 10-bit resolution analog inputs with screw terminal connector

• 2 8-bit resolution analog outputs with screw terminal connector

• 2 digital inputs with screw terminal connector and pushbutton inputs

• 2 digital outputs with screw terminal connector and LED outputs

• Digital shaft encoder

• Piezoelectric transducer

• Real-time clock

• Temperature sensor

10 Introduction

A Gizmo 4 I/O library is included with the NodeBuilder software that provides easy-to-use high-level
functions for accessing the display, analog I/O, piezo transducer, real-time clock, and temperature
sensor. For a description of the I/O devices on the Gizmo 4 board and a description of the Gizmo 4 I/O
library, see the Gizmo 4 User’s Guide.

LonMaker Integration Tool CD

The LonMaker tool is an integral part of your NodeBuilder development kit that you can use to install,
connect, configure, test, and update the devices in your project. It is a software package for designing,
installing, and maintaining L
system, the LonMaker tool combines a powerful, client-server architecture with an easy-to-use Visio
user interface. The LonMaker tool is compatible with a number of LNS plug-ins, including the
NodeBuilder Project Manager.

The LonMaker tool can be used to manage all phases of a network’s life cycle, from the initial design
and commissioning to the ongoing operation, because it provides the functionality of several network
tools in one single solution:

• Network Design Tool. You can design a network onsite or offsite (either connected to the network

over the Internet or not connected to it all), and then modify it anytime. The LonMaker tool can
also learn an existing network’s design through a process called network recovery.

• Network Installation Tool. You can rapidly install a network designed offsite once it is brought

onsite. The device definitions can be quickly and easily associated with their corresponding
physical devices to reduce on-site commissioning time. The LonMaker Browser provides
complete access to all network variables and configuration properties.

ONWORKS control networks. Based on Echelon’s LNS network operating

• Network Documentation Tool. You can create a LonMaker drawing during the network design

and installation process. This LonMaker drawing is an accurate, logical representation of the
installed physical network. The LonMaker drawing is therefore an essential component of as-built
reports.

• Network Operation Tool. You can operate the network using the operator interface pages

contained within the LonMaker drawing.

• Network Maintenance Tool. You can easily add, test, remove, modify, or replace devices, routers,

channels, subsystems, and connections to maintain the network.

This guide describes many of the LonMaker functions that you will use with the NodeBuilder tool.
See the LonMaker User’s Guide for more information on the LonMaker tool and to learn how it can be
used to install, operate, and maintain your operational networks in addition to your development
networks.

LonScanner Protocol Analyzer CD

The LonScanner Protocol Analyzer is a software package that provides network diagnostic tools to
observe, analyze, and diagnose the behavior of installed L
devices that you have built with the NodeBuilder tool. You can use the LonScanner tool with the U10
or U20 USB network interface included with the NodeBuilder FX/FT and FX/PL Tools, and you also
use it with other network interfaces including an IP-852 (ISO/IEC 14908-4) interface as described in
the LonScanner Protocol Analyzer User’s Guide. For more information on the LonScanner tool, see
the LonScanner Protocol Analyzer User’s Guide.

ONWORKS networks, including network with

U10/U20 USB Network Interface

The NodeBuilder FX/FT Development Tool and NodeBuilder FX/PL Development Tool include U10
and U20 USB network interfaces, respectively. The U10 and U20 USB Network Interfaces are
low-cost, high-performance L

NodeBuilder FX User's Guide 11

ONWORKS interfaces for USB-enabled computers and controllers.

The U10 USB Network Interface connects directly to TP/FT-10 Free Topology Twisted Pair (ISO/IEC
14908-2) L
Interface connects to PL-20 C-Band Power Line (ISO/IEC 14908-3) L

ONWORKS channels through a high-quality removable connector. The U20 USB Network

ONWORKS channels through an

included power supply with integrated coupler. The U20 USB Network Interface can also be
connected directly to 10.8-18VDC power systems (such as those in automobiles, trucks and buses)
without a coupling circuit, or to virtually any powered line through a customer-supplied coupler/power
supply.

The drivers for U10 and U20 USB network interfaces are automatically installed on your computer
when you install the LonMaker Integration Tool CD.

The USB Network Interfaces can be used with virtually any computer-based L
including all LNS

and OpenLDV

™

based applications such as the NodeBuilder Development tool,

ONWORKS application,

LonMaker tool, and LonScanner Protocol Analyzer.

For more information on installing and using the U10 and U20 USB network interfaces, see the
LonWorks USB Network Interface User’s Guide.

Introduction to NodeBuilder Device Development and LONWORKS Networks

A LONWORKS network consists of intelligent devices (such as sensors, actuators, and controllers) that
communicate with each other using a common protocol over one or more communications channels.
Network devices are sometimes called nodes.

Devices may be Neuron hosted or host-based. Neuron hosted devices run a compiled Neuron C
application on a Neuron Chip or Smart Transceiver. You can use the NodeBuilder tool to develop,
test, and debug Neuron C applications for Neuron hosted devices.

Host-based devices run applications on a processor other than a Neuron Chip or Smart Transceiver.
Host-based devices may run applications written in any language available to the processor. A
host-based device may use a Neuron Chip or Smart Transceiver as a communications processor, or it
may handle both application processing and communications processing on the host processor. The
NodeBuilder tool supports some of the common tasks occurring in the creation of host-based devices;
however, an additional host-based device development tool, such as the ShortStack
Kit or the FTXL

™

Developer’s Kit, is required.

®

2.1 Developer’s

Each device includes one or more processors that implement the ISO/IEC

14908-1 Control Network

Protocol (CNP). Each device also includes a component called a transceiver to provide its interface to
the communications channel.

A device publishes and consumes information as instructed by the application that it is running. The
applications on different devices are not synchronized, and it is possible that multiple devices may all
try to talk at the same time. Meaningful transfer of information between devices on a network,
therefore, requires organization in the form of a set of rules and procedures. These rules and
procedures are the communication protocol, which may be referred to simply as the protocol. The
protocol defines the format of the messages being transmitted between devices and defines the actions
expected when one device sends a message to another. The protocol normally takes the form of
embedded software or firmware code in each device on the network. The CNP

is an open protocol

defined by the ISO/IEC 14908-1 standard (defined nationally in the United States, Europe, and China
by the ANSI/EIA 709.1, EN 14908, and GB/Z 20177 standards, respectively).

Channels

A channel is the physical media between devices upon which the devices communicate. The LonTalk
protocol is media independent; therefore, numerous types of media can be used for channels: twisted
pair, power line, fiber optics, IP, and radio frequency (RF) to name a few. Channels are categorized
into channel types, and the channel types are characterized by the device transceiver. Common

12 Introduction

channel types include TP/FT-10 (ISO/IEC 14908-2 twisted pair free topology channel), TP/XF-1250
(high-speed twisted pair channel), PL-20 (ISO/IEC 14908-3 power line channel), FO-20
(ANSI/CEA-709.4 fiber optics channel), and IP-852 (ISO/IEC 14908-4 IP-communication).

Different transceivers may be able to interoperate on the same channel; therefore, each transceiver type
specifies the channel type or types that it supports. The choice of channel type affects transmission
speed and distance as well as the network topology.

The NodeBuilder tool, LonMaker tool, and LonScanner tool, and Neuron chips support all standard
channel types, but not all Neuron chips support all transceiver and channel types. Smart Transceivers
combine the transceiver and Neuron chip core in the same chip, and therefore support the channel
types supported by the integrated transceiver.

Routers

Multiple channels can be connected using routers. Routers are used to manage network message
traffic, extend the physical size of a channel (both length and number of devices attached), and connect
channels that use different media (channel types) together. Unlike other devices, routers are always
attached to at least two channels.

The NodeBuilder tool does not require routers, but the LonMaker tool can be used to create complex
networks that include multiple routers. Typically, device development networks use a simple
topology, but you can create a complex network when creating a device application with the
NodeBuilder tool.

Applications

Every LONWORKS device contains an application that defines the device’s behavior. The application
defines the inputs and outputs of the device. The inputs to a device can include information sent on

ONWORKS channels from other devices, as well as information from the device hardware (for

L
example, the temperature from a temperature sensing device). The outputs from a device can include
information sent on L
hardware (for example, a fan, light, heater, or actuator). You can use the NodeBuilder tool to write a
device’s Neuron C application.

ONWORKS channels to other devices, as well as commands sent to the device

Program IDs

Every LONWORKS application has a unique, 16 digit, hexadecimal Standard Program ID with the
format FM:MM:MM:CC:CC:UU:TT:NN. This Program ID is broken down into the following
fields:

Field Description

Format (F)

A 1 hex-digit value defining the structure of the program ID. The upper
bit of the format defines the program ID as a standard program ID (SPID)
or a text program ID. The upper bit is set for standard program IDs, so
formats 8–15 (0x8–0xF) are reserved for standard program IDs.

• Program ID format 8 is reserved for L

• Program ID format 9 is used for devices that will not be L

certified, or for devices that will be certified but are still in
development or have not yet completed the certification process.

ONMARK certified devices.

ONMARK

• Program ID formats 10–15 (0xA–0xF) are reserved for future use.

Text program ID formats are used by network interfaces and legacy
devices and, with the exception of network interfaces, should not be
used for new devices.

The NodeBuilder tool can be used to create applications with program ID

NodeBuilder FX User's Guide 13

Field Description

format 8 or 9.

Manufacturer ID (M)

Device Class (C)

Usage (U)

A 5 hex-digit ID that is unique to each L

ONWORKS device manufacturer.

The upper bit identifies the manufacturer ID as a standard manufacturer
ID (upper bit clear) or a temporary manufacturer ID (upper bit set).

• Standard manufacturer IDs are assigned to manufacturers when they

ONMARK International, and are also published by LONMARK

join L
International so that the device manufacturer of a L

ONMARK certified

device is easily identified. Standard manufacturer IDs are never
reused or reassigned. If your company is a L

ONMARK member, but

you do not know your manufacturer ID, you can find your ID in the
list of manufacturer IDs at

www.lonmark.org/spid. The most current

list at the time of release of the NodeBuilder tool is also included with
the NodeBuilder software.

• Temporary manufacturer IDs are available at no charge to anyone on

request by filling out a simple form at

www.lonmark.org/mid.

A 4 hex-digit value identifying the primary function of the device. This
value is drawn from a registry of pre-defined device class definitions. If
an appropriate device class designation is not available, L

ONMARK

International Secretary will assign one, upon request.

A 2 hex-digit value identifying the intended usage of the device. The
upper bit specifies whether the device has a changeable interface. The
next bit specifies whether the remainder of the usage field specifies a
standard usage or a functional-profile specific usage. The standard usage
values are drawn from a registry of pre-defined usage definitions. If an
appropriate usage designation is not available one will be assigned upon
request. If the second bit is set, a custom set of usage values is specified
by the primary functional profile for the device.

Channel Type (T)

A 2 hex-digit value identifying the channel type supported by the device’s

ONWORKS transceiver. The standard channel-type values are drawn

L
from a registry of pre-defined channel-type definitions. A custom
channel-type is available for channel types not listed in the standard
registry.

Model Number (N)

A 2 hex-digit value identifying the specific product model. Model
numbers are assigned by the product manufacturer and must be unique
within the device class, usage, and channel type for the manufacturer. The
same hardware may be used for multiple model numbers depending on the
program that is loaded into the hardware. The model number within the
program ID does not have to conform to your published model number.

See the

LonMark Application Layer Interoperability Guidelines for more

information about program IDs.

Network Variables

Applications exchange information with other LONWORKS devices using network variables. Every
network variable has a direction, type, and length. The network variable direction can be either input
or output, depending on whether the network variable is used to receive or send data. The network
variable type determines the format of the data.

14 Introduction

Network variables of identical type and length but opposite directions can be connected to allow the
devices to share information. For example, an application on a lighting device could have an input
network variable that was of the switch type, while an application on a dimmer-switch device could
have an output network variable of the same type. A network management tool such as the LonMaker
Integration Tool could be used to connect these two devices, allowing the switch to control the lighting
device, as shown in the following figure:

A single network variable may be connected to multiple network variables of the same type but
opposite direction. The following example shows the same switch being used to control three lights:

The application program in a device does not need to know where input network variable values come
from or where output network variable values go. When the application program has a changed value
for an output network variable, it simply assigns the new value to the output network variable.

Through a process called binding that takes place during network design and installation, the device is
configured to know the logical address of the other device or group of devices in the network
expecting that network variable’s values. The device’s embedded firmware assembles and sends the
appropriate packet(s) to these destinations. Similarly, when the device receives an updated value for
an input network variable required by its application program, its firmware passes the data to the
application program. The binding process thus creates logical connections between an output network
variable in one device and an input network variable in another device or group of devices.

Connections may be thought of as virtual wires. For example, the dimmer-switch device in the
dimmer-switch-light example could be replaced with an occupancy sensor, without making any
changes to the lighting device.

The NodeBuilder Code Wizard automatically generates the required network variable declarations for
your device’s interface in your device’s Neuron C application. Typically, you don’t need implement
any code in the device application to handle the binding process, or the source or destination devices

NodeBuilder FX User's Guide 15

for network variable values. Neuron C provides an easy-to-use programming model familiar to any C
language programmer that encapsulates the complexity of distributed applications.

Configuration Properties

LONWORKS applications may also contain configuration properties. Configuration properties allow
the device’s behavior to be customized using a network management tool such as the LonMaker tool or
a customized plug-in created for the device (see the LNS Plug-in Programmer’s Guide for more
information on creating LNS device plug-ins).

For example, an application may allow an arithmetic function (add, subtract, multiply, or divide) to be
performed on two values received from two network variables. The function to be performed could be
determined by a configuration property. Another example of a configuration property is a heartbeat
that determines how often a device transmits network variable updates over the network.

Like network variables, configuration properties have types that determine the type and format of the
data they contain.

The NodeBuilder Code Wizard automatically generates the required configuration property
declarations for your device’s interface and most of the required infrastructure code in your device’s
Neuron C application. The NodeBuilder tool supports configuration properties with an easy-to-use
programming model in Neuron C.

Functional Blocks

Applications in devices are divided into one or more functional blocks. A functional block is a
collection of network variables and configuration properties, which are used together to perform one
task. These network variables and configuration properties are called the functional block members.
For example, a digital input device could have four digital input functional blocks that contain the
configuration properties and output network variable members for each of the four hardware digital
inputs on the device.

The NodeBuilder Code Wizard automatically generates the required functional block declarations for
your device’s interface in your device’s Neuron C application.

A functional block is an implementation of a functional profile.

Functional Profiles

A functional profile defines mandatory and optional network variable and configuration property
members for a type of functional block. For example, the standard functional profile for a light
actuator has mandatory SNVT_switch input and output network variables, optional
SNVT_elapsed_tm and SNVT_elec_kwh output network variables, and a number of optional
configuration properties. The following diagram illustrates the components of the standard light
actuator functional profile:

16 Introduction