Echelon NodeBuilder FX-PL Examples User Manual

NodeBuilder

Examples Guide

FX/PL

0 7 8 - 0 4 0 3 - 0 1 A

Echelon, LON, LonWorks, Neuron, 3120, 3150, Digital Home, i.LON, LNS, LonMaker, LonMark, LonPoint, LonTalk, NodeBuilder, and the Echelon logo are trademarks of Echelon Corporation registered in the U nited States and other countries. 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.

Preface .................................................................................................... iv

Purpose ...........................................................................................................v

Audience..........................................................................................................v

System Requirements..................................................................................... v

Content........................................................................................................... vi

Related Manuals............................................................................................. vi

For More Information and Technical Support.................................................vii

1 Using the NodeBuilder FX/PL Example........................................... 1

Introduction to the NodeBuilder FX/PL Example.............................................2

Using the Pre-Built Example Device Application......................................4

Restoring the LonMaker Network Backup..........................................4

Downloading the Example Application...............................................8

Testing the I/O Devices on the Gizmo 4 I/O Board..........................10

Testing Switch and Lamp Devices.............................................10

Testing Alarm Devices...............................................................11

Creating the Example Device Application...............................................14

Step 1: Creating the NodeBuilder Project .......................................14

Step 2: Configuring the Node Object................................................15

Step 3: Adding Digital I/O.................................................................16

Step 4: Implementing Analog Input and Output...............................18

Step 5: Implementing a Simple Type Translator..............................22

Step 6: Enhancing the Type Translator............................................23

Step 7: Implementing the Temperature Sensor...............................25

Step 8: Implementing the Real Time Keeper ...................................27

Step 9: Implementing the Wheel Input.............................................30

Continuing with the NodeBuilder Example....................................................34

NodeBuilder FX/PL Examples Guide iii

Preface

The NodeBuilder® FX/PL Development Tool includes a Neuron C example

application that you can load into your LTM-10A Platform. You can use this

example to test the I/O devices on the Gizmo 4 I/O Board, and create a simple

managed LONWORKS® network. You can follow the instructions in this document to

create the example device application from scratch.

iv Preface

Purpose

This document describes how to load and use the Neuron C example application included with the NodeBuilder FX/PL Development Tool.

Audience

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

System Requirements

Requirements for computers running the NodeBuilder PL examples 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 U20 USB network interface (included with

the NodeBuilder FX/PL Development Tool.

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

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

ONWORKS-IP Server. If you are using

NodeBuilder FX/PL Examples Guide v

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:

•

Using the NodeBuilder FX/PL Example. Introduces the Neuron C example application that you can run on an LTM-10A Platform and test with the Gizmo 4 I/O Board. Describes how to load the pre-built example application on an LTM-10A Platform using the LonMaker Integration Tool, which is included with the NodeBuilder FX Development tool, and describes how to use the I/O devices on the Gizmo 4 I/O Board to test the example application. Includes a detailed nine-step exercise that you can follow to create the example device application from scratch.

ONWORKS-IP Configuration

Related Manuals

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

www.echelon.com/docs.

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

ONWORKS

Platform

Plug-in Programmer's Guide

LNS

LonMaker

ONMARK

ONWORKS

User’s Guide

SNVT and SCPT Guide

USB Network Interface

User's Guide

Provides a high-level introduction to L the tools and components that are used for developing, installing, operating, and maintaining them.

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

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

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

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

ONWORKS networks and

ONWORKS networks.

vi Preface

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

applications and I/O hardware prototy pes. 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 Neur on

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

NodeBuilder Guide

FX User’s Guide

Resource Editor User’s

Provides reference information for Neuron C errors. Describes how to use the NodeBuilder tool to develop

ONWORKS device applications and build and test prototype and

L production L

ONWORKS devices

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: +1-408-938-5200 Fax: +1-408-790-3801

lonsupport@echelon.com

NodeBuilder FX/PL Examples Guide vii

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: +44 (0)1923 430200 Fax: +44 (0)1923 430300

lonsupport@echelon.co.uk

Japan

China

Other Regions

Japanese Echelon Japan

Holland Hills Mori Tower, 18F 5-11-2 Toranomon, Minato-ku Tokyo 105-0001 Japan Phone: +81-3-5733-3320 Fax: +81-3-5733-3321

lonsupport@echelon.co.jp

Chinese English

Echelon Greater China Rm. 1007-1008, IBM Tower Pacific Century Place 2A Gong Ti Bei Lu Chaoyang District Beijing 100027, China Phone: +86-10-6539-3750 Fax: +86-10-6539-3754

lonsupport@echelon.com.cn

English Japanese

Phone: +1-408-938-5200 Fax: +1-408-328-3801

lonsupport@echelon.com

viii Preface

Using the NodeBuilder FX/PL Example

This chapter introduces the Neuron C example application that you can run on an

LTM-10A Platform and test with the Gizmo 4 I/O Board. It describes how to load

the pre-built example application on an LTM-10A Platform using the LonMaker

Integration Tool, which is included with the NodeBuilder FX Development tool, and

how to use the I/O devices on the Gizmo 4 I/O Board to test the example application.

It includes a detailed nine-step exercise that you can follow to create the example

device application from scratch.

NodeBuilder FX/PL Examples Guide 1

Introduction to the NodeBuilder FX/PL Example

The NodeBuilder FX/PL Development Tool includes a Neuron C example application, NcExample, that you can load into your LTM-10A Platform. You can use this example application to test the I/O devices on the Gizmo 4 I/O Board, and create simple managed L

The example application is designed to run on a Gizmo 4 I/O Board attached to an LTM-10A Platform. If you do not have a Gizmo 4 I/O Board, you can still use the NodeBuilder tool to create and compile the application, but you cannot observe how the device application interacts with the I/O devices Gizmo 4 I/O Board.

The NcExample device application is stored the C:\LonWorks\NeuronC\Examples\NodeBuilder LTM-10A directory. Note that the default L C:\LonWorks or C:\Program Files\LonWorks.

ONWORKS folder on your computer is typically

ONWORKS networks.

The NodeBuilder LTM-10A folder contains the following files and subfolders:

Database

NcExample

PlugIn

This folder contains a LonMaker network backup file (.zip) that includes an LNS database and LonMaker drawing containing the example device and all the functional blocks and network variables in the device’s external interface. You can restore this backup file with the LonMaker tool. When you restore this backup, the LNS database and LonMaker drawing are placed in the C:\Lm\Db and C:\Lm\Drawings folders, respectively.

After you restore the network, you can use the LonMaker tool to download the example application to your LTM-10A Platform and test the I/O devices on the Gizmo 4 I/O Board.

This folder contains the example NodeBuilder project and all source code files and header files used by the NcExample device application.

This folder contains the LNS device plug-in used to configure the NcExample device application.

2 Using the NodeBuilder FX/PL Example

Released Binaries

Types

NodeBuilder Project Files (.NbOpt and .NbPrj)

The NcExample device application includes a pre-built binary application image file (.apb extension) that you can download to your LTM-10A Platform using the LonMaker tool. This folder also contains a pre-built text device interface file (.xif extension) that exposes the example application’s device interface so that the LonMaker tool can manage the example application.

After you restore the backup and load the NcExample device application, you can test the I/O devices on the Gizmo 4 I/O Board in a simple managed L

ONWORKS network (see Testing the

I/O Devices on the Gizmo 4 I/O Board later in this chapter for how to do this).

This folder contains the user-defined functional profiles (UFPTs), network variable types (UNVTs), and con fig urat ion property types (UCPTs) developed f or t he NcExample device application.

The example includes a NodeBuilder project that you can open with the NodeBuilder tool in order browse the example application and learn how to develop your own device applications. The NodeBuilder project includes the following files:

• Options File (*.NbOpt). Contains the NodeBuilder project

options for a project. There is one options file per project.

• Project File (*.NbPrj). Contains a project definition

including the project version and a list of the device templates and the hardware templates for a project. There is one project file per project.

You can use the pre-built NcExample device application to observe ho w n et wo rk vari able values are updated when you use the I/O devices on the Gizmo 4 I/O Board. To do this, you restore a LonMaker network backup, commission the example device in the LonMaker drawing, and press the buttons on the Gizmo 4 I/O Board.

When you are done using the NcExample device application, you can create your own example device application. You can create a simple device application following the quick-start exercise in Chapter 3 of the NodeBuilder User’s Guide; you can create a more complex device application fo llowing the steps described in

Creating the Example Device Application later in this chapter. In both exercises, you will go through all the steps of creating a device, including creating the NodeBuilder project, the device template, the device interface, and the Neuron C code that implements your device interface; implementing device functionality in the Neuron C code; building and downloading the device application; and testing the device in a L

ONWORKS network.

In the quick-start exercise in the NodeBuilder User’s Guide, you will develop a simple device with one sensor and one actuator. The sensor is a simple sensor that monitors a push button on the Gizmo 4 I/O Board and toggles a network variable output each time the button is pressed. The actuator drives the state of an LED on the Gizmo 4 I/O Board based on the state of a network variabl e in pu t.

In the exercise later in this chapter, you will create the NcExample device application from scratch. This is a more complex device that uses all the I/O devices on the Gizmo 4 I/O Board: the push buttons, LEDs, temperature sensor, LCD, and quadrature shaft encoder.

The following sections describe how to do the following:

1. Use the pre-built NcExample device application with the LonMaker tool.

2. Create the NcExample device application from scratch using the NodeBuilder tool and the

LonMaker tool.

NodeBuilder FX/PL Examples Guide 3

Using the Pre-Built Example Device Application

You can use the LonMaker tool to download the NcExample device application to the LTM-10A Platform and install it in a L LonWorks\NeuronC\Examples\NodeBuilder LTM-10A\Database folder, load the pre-built binary application image file (.apb extension) for the NcExample application to the device, and then commission the example device. After you install the example device, you can use the I/O devices on the Gizmo 4 I/O Board and observe how network variable values are updated.

Restoring the LonMaker Network Backup

To restore the LonMaker network backup, follow these steps:

1. Connect your LTM-10A and Gizmo 4 I/O Board following Chapter 2 of the NodeBuilder User’s

Guide or the Quick-Start Guide included with your NodeBuilder FX/PL Development Tool.

2. Verify that you have installed and activated the LonMaker tool following Chapter 2 of the

LonMaker User’s Guide.

3. Start the LonMaker tool. To do this, click Start on the taskbar, point to Programs, point to the

Echelon LonMaker folder, and then click LonMaker. The LonMaker Design Manager opens.

ONWORKS network. To do this, you restore the NcExa.zip file in the

4. Click Restore. The Select Backup File dialog opens. Browse to the

LonWorks\NeuronC\Examples\NodeBuilder LTM-10A\Database folder, and then double-click the NcExa.zip backup file (.zip extension).

5. The Confirm Restore dialog opens.

4 Using the NodeBuilder FX/PL Example

6. Click OK.

7. By default, the LonMaker tool will prompt you to select whether to install any new files in the

Import folder (includes L

ONMARK

resource files) and then any new files in the Types folder

(includes XIF and application image files [.apb extension]). Click Yes to restore the files.

8. A message appears informing you that the network restore operation has been completed, and

prompting you to select whether to open the LonMaker network in order to reco mmission devices that have changed since the network was backed up. Click Yes.

• A message may appear informing you that Visio must be launched and initialized so that it

can work with the LonMaker tool. Click OK.

• A warning may appear asking you if you want to enable macros. You must enable macros for the LonMaker tool to function.

9. The Network Wizard opens with the Network Interface window displayed.

NodeBuilder FX/PL Examples Guide 5

+ 30 hidden pages

Echelon NodeBuilder FX-PL Examples User Manual

Table of Contents

Preface

Purpose

Audience

System Requirements

Content

Related Manuals

For More Information and Technical Support

Using the NodeBuilder FX/PL Example

Introduction to the NodeBuilder FX/PL Example

Using the Pre-Built Example Device Application

Restoring the LonMaker Network Backup