IzoTTM NodeBuilder User’s Guide Develop hardware devices and software applications using Echelon's Series 6000, 5000, and 3100 chips and Smart Transceivers.
Echelon, LON, LonWorks, Neuron, 3120, 3150, Digital Home, i.LON, IzoT, FTXL, LonScanner, LonSupport, LNS, LonMaker, LONMARK, LonPoint, LonTalk, NodeBuilder, ShortStack, and the Echelon logo are trademarks of Echelon Corporation that may be registered in the United States and other countries. Other brand and product names are trademarks or registered trademarks of their respective holders.
CONTENTS Preface ...................................................................................................ix Purpose ........................................................................................................... x Audience .......................................................................................................... x Hardware Requirements .................................................................................. x Content ..........................................
FT 6000 Evaluation Boards .............................................................. 39 LTM-10A Platform and Gizmo 4 I/O Board ...................................... 41 Step 5: Compiling, Building, and Downloading the Application .............. 42 Step 6: Testing the Device Interface ....................................................... 46 Step 7: Debugging the Device Application ............................................. 48 Step 8: Connecting and Testing the Device in a Network ...................
3120 and 3170 Neuron Core ................................................... 122 Setting the Hardware Template Description................................... 122 6 Defining Device Interfaces and Creating their Neuron C Application Framework ..........................................................................................124 Introduction to Device Interfaces ................................................................. 125 Starting the Code Wizard ..............................................
Neuron C Version 2 Features Not Supported by the Code Wizard 183 Message Tags.......................................................................... 183 I/O Models ................................................................................ 183 Network Variables .................................................................... 183 Configuration Properties .......................................................... 183 when() clauses ..................................................................
Debugging Interrupts for 5000 or 6000 Series chips ............................ 239 Using Statement Expansion .................................................................. 239 Using the Watch List Pane .................................................................... 239 Using the Call Stack Pane .................................................................... 243 Using the Debug Device Manager Pane............................................... 243 Peeking and Poking Memory ....................
viii Preface
Preface The IzoT™ NodeBuilder® Development Tool is a complete hardware and software platform that is used to develop applications for Neuron Chips and Echelon Smart Transceivers. The IzoT NodeBuilder tool lets you create, debug, test, and maintain IzoT and 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 IzoT NodeBuilder tool to develop IzoT and LONWORKS device applications and build and test prototype and production IzoT and 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 IzoT NodeBuilder tool are listed below: • Microsoft® Windows. Windows 8 64-bit and 32-bit, or Windows 7 64-bit and 32-bit, or Windows XP 32-bit.
Explains how to manage development and release targets and insert libraries into a device template. Describes how to use the Hardware Template Editor to create and edit hardware templates. • Defining Device Interfaces and Creating their Neuron C Application Framework. Describes how to use the NodeBuilder Code Wizard to define your device interface and generate Neuron C code that implements it.
IzoT Commissioning ToolUser’s Guide (078-0514-01) Describes how to use the IzoT Commissioing Tool to design, commission, modify, and maintain LONWORKS networks. LONMARK SNVT and SCPT Guide Documents the standard network variable types (SNVTs), standard configuration property types (SCPTs), and standard enumeration types that you can declare in your applications. IZOT Plug-in for WireShark Guide (078-9511-01A) Describes how to use the IzoT Plug-in for WireShark.
Region Languages Supported Contact Information Europe English German French Italian Echelon Europe Ltd. Suite 12 Building 6 Croxley Green Business Park Hatters Lane Watford Hertfordshire WD18 8YH United Kingdom Phone: +44 (0)1923 430200 Fax: +44 (0)1923 430300 lonsupport@echelon.co.uk Japan 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 IzoT NodeBuilder Development Tool. It lists the new features in the IzoT NodeBuilder tool, summarizes the components included with theIzoTNodeBuilder tool, and provides an overview of NodeBuilder device development and network integration.
Introduction to the IzoT NodeBuilder Tool The IzoT NodeBuilder Development Tool is a complete hardware and software platform for developing, debugging, testing, and maintaining IzoT and LONWORKS devices based on the Neuron 6000 Processor and FT 6000 Smart Transceiver and all previous-generation Series 5000 and Series 3100 chips.
devices in Compatibility Mode can also communicate with LonTalk devices on different channels as long as there is a route created between the channels with one or more IzoT routers. In Enhanced Mode, LonTalk/IP devices cannot communicate with LonTalk devices, even with the use of IzoT routers. You can configure the IzoT Router included with the FT 6000 EVK to operate in either Enhanced Mode or Compatibility Mode.
FT 6000 EVB Evaluation Board The FT 6000 EVB is a complete 6000 Series IzoT and LONWORKS device that you can use to create IzoT and LONWORKS devices. The FT 6000 EVB includes a FT 6050 Smart Transceiver with an external 10 MHz crystal (you can adjust the system’s internal clock speed from 5MHz to 80MHz), an FT-X3 communication transformer, 64KB external serial EEPROM and flash memory devices, and a 3.3V power source.
// // // // // // // // // // // // TO DO: add code to return the current length of the network variable with index "nvIndex." Example code follows: switch case if && (nvIndex) { nviChangeableNv::global_index: (nviChangeableNv::cpNvType.type_category != NVT_CAT_INITIAL nviChangeableNv::cpNvType.type_category != NVT_CAT_NUL) { uResult = nviChangeableNv::cpNvType.
What's Included with the IzoT FT 6000 EVK The FT 6000 EVK includes the following components: • IzoT NodeBuilder Development Tool. The IzoT NodeBuilder Development Tool is an integrated development environment (IDE) for developing applications for Series 6000, 5000, and 3100 chips. It is available as a free download that requires a serial number to be installed.
• NodeBuilder Editor. Edit the Neuron C source code generated by the Code Wizard to create your device’s application, or create and edit your own Neuron C code. • NodeBuilder Debugger. Debug your application with a source-level view of your application code as it executes. • NodeBuilder Project Manager. Build and download your application image to your development platform or to your own device hardware.
For more information on the FT 6000 EVB hardware, including detailed descriptions of its Neuron core, I/O devices, service pin and reset buttons and LEDs, and jumper settings, see the FT 6000 EVB Hardware Guide. IzoT Commissioning Tool The IzoT Commissioning Tool is a software tool that you can use to install, connect, configure, test, and update devices that you develop with the IzoT NodeBuilder software.
Introduction to NodeBuilder Device Development and Network Integration An IzoT or LONWORKS network consists of intelligent devices (such as sensors, actuators, and controllers) that communicate with each other using a common protocol over one or more communications channels. Network devices are sometimes called nodes. Devices may be Neuron hosted or host-based. Neuron hosted devices run a compiled Neuron C application on a Neuron Chip or Smart Transceiver.
channels that use different media (channel types) together. Unlike other devices, routers are always attached to at least two channels. The IzoT Router can be configured to act as a DHCP relay for address allocation on the LonTalk/IP network. DHCP relay can be used to have a single server perform all of the allocation of addresses in a network, and then have the server’s allocations forwarded onto another subnet.
Field Description • 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. Standard manufacturer IDs are never reused or reassigned. 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.
A single network variable may be connected to multiple network variables of the same type but opposite direction. The following example shows the same switch being used to control three lights: The application program in a device does not need to know where input network variable values come from or where output network variable values go. When the application program has a changed value for an output network variable, it simply assigns the new value to the output network variable.
IzoT Commissioning Tool or a customized plug-in created for the device (see the OpenLNS Plug-in Programmer’s Guide for more information on creating OpenLNS device plug-ins). For example, an application may allow an arithmetic function (add, subtract, multiply, or divide) to be performed on two values received from two network variables. The function to be performed could be determined by a configuration property.
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.
Device manufacturers may also create user resource files that contain manufacturer-defined types and profiles called user network variable types (UNVTs), user configuration property types (UCPTs), and user functional profiles (UFPTs). You can create applications that only use the standard types and profiles. In this case, you do not need to create user-defined resource files. If you need to define any new user types or profiles, you will use the NodeBuilder Resource Editor to create them.
16 Introduction
2 Installing the IzoT NodeBuilder Development Tool This chapter describes how to get started with your IzoT NodeBuilder tool, including how to install the IzoT NodeBuilder software and connect the FT 6000 EVK hardware.
Installing the IzoT FT 6000 EVK To install your IzoT FT 6000 EVK, follow these steps: 1. Verify that you have a manufacturer ID. A manufacturer ID is required for many IzoT 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.
2. Run the IzoT NodeBuilder installer. 3. Run the NodeBuilder430.exe self-extracting installation program. The Welcome window of the NodeBuilder software installer opens. 4. Click Next. The NodeBuilder Development Tool License Agreement window opens. 5. 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.
6. Enter the NodeBuilder serial number on the back of IzoT Commissioning Tool DVD case in the Serial Number box. Optionally, you can enter the following registration information. The IzoT NodeBuilder tool automatically enters this information into your resource files. Your phone number, e-mail address, and Web address will be included with any resource file that you create and distribute. User Name Your name.
7. Click Next. If your computer does not have a LONWORKS directory, the Destination Location window appears. Choose a LONWORKS folder in which you want the IzoT NodeBuilder software installed.
10. Click Install to begin the NodeBuilder software installation. Before installing the IzoT NodeBuilder software, the following programs are automatically installed or upgraded on your computer (if they are not already installed on your computer, or if they are installed, but have a lower version): NodeBuilder Resource Editor 4.0, LONMARK Resource Files 14.00, LNS Plug-in Framework 1.10, and ISI Developer’s Kit 3.02. 11.
13. 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. 14. If you do not have a PDF document viewer, install Adobe Reader from get.adobe.com/reader/.
3 IzoT NodeBuilder Quick-Start Exercise This chapter demonstrates how to create an IzoT or LONWORKS device using the IzoT NodeBuilder Development tool.
IzoT NodeBuilder Quick-Start Exercise The following quick-start exercise demonstrates how to create an IzoT or LONWORKS device with the IzoT NodeBuilder tool. It introduces NodeBuilder features and provides some familiarity with the NodeBuilder interface. The first step required to develop a device is to define the requirements for the device. For this quick-start exercise, you will develop a device with one sensor and one actuator.
1. Create a new IzoT CT network. To do this, follow these steps: a. Click Start on the taskbar, point to Programs, point to Echelon OpenLNS CT, and then select OpenLNS Commissioning Tool. The LonMaker Design Manager opens. b. In the Network Name property under New Network, enter IzoT NB Exercise. c. Clear the Show All Options check box under New Network if it is selected. d. Click Create Network to create the new network. e.
f. Select the Network Attached check box and then select the LonTalk/IP network interface you created when you installed your FT 6000 EVK. g. Click Next. The Management Mode page appears. h. Select OnNet. This means that changes to the IzoT CT drawing are sent immediately to your NodeBuilder devices on the network. Click Finish. i. IzoT CT creates and opens a new network drawing. For more information on creating and opening IzoT CT networks, see Chapter 3 of the IzoT Commissioning Tool User’s Guide.
5. Accept the default NodeBuilder Project Name, which is the same name as the IzoT CT 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. For more information on creating NodeBuilder projects, see Chapter 4, Creating and Opening NodeBuilder Projects.
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 IzoT NodeBuilder tool installation is shown by default.
• In the Device Class (CC:CC) property, select the Multi-I/O module (5.01) option. • In the Usage (UU) property, select the General option. • In the Channel Type (TT) property, select the TP/FT-10 option. • In the Model Number (NN) property, enter 01. 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.
• 8. 32 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 IzoT 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 IzoT 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. 34 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.
36 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 IzoT NB 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 6000 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 IzoT 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 IzoT NodeBuilder tool will create downloadable application image files and device interface files.
CT displays a network drawing that shows the devices, functional blocks, and connections in your network. IzoT CTl also displays stencils that contain shapes that you can drag to your IzoT CT drawing. IzoT CT 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.
44 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 IzoT 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. IzoT CT loads the application image for your IzoT NB Example Device application to the development platform and makes it operational. When IzoT CT is done commissioning, it will return to the IzoT CT 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. 12.
To test your device’s interface with the IzoT Browser, follow these steps: 1. Right-click the IzoT NB Example Device device in your IzoT CT drawing, then click Browse on the shortcut menu. 2. The IzoT 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. You can only write values to the input network variables (blue) and writable configuration properties (green).
4. Press and hold the left button at the bottom of your development board (SW1 on the FT 6000 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.
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 IzoT 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.
50 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 6000 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 IzoT Commissioning Tool to connect your development devices to other devices and verify their operation within a network.
5. Click Finish. The New Functional Block wizard closes and the IzoT CT 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.
56 7. Click Finish. The New Functional Block wizard closes and the IzoT CT 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.
58 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 6000 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 an IzoT CT stencil. Create an IzoT device plug-in. Create an HMI. Create a device installation application Apply for LONMARK certification for your device.
b. The Device Properties dialog opens with the Attributes tab selected. This dialog allows you to read and write to the properties of the IzoT CT device. c. In the Device Name property, enter the name to be shown for the custom device shape in your IzoT CT stencil. d. Click the Basic Properties tab.
62 e. Set the Location and Ping Interval properties to the values to be saved with the custom device shape in your IzoT CT stencil. See the IzoT CT 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.
g. Set the Non-group Receive Timer property to the value to be saved with the custom device shape in your IzoT CT stencil. See the IzoT CT online help file for more information on this property. h. Click OK. i. Drag your NodeBuilder device to your IzoT CT stencil. A new custom IzoT CT 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 IzoT CT 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 IzoT CT 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 IzoT Commissioning Tool to design a simple HMI for your device.
HKEY_LOCAL_MACHINE\SOFTWARE\LonWorks\LonWorks Path The following table lists and describes the files that your installation application should install: Programmable Application Image Files (.APB and .NXE) The IzoT Commissioning Tool and other IzoT, OpenLNS, and 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.
Your installation executable should install your device interface files in a subdirectory labeled with your company name (C:\Program Files (x86)\LonWorks\Import\YourCompany, for example). Your installation should search for your company’s folder and, if not found, it should create a folder with your company’s name. See Building an Application Image in Chapter 8 for more information on these device interface files. Device Resource Files (.TYP, .FMT, .
68 Creating and Opening IzoT NodeBuilder Projects
4 Creating and Opening IzoT NodeBuilder Projects This chapter describes how to create, open, and copy IzoT 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 IzoT CT You can create a NodeBuilder project by starting the NodeBuilder Project Manager from the IzoT Commissioning Tool. To do this, follow these steps: 1. Create or open a IzoT CT drawing. See the IzoT Commissioning User’s Guide for more information on creating and opening IzoT CT drawings. If you will want to load the application you develop into a device, make sure the IzoT CT computer is attached to the network. 2.
property, and then select the IzoT network interface to be used for communication between the IzoT CT 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 IzoT CT network, and disable automatic IzoT 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 IzoT Commissioning Tool. To do this, follow these steps: 76 1. Create or open an IzoT CT network. See the IzoT Commissioning User’s Guide for more information on creating and opening IzoT CT networks. If you plan on downloading your device application to a device, make sure that the IzoT CT 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 IzoT 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 IzoT CT 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.
3. In the NodeBuilder Project dialog, select the Open an Existing NodeBuilder Project option and then click Next. 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:\Users\Public\Documents\LonWorks\OpenLnsCt \Source\ by default), and then select the project file (.NbPrj extension) in the project folder. 5. Click Finish.
• You can open specific windows within the default project by right-clicking a Development Target or Release Target device shape in the IzoT CT drawing, pointing to Custom, and then clicking Edit Source, NodeBuilder Properties, Build, or Debug on the shortcut menu. 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.
5. If you have previously associated a IzoT CT 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:\Users\Public\Documents\LonWorks\OpenLnsCt \Source\ by default), and then select the project file (.NbPrj extension) in the project folder. 7.
82 3. In the Database Name property under Existing Network, select the IzoT CT network design associated with the NodeBuilder project to be copied and then click Backup. 4. The OpenLNS CT 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 IzoT CT drawing, IzoT network database, and the NodeBuilder project are all stored in a single IzoT CT backup file (.zip extension) that is specified in the Backup File property (C:\Users\Public\Documents\LonWorks\OpenLnsCt \Backup\\_.zip by default). 7. After the backup has been created, copy the IzoT CT backup file from the source computer to a USB drive, another removable media, or a shared network drive with read/write permissions. 8.
11. Click OK. The IzoT CT drawing, IzoT network database, and the NodeBuilder project are copied to the target computer. The NodeBuilder project is associated with the IzoT CT network. 12. A message appears informing you that the network restore operation has been completed, and prompting you to select whether to open the IzoT CT 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.
5. Copy the user-defined hardware template backup to the C:\Program Files (x86)\LonWorks\NodeBuilder\Templates\Hardware\User directory on the target computer. You need to create a User folder in the Hardware directory if one does not already exist. 6. Copy the library backup to the same folder as they were located on the source computer. If this is not possible, you can re-add them to the project as described in Inserting a Library into a NodeBuilder Device Template. 7.
11. Browse to and open the device template folder backed up in step 3, and then select the NodeBuilder device template file (.NbDt extension). The device template is added to the NodeBuilder project under the Device Templates folder in the Project Pane.
With on the shortcut menu. Choose Microsoft Excel, Internet Explorer, or another XML browsing tool. The following XML files are created and maintained by the IzoT NodeBuilder tool: Project File (*.NbPrj) Contains a project definition including the project version and a list of the device templates and the hardware templates for a project. There is one project file per project. This file is stored in the project folder (C:\Users\Public\Documents\LonWorks\OpenLnsCt\Source\).
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 IzoT 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 IzoT 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. 90 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.
94 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 pre-defines several preprocessor symbols, including: _ECHELON, _NEURONC, _NODEBUILDER, and _NCC6. See the Neuron C Reference Guide for a complete list and 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 IzoT 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 IzoT 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.
Because the pragma library directive supports location-independent references to your library, this is the recommended method. To insert a library into a NodeBuilder device template, follow these steps: 112 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 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 IzoT 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.
however, 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 IzoT 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 IzoT 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.
6000 Series Chips The address ranges and consumption for the on-chip and off-chip memory of the 6000 Series chips are as follows: Off-Chip ROM The 6000 Series chips do not support off-chip memory; therefore, this property is set to N/A. Extended Non-Volatile The 6000 Series chips use a serial memory interface for external non-volatile flash memory devices.
IzoT NodeBuilder User's Guide 123
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: 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.
2. The NV Properties dialog opens. 3.
Name Displays the name of the network variable that will be used in the IzoT Commissioning 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 IzoT Commissioning 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 IzoT Commissioning 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. 152 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 IzoT Commissioning 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.
functional block is based. For example, a UNVT could not be added to a SFPT, but a SNVT may be added to a UFPT. 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 IzoT Commissioning 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.
If you are selecting a UNVT, the list contains all the UNVTs in resource files of the scope specified in the Scope field that match the program ID template to the degree specified by the scope. The network variable’s type must have a scope that is equal to or lower then the scope of the functional profile upon which the functional block is based. 7. In the Direction property, select whether you are adding an Input or Output network variable. 8.
Alternatively, you can right-click the Configuration properties folder in the Program Interface pane and select Add CP from the shortcut menu, or you can drag a configuration property from a Configuration properties folder in the Resource pane to the functional block’s Implementation-specific CPs folder or the Configuration properties folder in the Program Interface pane. 2.
3. In the Name property, enter a name for the configuration property as it will appear in the IzoT Commissioning 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.
5. In the Select Resource Type box, select whether the configuration property you are adding is based on a Standard or User-Defined type. If you select a User-Defined type, select the Scope 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.
Float SNVT_volt_f {0, 0x42, 1, 0x7c, 0x6666} 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. 168 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.
172 Defining Device Interfaces and Creating their Neuron C Framework
7 Developing Device Applications This chapter provides an overview of the Neuron C Version 2.3 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.3 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.
• const declares a value that cannot be modified by the application program. Affects self-documentation (SD) data generated by the Neuron C compiler when used in conjunction with the declaration of CP families or configuration network variables. 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 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.
• Default directors for functional blocks or functional block arrays. The source code for each functional block or functional block array contains a default implementation of a director function • Utility functions to manage functional block state. The Code Wizard generates common.h and common.nc files, which contain some utility functions. Most utility functions are delivered with the CodeWizard-3.lib library file (CodeWizard.lib for version 2 templates), and they are declared in the CodeWizard.
}; // // 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 }; : : // //}}NodeBuilder Code Wizard End // //
.... 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. Add interrupt-tasks Responding to Interrupt Requests You can add interrupt-tasks to respond to interrupt requests, as needed.
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. Whenever the firmware needs the length of a network variable, it calls the network variable length override system image extension to get it. This method provides reliable updates to network variable sizes.
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.3.
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.nc file). This code is only generated if the you selected the FTP configuration property access method.
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. How to search for a text string in a single source file or in all source files in the project. How to use bookmarks to return to frequently used parts of your code.
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,). Replacing Text You can search for a string and automatically replace it with another string.
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 6000 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 IzoT 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 IzoT 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 IzoT Commissioning 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 .
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 or 6000 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 IzoT NodeBuilder tool. It does not remove any files that you have generated with the IzoT 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 IzoT Commissioning tool and the LonMaker drawing containing the device must be open and attached to the network. The Load After Build ) on the NodeBuilder toolbar reflects changes to this option button ( 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 FT 6000 Smart Transceiver Neuron 3150 Chip On-chip ROM 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 serial EEPROM .NMF Compatible Device Programmer Off-chip serial EEPROM or flash .
Programming 5000 and 6000 Off-chip Memory A 5000 or 6000 Series device requires at least 2K of external serial EEPROM, and it can optionally contain external serial flash memory. There is no on-chip non-volatile memory provided for the application. Many types of EEPROM devices are supported; however, Echelon currently supports and provides drivers for only the following three external flash devices: Atmel AT25F512AN, ST M25P05-AVMN6T, and SST25VF512A.
some pins that are multifunctional; therefore you must program each external non-volatile memory device individually. After you connect the I2C or SPI interface to the Aardvark programmer or other compatible in-circuit device programmer, you can use a program such as the Flash Center Memory Programmer from TotalPhase to program your external serial EEPROM or flash memory device. You can download the Flash Center Memory Programmer for free from the TotalPhase Web site at www.totalphase.
FT 5000/6000-Aardvark I2C Connection [(via Jumpers and 10-pin split cable (Total Phase Part No. TP240212)] FT 5000 J1 45 1 2 1 3 Aardvark SCL SCL J2 SDA_CS1~ 1 43 2 3 3 SDA 2 GND GND 10 GND VCC VCC R2 4.99k R1 4.99k SDA SCL Serial EEPROM Device GND 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.
Serial EEPROM-Aardvark I2C Connection (Direct Connection) FT 5000 SCL SDA_CS1~ RST~ 45 1 43 3 28 2 Aardvark SCL 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: Serial EEPROM or Flash-Aardvark SPI Connection [(via Jumpers and 10-pin split cable (Total Phase Part No.
Serial EEPROM or Flash-Aardvark SPI Connection (Direct Connection) FT 5000 8 48 MOSI MOSI MISO 46 5 47 7 MISO SCLK SCK 9 40 SS CSO~ RST~ Aardvark 28 2 GND 10 GND GND VCC R1..3 3xR49.9 R4 100k CSO~ SCK MISO MOSI Serial EEPROM or Flash Device GND Note: Pins 2 and 10 on the Aardvark are both connected to ground inside the Aardvark.
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 and 6000 Series chips are compatible with device applications written for 3150 and 3120 Neuron Chips and Smart Transceivers. You can use the IzoT NodeBuilder tool to port your old application to a 5000 or 6000 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 or FT 6000 Smart Transceiver, and then re-build the device application.
used with any device. You can also create custom stencils with shapes customized for your devices and networks. 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 IzoT NodeBuilder tool.
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 IzoT Commissioning tool loads the application image for your device application to the device and makes it operational. When the IzoT Commissioning 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.
216 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 IzoT 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. 220 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.
9 Testing a NodeBuilder Device Using the IzoT Commissioning Tool This chapter describes how to use the Data Point shape and LonMaker Browser in the IzoT Commissioning tool to monitor and control your device. It explains how to use the IzoT Commissioning tool to connect your NodeBuilder device to other LONWORKS devices in a network.
Introduction to Testing NodeBuilder Devices You can use the IzoT Commissioning tool to test your NodeBuilder device. You can press the hardware inputs on your device and use the IzoT Commissioning tool to monitor changes to the values of the network variables in the device interface. You can also use the IzoT Commissioning 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.
226 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. Click the Monitor All button on the toolbar to start polling all network variable and 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 IzoT Commissioning Tool 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 IzoT Commissioning 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.
230 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.
232 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: 240 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.
248 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.
256 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. 6000 Series Chip The term used to collectively refer to the Neuron 6000 Processor and FT 6000 Smart Transceiver.
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 and 6000 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.
FT 6000 EVB A LONWORKS evaluation board that uses Echelon’s FT 6000 Smart Transceiver. It features a compact design that includes the following I/O devices that you can use to develop prototype devices and run the FT 6000 EVB examples: 4 x 20 character LCD display, 4-way joystick with center push button, 2 push-button inputs, 2 LED outputs, digital light sensor, and digital temperature sensor. FT 6000 Smart Transceiver A chip that integrates a Neuron 6000 processor core and a TP/FT-10 transceiver.
i.LON IP-852 Router An i.LON IP-852 router forwards ISO/IEC 14908-2 packets enveloped in ISO/IEC 14908-4 packets over an IP-852 channel. i.LON IP-852 routers include the i.LON SmartServer with IP-852 routing, i.LON 100 e3 Internet Server with IP-852 routing, and the i.LON 600 LONWORKS-IP Server. I/O Object An instantiation of an I/O model. An I/O objects consists of a specific I/O model, and its pin assignment, modifiers, and name.
IzoT NodeBuilder Tool A hardware and software platform that is used to develop applications for Neuron Chips and Echelon Smart Transceivers. The IzoT NodeBuilder tool provides complete support for creating, debugging, testing, and maintaining LONWORKS devices. You can use the IzoT NodeBuilder tool all to create many types of devices, including VAV controllers, thermostats, washing machines, card-access readers, refrigerators, lighting ballasts, blinds, and pumps.
LONWORKS 2.0 Platform The next generation of LONWORKS products designed to both increase the power and capability of LONWORKS devices, and to decrease the costs of device development and devices. LONWORKS Network A network of intelligent devices (such as sensors, actuators, and controllers) that communicate with each other using a common protocol over one or more communications channels.
supports the mapping of external non-volatile memory from 0x4000 to 0xDFFF in the Neuron address space (a maximum of 42KB). Neuron Assembler (NAS) A Neuron C tool that is used to produce Neuron object files. 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.
NodeBuilder Device Template An XML file with a .NbDt extension that specifies the information required for the IzoT 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 NodeBuilder Hardware Template A file with a .NbHwt extension that defines the hardware configuration for a target device.
PCC-10 A type II PC (formerly PCMCIA) card network services interface (NSI) that includes an integral FTT-10 transceiver. Other transceiver types can be connected to the PCC-10 via external transceiver “pods”. The PCC-10 is the best NSI to use with laptop, notebook, or embedded PCs. PCLTA-10/20 A ½ size ISA card network services interface (NSI). Unlike the PCNSI, it includes a twisted pair transceiver onboard, eliminating the need to attach a separate SMX transceiver assembly.
SLTA-10 A serial NSI interface with built-in twisted pair transceiver that connects to any host with an EIA-232 (formerly RS232) port. It can also connect to the host remotely using a Hayes-compatible modem. The SLTA-10 is the best NSI to use for remote application or for portable hosts that do not contain a type II PC slot or a USB interface. The SLTA-10 adapter is supported, but not recommended unless dial-up operation through a modem and a serial connection is required.
Target Device A LONWORKS device application that is built by the IzoT NodeBuilder tool. There are two types of targets, development targets and release targets. Development targets are used during development; release targets are used when development is complete and the device will be released to production. TP/FT-10 The free topology twisted pair LONWORKS channel type, which has 78Kbps bit rate. U10/20 USB Network Interface.
270 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.
IzoT™ 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.
• “IzoT Device” means a product designed for use in a network based upon Echelon’s IzoT Platform. • “Your Device” means an IzoT Device that you developed by using the Licensed Software. • “Your IzoT Network Services Application” means Your software product that makes calls to the IzoT Network Services Server (as described in the Documentation) and incorporates the IzoT Network Services Server software. • “You(r)” means Licensee, i.e.
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.
IzoT Network Services Applications, or (ii) inform the end-user that there will be no support for Your Devices and Your IzoT Network Services Applications. GENERAL This Agreement shall not be governed by the 1980 U.N. Convention on Contracts for the International Sale of Goods; rather, this Agreement shall be governed by the laws of the State of California, including its Uniform Commercial Code, without reference to conflicts of laws principles.
