NodeUtil Node Utility ReadMe File
Release 2.04, December 2006

Copyright © 1994 – 2006 Echelon Corporation
All Rights Reserved

1         Overview

This document describes how to use the NodeUtil Node Utility.  NodeUtil is a Windows console application that can be used with Echelon’s family of network interfaces (including the PCLTA-20, PCLTA-21, PCC-10, i.LON 10, i.LON 100, i.LON 600, SLTA-10, U10, and U20 network interfaces) to diagnose and configure LonWorks® network interfaces, routers, and devices.

NodeUtil is a test and diagnostic tool—it is not a network management tool.  It will not assign destination addresses or bind network variables.  Nor will it format LonMark® interoperable device information.  A large number of LNS® based network management, diagnostic, monitoring and control tools are available; a directory of LNS based tools is available at www.echelon.com/lns.  A popular LNS based network engineering tool is the LonMaker® Integration Tool; see www.echelon.com/lonmaker for more information.  NodeUtil runs on top of OpenLDV™ 3.3C or higher.  The OpenLDV driver is included with the LNS Turbo Edition and the LonMaker Integration Tool Turbo Edition, and is available for royalty-free download from www.echelon.com/OpenLDV.

Additional information and updates, including critical updates, may be available in Echelon’s Downloads web page at www.echelon.com/downloads.

NodeUtil is provided as an unsupported software tool.

2         Contents

1      Overview.. 1

2      Contents. 1

3      Requirements. 3

3.1       PC Hardware Requirements. 3

3.2       PC Software Requirements. 4

4      Changes in this Release. 4

4.1       Release 2.04. 4

4.2       Release 2.03. 4

4.3       Release 2.02. 4

4.4       Release 2.01. 4

4.5       Release 2.00. 4

4.6       Release 1.97. 5

4.7       Release 1.96. 5

4.8       Release 1.94. 5

4.9       Release 1.93. 5

4.10     Release 1.92. 5

4.11     Release 1.89. 5

4.12     Release 1.88. 5

4.13     Release 1.87. 5

4.14     Release 1.84. 6

5      Getting Started. 6

5.1       Command Line Parameters. 6

5.2       The NodeUtil Main Menu. 7

5.2.1        F1 Show Banner 8

5.2.2        (A)dd Device to List 8

5.2.3        Set the (D)omain of the Network Interface. 9

5.2.4        (E)xit this Application and Return to Command Prompt 9

5.2.5        (F)ind Devices in the Current Domain. 9

5.2.6        Find Devices in All (1)-byte Domains. 10

5.2.7        (G)o to Device Menu. 10

5.2.8        (H)elp with Commands. 10

5.2.9        Redirect (I)nput from a File. 10

5.2.10      Display Device (L)ist 11

5.2.11      Change Device (M)ode and State. 11

5.2.12      Redirect (O)utput to a File. 11

5.2.13      Send a Service (P)in Message. 11

5.2.14      (R)eboot 3150 Device. 11

5.2.15      Report Device (S)tatus and Statistics. 11

5.2.16      (T)ransceiver Parameters. 12

5.2.17      Control (V)erbose Modes. 12

5.2.18      (W)ink a Device. 12

5.2.19      Shell out to Command Prompt ((Z) command) 12

5.3       The NodeUtil Device Menu. 12

5.3.1        F1 Show Benner 13

5.3.2        Node (A)ddress Table. 13

5.3.3        (B)uffer Configuration. 13

5.3.4        Application (C)onfiguration Structures. 13

5.3.5        Device (D)omain Table. 13

5.3.6        (E)xit this Menu and Return to Main Menu. 14

5.3.7        Configuration (F)iles. 14

5.3.8        (G)o to Another Device. 14

5.3.9        (H)elp with Device Commands. 14

5.3.10      Network Variable Al(I)as Table. 14

5.3.11      (J)am Network Variable Type. 14

5.3.12      Chec(K) Neuron Executable. 14

5.3.13      (L)ist Network Variables. 14

5.3.14      Change Device (M)ode and State. 14

5.3.15      (N)etwork Variable Configuration Table. 15

5.3.16      Redirect (O)utput to a File. 15

5.3.17      (P)oll Network Variable. 15

5.3.18      (Q)uickly Send a Message. 15

5.3.19      (R)ead Device Memory. 15

5.3.20      Report Device (S)tatus and Statistics. 15

5.3.21      (T)ransceiver Parameters. 16

5.3.22      (U)pdate Input Network Variable. 16

5.3.23      Control (V)erbose Modes. 16

5.3.24      (W)rite Device Memory. 17

5.3.25      Create a (X)IF File. 17

5.3.26      Download Neuron Executable ((Y) Command) 17

6      Feedback. 18

7      License. 18

 

3         Requirements

3.1           PC Hardware Requirements

The following are minimum requirements:

3.2           PC Software Requirements

The following are minimum requirements:

 

4         Changes in this Release

This section lists the major changes implemented since NodeUtil 1.84. 

4.1           Release 2.04

4.2           Release 2.03

4.3           Release 2.02    

4.4           Release 2.01

4.5           Release 2.00

4.6           Release 1.97

4.7           Release 1.96

4.8           Release 1.94

4.9           Release 1.93

4.10     Release 1.92

4.11     Release 1.89

4.12     Release 1.88

4.13     Release 1.87

4.14     Release 1.84

5         Getting Started

To install NodeUtil, follow these steps:

  1. Install OpenLDV 3.3C or newer if you do not already have it.  You can download OpenLDV from www.echelon.com/openldv.
  2. If you are using an Echelon network interface that needs a driver in addition to the OpenLDV driver, verify that you have installed that driver.  The OpenLDV ReadMe lists the network interfaces that require separate drivers.
  3. Configure your network interface driver if required.  See the documentation for your selected network interface for details. 
  4. Install StdXcvr.xml if you do no already have it.  This file is automatically installed by many applications including the LonMaker Integration Tool, NodeBuilder® Development Tool, NodeBuilder Resource Editor, and ShortStack Developer’s Kit.  If you have it installed, it will be in your LonWorks Types directory.  This directory is C:\LonWorks\Types by default, but you may have changed the location of your LonWorks directory when you installed your first LonWorks tool.  If you do not have a StdXcvr.xml file in your LonWorks Types directory, download the file from the Design Guidelines page that you can reach from www.lonmark.org.

To start NodeUtil, follow these steps:

  1. Open a Windows command prompt by clicking Start, pointing to All Programs, pointing to Accessories, and then clicking Command Prompt.  Set the path to the folder containing NodeUtil and then start NodeUtil as described in the next section.  Alternatively, you can create a shortcut for NodeUtil that sets the starting directory to the directory containing NodeUtil.  Your shortcut can also specify the command line options as described in the next section.
  2. NodeUtil starts, displays a sign-on message, and displays a menu of commands.  If there is any problem in opening the network driver, NodeUtil displays error messages and exists back to the command prompt.  If this happens, check that the network driver is loaded correctly, that you have OpenLDV 3.3C or higher installed, and that your network interface hardware is correctly configured.  If NodeUtil succeeds in opening the network driver, it displays the following message:

Echelon Node Utility Release 2.04

Successfully installed TP/FT-10 network interface.

Welcome to the Echelon Node Utility application.

Activate the service pin on remote device to access it.

Enter one of the following commands by typing the indicated letter:

This is followed by the NodeUtil Main menu.

5.1           Command Line Parameters

NodeUtil accepts command line parameters, with the following form:

NodeUtil [-D<interface name>] [-V] [-A] [-S] [-I<infile>] [-O<outfile>]

The -D<interface name> parameter is required if your network interface is not named LON1, all others are optional.  If you specify an invalid parameter, NodeUtil will display a help message.

The -D parameter specifies the network interface name to use.  The default is -DLON1.  To specify an i.LON 10, i.LON 100, or i.LON 600, use the form x.<Profile>.<i.LON name>.  For example, -Dx.Default.iLONatHQ specifies the Default xDriver profile, with the iLONatHQ i.LON.  See the OpenLDV Programmer’s Guide, and the OpenLDV Programmer’s Guide, xDriver Supplement for details.

The -V parameter causes NodeUtil to start up in verbose mode.  In this mode, NodeUtil displays all network interface messages in detail.

The -A parameter causes NodeUtil to start up in application mode.  In this mode, NodeUtil does not configure the network interface, and does not accept service pin messages.  If this parameter is not specified, NodeUtil assigns the network interface to a random subnet address in the zero-length domain with a node ID of 126, and sets the network interface to the configured state.

The -S parameter causes NodeUtil to use slower transaction timers, suitable for use with PL-20 power line channels.  By default, NodeUtil uses transaction timers that are suitable for TP/FT-10 channels.

The –I parameter allows input from a text file instead of from the keyboard.  Commands that don't require a carriage return must be on their own line and input that requires a carriage return must be on its own line.  NV data is in hex.  For example, the following script adds a device based on a Neuron ID, goes to it, polls its first NV, and updates its second NV with a SNVT_switch value of 100% and on:

A

9000011E28061102

G

1

P

1

U

2

C8 00

The –O parameter copies all of the NodeUtil output to the specified file.  You can use this parameter to create a script file to be used with the –I parameter, deleting any parts of the file that are not command inputs.

5.2           The NodeUtil Main Menu

The Main menu for NodeUtil is as follows:

F1-- Show Banner.

A -- (A)dd device to list.

D -- Set the (D)omain of the network interface.

E -- (E)xit this application.

F -- (F)ind devices in the current domain.

1 -- Find devices in all (1)-byte domains.

G -- (G)o to device menu....

H -- (H)elp with commands.

I -- Redirect (I)nput from a file.

L -- Display device (L)ist.

M -- Change device (M)ode or state.

O -- Redirect (O)utput to a file.

P -- Send a service (P)in message.

R -- (R)eboot 3150 device.

S -- Report device (S)tatus and statistics.

T -- (T)ransceiver parameters.

V -- Control (V)erbose modes.

W -- (W)ink a device.

Z -- Shell out to command prompt.

NodeUtil>

Type the indicated letter or function key to invoke the corresponding command.  You can stop any command by pressing the ESC key.  The main menu commands are described in this section.

The G, M, R, S, and W commands prompt you to enter an ID for the device you wish to address with the command.  NodeUtil maintains a list of devices that it knows about, indexed by ID number.  This device list initially contains only the network interface itself, which has an ID of 0.  For most of these commands, the default device is the last device in the list.  You can use any of the following methods to add devices to the NodeUtil device list:

You can use the (G)o to Device Menu command to display the device menu. 

5.2.1                  F1 Show Banner

Displays the name and version of the NodeUtil utility. 

5.2.2                  (A)dd Device to List

Add a device to the device list by entering the device’s Neuron ID.  Enter the Neuron ID as six hex values, optionally separated by spaces.  For example, you can enter “9000011E28061102 or “90 00 01 1E 28 06 11 02If NodeUtil can communicate with the device, it will be added to the directory.

5.2.3                  Set the (D)omain of the Network Interface

Displays and optionally sets the first domain table entry of the network interface.  This command is useful before entering the (F)ind Devices in the Current Domain command since the (F)ind Devices in the Current Domain command broadcasts on the domain you assign the network interface.

When you enter the D command, you will be prompted for the following parameters:

  1. Enter the desired domain ID length (0, 1, 3 or 6 bytes).  Press the ESC key to not change the domain.
  2. Enter the domain ID values in hex, optionally separated by spaces.  For example, enter “0011AB” or “00 11 AB” for a three-byte domain.  The default domain ID is all zeroes.
  3. Enter the subnet ID for the network interface.  The node ID in that subnet is fixed at 126 decimal, or 7E hex.
  4. Enter the authentication key to use for the primary domain table entry.  Enter the key as hex bytes separated by spaces.  The default key is 0xFF for all bytes.

The second domain table entry of the network interface is always set to the zero-length domain for the purpose of receiving service pin messages.

Changing the authentication key is useful if you need to update network variables that have been configured as authenticated.  An update to an authenticated network variable must be sent using a domain in which the target device is configured, using the correct authentication key.

At the end of this process, you will be given an opportunity to cancel the command before the new domain entry is written into the device.

5.2.4                  (E)xit this Application and Return to Command Prompt

Exits from NodeUtil.  The device list is not saved.

5.2.5                  (F)ind Devices in the Current Domain

Finds all devices in the current domain.  The current domain is set by the Set the (D)omain of the Network Interface command.  This command sends a domain-wide Query ID broadcast to all devices, and then queries all responding devices for their identification.  Each new device is added to the device list.  This command is useful when the service pins of the remote devices are not accessible.  It will discover unconfigured and application-less devices, as well as devices that are configured in the domain of the network interface. 

To query for devices configured in a specific domain, use the Set the (D)omain of the Network Interface command before the (F)ind Devices in the Current Domain command.  The (F)ind Devices command broadcasts on the domain you assign to the network interface.  Changing the domain and subnet to the configured domain for the network is especially useful if your network contains routers.  Normally, routers are set to the configured routing mode, as that mode is the most bandwidth efficient.  In the configured routing mode, routers will only pass messages for the configured domains.  If the routers are set to the repeater mode, though, it may not be necessary to modify the domain and subnet node address of the network interface in order to find devices on domains, because the routers will pass valid messages sent on any domain.

5.2.6                  Find Devices in All (1)-byte Domains

Finds all devices in all one-byte domains.  This command sends a domain-wide Query ID broadcast in each of the one-byte domains, and then queries all responding devices for their identification.  Each new device is added to the device list.  This command is useful when you do not know the domain of the devices in the network, and you are not able to physically access the devices in order to press the service pin.  It will discover unconfigured and applicationless devices, as well as devices that are configured in the domain of the network interface.  This command remembers the domain information in the network interface before the command was started, and rewrites the domain information back into the network interface when the command completes.  This command may take a long time to complete.  You may interrupt the command by pressing any key on the keyboard.  To query for devices configured in a specific domain, use the Set the (D)omain of the Network Interface command before the Find Devices in All (1)-byte Domains command.

5.2.7                  (G)o to Device Menu

Displays the device list, and switches to the device menu.  Enter the ID of the device you wish to address.  The prompt changes to DEVICE:x>, where x is the ID of the device for the device menu.  To return to the main menu, use the (E)xit command.

You can use the device menu to display and update various data structures within a device, and to interact with the device using network variables or application messages.  For descriptions of the information displayed by the device menu commands see the FT 3120® / FT 3150® Smart Transceiver Data Book or the PL 3120 / PL 3150 Smart Transceiver Data Book available from www.echelon.com/products.  See The NodeUtil Device Menu for a description of the device menu and its commands.

5.2.8                  (H)elp with Commands

Displays the main menu.  The main menu is also displayed if any unrecognized commands are entered.

5.2.9                  Redirect (I)nput from a File

Executes a command script.  A command script is a text file containing NodeUtil commands.  Commands that don't require a carriage return must be on their own line and input that requires a carriage return must be on its own line.  NV data is in hex.  You can use any file extension, but a common extension is “.scr”.

For example, to add device with a Neuron ID of 112233445566 to the device list with the (A)dd Device to List command, then go to the device (with index 1) with the (G)o to Device Menu command, and finally read the memory from 0xF000 and 0x0100 bytes length with (R)ead Device Memory command, create a text file with the following commands:

A

112233445566

G

1

R

f000

0100

You can optionally execute the script repeatedly.

5.2.10             Display Device (L)ist

Displays the NodeUtil device list.  You can add devices to the list using any of the methods described in The NodeUtil Main Menu.  The list includes the network interface, devices, and routers.  For each device (and for each side of a router), the NodeUtil device ID, Neuron ID, and program ID is displayed.  The program ID is displayed in hex.  It is also displayed in text if it is a text program ID.

5.2.11             Change Device (M)ode and State

Changes the device mode or state for one or all devices.  If there is more than one device in the device list, you are prompted to enter a device ID, or to select all devices.  The default is all devices, meaning that the mode or state that you select will be changed for all devices in the current domain.  See the device Change Device (M)ode or State command for more details.

5.2.12             Redirect (O)utput to a File

Redirects all NodeUtil output to a file.  You will be prompted for the file name.  The default file name extension is .log.  If the file already exists, you will be asked if you wish to (O)verwrite the file from the beginning, or (A)ppend output to the end of the file.  To stop redirection, enter a null file name.  This command is useful for saving the output of any of the other NodeUtil commands.

5.2.13             Send a Service (P)in Message

Sends a service pin message using the NodeUtil network interface.

5.2.14             (R)eboot 3150 Device

Restores the contents of the on-chip EEPROM memory of the indicated device to the state it had when the off-chip EPROM was first installed.

Use this command with caution.

This command restores the communications parameters, device state, buffer configuration, and on-chip EEPROM variables.  It also re-initializes the domain, address, and network variable configuration tables.

This command does not operate on a Neuron 3120 based device.  If the (R)eboot 3150 Device command is executed on the network interface used to run NodeUtil, it will be reconfigured so that it can continue to be used if it is a Neuron 3150 based device.

5.2.15             Report Device (S)tatus and Statistics

Sends a message to query the status of the indicated device, and displays the results.  If you invoke this command from the main menu, you are prompted to enter a device ID.  See the device Report Device (S)tatus and Statistics commands for more details.

5.2.16             (T)ransceiver Parameters

Displays the transceiver ID of the network interface, and allows you to set the transceiver ID for network interfaces with software-configurable transceiver IDs.  For all network interfaces, this command also allows you to change the transceiver parameters for the network interface.  See the device (T)ransceiver Parameters command for more details.

5.2.17             Control (V)erbose Modes

Enables or disables two verbose modes.  These are useful for debugging network problems.  You can enable or disable verbose mode for network interface messages and for network traffic.  If you enable verbose mode for network interface messages, NodeUtil displays the contents of all application buffers going to and coming from the NodeUtil network interface.  If you enable verbose mode for network traffic, any incoming message addressed to the application processor on the network interface is displayed.  By default, network interface message verbose mode is off, and network traffic verbose mode is on.

5.2.18             (W)ink a Device

Sends the wink message to a device or all devices.  If the device has been programmed to respond to this message, it will activate the wink task.  When you are prompted to enter a device ID for this command, the default is all devices, meaning that the wink message is sent as a broadcast to all devices configured in the current domain.

5.2.19             Shell out to Command Prompt ((Z) command)

Opens a Windows command prompt without losing the device list.  Type exit at the command prompt to return to NodeUtil.

 

5.3           The NodeUtil Device Menu

After you enter the (G)o to Device Menu command, the following device menu is displayed:

F1-- Show Banner.

A -- Device (A)ddress table.

B -- (B)uffer configuration.

C -- Application (C)onfiguration structures.

D -- Device (D)omain table.

E -- (E)xit this menu and return to main menu.

F -- Configuration (F)iles. **

G -- (G)o to another device.

H -- (H)elp with device commands.

I -- Network variable al(I)as table. **

J -- (J)am network variable type. **

K -- Chec(K) Neuron executable. **

L -- (L)ist network variables. **

M -- Change device (M)ode or state.

N -- (N)etwork Variable configuration table. **

O -- Redirect (O)utput to a file.

P -- (P)oll network variable. **

Q -- (Q)uickly send a message.

R -- (R)ead device memory.

S -- Report device (S)tatus and statistics.

T -- (T)ransceiver parameters.

U -- (U)pdate input network variable. **

V -- Control (V)erbose modes.

W -- (W)rite device memory.

X -- Create device interface ((X)IF) file. **

Y -- Download Neuron executable. **

** These commands are not available for the NodeUtil network interface, or for routers.

Type the indicated letter or function key to invoke the corresponding command.  You can stop any command by pressing the ESC key.  The device menu commands are described in this section.  These commands all operate on the selected device, which is displayed in the NodeUtil prompt.

5.3.1                  F1 Show Benner

Displays the name and version of the NodeUtil utility. 

5.3.2                  Node (A)ddress Table

Displays a selected address table entry or the entire address table for the selected device.  For a description of the address table entry fields, see the FT 3120 / FT 3150 Smart Transceiver Data Book or the PL 3120 / PL 3150 Smart Transceiver Data Book available from www.echelon.com/products.

5.3.3                   (B)uffer Configuration

Displays the buffer configuration of the selected device.  For buffer configuration information, see the FT 3120 / FT 3150 Smart Transceiver Data Book or the PL 3120 / PL 3150 Smart Transceiver Data Book available from www.echelon.com/products.  After displaying the current buffer configuration, you can change the configuration, one value at a time.  For each value, the default value is the current setting.  If the value you enter is not a valid value, you will be prompted again, or the next larger valid value will be substituted.  At the end of this process, the new configuration will be displayed, and you can accept or cancel the command before the new values are written to the device.  If you configure the device to use more RAM than is actually available, the device will most likely crash.  If the device is Neuron 3120 based, it may not be recoverable.  If it is based on the Neuron 3150, you may be able to recover it with the (R)eboot command.  If the device is not recoverable with the reboot command of NodeUtil and the device is based on a Neuron 3150, you can use the EEBLANK program available from hwww.echelon.com/downloads to blank the EEPROM and reboot the default image.

5.3.4                  Application (C)onfiguration Structures

Displays data from the read-only and configuration data structures of the selected device.  For a description of these data structures, see the FT 3120 / FT 3150 Smart Transceiver Data Book or the PL 3120 / PL 3150 Smart Transceiver Data Book available from www.echelon.com/products.

5.3.5                  Device (D)omain Table

Displays a selected domain table entry or the entire domain table of the selected device.

5.3.6                  (E)xit this Menu and Return to Main Menu

Exits from the device menu and returns to the main menu.  The prompt changes to NodeUtil>.

5.3.7                  Configuration (F)iles

Reads the configuration file from the selected device and interprets the template.  This command is supported only for devices that have a LonMark compliant Node Object functional block which allows for direct memory read access to the configuration file.  Enter the index of the SNVT_address network variable which points to the file directory.  The template is checked for syntax errors.

5.3.8                  (G)o to Another Device

Displays the device list, and allows you to select another device for device menu operations.  The prompt changes to DEVICE:x>, where x is the ID of the selected device.

5.3.9                  (H)elp with Device Commands

Displays the device menu.  The device menu is also displayed if any unrecognized commands are entered.

5.3.10             Network Variable Al(I)as Table

Displays a selected network variable alias table entry or the entire network variable alias table of the selected device.

5.3.11              (J)am Network Variable Type

Displays and optionally sets a network variable type.  To change a network variable type, enter the index of the network variable, and then enter the SNVT index of the new type.  This command can only be used on Neuron hosted devices which have specified one of the snvt_si_eecode or snvt_si_ramcode Neuron C compiler directives.

5.3.12             Chec(K) Neuron Executable

Compares the dowloadable image file (.nxe or .ndl extension) contents on the computer and the application image loaded on the device.  Any differences are displayed.

5.3.13             (L)ist Network Variables

Displays the self-documentation and other network variable information available on the selected device, in Neuron C source format.  You can save the information in a .hc file.  If the device is LonMark certified or LonMark compliant, the device and network variable self-documentation strings are interpreted and checked for errors.

5.3.14             Change Device (M)ode and State.

Changes the selected device's mode or state.  You can reset the device, change the application mode to online or offline, or change the device state to applicationless, unconfigured, configured, or hard offline.  For a description of these modes and states, see the FT 3120 / FT 3150 Smart Transceiver Data Book or the PL 3120 / PL 3150 Smart Transceiver Data Book available from www.echelon.com/products

If the device is a router, you can also set the router type to configured, learning, bridge, or repeater.

5.3.15              (N)etwork Variable Configuration Table

Displays a selected network variable configuration table entry or the entire network variable configuration table of the selected device.  For a description of the network variable configuration table structure and its elements, see the FT 3120 / FT 3150 Smart Transceiver Data Book or the PL 3120 / PL 3150 Smart Transceiver Data Book available from www.echelon.com/products.

5.3.16             Redirect (O)utput to a File

Redirects all NodeUtil output to a file.  You will be prompted for the file name. The default file extension is .log.  If the file already exists, you can specify whether to overwrite the file from the beginning or append output to the end of the existing file.  To stop redirection, enter an empty file name.  This command is useful for saving the output of any of the other NodeUtil commands.

5.3.17             (P)oll Network Variable

Fetches the value of a selected network variable, or every network variable on the selected device.  Enter the index of the network variable on the device, or just press the ENTER key to fetch all network variables on the selected device.  The network variable values are displayed in hex bytes, and may be further interpreted depending on length.

5.3.18             (Q)uickly Send a Message

Sends a LonTalk message to the selected device.  You can specify the service type (acknowledged, unacknowledged, request/response, or repeated), whether to use authentication or not, message code, and data to send. 

5.3.19             (R)ead Device Memory

Displays the memory contents of the selected device.  You can specify the starting address in hex and the number of bytes to read in hex.  The memory contents is displayed in hex bytes.  Use the Redirect (O)utput to a File command before the (R)ead Device Memory command to save the output to a file.

5.3.20             Report Device (S)tatus and Statistics

Sends a message to query the status of the selected device, and displays the results.  For a description of the meanings of the returned values, see the FT 3120 / FT 3150 Smart Transceiver Data Book or the PL 3120 / PL 3150 Smart Transceiver Data Book available from www.echelon.com/products.  If the selected device is a router, additional information is displayed including the router type.  For a description of the meanings of these router-specific values, see the LonWorks Router User’s Guide available from www.echelon.com/products.

You will then be given an opportunity to clear the status of the device, which clears the error counters, the reset cause and the last error logged.

5.3.21             (T)ransceiver Parameters

Displays the transceiver (communications) parameters of the selected device.  The information displayed will depend on the transceiver type.  For a description of the meanings of these values, see the FT 3120 / FT 3150 Smart Transceiver Data Book or the PL 3120 / PL 3150 Smart Transceiver Data Book available from www.echelon.com/products.

If the selected device is a network interface that supports changing the input clock, you will then be prompted to change the input clock rate by selecting from a menu.  The choices are 5, 10, and 20 MHz.  You will then be given an opportunity to change the transceiver parameters by selecting from a menu.  The choices depend on the Neuron input clock rate.

NodeUtil does not support changing the transceiver parameters for devices with input clocks less than 5 MHz.

If the device implements transceiver ID (XID) pins, you will typically not be able to change the interface bit rate or the transceiver type (differential, single-ended or special-purpose).  To change types of devices, you must physically set the value read from the XID pins to 30 decimal, or 1E hex first.

Selecting incorrect communications parameters may make it impossible to communicate with the device over the network.  If the device contains a 3120 chip, it may not be recoverable.  If it is contains a 3150 chip, you will be able to recover it using the EEBLANK program available from www.echelon.com/downloads.

5.3.22              (U)pdate Input Network Variable

Updates an input network variable on the selected device.  Enter the index of the network variable.  The data from the last network variable update to the selected network variable is displayed.  At the prompt, enter the data to be sent to the network variable in hex bytes.  Separate each pair of hex digits with a space, and enter all the required data on one line. The data values for any bytes that you do not enter after the first character default to zero.  For example, you can enter 01 00 00 or just enter 1 to set a SNVT_switch_2 input to on.  Press ENTER without any characters to cancel the update.  For example, you can enter 00 00 00 or just enter 0 to set a SNVT_switch_2 input to off, but if you just press the ENTER key without entering any data, the input value is not changed.

You can use the Set (D)omain command to configure the NodeUtil network interface with a domain and authentication key to match those of the destination device if the network variable has been configured as authenticated

5.3.23             Control (V)erbose Modes

Enables or disables two verbose modes.  These are useful for debugging network problems.  You can enable or disable verbose mode for network interface messages and for network traffic.  If you enable verbose mode for network interface messages, NodeUtil displays the contents of all application buffers going to and coming from the NodeUtil network interface.  If you enable verbose mode for network traffic, any incoming message addressed to the application processor on the network interface is displayed.  By default, network interface message verbose mode is off, and network traffic verbose mode is on.

5.3.24             (W)rite Device Memory

Write to the memory of the selected device.  You can specify the starting address in hex.  The contents of the memory address you specify are displayed in hex.  Enter a new value for the location in hex and then press the ENTER key.  Just press the ENTER key to leave the value unchanged.  To stop entering data, enter any value that is not a hex character such as a period (.), and then press ENTER.

If you change any of the data in memory, you will be given the opportunity to update both the application and configuration checksums, or just the configuration checksum.  For a description of which data structures are part of each of these checksums, see the FT 3120 / FT 3150 Smart Transceiver Data Book or the PL 3120 / PL 3150 Smart Transceiver Data Book available from www.echelon.com/products.

The device should be in the applicationless state before you change any of the application image memory, otherwise the device will report an application checksum error.  Similarly, the device should be in the applicationless or unconfigured state before you change any of the network image memory, otherwise the device will report a configuration checksum error.

5.3.25             Create a (X)IF File

Creates a version 3 device interface file (.xif extension) for the selected device.  You can enter a file name for the XIF file.  If the device has an alphanumeric program ID, this ID is the default filename.  If output redirection is in effect, the current output file is closed before creating the XIF file.  You can use the generated XIF file with any Echelon or third-party LNS tool, including the LonMaker Integration Tool.

5.3.26             Download Neuron Executable ((Y) Command)

Download a Neuron application image file to the selected device.  You can specify an application image file (.ndl or .nxe extension) that is generated by the NodeBuilder or Mini EVK tools.  If the device already contains an alphanumeric application ID, this name is the default for the application image file name. 

If the download was successful, you will then be asked if you want to set the device configured, online.  Answer yes to this question only if the device already contains a valid network configuration for this application.  By default, the device will be set to the unconfigured state.  After setting the state, NodeUtil reads the state of the device and displays any errors.

This command does not check that the application image file that you are loading is compatible with the device hardware configuration.  Before loading an application to a device, verify that the application image file was linked using the correct Neuron model and firmware version for your target device.  For Neuron 3150 based devices, also verify that the application image file was linked using the correct memory map for the device.

If an incompatible application image file is loaded to a device, the device may start watchdog resetting.  You may be able to recover it by downloading a compatible application image file.  If not, you can recover Neuron 3150 based devices using the EEBLANK utility available from www.echelon.com/downloads.  However, Neuron 3120 based devices may be totally unrecoverable.

If you attempt to set the device to the configured state after loading, but the device does not contain a valid network configuration for this application, then the Neuron firmware will detect a configuration checksum error and set the device to be unconfigured.

6         Feedback

Echelon welcomes your comments on the NodeUtil software.  Please direct any non-technical support comments to OpenLDV@echelon.com.

7         License

NodeUtil Software License Agreement

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. BY DOWNLOADING LICENSED SOFTWARE, OR INSTALLING LICENSED SOFTWARE, OR USING LICENSED SOFTWARE, YOU ARE AGREEING TO BE BOUND BY THE TERMS AND CONDITIONS OF THIS SOFTWARE LICENSE AGREEMENT.  IF YOU DO NOT AGREE WITH THE TERMS AND CONDITIONS OF THIS SOFTWARE LICENSE AGREEMENT, THEN YOU SHOULD NOT DOWNLOAD OR INSTALL OR USE ANY LICENSED SOFTWARE. BY DOING SO YOU FOREGO ANY IMPLIED OR STATED RIGHTS TO DOWNLOAD OR INSTALL OR USE LICENSED SOFTWARE.

Software License Agreement

Echelon Corporation ("Echelon") grants You a non-exclusive, non-transferable license to use the copy of the Licensed Software and any updates or upgrades thereto provided by Echelon according to the terms set forth below. If the Licensed Software is being provided to you as an update or upgrade to software which You have previously licensed, then You agree to destroy all copies of the prior release of this software within thirty (30) days after this download; provided, however, that You may retain one (1) copy of the prior release for backup, archival and support purposes. As used herein,

"Licensed Software" means the NodeUtil.exe Windows executable file and this Readme.htm file.

"Network Adapter" means any product in the following product families: the i.LON(r) 10 Ethernet Adapter, i.LON 100 Internet Server, LTS-20 SLTA Core Module, PCC-10 PC Card Network Adapter, PCLTA-10/20 Network Adapter, PL-SLTA Power Line Serial LonTalk(r) Adapter, SLTA/10 Serial LonTalk Adapter, and any updates thereof and replacements thereto.

"You(r)" means the company, entity or individual who downloads the Licensed Software from a web site on which Echelon has made it available, or who has otherwise rightfully acquired the Licensed Software.

LICENSE

You may:

(a) download the Licensed Software onto Your computer,

(b) make a limited number of copies of the Licensed Software solely for backup purposes, provided that You reproduce, unaltered, all proprietary notices on or in the copies, and

(c) use, reproduce and distribute the Licensed Software, in binary form only, solely for use with a Network Adapter, provided that you reproduce, unaltered, all proprietary notices on or in the copies.  You may not modify any of the Licensed Software files.

You remain solely responsible for support, services, upgrades or other technical assistance for Your customers ("Support") with respect to the Licensed Software, and will indemnify and hold Echelon harmless from all loss, cost liability and expense arising from Your use or distribution of the Licensed Software ("Indemnification"). You agree that the foregoing Support and Indemnification obligations are provided by you in partial consideration for the rights granted to You hereunder.

You may not and shall not permit others to:

(a) copy the Licensed Software (except as expressly permitted above),

(b) modify or translate any Licensed Software,

(c) modify, translate, reverse engineer, decompile, disassemble or otherwise attempt (i) to defeat, avoid, bypass, remove, deactivate, or otherwise circumvent any software protection mechanisms in the Licensed Software, including without limitation any such mechanism used to restrict or control the functionality of the Licensed Software, or (ii) to derive the source code or the underlying ideas, algorithms, structure or organization from the Licensed Software,

(d) distribute, rent, transfer or grant any rights in the Licensed Software (except as expressly permitted above) in any form to any person without the prior written consent of Echelon,

(e) use the Licensed Software with LonWorks network adapters not manufactured by Echelon, or

(f) without limiting the foregoing, use the Licensed Software to build a LonTalk Protocol analyzer or otherwise to gain access to messages on a LonTalk channel that are not addressed at LonTalk Layer 5 or higher to the Network Adapter.

This license is not a sale. Title and copyrights to the Licensed Software and any copies made by you remain with Echelon and its suppliers. Unauthorized copying of the Licensed Software, or failure to 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. This license will also automatically terminate if You go into liquidation, suffer or make any winding up petition, make an arrangement with Your creditors, or suffer or file any similar action in any jurisdiction in consequence of debt. Upon termination of this license for any reason, You will destroy all copies of the Licensed Software. Any use of the Licensed Software after termination is unlawful.

TRADEMARKS

You may not use Echelon's name, logo or trademarks, except that You may make appropriate and truthful reference to Echelon and Echelon products and technology in Your company and product literature, in accordance with Echelon's guidelines for use of its trademarks and provided that you properly attribute Echelon's trademark. No license is granted, express or implied, under any Echelon trademarks, trade names or service marks.

LIMITED WARRANTY AND DISCLAIMER

THIS LICENSED SOFTWARE IS PROVIDED "AS IS" WITHOUT REPRESENTATION, WARRANTY OR CONDITION OF ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR ANY PARTICULAR PURPOSE AND NONINFRINGEMENT.  The entire risk as to the quality and performance of the Licensed Software is borne by Recipient.  Should the Licensed Software prove defective, Recipient and not Echelon assumes the entire cost of any service and repair.

SOME STATES OR OTHER JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSIONS MAY NOT APPLY TO YOU. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY FROM STATE TO STATE AND JURISDICTION TO JURISDICTION.

LIMITATION OF LIABILITY

IN NO EVENT WILL ECHELON OR ITS SUPPLIERS BE LIABLE FOR LOSS OF OR CORRUPTION TO DATA, LOST PROFITS OR LOSS OF CONTRACTS, COST OF PROCUREMENT OF SUBSTITUTE PRODUCTS OR OTHER SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR INDIRECT DAMAGES ARISING FROM THE SUPPLY OR USE OF THE LICENSED SOFTWARE, HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY (INCLUDING NEGLIGENCE). THIS LIMITATION WILL APPLY EVEN IF ECHELON OR AN AUTHORIZED DISTRIBUTOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, EXCEPT TO THE EXTENT THAT LIABILITY MAY NOT BY LAW BE LIMITED OR EXCLUDED, AND NOTWITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY. IN NO EVENT SHALL ECHELON'S LIABILITY EXCEED ONE THOUSAND DOLLARS ($1,000).  YOU AGREE THAT THE FOREGOING LIMITATIONS REFLECT A REASONABLE ALLOCATION OF RISK.

SOME STATES OR OTHER JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITATIONS AND EXCLUSIONS MAY NOT APPLY TO YOU.

SAFE OPERATION

YOU ASSUME RESPONSIBILITY FOR, AND HEREBY AGREE TO USE YOUR BEST EFFORTS IN, DESIGNING YOUR PRODUCTS TO PROVIDE FOR SAFE OPERATION THEREOF, INCLUDING, BUT NOT LIMITED TO, COMPLIANCE OR QUALIFICATION WITH RESPECT TO ALL SAFETY LAWS, REGULATIONS AND AGENCY APPROVALS, AS APPLICABLE. THE NEURON® CHIP, LONTALK PROTOCOL, NEURON CHIP FIRMWARE, NETWORK ADAPTERS, AND THE LICENSED SOFTWARE ARE NOT DESIGNED OR INTENDED FOR USE AS COMPONENTS IN EQUIPMENT INTENDED FOR SURGICAL IMPLANT INTO THE BODY, OR OTHER APPLICATIONS INTENDED TO SUPPORT OR SUSTAIN LIFE, FOR USE IN FLIGHT CONTROL OR ENGINE CONTROL EQUIPMENT WITHIN AN AIRCRAFT, OR FOR ANY OTHER APPLICATION IN WHICH THE FAILURE OF THE NEURON CHIP, LONTALK PROTOCOL, NEURON CHIP FIRMWARE, NETWORK ADAPTERS, OR THE LICENSED SOFTWARE COULD CREATE A SITUATION IN WHICH PERSONAL INJURY OR DEATH MAY OCCUR, AND YOU SHALL HAVE NO RIGHTS HEREUNDER FOR ANY SUCH APPLICATIONS.

COMPLIANCE WITH EXPORT CONTROL LAWS

You agree to comply with all applicable export and reexport control laws and regulations, including the Export Administration Regulations ("EAR") maintained by the United States Department of Commerce. Specifically, You covenant that You shall not -- directly or indirectly -- sell, export, reexport, transfer, divert, or otherwise dispose of any software, source code, or technology (including products derived from or based on such technology) received from Echelon under this Agreement to any country (or national thereof) subject to antiterrorism controls or U.S. embargo, or to any other person, entity, or destination prohibited by the laws or regulations of the United States, without obtaining prior authorization from the competent government authorities as required by those laws and regulations. You agree to indemnify, to the fullest extent permitted by law, Echelon from and against any fines or penalties that may arise as a result of Your breach of this provision. This export control clause shall survive termination or cancellation of this Agreement.

LANGUAGE

The parties hereto confirm that it is their wish that this Agreement, as well as other documents relating hereto, have been and shall be written in the English language only.

Les parties aux présentes confirment leur volonté que cette convention de même que tous les documents y compris tout avis qui s'y rattache, soient rédigés en langue anglaise.

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. This Agreement is the entire agreement between us with respect to the Licensed Software. This Agreement supersedes any other communications or advertising with respect to the Licensed Software. If any provision of this Agreement is held invalid or unenforceable, such provision shall be revised to the extent necessary to cure the invalidity or unenforceability, and the remainder of the Agreement shall continue in full force and effect. If You are acquiring the Licensed Software on behalf of any part of the U.S. Government, the following provisions apply. The Licensed Software and documentation thereto are deemed to be "commercial computer software" and "commercial computer software documentation", respectively, pursuant to DFAR Section 227.7202 and DFAR Section 12.212, as applicable. Any use, modification, reproduction, release, performing, displaying, or disclosing of the software or documentation by the U.S. Government shall be governed solely by the terms of this Agreement and shall be prohibited except to the extent expressly permitted by the terms of this Agreement. Any technical data provided that is not covered by the above provisions is deemed to be "technical data-commercial items" pursuant to DFAR Section 227.7015(a). Any use, modification, reproduction, release, performance, display or disclosure of such technical data shall be governed by the terms of DFAR Section 227.7015(b).

 

Echelon, LonMark, LonTalk, LonWorks, LNS, i.LON and Neuron are registered trademarks of Echelon Corporation in the U.S. and other countries.  LonMaker, LonSupport and OpenLDV are trademarks of Echelon Corporation in the U.S. and other countries.