NodeUtil Node Utility User’s Guide 078-0438-01A
Echelon, i.LON, LNS, LonMaker, LONMARK, LonTalk, LONWORKS, Neuron, NodeBuilder, ShortStack, 3120, 3150, and the Echelon logo are trademarks of Echelon Corporation registered in the United States and other countries. FTXL, OpenLDV, 3170, and 3190 are trademarks of the Echelon Corporation. Other brand and product names are trademarks or registered trademarks of their respective holders.
Welcome The NodeUtil Node Utility is a test and diagnostic tool 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, i.LON SmartServer, SLTA-10, U10, and U20 network interfaces). You can use the NodeUtil Node Utility to diagnose and configure LONWORKS® network interfaces, routers, and devices.
• LonMaker User's Guide (078-0333-01A). This manual describes how to use the Turbo edition of the LonMaker Integration Tool to design, commission, monitor and control, maintain, and manage a network. • LonWorks Router User’s Guide (078-0018-01D). This manual provides • Mini FX User’s Guide (078-0398-01A). This manual describes how to use the Mini FX Evaluation Kit.
Table of Contents Welcome .........................................................................................................iii Audience ........................................................................................................iii Related Documentation ................................................................................iii Chapter 1. Introduction ..................................................................................... 1 Introduction..............................
P – Poll Network Variable .................................................................... 20 Q – Quickly Send a Message................................................................. 20 R – Read Device Memory ...................................................................... 20 S – Report Device Status and Statistics .............................................. 20 T – Transceiver Parameters ................................................................. 21 U – Update Input Network Variable...
1 Introduction This chapter introduces the NodeUtil Node Utility. It also includes hardware and software requirements and installation instructions.
Introduction The NodeUtil Node Utility is a console application for Microsoft® Windows® systems 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, i.LON SmartServer, SLTA-10, U10, and U20 network interfaces) to diagnose and configure LONWORKS® network interfaces, routers, and devices.
PC Software Requirements The following are minimum requirements: • Microsoft Windows XP or 32-bit version of Windows 7, Windows Vista®, or Windows Server 2008 • OpenLDV 3.3C or later • Appropriate Echelon network interface driver (if you are using an SLTA10 or LTS-20) • Windows TCP/IP software (if you are using an i.LON 10, i.LON 100, i.LON 600, or SmartServer network interface) Installing the NodeUtil Node Utility Before you install the NodeUtil Node Utility, perform the following tasks: 1.
folder to your Windows path, which makes it easy to run NodeUtil from any directory.
2 Using NodeUtil This chapter describes how to start the NodeUtil Node Utility, including the command-line parameters. It also describes the NodeUtil main menu and the NodeUtil device menu.
Starting NodeUtil To start the NodeUtil Node Utility, perform the following steps: 1. Open a Windows command prompt. Windows 7: Start → All Programs → Accessories → Command Prompt Windows XP: Start → Programs → Accessories → Command Prompt 2. If you installed NodeUtil in a directory that is not in your Windows path, use the cd (change directory) command set the current directory to the folder that contains the NodeUtil.exe file. 3.
where include the following: [-Ddevice] [-A] [-B] [-H] [-Iinputfile] [-J] [-M] [-Ooutputfile] [-S] [-V] [-?]. These parameters are described below: –D The –D parameter specifies the name of the network interface that you want to use. This parameter is required if your network interface is not named LON1, but is optional if you use LON1. If you specify an invalid network interface name, NodeUtil displays an error message.
or ShortStack device that is not currently attached to its host processor, use the –J parameter in addition to the –M parameter. –O The –O parameter specifies that output from the NodeUtil Node Utility be copied to the specified file. You can use this parameter to create a script file that you can use with the –I parameter. See Using a Script File with NodeUtil on page 25 for more information.
example, add the –D parameter to specify the network interface. The text in the Target field should look similar to the following command: "C:\LonWorks\NodeUtil\NodeUtil.exe" -DLON2 –S You should not need to make any other changes to the shortcut, so you can click OK to save your changes and close the dialog. To add the shortcut to your Windows Desktop: 1. In Windows Explorer, navigate to the folder in which you created the shortcut to the NodeUtil Node Utility. 2.
Type the indicated letter (or function key) to run the corresponding command. You can stop any command by pressing the ESC key. The G, M, R, S, and W commands prompt you to enter an ID for the device that you want 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.
2. For domain ID length greater than zero, 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. The subnet ID for the network interface. The node ID in that subnet is fixed at 126 (decimal) or 7E (hexadecimal). 4. 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. 5.
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. This command discovers unconfigured and applicationless devices, as well as devices that are configured in the domain of the network interface. This command uses the domain information stored in the network interface, and rewrites the domain information to the network interface when the command completes.
See the device menu Change Device Mode or State command, M – Change Device Mode or State on page 20, for more information. P – Send a Service Pin Message Use this command to send a service pin message using the NodeUtil network interface. Q – Quickly Add Device to List Use this command to add a device to the NodeUtil device list without attempting to communicate with the device.
See the device menu Transceiver Parameters command, T – Transceiver Parameters on page 21, for more information. V – Control Verbose Modes Use this command to enable or disable two verbose modes: for network interface messages and for network traffic. These modes are useful for debugging network problems. By default, network interface message verbose mode is off, and network traffic verbose mode is on.
This command is useful for saving the output of any of the NodeUtil commands, and for creating script files. See Using a Script File with NodeUtil on page 25 for more information. The NodeUtil Device Menu From the NodeUtil main menu, enter the (G)o to device menu command to display the current device list and switch to the device menu for a specific device. Enter the ID of the device (first column of the device list) that you want to address.
Important: The following commands are not available for the NodeUtil network interface or for routers: F, I, J, K, L, N, P, U, X, Y, =, or *. Type the indicated letter (or function key) to run the corresponding command. You can stop any command by pressing the ESC key. These commands operate on the selected device, which is displayed in the NodeUtil DEVICE prompt. F1 – Show Banner Use this command to display the name and version of the NodeUtil Node Utility.
value, the utility displays an error message (Value out of range) and displays the maximum allowable size, and you are prompted to enter a new value. See the ISO/IEC 14908-1 Control Network Protocol standard for a description of the address table. B – Buffer Configuration Use this command to display the buffer configuration of the selected device. The columns of data displayed include: • Type – Defines the buffer type. • Count – Defines the current buffer count for the specified buffer type.
D – Device Domain Table Use this command to display a selected domain table entry or the entire domain table of the selected device. You can also update the domain. You can set the authentication key even if the domain is not used. Note: When you update a device domain table, you are prompted whether (Y|[N]) to use Open Media Authentication (OMA), which allows you to send authentication keys securely over the network. The default is N because most devices do not use OMA.
• Prio – Defines whether the network variable is a priority network variable. It is specified by bind_info(priority | nonpriority) in the Neuron C declaration of the network variable. • Auth – Defines whether the network variable uses authentication. It is specified by bind_info(authenticated | nonauthenticated) in the Neuron C declaration of the network variable. • Addridx – Defines the index into the address table for the network variable.
M – Change Device Mode or State Use this command to change 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. If the device is a router, you can also set the router type to configured, learning, bridge, or repeater.
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. You are given an opportunity to clear the status of the device, which clears the error counters, the reset cause, and the last error logged. Clearing the status can be useful before running the Performance test ([) command; see [ – Performance Test on page 23.
variable index). 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 hexadecimal bytes. Separate each pair of hexadecimal 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 network variable to the on state.
generated XIF file with any Echelon or third-party LNS tool, including the LonMaker Integration Tool. If output redirection is in effect, the current output file is closed before creating the XIF file. Y – Download Neuron Executable Use this command to 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 FX Development Tool or Mini FX application.
• Number of iterations – How many times to repeat the performance test before displaying the collected data. The default is once. For an indefinite number of iterations, specify 0. You can press the [ key at any time to end the test. • Delay between messages – How long, in milliseconds, to delay between sending messages to the device. The default is no delay. • Acknowledged, Unacknowledged, Request, or Repeated – The type of message service to use for each message. The default is Acknowledged.
You can run a script repeatedly, as needed. See Using a Script File with NodeUtil for more information. > – Redirect Output to a File Use this command to redirect all NodeUtil output to a file. You are prompted to specify the file name. The default file name extension is .log. If the file already exists, you are asked if you want 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.
Example 2 The following script defines the domain and authentication key for a device that will be discovered and managed by a SmartServer. The script also places the device in the configured, online state and enables network management authentication. Run this script from the NodeUtil device menu for the device. Step 1. Set domain 0 to unused with OMA and set the first half of the 96-bit key. d 0 y u 112233445566 y y Step 2.
e Note that this script uses the string “112233445566” as the first half of the 96-bit key and the string “665544332211” as second half of the 96-bit key. Using a key of “112233445566665544332211” is better than not using authentication, but it is considered a weak key. Example 3 The following script clears the non-volatile memory of the FT 5000 Smart Transceiver on the Echelon FT 5000 Evaluation Board. You use this script if you need to clear the onboard EEPROM non-volatile memory.
A License Agreement This appendix shows the software license agreement for the NodeUtil Node Utility software.
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.
(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 ide
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).
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.
www.echelon.
