NodeBuilder® FX User’s Guide ® 078-0405-01A
Echelon, LON, LonWorks, Neuron, 3120, 3150, Digital Home, i.LON, LNS, LonMaker, LONMARK, 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.
Table of Contents Preface .................................................................................................... ix Purpose ........................................................................................................... x Audience.......................................................................................................... x Hardware Requirements.................................................................................. x Content .................................
Device Interface Files ............................................................................. 17 Resource Files ........................................................................................ 18 Targets .................................................................................................... 18 2 Installing the NodeBuilder FX Development Tool ........................ 19 Installing the NodeBuilder FX Development Tool..........................................
Specifying the Device Template Name................................................... 97 Specifying the Program ID ...................................................................... 98 Specifying Target Platforms.................................................................. 103 Managing and Editing Device Templates.................................................... 105 Managing Device Templates ................................................................
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...
Upgrading Device Applications ............................................................. 217 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.................................
viii Preface
Preface The NodeBuilder FX Development Tool is a complete hardware and software platform that is used to develop applications for Neuron® Chips and Echelon® Smart 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.
Purpose This document describes how to use the NodeBuilder tool to develop LONWORKS device applications and build and test prototype and production LONWORKS 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® Windows Vista or Microsoft Windows XP.
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 LONWORKS-IP Server. If you are using 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 LONWORKS-IP Configuration Server application software.
• 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.
LONWORKS® USB Network Interface User’s Guide 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.
xiv Region Europe Languages Supported English German French Italian Contact Information 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 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.
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.
Introduction to the NodeBuilder Tool The NodeBuilder FX Development Tool is a complete hardware and software platform for developing, debugging, testing, and maintaining LONWORKS devices based on the Neuron 5000 Processor and FT 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.
• • • 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.
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.
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).
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.
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.
Turbo Edition CD U10/U20 USB Network Interface 5 5 * 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.
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.
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.
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.
The U10 USB Network Interface connects directly to TP/FT-10 Free Topology Twisted Pair (ISO/IEC 14908-2) LONWORKS channels through a high-quality removable connector. The U20 USB Network Interface connects to PL-20 C-Band Power Line (ISO/IEC 14908-3) LONWORKS channels through an included power supply with integrated coupler. The U20 USB Network Interface can also be connected directly to 10.
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.
Field Description format 8 or 9. Manufacturer ID (M) A 5 hex-digit ID that is unique to each LONWORKS 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 join LONMARK International, and are also published by LONMARK International so that the device manufacturer of a LONMARK certified device is easily identified.
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.
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.
When a functional block is created from a functional profile, the application designer can determine which of the optional configuration properties and network variables to implement. Hardware Templates A hardware template is a file with a .NbHwt extension that defines the hardware configuration for a device. It specifies hardware attributes that include the transceiver type, Neuron Chip or Smart Transceiver model, clock speed, system image, and memory configuration.
A text device interface file with a .XIF extension is required by the LonMark Application Layer Interoperability Guidelines. A text device interface file is automatically produced by the NodeBuilder tool when you build an application. The NodeBuilder tool also automatically creates binary (.XFB extension) and optimized-binary (.XFO extension) versions of the device interface file that speed the import process for LNS tools such as the LonMaker tool.
2 Installing the NodeBuilder FX Development Tool This chapter describes how to get started with your NodeBuilder tool, including how to install the NodeBuilder software and connect the NodeBuilder hardware.
Installing the NodeBuilder FX Development Tool To install your NodeBuilder FX Development Tool, follow these steps: 1. Verify that you have a manufacturer ID. A manufacturer ID is required for many NodeBuilder tool functions. Standard manufacturer IDs are assigned to manufacturers when they join LONMARK International, and are also published by LONMARK International so that the device manufacturer of a LONMARK certified device is easily identified.
7. Connect the NodeBuilder hardware as described in Connecting the NodeBuilder Hardware later in this chapter. 8. If you do not have the LonMaker FX tool, which is scheduled to be released in 2010, or you are developing 3100 Series devices, order 500 LonMaker development credits as described in Chapter 10 of the LonMaker User’s Guide. You do not need to order LonMaker credits if you have the LonMaker FX tool and you are developing 5000 Series devices.
22 4. Click Microsoft .NET Framework 3.5 SP1 to install Microsoft .NET Framework 3.5 SP1 and then follow the on-screen instructions. Microsoft .NET Framework 3.5 SP1 is required to run the NodeBuilder tool. 5. After Microsoft .NET Framework 3.5 SP1is installed, click the Echelon NodeBuilder FX Development Tool button in the Taskbar to return to the NodeBuilder installer, and then click NodeBuilder FX in the Install Products dialog. The Welcome window of the NodeBuilder software installer opens. 6.
7. Read the license agreement (see Appendix D, NodeBuilder Software License Agreement, for a printed version of this license agreement). If you agree with the terms, click Accept the Terms and then click Next. The Customer Information window appears. 8. Enter the NodeBuilder serial number on the back of NodeBuilder FX Development Tool CD in the Serial Number box. Optionally, you can enter the following registration information.
your computer. Organization The name of your company. The name may be entered automatically based on the user currently logged on and whether other Echelon products are installed on your computer. Manufacturer ID If you have a standard manufacturer ID, enter it decimal format. If your company is a LONMARK 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.
11. Select the type of installation to be performed. Select Complete to install NodeBuilder features or select Custom to choose whether to install the FT 5000 EVB examples, NodeBuilder LTM-10A examples, both sets of examples, or neither on your computer. Click Next. The Ready to Install window appears. 12. Click Install to begin the NodeBuilder software installation.
14. Click Finish. If a window appears prompting you to reboot your computer now or later, click Yes to reboot your computer now. 15. Once the installation has completed, you will be given the option to view the ReadMe file. See the ReadMe file for updates to the NodeBuilder documentation. 16. Install LNS Server/Turbo Edition SP5 after the NodeBuilder tool is installed and you have performed any required reboots.
4. Connect the orange network connector on each FT 5000 EVB to the included network cable. 5. Use the included U10 USB Network Interface to attach the computer running the NodeBuilder tool to the TP/FT-10 channel. To do this, connect the black network connector on the network cable to the U10 USB Network Interface, and then plug the U10 USB Network Interface into an available USB port on your computer.
If this is the only LONWORKS interface installed on your computer, it will automatically use the default name LON1, and you can proceed directly to your software application and begin using the interface as LON1. If you have another network interface installed on your computer, you can check the name used by the U10 USB Network Interface in the LONWORKS Interfaces application. You can also use this application to configure the buffer sizes and counts used by the U10 USB Network Interface.
Connecting the NodeBuilder FX/PL Hardware To connect the NodeBuilder FX/PL hardware, follow these steps: 1. Unpack the equipment from the shipping carton. Avoid touching areas of integrated circuitry, as static discharge could damage circuits. 2. Verify that all of the following hardware and software items are present. Item 3. Qty LTM-10A Platform (with built-in PL-22 power line transceiver) 1 LTM-10A Power Supply 1 Gizmo 4 I/O Board 1 LONWORKS Power Line Couplers.
5. Connect the Gizmo 4 I/O Board to the LTM-10A Platform using the provided ribbon cable. Plug one end of the ribbon cable into the I/O CONNECTOR on the Gizmo 4 I/O Board, and plug the other end into the I/O connector on the LTM-10A Platform. For more information on connecting the NodeBuilder FX/PL hardware, see the LTM-10A User’s Guide and the Gizmo 4 User’s Guide. 6.
3 NodeBuilder Quick-Start Exercise This chapter demonstrates how to create a LONWORKS device using the NodeBuilder Development tool.
NodeBuilder Quick-Start Exercise The following quick-start exercise demonstrates how to create a LONWORKS device with the NodeBuilder tool. It introduces NodeBuilder FX features and provides some familiarity with the NodeBuilder interface. You can use either the FT 5000 EVB Evaluation Board or the LTM-10A Platform with the Gizmo 4 I/O Board as the hardware platform for this exercise. The first step required to develop a device is to define the requirements for the device.
1. Create a new LonMaker network. To do this, follow these steps: a. Verify that your LonMaker computer is physically attached to the network via the USB 10/20 interface provided with the NodeBuilder FX Development Kit (or with another network interface). b. Click Start on the taskbar, point to Programs, point to Echelon LonMaker, and then select LonMaker. The LonMaker Design Manager opens. c. In the Network Name property under New Network, enter NB_FX Exercise. d.
g. Select the Network Attached check box and then select the network interface attached to your LonMaker computer that is to be used for communication between the LonMaker tool and your development platform or platforms. You can use the U10 or U20 USB Network Interface included with your development platform, or you can use another network interface such as a PCC-10, PCLTA-20, PCLTA-21, i.LON 10 Ethernet Adaptor, i.LON server.
i. Select OnNet. This means that changes to the LonMaker drawing are sent immediately to your NodeBuilder devices on the network. Click Finish. j. The LonMaker tool creates and opens a new network drawing. For more information on creating and opening LonMaker networks, see Chapter 3 of the LonMaker User’s Guide. 2. Click LonMaker and then click NodeBuilder.
3. The New Project wizard opens. 4. Accept the default Create a New NodeBuilder Project option, and then click Next. 5. Accept the default NodeBuilder Project Name, which is the same name as the LonMaker network, and then click Next. 6. Accept the defaults in the Specify Default Project Settings dialog, and then click Finish. 7. The NodeBuilder New Device Template wizard starts. Proceed to the next section to create a NodeBuilder device template.
2. Click Next. The Program ID window appears. 3. Click Calculator. The Standard Program ID Calculator dialog opens.
4. Enter the following values for the program ID fields: • In the Manufacturer ID (M:MM:MM) property, enter your standard manufacturer ID or temporary manufacturer ID in decimal format, or select the Examples manufacturer ID. By default, the manufacturer ID that you entered during of the NodeBuilder tool installation is shown by default. If your company is a LONMARK 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.
Note: The current list of manufacturer IDs, device classes, usage values, and channel types are defined in an XML file (spidData.xml) that is available at www.lonmark.org/spid. This file is updated as LONMARK International adds new manufacturer IDs, device classes, usage values, and channel types. 5. Click OK to return to the New Device Template wizard. The Program ID property contains the program ID you specified in the Standard Program ID Calculator dialog.
• 8. 40 If you are using the NodeBuilder FX/PL hardware (LTM-10A Platform with Gizmo 4 I/O Board), select LTM-10A RAM in the Development Build Hardware Template property, and then select LTM-10A Flash in the Release Build Hardware Template property. Click Finish. The NodeBuilder Code Wizard starts. There will be an initial pause as it reads the available resource files. Proceed to the next section to generate Neuron C code that defines your device’s interface.
Step 3: Defining the Device Interface and Creating its Neuron C Application Framework You can develop device applications with the NodeBuilder tool using the Neuron C programming language. Neuron C is based on ANSI C, with extensions for network communication, hardware I/O, timing, and event handling. The NodeBuilder tool includes a NodeBuilder Code Wizard, which automatically generates Neuron C source code that defines the device interface (XIF).
• A simple Node Object with no configuration properties (the NodeBuilder Code Wizard automatically creates this functional block). To define your device interface and automatically create Neuron C source code for it using the Code Wizard, follow these steps: 1. 42 Create an open-loop sensor functional block with a SNVT_switch network variable. To do this, follow these steps: a.
c. Rename the openLoopSensor functional block to “Switch”. To do this, right-click the openLoopSensor functional block in the Program Interface pane, click Rename on the shortcut menu, enter Switch, and then press ENTER or TAB. A warning message appears warning that new source files will be generated as a result of the name change. Click OK. d. Expand the Switch functional block, and then expand the Mandatory NVs folder to display the nvoSwitch network variable.
44 e. Double-click the nvoValue network variable, or right-click it and then select Properties on the shortcut menu. The NV Properties dialog opens. f. In the Name property, change the network variable name to nvoSwitch. g. In the NV Type property, select SNVT_switch, and then click OK.
2. Create an open-loop actuator with a SNVT_switch network variable. a. Drag a SFPTopenLoopActuator functional profile template from the Resource Pane on the left side to the Functional Blocks folder in the Program Interface pane on the right side. b. Rename the openLoopActuator functional block to “LED”. A warning message appears warning that new source files will be generated as a result of the name change. Click OK. c.
5. Double-click the NB FX Example Device.nc file in the Project pane to open the main Neuron C file for this new device template. 6. Open the Switch.h and LED.h header files and view the functional block and configuration property declarations. 7. Open the Switch.nc and LED.nc Neuron C files and view the default implementation of the director function (named SwitchDirector or equivalent).
follow the section corresponding with the development platform or platforms you are using for the appropriate code to use. FT 5000 Evaluation Boards 1. Declare the I/O hardware for the Switch following these steps: a. Double-click the Switch.h file in the Project pane to edit the source file. b. Find the following line of code near the end of the Editor window: //}}NodeBuilder Code Wizard End c. Add the following line of code after the line referenced in step b. IO_9 input bit ioSwitch1; 2.
LTM-10A Platform and Gizmo 4 I/O Board 1. Declare the I/O hardware for the Switch following these steps: a. Double-click the Switch.h file in the Project pane to edit the source file. b. Find the following line of code near the end of the Editor window: //}}NodeBuilder Code Wizard End c. Add the following line of code after the line referenced in step b. IO_6 input bit ioSwitch1; 2. Add functionality to the Switch I/O following these steps: a. Double-click the Switch.nc file in the Project pane.
Step 5: Compiling, Building, and Downloading the Application The NodeBuilder tool includes a complete set of tools for compiling your Neuron C application, building an application image that can be loaded into your device, and downloading your application image to your device. When you build your application, the NodeBuilder tool will create downloadable application image files and device interface files.
The LonMaker tool also displays stencils that contain shapes that you can drag to your LonMaker drawing. The LonMaker tool includes a NodeBuilder Basic Shapes 4.00 stencil with shapes that you will use to add new devices, functional blocks, and connections to your network drawing. The NodeBuilder Basic Shapes 4.00 stencil contains shapes that can be used with any device. You can also create custom stencils with shapes customized for your devices and networks. The NodeBuilder Basic Shapes 4.
6. Click Next three times. The window in the New Device Wizard lets you select the application image to be downloaded to your device. 7. Select the Load Application Image check box and then click Next. This specifies that you will download to the device the binary application image file (.APB extension) that was automatically created when you built the device with the NodeBuilder tool.
8. The next window lets you set the initial device state and the source of configuration property values when your device is commissioned. 9. Select the Online option under State. This means that your device will run its application after it has been commissioned. 10. Click Finish. The Press Service Pin window appears.
11. Press the service pin on the development platform to be loaded and commissioned. The LonMaker tool loads the application image for your NB FX Example Device application to the development platform and makes it operational. When the LonMaker tool is done commissioning, it will return to the LonMaker drawing. The device shape will be will be solid green indicating that the device has been commissioned and is online.
To test your device’s interface with the LonMaker Browser, follow these steps: 54 1. Right-click the NB FX Example Device device in your LonMaker drawing, then click Browse on the shortcut menu. 2. The LonMaker Browser opens. It displays the three functional blocks in your device interface (LED, NodeObject, and Switch) and the network variables and configuration properties within each functional block.
4. Press and hold the left button at the bottom of your development board (SW1 on the FT 5000 EVB; IO_6 on the Gizmo 4 I/O Board). The value of the nvoSwitch network variable in the Switch functional block changes to 100.0 1, which means that the switch is at its maximum level (100%) and on. 5. Release the left button at the bottom of your development board. The value of the nvoSwitch network variable in the Switch functional block changes back to 0.
56 3. The NodeBuilder Project Manager appears, and a debug session for the device starts. There is a short pause as the debug session is started while the NodeBuilder tool establishes communication with the device’s debug kernel. 4. Double-click the Switch.nc file in the Project pane. A Debug window appears for the Switch.nc file. 5. Find the when(io_changes(ioSwitch)) clause near the end of the file. This is the code you added in Step 4: Developing the Device Application.
6. Right-click the nvoSwitch.state = !input_value line, and then click Toggle Breakpoint on the shortcut menu, or click anywhere in the line and press F9. 7. A breakpoint marker ( ) appears next to the line, and the line is added to the Breakpoint List pane at the bottom of the NodeBuilder Project Manager. 8. Press and then release the left button at the bottom of your development board (SW1 on the FT 5000 EVB; IO_6 on the Gizmo 4 I/O Board).
9. Right-click the input_value variable in the line of code in which you set the breakpoint, and then click Watch Variable on the shortcut menu. 10. The Watch Variable dialog opens.
11. Click Add Watch. The variable is added to the Watch List pane at the bottom of the NodeBuilder Project Manager. This pane displays each of the variables added to the watch list and their current values. ) in the debug toolbar to step through the code in the function until 12. Click the Step Into button ( you reach the end of the when clause. The input_value variable is 0. 13. Click the Step Into button to observe that the function executes a second time. The input_value variable is now 1. 14.
16. The NodeBuilder debugger has demonstrated that events occur when the button is both pressed and released. To implement the desired behavior in which an event occurs only when the button is pressed, change the following lines of code in the Switch.nc file: nvoSwitch.state = !input_value; nvoSwitch.value = input_value ? 200u : 0; to the following: if (!input_value) { } nvoSwitch.state ^= 1; nvoSwitch.value = nvoSwitch.state ? 200u : 0; 17. Verify that the Load after Build option ( ) is set. 18.
Step 8: Connecting and Testing the Device in a Network Once you determine that your device is functioning as desired, you can test it as part of a network. You can use the LonMaker tool to connect your development devices to other devices and verify their operation within a network.
62 5. Click Finish. The New Functional Block wizard closes and the LonMaker drawing appears. A new Left Switch functional block shape appears on the drawing. 6. Repeat steps 2–4 to create a new functional block shape named “Left LED”. In the Name property under Functional Block in the Functional Block Wizard, select LED. In the New FB Name: property, enter Left LED.
7. Click Finish. The New Functional Block wizard closes and the LonMaker drawing appears. A new Left LED functional block shape appears on the drawing. 8. Connect the nvoSwitch output network variable of the Left Switch functional block to the nviLamp input network variable of the Left LED functional block.
9. a. Drag the Connector shape from the NodeBuilder Basic Shapes 4.00 stencil to the drawing. Position the left end of the shape over the tip of the nvoSwitch output network variable on the Left Switch functional block before releasing the mouse button. A red box appears around the end of the Connector shape when you have positioned it correctly over the Network Variable shape. b.
b. Right-click the new Connector shape and select Monitor Input Value to display the current value of the nvoSwitch network variable on the Left Switch functional block. c. Right-click the new Connector shape and select Monitor Output Value to display the current value of the nviLamp network variable on the Left LED functional block.
10. Press the left button at the bottom of your development board (SW1 on the FT 5000 EVB; IO_6 on the Gizmo 4 I/O Board) repeatedly to test the connection between the nvoSwitch output network variable of the Left Switch functional block and the nviLamp input network variable of the Left LED functional block.
Additional Device Development Steps After you create your device application and successfully test your device in a network, you can perform the following additional steps in the device development process, which are summarized in the following sections: • • • • • • Create a LonMaker stencil. Create an LNS device plug-in. Create an HMI. Create a device installation application Submit an OEM license. Apply for LONMARK certification for your device.
68 b. The Device Properties dialog opens with the Attributes tab selected. This dialog allows you to read and write to the properties of the LonMaker device. c. In the Device Name property, enter the name to be shown for the custom device shape in your LonMaker stencil. d. Click the Basic Properties tab.
e. Set the Location and Ping Interval properties to the values to be saved with the custom device shape in your LonMaker stencil. See the LonMaker online help file for more information on these properties. Note that changes made to the Description are not saved in the custom device shape. f. Click the Advanced Properties tab.
70 g. Set the Non-group Receive Timer property to the value to be saved with the custom device shape in your LonMaker stencil. See the LonMaker online help file for more information on this property. h. Click OK. i. Drag your NodeBuilder device to your LonMaker stencil. A new custom LonMaker master shape with the device name specified in step c appears in the stencil. j. Click the disk icon ( ) on the stencil’s title bar. Specify a name and location for your LonMaker stencil file (.
3. Create custom functional block shapes. Custom functional block shapes let you provide network integrators with functional block shapes that have built-in network variable shapes. To do this follow these steps: a. Verify that functional block shapes for each functional block defined by the device interface have been added to the LonMaker drawing. To create a functional block shape, drag a Functional Block shape from the NodeBuilder Basic Shapes 4.
Developing an HMI You can create a human machine interface (HMI) for your device so that end users can monitor and control it. You will typically create an HMI if you are building a complete system that requires one; however, if your device is installed by integrators where each installation is unique, the integrators will typically develop the required HMIs. You can use the LonMaker tool to design a simple HMI for your device.
Programmable Application Image Files (.APB and .NXE) The LonMaker tool and other LNS network tools use programmable application image files to download the compiled application image to a device. The programmable application image files have .APB, .NDL, and .NXE extensions. On a NodeBuilder computer, the programmable application image files are stored in the Development or Release target folder within the device template folder.
on these device interface files. Device Resource Files (.TYP, .FMT, .FPT) Resource files are the files created by the NodeBuilder Resource that contain network variable and configuration property type information and functional profile definitions. You must install all resource files that are used by your device.
NodeBuilder FX User's Guide 75
4 Creating and Opening NodeBuilder Projects This chapter describes how to create, open, and copy NodeBuilder projects, and how to copy NodeBuilder projects and NodeBuilder device templates to another computer.
Introduction to the NodeBuilder Project Manager A NodeBuilder project collects all the information about a set of devices that you are developing. You will create, manage, and use NodeBuilder projects from the NodeBuilder Project Manager. The project manager provides an integrated view of your entire project and provides the tools you will use to define and build your project.
Edit Lets you to edit any of the Neuron C source files or header files that are used in the project. See Chapter 7, Developing Device Applications, for more information on using the Edit pane. Results The Results pane contains three tabs: Messages, Search Results, and Event Log. • The Messages tab displays compiler and other messages generated when you build the application image for a NodeBuilder device template.
Settings Opens the NodeBuilder Project Properties dialog with the Project tab selected. The Project tab displays the project settings. Properties Displays file properties of the NodeBuilder project file (.NbPrj extension). The properties include the file name, location, size, and the dates on which the file was created, last modified, and last accessed. The Project folder may also contain the following three folders: Device Templates, Devices, and Hardware Templates.
Creating a NodeBuilder Project from the LonMaker Tool You can create a NodeBuilder project by starting the NodeBuilder Project Manager from the LonMaker tool. To do this, follow these steps: 1. Create or open a LonMaker drawing. See the LonMaker User’s Guide for more information on creating and opening LonMaker drawings. If you will want to load the application you develop into a device, make sure the LonMaker computer is attached to the network. 2. Open the LonMaker menu then click NodeBuilder.
Network property, and then select the LNS network interface to be used for communication between the LonMaker network and your NodeBuilder device in the Network Interface property. Alternatively, you can select the Do Not Open Any Network check box to create a new project that is not associated with a LonMaker network, and disable automatic LNS device template creation and automatic load after build. 4. Click Next. 5. The Specify New Project Name dialog opens. 6.
8. 9. Specify the following properties: Project Name The name of the project as specified in the Specify New Project Name dialog. This is a read-only field. Location The location of the project folder as specified in the Specify New Project Name dialog. This is a read-only field. Default Transceiver Type The transceiver type to be used for Hardware Templates that specify “default” for the transceiver type. The default transceiver type is TP/FT-10.
Creating a NodeBuilder Project from the New Device Wizard You can create a NodeBuilder project from the New Device Wizard in the LonMaker tool. To do this, follow these steps: 84 1. Create or open a LonMaker network. See the LonMaker User’s Guide for more information on creating and opening LonMaker networks. If you plan on downloading your device application to a device, make sure that the LonMaker computer is attached to the network. 2.
4. Click Next. The next page in the New Device Wizard lets you select the NodeBuilder device template. 5. Click Start NodeBuilder to create a new NodeBuilder project. The NodeBuilder tool starts automatically. 6. The New Project wizard opens.
7. Accept the default Create a New NodeBuilder Project option, and then click Next. 8. Accept the default NodeBuilder Project Name, which is the same name as the LonMaker network, and then click Next. 9. Accept the defaults in the Specify Default Project Settings dialog, and then click Finish. 10. The NodeBuilder New Device Template wizard starts. Proceed to the Specifying the Device Template Name section in Chapter 5 to create a device template.
4. The Select NodeBuilder Project File dialog opens. Click the button to the right of the Project File property, browse to and select the desired project folder (C:\Lm\Source\ by default), and then select the project file (.NbPrj extension) in the project folder. 5. Click Finish. Notes: • You can open a project and start the New Device Template wizard at the same time by dragging a Development Target or Release Target device shape from the NodeBuilder Basic Shapes 4.
Opening a NodeBuilder Project from the NodeBuilder Project Manager You can open a NodeBuilder project by starting the NodeBuilder Project Manager standalone. To do this, follow these steps: 1. Open the NodeBuilder Project Manager. To do this, click Start on the taskbar, point to Programs, point to Echelon NodeBuilder, and then click NodeBuilder Development Tool. The NodeBuilder Project Manager starts. 2. Click File and then click Open Project. The New Project wizard starts with the Select Network dialog.
5. If you have previously associated a LonMaker network with this NodeBuilder project, it appears in the Project File property. 6. To select a different NodeBuilder project, click the button to the right of the Project File property, browse to and select your project folder (C:\Lm\Source\ by default), and then select the project file (.NbPrj extension) in the project folder. 7.
90 4. The LonMaker Backup dialog opens. 5. Select the Backup Drawing, Backup Database, Backup NodeBuilder Project check boxes under Backup Selection (the Backup Drawing and Backup Database check boxes are selected by default), and then click OK. 6. The LonMaker drawing, LNS network database, and the NodeBuilder project are all stored in a single LonMaker backup file (.zip extension) that is specified in the Backup File property (C:\LM\Backup\\_.
7. After the backup has been created, copy the LonMaker backup file from the source computer to a USB drive, another removable media, or a shared network drive with read/write permissions. 8. On the target computer, start the LonMaker tool and then 9. Click Restore. The LonMaker Restore dialog opens. 10. Click Browse to specify the location of the LonMaker backup file, and then click OK. The Confirm Restore dialog opens. 11. Click OK.
12. 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 recommission devices that have changed since the network was backed up. • Click Yes if you made any changes to the network since it was backed up. This prevents the network from behaving unpredictably if the LonMaker network design is not in sync with the physical devices. Proceed to recommission and resynchronize the network.
4. On the source computer, copy any user-defined hardware templates and custom libraries to the USB drive, another removable media, or a shared network drive with read/write permissions. By default, user-defined hardware templates are stored in the C:\LonWorks\NodeBuilder\Templates\Hardware\User directory. 5. Copy the device template backups to the C:\Lm\Source\ directory of the target NodeBuilder project on the target computer. 6.
install and register the resource files on the target computer. User-defined resource files include the network variable types, configuration property types, functional profiles, enumerations, languages, and formats that you have created in your resource file set. To copy resource files to another computer, follow these steps: 1.
5 Creating and Using Device Templates This chapter describes how to use the New Device Template wizard in the NodeBuilder Project Manager to create, manage, and edit NodeBuilder device templates. It explains how to manage development and release targets and insert libraries into a device template. It describes how to use the Hardware Template Editor to create and edit hardware templates.
Introduction to Device Templates Each type of device that you develop with the NodeBuilder tool is defined by a pair of device templates: a NodeBuilder device template and an LNS device template. The NodeBuilder device template is an XML file with a .NbDt extension that specifies the information required for the NodeBuilder tool to build the device application. The NodeBuilder device template includes a list of Neuron C source code files and the hardware template name.
3. Proceed to the next section to specify the device template name. Specifying the Device Template Name To specify the device template name, follow these steps: 1. In the NodeBuilder Device Template Name property, enter a valid Windows file name for the device template. A NodeBuilder device template file (.NbDt extension) with this name will be created in the folder specified in the NodeBuilder Device Template property under Folders.
2. Optionally, in the Source File Name property, you can enter the name of the Neuron C source file for this device template. By default, this field is set to .nc, and the file will be created in the folder specified in the NodeBuilder Device Template property under Folders. To select an existing source file, click Browse. 3. Optionally, in the NodeBuilder Device Template property under Folders, you can enter the device template folder where the device template file will be stored.
The Standard Program ID Calculator helps you select the appropriate values for the program ID fields. It lets you select the values from lists contained in a program ID definition file distributed by LONMARK International. The current file (spidData.xml) is available at http://www.lonmark.org/spid. This file is updated as LONMARK International adds new manufacturer IDs, device classes, usage values, and channel types.
c. In the Device Class (CC:CC) property, select the primary function of the device. To enter a device class value that has not yet been added to the standard list, select , and then enter decimal values from 0 to 255 in the boxes to the right (the calculator will convert the values to hex format). d. In the Usage (UU) property, select the intended use of the device.
3. Click OK to return to the Program ID dialog in the New Device Template wizard. The Program ID property contains the program ID you specified in the Standard Program ID Calculator dialog. 4. Verify that the Enable check box under Automatic Program ID Management is selected. This enables the Model number (NN) field in the program ID to be incremented automatically when the external interface of the device is changed.
of model numbers specified by the Min Model # and Max Model # properties to avoid two devices having the same program ID but different external interfaces. When the Max model # value is reached, the model number field of the Program ID will be reset to the Min model # value. When this check box is selected, the Min model # and Max model # properties are enabled, and the Nonstandard (ASCII) Program ID Type is disabled.
8. Proceed to the next section to specify the hardware templates used by development and release devices. Specifying Target Platforms You can specify the hardware templates used for targets. A hardware template is a file that defines the hardware configuration for a device. It specifies hardware attributes including platform, transceiver type, Neuron Chip or Smart Transceiver model, clock speed, system image, and memory configuration.
2. In the Release Build Hardware Template property, select the hardware template to be used for release targets. The list contains all the hardware templates in the Hardware Templates folder in the Project pane. 3. Select the Run NodeBuilder Code Wizard check box to run the NodeBuilder Code Wizard immediately after clicking Finish. This check box is selected by default. Note: You can change the default setting of this option.
menu. The NodeBuilder Project Properties dialog opens. Click the Options tab, change the setting, and then click OK. 4. Click Finish. If you selected the Run NodeBuilder Code Wizard check box, the NodeBuilder Code Wizard starts. See Chapter 6, Defining Device Interfaces and Creating their Neuron C Application Framework, for more information about the NodeBuilder Code Wizard.
Output Files in Chapter 8 for more information on removing the files and folders produced by a build. Status Displays the build status for all device templates. See Viewing Build Status in Chapter 8 for more information on viewing the build status of NodeBuilder device templates and targets. Viewing and Editing Device Templates After you create a device template ( ), you can view and edit its properties.
menu. When a device template is excluded, you can still explicitly build the device template by right-clicking the device template and selecting Build from the shortcut menu. Status Displays the build status for this device template. See Viewing Build Status in Chapter 8 for more information on viewing the build status of NodeBuilder device templates and targets. Properties Displays the name, location, size, and the dates on which the file was created, last modified, and last accessed.
Source Files This folder contains all the source files associated with this device template except for the main source file. When you add source files to the NodeBuilder project directly or using the NodeBuilder Code Wizard, they are added to this folder. Adding Source Files You can add other files to this folder, including Neuron C source files (.nc extension), header files (.h extension), C files (.c extension), text files (.txt extension), or other specification or documentation files.
Managing Development and Release Targets Each NodeBuilder device template in the Project pane contains Development and Release targets ( that can be built. These targets are defined by their hardware templates and dependencies. ) A hardware template ( ) is a file that defines the hardware configuration for a target. It specifies hardware attributes including platform, transceiver type, Neuron Chip or Smart Transceiver model, clock speed, system image, and memory configuration.
Settings Opens the NodeBuilder Device Template Target Properties dialog, which includes compiling, linking, exporting, and configuration options for the target. See the following subsections for more information on the target properties you can set in this dialog. Set Hardware Template Opens the Set Target Device Hardware Template dialog, where you can select the hardware template to be used for this target. You can select from all hardware templates contained in the Hardware Templates folder.
You can set the following properties: Defines You can define a symbol, which can then be tested from the program using the ifdef or ifndef directive. The default is _DEBUG for development targets. This field is blank by default for release targets. The NodeBuilder FX tool includes the following standard, pre-defined preprocessor symbols: _ECHELON, _NEURONC, _NODEBUILDER, and _NCC5. See the Neuron C Reference Guide for more information on these symbols.
Debug Kernel Options Disable optimizer Disables the compiler’s code optimizer. Optimization typically generates smaller and faster code, and is typically enabled for release targets. However, optimization can severely change the code initially generated by the compiler, which can make it difficult to place and use breakpoints in an application that is being debugged. This check box is selected by default. Note: Debugging an optimized application is not supported.
Enable Function Execute Enables the debugger to get and update the values of system timers and to update the values of network variables in the watch list when suspended at a breakpoint. This check box is selected by default. Setting Device Template Target Properties: Linker The Neuron Linker (NLD) is a Neuron C tool that is used to produce Neuron executable files. It links the application image, user-libraries, system libraries, and the Neuron firmware. You can modify the linker options for a target.
Compatible EEPROM to meet system requirements. In NodeBuilder 3.0 and prior releases, the NodeBuilder tool allocated system on-chip EEPROM after placement of explicit and implicit on-chip EEPROM variables. This could cause link failure in applications that declare a large amount of implicit on-chip EEPROM variables. Implicit on-chip EEPROM variables are those application EEPROM variables declared without use of the explicit onchip or offchip keyword.
You can set the following properties: Boot ID Generation Checksum All Code Select whether the boot ID is generated automatically or manually. Note: This option is intended for Neuron 3150 Chips and 3150 Smart Transceivers. • Automatic. Allocates a new boot ID each time the application image is built. This causes the on-chip EEPROM to be rebooted from the system image if the external memory device has been updated. This is the default.
application image inconsistency, or other fatal application error. • Application Always. Reboot every time the Neuron Chip is reset. Specify when to copy the on-chip part of the application image from ROM into the on-chip EEPROM. All applications have at least part of their image in on-chip EEPROM in the Read-Only data structure. See Appendix A of the Neuron Chip Data Book for a description of this structure.
You can select the Export Configured check box to enable the NodeBuilder tool build a configured device application for the target. The target will have the properties set in this dialog set when the application is downloaded to the device. This information is used to set the fields of the system domain table and other configuration data structures (see the Neuron C Reference Guide for more information). This check box is cleared by default.
is sent using subnet/node addressing regardless of the addressing format of the original message. • Length Devices are no longer protected against receiving their own messages in looping topologies. This must be considered when designing the application.
1. Expand the device template in the Project pane of the NodeBuilder project manager. 2. Right-click the Libraries folder and then click Insert on the shortcut menu. 3. The Specify Library Type dialog opens. 4. Select a Custom Library or a Standard library to add to the device template and then click Next. Standard libraries (.lib extension) are stored in the C:\LonWorks\Images folder; custom libraries can be stored anywhere. 5.
Select one or more of the following standard libraries in the C:\LonWorks\Images folder to be explicitly included in the project (for documentation purposes only) and then click Finish. CodeWizard-3.lib The NodeBuilder Code Wizard library used by the version 3 code template. The Code Wizard library supplies most of the utility functions defined in the CodeWizard.h file. See Version 3 Templates in Chapter 6 for more information on the version 3 code templates.
When you build the application image, the NodeBuilder tool first searches for the selected libraries in the folder within the Images folder that contains the system image for the target (for example, C:\LonWorks\Images\Ver18). If the libraries are not in the version folder, the libraries in the parent C:\LonWorks\Images folder are used. 6. If you selected Custom Library in step 4, the Specify Custom Libraries dialog opens. Enter the full path of the library or libraries to be added to the device template.
you can use the Insert Copy feature to create your own custom hardware template based on a Standard template and then edit your custom template. • The User Templates folder contains your custom hardware templates that can be used by all NodeBuilder projects on this computer. Any hardware templates unique to this project are located in the Hardware Templates folder, and are not contained in the Standard Templates or User Templates folders. To create hardware templates, you do the following: 1.
New Creates a new hardware template to be added to the selected folder. Selecting this option opens the Hardware Template Editor dialog where you can create a new hardware template. • If you are creating a hardware template in the Hardware Templates folder, it will be placed in the NodeBuilder project folder (for example, C:\Lm\Source\NB_FX Exercise).
• Do not modify hardware templates in the Standard Templates folder because any changes that you make will be overwritten by future NodeBuilder updates. To modify a standard template, first insert a copy in the User Templates folder, and then edit the resulting custom template. Future upgrades of the NodeBuilder tool will not modify any user templates. • You can remove project-specific hardware templates in the Hardware Templates folder.
You can set the following properties on the Hardware tab: Hardware Template Name Enter the name of the hardware template. By default, new hardware templates are named Custom 1, Custom 2, and so on. The hardware template name may be any valid Windows file name. The name can contain up to 210 characters, including spaces. The name cannot contain the following characters: \ / : * ? “ < > |. Platform A platform is a category of hardware implementations.
Transceiver Type Select the transceiver type supported by the Neuron Chip or Smart Transceiver model selected in the Neuron Chip Model property. Each transceiver type identifies a unique set of transceiver parameters that are included in the application image. The default transceiver type is TP/FT-10. Select to use the project default transceiver. You can set the default transceiver in the Project tab of the NodeBuilder Project Properties dialog.
System Image Version Select the system image version for the selected Neuron Chip or Smart Transceiver model. See your Neuron Chip or Smart Transceiver data book for more information. Select to use the default system image for the chosen chip. The default system image is the most current system image version included with this version of the NodeBuilder tool and any applied service packs. Select to specify your own custom system image in the Image Name property.
The Memory Addresses box details how on chip and off-chip memory is organized on the selected Neuron Chip or Smart Transceiver model. These values are dependent on the chip type and may be modified depending on the Neuron chip model and available memory. You can modify the Start and End locations for available memory by clicking the arrows. A value of 0x0000 is displayed for any memory location that has not been set; N/A is displayed for any memory location that is not available.
3150 Neuron Core For Neuron 3150 Chips, 3150 FT Smart Transceivers, and 3150 PL Smart Transceivers, the on-chip memory values are dependent on the chip type and may not be modified with the exception of the Extended On-chip RAM. The Type property in the Non-Volatile Memory box specifies the type of non-volatile memory (EEPROM, FLASH, and NVRAM) used, if any. For devices where the system image is kept in non-volatile memory, select either flash or NVRAM. EEPROM is not supported for this configuration.
130 Creating and Using Device Templates
6 Defining Device Interfaces and Creating their Neuron C Application Framework This chapter describes how to use the NodeBuilder Code Wizard to define your device interface and generate Neuron C code that implements it. 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 application.
Introduction to Device Interfaces The NodeBuilder Code Wizard generates Neuron C source code that implements your device interface and creates the Neuron C framework for your device application. The device interface defines the functional blocks, network variables, and configuration properties implemented by your device.
The NodeBuilder Code Wizard opens. The NodeBuilder Code Wizard user interface is essentially divided into two panes: the Resource pane and the Program Interface pane. The following sections describe how to use these panes. Using the Resource Pane The Resource pane provides the full functionality of the NodeBuilder Resource Editor. It lists functional profiles, network variable types, and configuration property types, which are collectively referred to as resources.
section. For more information on creating and editing resource file sets and resources, see the NodeBuilder Resource Editor User’s Guide. The Resource pane displays a hierarchical view of your resource catalog. The resource catalog file ( ) is at the top of the hierarchy. The resource catalog file is used to identify all the directories containing resource file sets. The resource catalog file has a .Cat extension. The default resource catalog file is Ldrf.
The scope may be one of the following values: Scope Program ID Fields Used 0 1 2 3 4 5 6 Standard Device Class Device Class and Usage Manufacturer Manufacturer and Device Class Manufacturer, Device Class, and Device Subclass Manufacturer, Device Class, Device Subclass, and Device Model For a device to use a resource file set, the program ID of the device must match the program ID of the resource file set to the degree specified by the scope.
Resource Description Functional Profiles Functional profiles define a template for functional blocks. A functional block is a collection of network variables and configuration properties designed to perform a single function on a device. Each functional profile can define mandatory and optional network variables and configuration properties, which are collectively known as mandatory and optional member network variables and configuration properties.
Resource Description Italian (default) Italian (Swiss) Norwegian (Bokmal) Polish Portuguese (Brazilian) Portuguese (default) Russian Slovak Spanish (default) Spanish (Mexican) Swedish Formats “ita” “its” “nor” “plk” “ptb” “ptg” “rus” “sky” “esp” “esm” “sve” Each network variable and configuration property type must have at least one format defined. This format describes how the value will appear when using text-oriented visualization tools such as the LonMaker Browser.
• The Functional Blocks folder contains all the functional blocks contained in this device interface. • The Network Variables folder contains all the device network variables for this device interface. Device network variables belong to the device and therefore are not contained in any functional block. You can use device network variables to create a portion of your device interface for proprietary or legacy information.
network variables. The Node Object functional block is a standard functional block that is used by network management tools to test and manage the other functional blocks on your device and is also used to report alarms generated by your device. If you remove the Node Object functional block, the Code Wizard cannot generate code for your device interface. See the LonMark Application Interoperability Guidelines for more information about the Node Object.
A network variable defines an operational input or output for the device. The structure, range, units, and format of the network variable are defined by a network variable type. A configuration property specifies a configuration option for a network variable, a functional block, or the entire device. The structure, range, units, and format of a configuration property are defined by a configuration property type.
Each functional profile has a name and number that is unique for the scope of the resource file set. The number is called the functional profile key or FPT key. If your device is a simple sensor or actuator, you can use functional profiles 1–4: SFPTopenLoopSensor (1), SFPTclosedLoopSensor (2), SFPTopenLoopActuator (3), or SFPTclosedLoopActuator (4). If your device is more complex, you can browse the other SFPTs in the Standard resource file set for any suitable standard profiles have been defined.
Adding Functional Blocks Functional blocks represent specific device functions. For example, a device could have four hardware digital inputs, and digital would have its own functional block. To add a functional block to a device template, follow these steps: 1. Drag the desired functional profile from the Resource Pane to the Functional Blocks folder in the Program Interface pane.
the Use Array checkbox, enter the number of functional blocks in the array in the Size box, and then click OK. 3. In the Program Interface pane, right-click the new functional block and then select Rename on the shortcut menu to change the name of the functional block. LNS network tools use this name is used to identify the functional block.
5. If any of the mandatory network variables do not have a default type set by the functional profile (for example, the nvoValue network variable in the openLoopSensor profile), you need to set the network variable type. See Editing Mandatory Network Variables for more information on how to do this and edit other network variable properties. Alternatively, you can add a functional block directly from the Program Interface pane following these steps: 144 1.
4. In the SFPT or UFPT property, select the desired functional profile template. 5. In the Name property, enter a name for your functional block. 6. To create a functional block array, select the Use Array checkbox, and then enter the number of functional blocks in the array in the Size box. See Using Large Functional Block Arrays for how to manage your device application’s memory when you are implementing large functional block arrays. 7. Click OK. 8.
146 2. The NV Properties dialog opens. 3.
Name Displays the name of the network variable that will be used in the LonMaker tool and other network management tools. The default name is the functional profile name. You can change the name of the network variable. The name must be unique to the device, can contain up to 16 alphanumeric characters, and must start with a letter. The name cannot contain spaces or the following characters: \ / : * ? “ < > |.
Service Type Displays the service type used by the network variable to send updates as specified in the functional profile (Unspecified, Acknowledged, Repeated, or Unacknowledged). This property is only available for output network variables. You can change the service type for mandatory and optional output network variables if the functional profile has not specified one, and you can change the service type for implementation-specific output network variables.
Modifiers Indicates whether the network variable uses the Synchronized or Polled modifiers. This property is only available for output network variables. You can change the modifiers for mandatory and optional output network variables if the functional profile has not specified them, and you can change the modifiers for implementation-specific output network variables. This property may be one of the following values. • None. The network variable is neither synchronous nor polled. • Synchronized.
4. Optionally, you can click Advanced to open the Advanced NV Properties dialog and further specify the storage class used by the network variable. Consider a scenario where you declare a large network variable array that exceeds the limits of the near RAM segment, which is 256 bytes. In this case, you need to move the network variable array to the far RAM segment by selecting the far check box in this dialog.
memory devices. far The network variable is placed in the far section of the variable space. By default, Neuron C variables are placed in the near RAM segment; however, the near RAM segment is limited to 256 bytes. Accessing data in near RAM is faster and requires less code space than accessing data in far RAM.
the network variable must have priority enabled when it is installed. To enable priority on a device installed in a LonMaker network, right click the device, click Properties on the shortcut menu, select the Advanced Properties tab and then set the priority to Enable Automatic or Enable - Manual. If you set the priority to Enable Manual, you must also set the priority slot. Setting the priority to Disable disables priority. 5. Click OK.
3. Edit the following properties: Name Displays the name of the configuration property that will be used in the LonMaker tool and other network management tools. The default name is the functional profile name. You can change the name of the configuration property. The name must be unique to the device, can contain up to 16 alphanumeric characters, and must start with a letter. The name cannot contain spaces or the following characters: \ / : * ? “ < > |.
Implement as CP Array check box is set appropriately and unavailable. If the functional profile template does not define how this configuration property must be implemented or if this is an implementation-specific configuration property, you have the option to configure the configuration property as an array or as a single configuration property.
modified only when the device has been set offline by a network tool such as the LonMaker tool. Do not set this option if you are using FTP to transfer configuration properties because devices must be online to run the file transfer protocol. • const_flg. Specifies that the configuration property should be considered read-only. It must not be written. It might be stored in ROM. An example of this kind of property is the device major version number. • obj_disabl_flg.
cleared by default. Initializer Optionally, you can set the value for the network variable when the device is reset. If this network variable is a structure, union, float, or enumeration, click Edit to open the Edit Initializer dialog and enter the value or values. See Setting Initial Values for Network Variables and Configuration Properties later in this chapter for more information. Note: Configuration properties have default values that are defined in resource files.
4. If you have shared two mandatory or optional configuration properties or if you have shared two implementation-specific configuration properties from a different functional block, they will appear in the Program Interface pane with the same configuration property name in their respective folders.
functional block or network variable arrays, or any combination thereof. 5. • A configuration property that is shared among the members of a functional block or network variable array must always be shared among all members of that array. • A configuration property can be shared between network variables on different functional blocks. • A configuration property that inherits its type from a network variable can only be shared between network variables that are all of the same type.
Alternatively, you can drag a network variable from the functional profile’s Optional NVs folder in the Resource pane to the functional block’s Optional NVs folder in the Program Interface pane. If a functional profile does not have any optional network variables defined, it does not have an Optional NVs folder. 2. The Implement Optional NV dialog opens. 3.
The name cannot contain spaces or the following characters: \ / : * ? “ < > |. 5. The Use Array check box in the Array Element Count box is a read-only property that indicates whether the optional network variable is implemented as a single network variable (the check box is cleared), or as an array of network variables that applies to an array of functional blocks (the check box is selected).
3. In the FPT Member Name property, select the optional configuration property from the list of those that have not yet been implemented in this functional block. 4. In the Name property, enter the name of the optional configuration property that will be displayed in the LonMaker tool and other network management tools. The default name is the functional profile name. This name must be unique to the device, can contain up to 16 alphanumeric characters, and must start with a letter.
See the Neuron C Programmer’s Guide and Neuron C Reference Guide for more information about implementing configuration property arrays. 6. In the Restriction Flags box, you can set configuration property flags that network tools must check in order to handle the configuration property appropriately. See Editing Mandatory Configuration Properties earlier in this chapter for more information on these flags. 7.
To add an implementation-specific network variable to a functional block, follow these steps: 1. Right-click the Implementation-specific NVs folder for the functional block in the Program Interface pane and then click Add NV on the shortcut menu.
3. In the Name property, enter a name for the network variable as it will appear in the LonMaker tool and other network management tools. This name must be unique to the device, can contain up to 16 alphanumeric characters, and must start with a letter. The name cannot contain spaces or the following characters: \ / : * ? “ < > |. The default name is nvValue. 4.
Implementation-specific configuration properties should be avoided as part of a device’s interoperable interface since they are not documented by a functional profile. WARNING: If you use implementation-specific configuration properties in your device interface, your device will not comply with interoperability guidelines version 3.4 (or better) and therefore cannot be certified by LONMARK.
3. In the Name property, enter a name for the configuration property as it will appear in the LonMaker tool and other network management tools. This name must be unique to the device, can contain up to 16 alphanumeric characters, and must start with a letter. The name cannot contain spaces or the following characters: \ / : * ? “ < > |. The default name is cpValue. 4.
of the functional profile containing the configuration property type. To use a User-Defined type, you must first add the resource file containing the UCPT to the resource catalog as described in the NodeBuilder Resource Editor User’s Guide. 6. In the SCPT or UCPT property, select the configuration property to be added to the functional block or device from the list.
Structure SNVT_switch {200, 0} Enumeration SNVT_hvac_mode HVAC_AUTO If you need help entering a valid initializer value, you can click the button to the right of the Initializer property to open the Edit Initializer dialog. This dialog provides information on the data type such as scaling, and minimum and maximum values.
The Structure Fields box displays all the fields in the structured network variable or configuration property. If no initializer has previously been set, the Value boxes for each field and the Initializer box are empty. To enter values for the fields in the structure, follow these steps: 1. Click anywhere in the field’s row. The scaling for the field is displayed in the Scalar Details box, and its minimum, maximum, and invalid (if any) values are displayed in the Limits box. 2.
3. All other fields in the structure are automatically set to their default values, which are defined in resource files. If no default value is defined for the field, it is set to 0 or the minimum value allowed if 0 is out of range. You can set all fields to their default values by clicking Use Default. The current initial value for the structure is displayed in the Initializer box. The values are enclosed in braces and are separated with commas (e.g., {SET_OFF, 0, 0} for a SNVT_setting data type). 4.
2. Click anywhere in the Value box, and select a value from the list of possible enumeration values. You can set the enumeration to its default value by clicking Use Default. 3. The current initial value for the enumeration is displayed in the Initializer box. You can edit the value by clicking Value in the Structure Fields box or directly editing the value in the Initializer box. 4. Click OK to save the changes.
3. The current initial value for the float or 32 data type is displayed in the Initializer box. You can edit the values of a field by either selecting the field and clicking Value in the Structure Fields box or directly editing the value in the Initializer box 4. Click OK to save the changes. The value specified in the Initializer box will be transferred to the Initializer property of the respective network variable or configuration property dialog.
Generating Code with the Code Wizard You can use the NodeBuilder Code Wizard to generate Neuron C source code that implements your device interface and creates the framework for your device application. To do this, click the Generate and Close option in the upper right-hand corner of the user interface. Alternatively, you can right-click the device template folder in the Program Interface pane and click Generate and Close on the shortcut menu.
The following table lists and describes the files created by the NodeBuilder Code Wizard. 174 Source File Description .nc The main Neuron C source file for the device application. All other files generated by the Code Wizard are included in this file using #include statements. .h Contains header information and function declarations for the main source file. Defines a number of constants that are used in the application code. .
Source File Description filesys.nc Contains functions used to facilitate transfer of configuration properties implemented as configuration files. This file is only generated if you selected the File Transfer Protocol configuration property access mode (for more information, see Using the Program Interface Pane earlier in this chapter). filesys.h Contains header information and function declarations for configuration properties implemented as configuration files. filexfer.
Each time you generate code using the Code Wizard, it checks whether each of the common files exists on the Include Search Path property. If a file exists, the Code Wizard uses the one in the common folder; otherwise it creates the file in the source files folder. Using Code Wizard Templates When you generate the Neuron C code for a device interface, the Code Wizard creates the source code file based on a code template.
Version 1 Templates The version 1 templates were the initial implementation of the Code Wizard templates, which are no longer supported by the Code Wizard. You should upgrade existing NodeBuilder projects to the Version 3 template because it generally results in more compact and faster code, and better compliance with interoperability guidelines. You can, however, continue using the Code Wizard with the version 1 templates.
178 Defining Device Interfaces and Creating their Neuron C Framework
7 Developing Device Applications This chapter provides an overview of the Neuron C Version 2.2 programming language. It describes how to edit the Neuron C source code generated by the NodeBuilder Code Wizard to implement your device functionality. It explains how to use the NodeBuilder Editor to edit, search, and bookmark Neuron C code.
Introduction to Neuron C Neuron C Version 2.2 is a programming language based on ANSI C that you can use to develop applications for Neuron Chips and Smart Transceivers. It includes network communication, I/O, interrupt-handling, and event-handling extensions to ANSI C, which make it a powerful tool for the development of LONWORKS device applications.
Each network variable, configuration property, and functional block is defined by a type definition contained in a resource file. Network variables and configuration properties are defined by network variable types (NVTs) and configuration property types (CPTs). Functional blocks are defined by functional profile templates (FPTs). Network variables, configuration properties, and functional blocks in Neuron C can use standardized, interoperable types.
Neuron C Variables The following sections briefly discuss various aspects of Neuron C-specific variable declarations. Data types affect what sort of data a variable represents. Storage classes affect where the variable is stored, whether it can be modified (and if so, how often), and whether there are any device interface aspects to modifying the data. Neuron C Variable Types Neuron C supports the following C variable types. The keywords shown in square brackets below are optional.
the declaration of CP families or configuration network variables. The Neuron C language does not permit the use of const with auto. • extern declares a data item or function that is defined in another module, in a library, or in the system image. • static declares a data item or function which is not to be made available to other modules at link time.
Declaration Example Simple data items int a, b, c; Data types typedef unsigned long ULONG; Enumerations enum hue {RED, GREEN, BLUE}; Pointers char *p; Functions int f(int a, int b); Arrays int a[4]; Structures and unions struct s { int field1; unsigned field2 : 3; unsigned field3 : 4; }; The Neuron C Version 2.
be completed by the developer. The C language comments supplied in the source files generated by the Code Wizard describe the aspects and ramifications of various interoperability procedures. For more information, see the LonMark Application Layer Interoperability Guidelines. • Default directors for functional blocks or functional block arrays.
nv_properties { cpTransInMin = 0, cpTransInMax = 3000L }; // // network output SNVT_lev_percent nvoPercentage; : : // //}}NodeBuilder Code Wizard End You can override the code generated by the NodeBuilder Code Wizard by moving the // command out of the Code Wizard section, as shown below: //{{NodeBuilder Code Wizard Start : // network input SNVT_temp_p nviTempP nv_properties { cpTransInMin = 0, cpTransInMax = 3000L }
SetLed( 1, DigitalOutput[1]::cpDigitalDefault.state ); setLockedOutBit( uFblockIndex, FALSE ); } .... Add when-tasks Responding to I/O and Timer Events You can add when-tasks to respond to I/O and timer-related events, as needed. Add these event handlers to the main source file if they affect global I/O or timers, and add them to the individual functional block’s source file if they affect functional block-specific items.
Another example is a scheduler that can control a variety of device types by allowing the integrator to change the type of the output of the scheduler. The Code Wizard generates code that contains a framework for supporting changeable network variable types. The method used by the Neuron firmware to change the size of a network variable uses an NV length override system image extension that is managed by the application.
The Code Wizard does not provide framework code for this task, but a commented source code example is provided in the Neuron C Programmer’s Guide. Neuron C Version 2 Features Not Supported by the Code Wizard The following overview summarizes features of the Neuron C Version 2 language that are currently not used or not supported by the NodeBuilder Code Wizard. See the Neuron C Programmer’s Guide and Neuron C Reference Guide for more information about Neuron C Version 2.2.
block or functional block array). This restriction applies to both the static and global configuration property sharing scopes. range_mode_string. The NodeBuilder Code Wizard does not support the range_mode_string option, which supports the setting of LONMARK range modification for a configuration property. when() clauses Unqualified when(msg_arrives). The NodeBuilder Code Wizard code generates an unqualified when(msg_arrives) task as part of the pre-defined FTP server implementation (see the filexfer.
by double clicking it. You can open multiple files in the Edit pane of the NodeBuilder Project Manager. You can switch between open files using the Window menu. You can cut, copy, and paste text using standard Windows commands. For example, you can cut selected text using CTRL+X, the Cut button on the toolbar, or by clicking Cut on the Edit menu. This section describes the following: 1. 2. 3. 4. The color-coding scheme used to highlight source code based on Neuron C syntax.
3. Enter the text string to search for in Find what. 4. Set Match Whole Word Only to find only whole words that match the string. Set Match case to make the search case sensitive. 5. Click Find Next to find the next occurrence of the string, starting from the current cursor position and moving down. Click Mark All to have every line in the file containing the string bookmarked (for more information, see Using Bookmarks later in this chapter,).
2. In the Text to Find property, enter the text string to be found. 3. In the File Types property, select the file types to be searched. By default, the search will look in Neuron C files (.nc extension), header files (.h extension), and C files (.c extension). You can remove a file type from the search by removing the corresponding *. entry. You can add additional file types by adding *. to this field. 4.
Expression Description ? The question mark replaces one or zero characters. The search must contain at least two other characters. Use \? to represent a question mark character. . The period replaces exactly one character. The search must contain at least two other characters. Use \. to represent a period character. (pattern) Matches the pattern and remembers the match.
5. In the Where property, select which files to search. You have the following three choices: • Search all Files in Project. Searches all files in the current NodeBuilder project. This is the default. • Search all Open Files. Searches all currently open files. Open the Window menu to see which files are currently open. • Search in Directories. Search all files in a specific directory. 6.
Alternatively, you can access this tab by clicking Project, clicking Settings, and then clicking the Editor tab, or by clicking the Project Settings button ( ) on the Editor toolbar, and then clicking the Editor tab. 2. Set the following properties: Code Settings Tab Width Determines the tab size. By default, the tab size is 4. Auto Indent Automatically indents code inside a function or conditional statement. This check box is selected by default. Syntax Coloring Enables syntax highlighting.
8 Building and Downloading Device Applications This chapter describes how to compile Neuron C source code, build an application image, and download the application image to a device. It explains how to add target devices to a NodeBuilder project and how to manage them.
Introduction to Building and Downloading Applications You can build an application image for one or more development or release targets in a NodeBuilder project. After you build the application image, you can download it to a development platform such as an FT 5000 EVB or an LTM-10A Platform, a custom device that you have manufactured, or a third-party device.
• To build one or more targets in the current NodeBuilder project, click one target device template, optionally, hold down CTRL and click the other targets or device templates containing the targets to be built, right-click one of the selected items, and then click Build on the shortcut menu. 4. The NodeBuilder tool automatically saves all unsaved project files when you start a build.
Note: To stop a build in progress, open the Project menu and then select Stop Build. 6. If the Load After Build option ( )in the NodeBuilder toolbar is set or if the Load after Build check box in the Build tab of the NodeBuilder Project Properties dialog is selected, all commissioned devices that use one of the applications produced by the build are automatically downloaded to the devices.
Downloadable Application Image Files These files contain the application image used by the LonMaker tool and other network tools to download the compiled application image to a device. (.APB, .NDL., and NXE,) There are three types of downloadable application image files: the binary application image file (.APB extension), the .NDL file, and the text application image file (.NXE extension). These files are described as follows: • The .
the application code and data that resides in off-chip EEPROM, flash, or NVRAM (if any). For these devices, this file is used with a device programmer to program the external memory chips. If the application image was built for a Neuron 3120 Chip, this file contains some or all of the on-chip EEPROM image in a special format for use only with a Neuron 3120 programmer. Device Interface Files (.XIF, .XFB, and .xfo) • Off-chip serial EEPROM. For the 5000 Series chips, the .
Excluding Targets from a Build You can exclude a target or a device template from project builds, and you can exclude a target from a device template build. To exclude a target or device template from a build, right-click the device template or the Release or Development target folder and then click Build Exclude on the shortcut menu. The selected device template or target folder will be dimmed.
Note: The Clean command only removes files and folders produced by the NodeBuilder tool. It does not remove any files that you have generated with the NodeBuilder tool. Viewing Build Status You can view the build status of all NodeBuilder device templates and targets. The build status shows whether the latest version of the source files have been compiled and built and whether all known devices have had the latest version of the application loaded.
2. The Build Status dialog opens. 3. Each row in this dialog represents a device template target or a target. Targets are listed beneath their associated device template target. The dialog has the following columns: Template The NodeBuilder device template. Target The target type (Release or Development). Device If this row contains the status for a target, this column displays the target name. If this column contains status for a device template target, this column is empty.
changed. This status is unlikely to occur. Link required. Applies to device template targets only. Indicates that one of the libraries or the system image has been modified since the application image was last built or that a property has been changed that requires the project be re-linked. Export required. Applies to device template targets only. Indicates that a property has been changed that requires the device to be exported. Load required. Applies to targets only.
process will move on to the next target, rather than aborting the build. 3. Load after Build Loads the application into a device immediately after the application image is built. The devices must be commissioned with the LonMaker tool and the LonMaker drawing containing the device must be open and ) on the attached to the network. The Load After Build button ( NodeBuilder toolbar reflects changes to this option and vice versa. This check box is selected by default.
Processor Neuron 5000 Processor System Image Memory Type On-chip ROM FT 5000 Smart Transceiver Neuron 3150 Chip Off-chip flash Application Memory Type Application Image File Extension Application Image Programming Tool Off-chip serial EEPROM .NME Off-chip serial flash .NMF Off-chip serial EEPROM or flash .NDL NodeLoad Utility Off-chip flash .NEI Device programmer .NDL NodeLoad Utility .NEI Neuron 3120 Programmer .APB and .NXE (TP/XF-1250 devices only) Network Tool .
The system image resides in on-chip ROM. The application image and the system image are copied from the external non-volatile memory into the on-chip RAM at chip startup and reset. The Neuron firmware is responsible for copying any writes that are directed towards external non-volatile memory. See the Neuron Chip or Smart Transceiver data book for more information. The build process produces an .NME file for application code and data designated for external EEPROM and an optional .
The following sections provide two sets of diagrams illustrating connection schemes that you could use for connecting external serial memory devices to the Aardvark programmer over the I2C and SPI interfaces in the Neuron core of the 5000 Series chips.
Note: In this diagram, all jumpers are set into position 1-2 for normal operation, and they are set into position 2-3 for in-circuit programming. You must always power off your device before changing the jumper settings.
FT 5000 45 Aardvark 1 SCL SDA_CS1~ RST~ SCL 43 3 28 2 SDA GND 10 GND VCC GND VCC R1 4.99k R2 4.99k SDA SCL Serial EEPROM Device GND Note: Pins 2 and 10 on the Aardvark are both connected to ground inside the Aardvark. As a result, when the Aardvark is connected to the device board, it finds a reference ground at pin 10 and it takes the RST~ line to ground on pin 2 at the same time.
Serial Memory Device-Aardvark Connection Scheme for SPI Interface To connect an external serial EEPROM or flash device to the Aardvark programmer and perform in-circuit programming over the SPI interface, you could use the following schemes: Notes: In this diagram, all jumpers are set into position 1-2 for normal operation, and they are set into position 2-3 for in-circuit programming. You must always power off your device before changing the jumper settings.
Note: Pins 2 and 10 on the Aardvark are both connected to ground inside the Aardvark. As a result, when the Aardvark is connected to the device board, it finds a reference ground at pin 10 and it takes the RST~ line to ground on pin 2 at the same time. This means that once the Aardvark connection is removed, the RST~ line is released and the 5000 Series chip resumes normal operation.
When using flash memory, always enable the flash programmer’s software data protect, SDP, feature if possible. You must have at least 0x5600 bytes mapped for flash or else the SDP algorithm will not work. You can define sections of application code that will reside in EEPROM, flash memory, or NVRAM, coexisting with the Neuron firmware and other application code in ROM. The portion of the code that will reside in EEPROM, flash, or NVRAM is contained in the EEPROM image file (.NEI extension).
areas, as well as in on-chip EEPROM. Whenever the Neuron Chip or Smart Transceiver is reset, the Neuron firmware compares the on-chip and off-chip signatures, and if there is a mismatch, the Neuron firmware changes the device state to applicationless. If the device copies the boot image to on-chip EEPROM, this check will follow that process, and will override the firmware state selection if the signatures do not match.
Upgrading 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.
The NodeBuilder Basic Shapes 4.00 stencil contains a Development Target Device shape and a Release Target Device shape. These special device types help distinguish between other devices on the network and the target devices used by the NodeBuilder tool. The NodeBuilder tool lets you create a mixed network of development hardware (such as the FT 5000 EVB or the LTM-10A Platform), release hardware (your own hardware), and other devices. 218 4.
8. Click Next three times. The window in the New Device Wizard lets you select the application image to be downloaded to your device. 9. Select the Load Application Image check box and then click Next. This specifies that you will download the binary application image file (.APB extension) built for the device application to the device.
10. The next window lets you set the initial device state and the source of configuration property values when your device is commissioned. 11. Select the Online option under State. This means that your device will run its application after it has been commissioned. 12. Click Finish. The Press Service Pin window appears.
13. Press the service pin on the development platform you to be loaded and commissioned. The LonMaker tool loads the application image for your device application to the device and makes it operational. When the LonMaker tool is done commissioning, it will return to the LonMaker drawing. The device shape will be will be solid green indicating that the device has been commissioned and is online. The device application will not do anything until you test the device or connect it to other devices. 14.
222 2. The Insert Device dialog opens. 3. This dialog organizes the devices in currently open LonMaker networks by LNS device template name. If the LNS device template used by the device is based on a NodeBuilder device template, the NodeBuilder device template name is displayed in the NB Dev Template column. These devices cannot be added to your NodeBuilder project. 4. Expand the folder containing the desired device template and then select the device to be added. 5.
7. Click OK to add the target to the Devices folder in the NodeBuilder Project pane. If this device is commissioned, the NodeBuilder tool will download the application to the device the next time you build it. Managing Target Devices You can build, debug, and edit target devices from the Project pane in the NodeBuilder Project Manager. The Devices folder in the Project pane contains all the targets defined in the current NodeBuilder project that you have created in a LonMaker network.
Remove Removes the device as a target for future builds. The device is removed from the current NodeBuilder project, but it is not removed from the LonMaker drawing or network, and none of the device files are deleted. To replace the LonMaker shape in your LonMaker drawing, drag the Device shape in the LonMaker Basic Shapes stencil over the Development or Release Target shape, select the Replace the Existing Device Shape with the Shaped just Dropped check box in the New Device Wizard, and then click OK.
3. You can view and set the following properties: Device Name Displays the name of the device specified in the LonMaker drawing. This field is read-only. Subsystem Displays the subsystem (drawing page) in the LonMaker drawing where the device is located. This field is read-only. NodeBuilder Device Template Displays the name of the current NodeBuilder device template used by the target.
Current LNS Device Template 4. 226 Displays the name of the LNS device template associated with the target. This field is read-only and is automatically updated if you build the target with a new NodeBuilder device template. Click OK to save the settings.
NodeBuilder FX User's Guide 227
9 Testing a NodeBuilder Device Using the LonMaker Tool This chapter 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 LONWORKS devices in a network.
Introduction to Testing NodeBuilder Devices You can use the LonMaker tool to test your NodeBuilder device. You can press the hardware inputs on your device and use the LonMaker tool to monitor changes to the values of the network variables in the device interface. You can also use the LonMaker tool to control the values of the input network variables and observe whether the hardware outputs function as designed and output network variable values change accordingly.
3. Expand the Subsystem icon, expand your NodeBuilder device icon, expand a functional block in the device interface corresponding to a hardware input, and then select an output network variable in the functional block; select the Enable Monitoring check box; and then click OK. 4. The Data Point shape is added to your LonMaker drawing. 5. Toggle the hardware input and observe the value of the corresponding output network variable change in the Data Point shape. 6.
7. Double-click the Data Point shape for the input network variable, enter a different value, and then click anywhere outside the Data Point shape. Observe the hardware output change based on the value you entered for the input network variable. If the data point has a structured value, you can also set the value by right-clicking the data point shape and selecting Value Details on the shortcut menu. The Set Network Variable Value dialog opens.
3. The LonMaker Browser opens. It displays the functional blocks in your device interface and the network variables and configuration properties within each functional block. You can only write values to the input network variables (blue) and writable configuration properties (green). 4. Right click anywhere in the row for each network variable and configuration property and click Properties on the shortcut menu.
234 5. The Network Variable Properties or Configuration Property Properties dialog opens. 6. Verify that the network variable or configuration property has the correct type and size. 7. Monitor All button on the toolbar to start polling all network variable and Click the configuration property values.
8. Change network variable and configuration property values and confirm that the device hardware works as designed. For example, toggle a hardware input and observe the value of the corresponding output network variable change. You can then change the value of an input network variable and observe the hardware output change based on the value you entered. For more information on using the LonMaker Browser, see Chapter 6 of the LonMaker User’s Guide.
c. In the New FB Name: property under Functional Block, enter the name for the functional block. The functional block name may be up to 85 alphanumeric characters and include embedded spaces; the name may not include the period, backslash, colon, forward slash, or double quote characters. d. Select the Create All Network Variable Shapes check box. 5. Click Finish. The New Functional Block wizard closes and the LonMaker drawing appears. A new functional block shape appears on the drawing. 6.
b. Drag the other end of the Connector shape to the input network variable of the other functional block until it snaps into place and a square box appears around the end of the Connector shape. There is a brief pause as the LonMaker tool updates the device over the network. Note: You can also create connections using the Connector tool ( ) on the Visio Standard toolbar or the Network Variable Connection dialog box.
238 b. Right-click the new Connector shape it and select Monitor Input Value to display the current value of the input network variable in the connection. c. Right-click the new Connector shape it and select Monitor Output Value to display the current value of the output network variable in the connection.
9. Toggle a hardware input to test the connection between the network variables change. Observe the hardware output and the current values of the network variables on the Connector shape change as you toggle the hardware input.
240 Testing a NodeBuilder Device Using the LonMaker Tool
10 Debugging a Neuron C Application This chapter describes how the use the NodeBuilder debugger to troubleshoot your Neuron C application.
Introduction to Debugging You can use the NodeBuilder debugger within the NodeBuilder Project Manager to control and observe the behavior of your device application over a LONWORKS channel in order to debug it. The debugger lets you set breakpoints, monitor network variables, halt the application, step through the application, view the call stack, and peek and poke memory. You can make changes to the code as you debug a single device or debug multiple devices simultaneously.
2. The NodeBuilder debugger opens. 3. The Debug menu appears on the NodeBuilder menu bar and four new panes open in the NodeBuilder project manager: the Debug Device Manager pane, the Breakpoint List pane, the Call Stack pane, and the Watch List pane.
Debug Device Manager Displays which devices are currently being debugged, and lets you pause and resume the application on each device. If at least one debug session is in progress, the status bar will indicate the device currently being debugged and its current state (Running, Halted, Reset, and so on). For more information, see Using the Debug Device Manager later in this chapter. Breakpoint List Displays all the breakpoints that have been set.
The following table describes each of the buttons in the Debugger toolbar. View Breakpoint List Toggles the breakpoint list pane. See Setting and Using Breakpoints later in this chapter for more information. View Watch List Toggles the watch list pane. See Using the Watch List Pane later in this chapter for more information. View Call Stack Toggles the call stack pane. See Using the Call Stack later in this chapter for more information. Resume Resumes execution of a halted application.
Halting an Application You can stop an application while it is running in debug mode by clicking the halt button ( ) on the Debugger toolbar. Alternatively, you can click Debug, point to Halt, and select Current Device or All Devices. If the device halts in application code, the editing pane displays the line of code where the application was halted using an arrow ( ) in the left margin.
Stepping Through Applications You can step through the code in your application one line at a time after you halt the application. You can step into or step over a line of code. The two methods are identical for all statements except for function calls. When you step over a function call, the function executes and you step to the line of code after the function call. When you step into a function, you step to the first executable line of the function.
To add a variable, network variable, or configuration property to the watch list and monitor its value in the Watch List pane, follow these steps: 248 1. Right-click a variable name or statement in the source code and then click Watch Variable on the shortcut menu. 2. The Watch Variable dialog opens. 3. If you right-clicked a variable name, the selected variable appears in the Watch Type box. You can proceed to step 5.
4. If you right-clicked a statement, the drop-down list in the Watch Type box is empty and you need to select one of the following types of variables to watch : • Watch variable. Enter a network variable using its global network variable name or using its functional block member name (for example, using the scope operator “::”). Similarly, you can enter a configuration network variable using its global network variable name or using the corresponding configuration property syntax.
Scalar network variables contain a single field that contains their value. If the variable does not exist, a Symbol Not Found dialog opens. 6. Optionally, you can edit the value of a variable or a field in a structure in the Watch List pane. a. To edit the value of a scalar variable, double-click anywhere in the row containing the variable or right-click the variable and then click Edit Value on the shortcut menu.
c. Enter the new value for the variable and then click OK. If you are editing the value of an enumerated type, select an enumeration from the list or click Enter in Decimal or Enter in Hex and then enter the desired index of the enumeration. d. Click OK to save the value. Notes: • To remove a variable from the watch list, right-click the variable in the Watch List pane and click Delete on the shortcut menu.
Stop All Stops debugging all devices, removes all the devices from the Debug Device Manager pane, and closes the NodeBuilder debugger. To restart debugging for a device, right-click the device under the Devices folder in the Project pane and click Debug on the shortcut menu. Allow Docking Docks the Debug Device Manager pane into the NodeBuilder Project Manager. The Debug Device Manager pane appears as a floating window that you can move and resize by default.
In the Address field, enter the address to start writing in. In the Count field, enter the number of bytes to write. In the Byte field, enter a two digit hexadecimal value. Click OK to write the value in Byte a number of times equal to Count starting at the address in Address. You are returned to the Peek/Poke Memory dialog. 4. Click Close to return to the NodeBuilder debugger. Executing Code in Development Targets Only You can designate code for execution in development targets only.
2. You can set the following options: Default Display Radix Specifies the default format in which data is displayed in the Watch List pane. You can choose to monitor data in the Watch List pane in Decimal or Hexadecimal format. Tick Interval Specifies how frequently (in milliseconds) the debugger processes incoming debug messages from the device. The default interval is 100 ms.
Fonts and Colors 3. Specifies the font, font size, and color used for text in the Breakpoint List, Call Stack, and Watch List panes. To change the font and color used in a pane, click the pane and then click Fonts and Colors. Click OK to save the settings.
256 Using the NodeBuilder Debugger
Appendix A Using the Command Line Project Make Facility This appendix describes how to use the command line project make facility with the project make command.
Using the NodeBuilder Command Line Project Make Facility You can invoke the NodeBuilder build tools from the Windows command line. You can use this feature to generate automated build scripts for your devices.
--defloc
Specifies a directory to search for the default command file. The default command file for the project make facility must be named lonpmk32.def. If a default directory that does not contain this file is specified, the command will fail silently. If no default directory is specified, the current directory will be searched for lonpmk32.def. The default command file can contain any number of command switches for the pmk command.-x Indicates that a clean operation will be performed on the specified NodeBuilder device template for the target specified by the –t command switch. A clean operation removes all files and folders produced by a build. The following example demonstrates a minimal command line invocation of the Project Make Facility: PMK –p=Test.nbprj –b=MyDevice.
Appendix B Using Source Control With a NodeBuilder Project This appendix describes how to manage a NodeBuilder project using a source control application.
Using Source Control with a NodeBuilder Project When developing a large NodeBuilder project, you can put the project under source control to allow multiple developers to work concurrently on different parts of the project. This appendix lists all the files associated with a NodeBuilder project that should be kept under source control. The following abbreviations for file locations are used throughout the table: The LONWORKS folder, which is typically C:\LonWorks.
Neuron C Source Files (.nc, .c, and .h) The main source file, .nc, is stored in the C:\Lm\Source\\ folder. This file and any files included with the #include directive must be checked in. Standard header files are stored in the C:\LonWorks\NeuronC\Include folder. These files should never be edited because future installs will overwrite modified files and changes would be lost.
264 Appendix B: Using Source Control with a NodeBuilder Project
Appendix C Glossary This appendix provides definitions for many terms commonly used with NodeBuilder device development.
3100 Series Chip The term used to collectively refer to all previous-generation Neuron chips, including the 3150 and 3120 Neuron chips; the 3150 and 3120 FT Smart Transceivers; and the 3170, 3150, and 3120 PL Smart Transceivers. 5000 Series Chip The term used to collectively refer to the Neuron 5000 Processor and FT 5000 Smart Transceiver. Application Device A LONWORKS device that runs a LonTalk Application (OSI Layer 7).
Channel 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 RF, and other types. Clock Multiplier For 5000 Series chips, you can select the frequency at which the Neuron Chip runs to modify the internal system clock speed.
Device A device that communicates on a LONWORKS network. A device may be an application device, network service device, or a router. Devices are sometimes referred to as nodes in LONWORKS documentation. Device Interface The logical interface to a device. A device’s interface specifies the number and types of functional blocks; number, types, directions, and connection attributes of network variables; and the number of message tags. The program ID field is used as the key to identify each external interface.
the FT 3150 EVB and FT 5000 EVBs. In a self-installed network, you can use the ISI protocol to connect the FT 3150 EVB running the MGSwitch, MGLight, or MGDemo applications to an FT 5000 EVB running the NcSimpleIsiExample or NcMultiSensorExample applications. FT/PL 3120 EVB A LONWORKS evaluation board that uses Echelon’s FT or PL 3120 Smart Transceiver. It is connected to a MiniGizmo board that includes eight push buttons, eight LEDs, a temperature sensor, and a piezo buzzer.
IP-852 Network Interface Formally called VNI, an IP-852 network interface enables IP-852 devices such as LNS Server computers, LonMaker computers, and i.LON IP-852 routers to be attached to IP-852 channels. An IP-852 network interface requires that the LONWORKS-IP Configuration Server be configured before trying to communicate with remote devices or remote computers.
LNS Server The computer containing the LNS global database acts as the LNS Server. The LNS global database contains the group of LONWORKS networks being managed with the LNS Server. Local Client A LonMaker computer that is also running the LNS Server. Local Device An FT 5000 EVB board running the NcMultiSensorExample application that receives SNVT_lux and/or SNVT_temp_p output network variable updates from another device (a remote device).
Mandatory Network Variable/Configuration Property A network variable/configuration property that must be implemented by the functional block, as specified by the functional profile that the functional block is instantiating. Mini Kit A tool for evaluating the development of control network applications with the ISO/IEC 14908 standard.
Neuron C A programming language based on ANSI C that you can use to develop applications for Neuron Chips and Smart Transceivers. It includes network communication, I/O, and event-handling extensions to ANSI C, which make it a powerful tool for the development of LONWORKS device applications. Neuron Chip A semiconductor component specifically designed for providing intelligence and networking capabilities to low-cost control devices.
NodeBuilder Hardware Template A file with a .NbHwt extension that defines the hardware configuration for a target device. It specifies hardware attributes including platform, transceiver type, Neuron Chip or Smart Transceiver model, clock speed, system image, and memory configuration. Several hardware templates are included with the NodeBuilder tool. You can use these or create your own.
network interface mode. In NSI mode, the host treats the PCNSI card as a smart peripheral device that provides access to an NSS either locally on the PC or remotely via the LONWORKS network. In network interface mode, the host uses the PCNSI card as a standard LONWORKS network interface. The PCNSI card is supported, but it is not recommended for use with the NodeBuilder FX tool.
which implements the ISI protocol) that replaces parts of the network management server’s functionality, resulting in a network that no longer requires a special tool or server to establish network communication or to change the configuration of the network. Service Pin Each Neuron Chip has a service pin used during installation to acquire the Neuron Chip’s Neuron ID.
User-defined Configuration Property Type (UCPT) A non-standard data structure used for configuration of the application program in a LONMARK device. UCPTs should be used only when there is no appropriate standard configuration property type (SCPT) defined. LONMARK-certified devices must have UCPTs documented in resource files according to a standard format, in order to allow the devices to be configured without the need for proprietary configuration tools.
278 Appendix C: Glossary
Appendix D NodeBuilder Software License Agreement When installing the NodeBuilder software, you must agree to the terms of the software license agreement detailed in this appendix.
NodeBuilder® Development Tool NOTICE This is a legal agreement between you and Echelon Corporation (“Echelon”). YOU MUST READ AND AGREE TO THE TERMS OF THIS SOFTWARE LICENSE AGREEMENT BEFORE ANY LICENSED SOFTWARE CAN BE DOWNLOADED OR INSTALLED OR USED.
software product shipped with the NodeBuilder Development Tool product and not contained in the NodeBuilder directories as identified in the Documentation.
one computer at a time, and provided that such installation and use otherwise comply with all the terms and conditions of this Agreement; (d) keep the original media on which the Licensed Software was provided by Echelon solely for backup or archival purposes; (e) make, use, and sell Your Devices that You developed pursuant to the terms of the LONWORKS OEM License Agreement between You and Echelon; (f) distribute Your Device Plug-ins; and (g) physically transfer any authorized copy of the Licensed Software
comply with the above restrictions, will result in automatic termination of this license and will make available to Echelon other legal remedies. TERMINATION This license will continue until terminated. Unauthorized copying of the Licensed Software or failure to comply with the above restrictions will result in automatic termination of this Agreement and will make available to Echelon other legal remedies.
MAY NOT APPLY TO YOU. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY FROM STATE TO STATE AND JURISDICTION TO JURISDICTION.
The parties hereto confirm that it is their wish that this Agreement, as well as other documents relating hereto, have been and shall be written in the English language only. Les parties aux présentes confirment leur volonté que cette convention de même que tous les documents y compris tout avis qui s’y rattache, soient rédigés en langue anglaise.
www.echelon.
