LonScanner™ FX Protocol Analyzer User’s Guide 078-0305-01B
Echelon, i.LON, LNS, LonMaker, LONMARK, LonTalk, LONWORKS, Neuron, NodeBuilder, and the Echelon logo are trademarks of Echelon Corporation registered in the United States and other countries. LonScanner is a trademark of the Echelon Corporation. Other brand and product names are trademarks or registered trademarks of their respective holders.
Welcome The Echelon® LonScanner™ Protocol Analyzer is a software tool that you can use to monitor, analyze, and diagnose the behavior of LONWORKS® networks. The LonScanner Protocol Analyzer connects to IP-852 (ISO/IEC 14908-4) and native LONWORKS (ISO/IEC 14908-1) channels, collects packets from those channels, and stores information from the packets into log files. You can use the log files to inspect and interpret the collected packets. You can monitor up to 10 channels at once with the protocol analyzer.
configuring the IP-852 channel with the Echelon LONWORKS/IP Configuration Server, and guidelines to follow when using NAT, DNS, or DHCP on the IP-852 channel. • LNS Programmer's Guide (078-0177-01F). This manual describes how to • LonMaker User's Guide (078-0333-01A). This manual describes how to use the LonMaker Integration Tool to design, commission, monitor and control, maintain, and manage a network. • LONMARK® Application Layer Interoperability Guidelines.
Table of Contents Welcome .........................................................................................................iii Audience ........................................................................................................iii What’s New for LonScanner FX...................................................................iii Related Documentation ................................................................................iii Chapter 1.
Searching By Log Number .................................................................... 45 Bookmarking Packet Log Entries ............................................................... 45 Formatting the Packet Log.......................................................................... 47 Selecting Data Fields ............................................................................ 47 Formatting Data Field Columns ..........................................................
1 Introduction to the LonScanner Protocol Analyzer This chapter introduces the LonScanner Protocol Analyzer. It describes how to install and activate the LonScanner software, and how to get started with the protocol analyzer.
Introduction The LonScanner FX Protocol Analyzer is a software tool that you can use to monitor, analyze, and diagnose the behavior of LONWORKS networks. The LonScanner FX Protocol Analyzer connects to IP-852 (ISO/IEC 14908-4) and native ISO/IEC 14908-1 channels, collects packets from those channels, and stores information from the packets into log files. You can use the log files to inspect and interpret the collected packets. You can monitor up to 10 channels at once with the protocol analyzer.
3. Click LonScanner FX Protocol Analyzer to continue. The Welcome window opens. 4. Click Next to continue. The License Agreement window opens. 5. Read the terms of the LonScanner FX Protocol Analyzer software license agreement. If you agree to the terms of the license agreement, click I Accept the Terms in the License Agreement. The User window opens. Note: The LonScanner software license is included in this document as Appendix B, LonScanner FX Protocol Analyzer Software License Agreement, on page 63. 6.
Figure 1. LonScanner License Activation Dialog To continue running in demonstration mode, click Continue Eval. When operating in demonstration mode, the protocol analyzer does not display every captured packet and displays only the first 20 packets of a saved or imported log file. After you activate the product, you will have access to all LonScanner features. If you choose to operate in demonstration mode, the LonScanner License Activation dialog appears every time you open the protocol analyzer.
• Select Professional Edition Activation Key, Single User if you do not have a prepaid key, and you are ordering a single activation key. You can use this option to activate a LonScanner FX Demo Edition or to add an additional user for a LonScanner FX Professional Edition. • Select Professional Edition Activation Key, 5-Pack if you do not have a prepaid key, and you are ordering a 5-pack with five activation keys.
Figure 2. LonScanner Transfer Activation Wizard 2. Click Next to continue. The main window opens, as shown in Figure 3. Figure 3. LonScanner Transfer Activation Wizard Main Window 3.
a. Step one must be performed on the target computer to which you want to transfer the activation. b. Step two must be performed on the computer that currently contains the activation that you want to transfer. The LonScanner software on this computer will no longer be activated after the transfer is complete, and will run in demonstration mode. c. Step three must be performed on the target computer to which you want to transfer the activation. This step completes the transfer.
network interface. For more information, see Monitoring a Network Channel. • Open an Existing Packet Log. Select this option to view a packet log saved from a previous monitoring session. For more information, see Opening an Existing Packet Log on page 9. Monitoring a Network Channel To monitor an IP-852 or LONWORKS channel, perform the following steps: 1.
SmartServer, i.LON 600 LONWORKS/IP Server, PCC-10, or PCLTA-20/21 network interface see Appendix A, Network Interfaces, on page 59. 2. Click OK to begin monitoring the selected channel. The main LonScanner window opens. A log entry is added to the Packet Log tab for each packet that the protocol analyzer receives from the channel. For an overview of the Packet Log tab and the rest of the main LonScanner window, see Log Files Overview on page 9. 3.
Figure 5. Main LonScanner Window The main window includes the following three main areas: • The Packet Log tab comprises the majority of the main LonScanner window. The Packet Log tab contains a series of log entries, one for each packet that the protocol analyzer collects from the channel. The log entries are listed sequentially by timestamp. See the online help for descriptions of the data fields listed for each packet.
Using the LonScanner Window This section provides a brief introduction to the features that you can access using the main LonScanner window. These features are described in more detail in later chapters, and in the LonScanner online help. LonScanner Menus Table 1 lists the LonScanner menus, and describes the functionality that is provided by each menu. For detailed descriptions of each menu option, see Chapters 2 and 3 of this document, and the LonScanner online help. Table 1.
Menu Description Help Use the Help menu to access information about the version and activation status of the LonScanner software, and to access the LonScanner online help. You can also access the LonScanner Transfer Activation Wizard from this menu. LonScanner Toolbar The LonScanner toolbar provides quick access to commonly used menu options. The LonScanner toolbar is shown in Figure 6. Figure 6. LonScanner Toolbar You can click a button on the toolbar to use the feature provided by that button.
Clears all data from the log file currently shown in the Packet Log tab. Starts the LNS Names Import Wizard, which you can use to import device and network variable names from an LNS database. Finds an occurrence of a string in the Packet Log tab. Finds the next occurrence of a string in the Packet Log tab. Creates a bookmark. You can use bookmarks to mark certain log entries as being of interest. Scrolls the Packet Log tab to the next bookmarked packet.
interface (that is, each tool can use the network interface at the same time). Network interface sharing applies to PCC-10, PCLTA-20/21, i.LON SmartServer, i.LON 100 Internet Server, i.LON 600 LONWORKS/IP Server, and U10/U20 USB Network Interfaces. You can also run the protocol analyzer and the LonMaker tool (or any custom LNS application) at the same time with the same network interface on a computer with an LNS 3 Server if you use an i.LON SmartServer, i.LON 100 Internet Server, or an i.
2 Logging Data This chapter describes how you can log packets with the protocol analyzer, and how you can view statistics related to those packets. The first part of this chapter describes how you can configure the behavior of the protocol analyzer while it monitors a channel and collects packets, including topics such as setting logging preferences, using the Capture and Auto-Scroll features, and filtering packets.
Configuring the LonScanner Protocol Analyzer You can configure the behavior of the protocol analyzer while it monitors a channel, including: • Setting logging preferences to control how the protocol analyzer collects and record packets from a channel. • Filtering packets to select which packet types are written to the log file.
Filtering Packets You can use filters to select the types of packets that are written to the log file. You can use two types of filters: • A global filter that applies to all packets • A device filter that applies to packets sent to and from specific devices on the network When the protocol analyzer receives a packet from the channel, it uses the global and device filter to determine if the packet passes the filter requirements, as described in Figure 9.
You can also filter packets with a custom filter file. To create and use a custom filter file, modify the LsCustomFilter.cpp file in the LonScanner Example Custom Filter directory. Configuring the Global and Device Filters To configure either the device filter or the global filter, perform the following steps: 1. Select Filter → Edit Filters to open the Device Filter dialog, as shown in Figure 10. Figure 10. Device Filter Dialog 2. To include all devices in the filter, skip to step 5.
it in the Device Filters list, and then click one of the buttons at the bottom of the Device Filter dialog: • New opens the Select Device to Add dialog, as described in step 2. • Delete removes the selected device from the device filter. • Sel Input opens the Input Mode dialog. You can use this dialog to specify whether or not packets sent to the selected device should pass the device filter requirements. • Sel Output opens the Output Mode dialog.
Figure 11. Global Filter Dialog 6. Under Mode, select Capture packets that pass the global and device filters to write packets that pass the requirements of the global and device filters into the Packet Log. Select Discard packets that pass the global and device filters to write packets that do not pass the requirements into the Packet Log. 7.
9. Click OK to save your changes and return to the Device Filter dialog. 10. Click OK on the Device Filter dialog. The protocol analyzer uses the updated filter configuration to filter all incoming packets. You can edit the configuration of the filter file again later by selecting Filter → Edit Filters, and repeating steps 2 through 10. You can select Filter → Set to Defaults at any time to revert the filter to the default filter settings.
Setting the Capture and Monitor Modes You can use the Capture and Monitor modes to control whether the packets collected from the channel are written to the log file, whether the Packet Log tab is refreshed as packets are received, and whether the Packet Log tab is automatically scrolled to display incoming packets. To record packets collected from the network into the current log file, click the Capture button on the LonScanner toolbar or select Network → Capture Mode.
Note: The data displayed on the statistics tabs is calculated based on the packets that pass the global and device filters and are written to the current log file. Packets that are discarded because they do not meet the current filter requirements are not used in the statistics calculations.
Viewing Bandwidth Utilization by Packet Type Select the Packet Types tab to view a breakdown of the packet types collected from the monitored channel. The packet types are grouped as good (valid) and bad (invalid) packets. For each packet type, the total number of collected packets of that type is listed. The percentage of the total packet count for each type is also listed. See the online help for descriptions of the packet types listed on the Packet Types tab.
Figure 14 shows a bandwidth utilization trend graph with example data. Figure 14. Bandwidth Utilization History Tab The BWU History tab includes two timestamps: the timestamp for the oldest and the newest update points on the trend graph. You can set the rate at which this display is updated, as well as the number of points that are displayed on the chart, with the statistics options dialogs. See Setting Statistics Options on page 26 for more information.
Figure 15. Error Rate History Tab The Err Rate History tab includes two timestamps: the timestamp for the oldest and the newest update points on the trend graph. You can set the rate at which this display is updated, as well as the number of points that are displayed on the chart, with the statistics options tabs. See Setting Statistics Options for more information.
Figure 16. General Tab 2. Configure the settings on the General tab. These settings determine the interval at which the statistics display is updated, and the format that is used to display the statistics. See the online help for descriptions of these fields. 3. Select the Bandwidth Graph tab, as shown in Figure 17. Figure 17. Bandwidth Graph Tab 4. Configure the settings on the Bandwidth Graph tab.
Bandwidth Utilization chart, whether logarithmic scaling should be used for the chart, and the colors that are used to display the chart. See the online help for descriptions of these fields. 5. Select the Error Graph tab, as shown in Figure 18. Figure 18. Error Graph Dialog 6. Configure the settings on the Error Graph tab.
Figure 19. Channel Type Dialog 9. Select the channel type and bandwidth utilization options for the channel that you are monitoring and click OK. These settings are important for calculating bandwidth utilization because the available bandwidth is determined by the channel type. When you begin monitoring a channel, the protocol analyzer attempts to determine the channel type automatically.
Names are not included in the packets sent over the network, nor are they saved in log files. However, you can use names to identify the devices that are sending or receiving messages on the channel that you are monitoring, to identify the network variables that are being updated by these messages, or to identify the domains and groups that exist on your network. When you start a LonScanner session, you can import names from an LNS database or from another channel.
Figure 20. LNS Names Import Wizard – Page One 2. Select the LNS database that contains the names that you want to import from the LNS Database Name dropdown list box, and click Next. The second page of the wizard displays, as shown in Figure 21 on page 32.
Figure 21. LNS Names Import Wizard – Page Two 3. Select the subsystem (or subsystems) that contains the names that you want to import from the Available Subsystems list. Alternatively, you can click Select All to select all subsystems, or click Select Subtree to select all subsystems within the currently selected subsystem. Click Next to continue. The third page of the wizard displays, as shown in Figure 22 on page 33.
Figure 22. LNS Names Import Wizard – Page Three 4. As the names are imported, it is possible that the names stored in the LNS database could conflict with names that you have previously imported or assigned. These conflicts can occur under the following circumstances: Two domains have the same ID. Two devices or router sides in the same domain have the same Neuron® ID. Two devices or router sides in the same domain have the same subnet/node address.
Figure 23. LNS Names Import Wizard – Page Four 5. Select a format for device and network variable names. Examples for each option are shown on the dialog. 6. Click Next. The LonScanner software imports the names from the LNS database. When it finishes the import, a completion dialog appears. Click Finish to exit the wizard. You can also click Save from the completion dialog to save the imported names into an .RTF file. 7. You can now use the imported names.
1. Select Names → Import from Names File. A dialog opens to remind you that names that you are currently using will be overwritten. 2. Click Yes to continue. The Windows Open dialog opens. 3. Browse for the names file that you want to use, and click Open to import the names. 4. You can now use the imported names. You can also use the Names menu to add new network object names or to customize the ones you imported. See Creating and Customizing Names on page 36 for more information.
Creating and Customizing Names You can use the Names menu to create your own names, or to customize the names that you already created. Creating Group Names You can create or change an ISO/IEC 14908-1 group name with the protocol analyzer. To create a group name, perform the following steps: 1. Select Names → Edit Groups to open the Select Group dialog, as shown in Figure 25. Figure 25. Select Group Dialog 2. Select a domain from the Domains list.
4. Enter the group ID for the group in the Group Number field, and enter the name for the group in the Group Name field. 5. Click OK to close the New Group dialog and return to the Select Group dialog. 6. The new group name is listed in the Groups list. You can edit the group name by selecting it and clicking Edit. You can delete the group name by selecting it and clicking Delete. 7. Click OK to close the dialog.
Figure 28. New Device Data Dialog 3. Enter the device’s name in the Device Name field, and then fill in the rest of the fields in the New Device Data dialog. See the online help for information about these fields. 4. Click OK to close the New Device Data dialog and return to the Select Device dialog. The new device name is listed in the Devices list. You can edit the device name by selecting it and clicking Edit. You can delete the device name by selecting it and clicking Delete. 5.
Figure 29. Edit Message Codes Dialog 2. The Edit Message Codes dialog lists all currently defined message code names. To create a new message code name, click New. The New Message Code dialog opens, as shown in Figure 30. Figure 30. New Message Code Dialog 3. Enter the name of the message code, and the message code to which the new name should apply. See the online help for more information on these settings. 4. Click OK to close the New Message Code dialog and return to the Edit Message Codes dialog.
Figure 31. Select Domain Dialog 2. The Select Domain dialog lists the domain names that are currently defined in your network. To create a new domain name, click New. The New Domain dialog opens, as shown in Figure 32. Figure 32. Edit Domain Dialog 3. Enter a name for the domain in the Domain Name field, and set the domain ID and length for the domain. See the online help for more information about these fields. 4. Click OK to close the New Domain dialog and return to the Select Domain dialog.
Managing Names Files You can save names that you have created, edited, or imported for later use by saving them into a names file. When you create, edit, or import names, the protocol analyzer starts using those names immediately. You can save the names to a names file to prevent changing them in future LonScanner sessions or to share them with other channels.
3 Analyzing Packet Log Details This chapter describes how to organize and analyze the data stored in your log files, including how to search a log file for a specific packet, how to bookmark certain packets as being of interest, and how to format the data in the Packet Log tab for display. It also describes how to print and export log files. You can use the features described in this chapter when viewing a saved log file, or when viewing an active log file.
Searching For Packet Log Entries You can quickly search a packet log to find a specific packet, even if your log file contains log entries for hundreds or even thousands of packets. You can search a log file for a string or for a specific packet number. Searching By String You can search any of the fields listed in the Packet Log tab for a specific string by performing the following steps: 1. Select Edit → Find to open the Find String dialog, as shown in Figure 33. Figure 33. Find String Dialog 2.
The LonScanner toolbar also includes buttons you can use to find a string, and to move to the next occurrence of a string once you have begun a search. For more information on the LonScanner toolbar, see LonScanner Toolbar on page 12. Searching By Log Number You can find a particular log entry by searching for its log packet number or its arrival sequence number. The log packet number is the number currently assigned to the packet in the log.
To use bookmarks, perform the following steps: 1. Right-click the log entry in the Packet Log tab and click Toggle Bookmark from the shortcut menu, or select Edit → Toggle Bookmark, to open the Add Bookmark dialog, as shown in Figure 35. For an active log, you can turn off autoscrolling so that you can see the selected log entry. Figure 35. Add Bookmark Dialog 2. Optional: Enter a name for the bookmark in the Name field.
1. Select Edit → Bookmarks to open the Bookmarks dialog, as shown in Figure 36. Figure 36. Bookmarks Dialog 2. The bookmarks are listed at the top of the dialog, sequentially by packet number. Click a bookmark in the list to select that bookmark, and then click Go To to scroll the Packet Log to that log entry. Or, click Delete to remove the log entry from the log. To remove all packets at once, click Delete All.
Figure 37. Select Columns Dialog 2. The fields that are currently displayed in the Packet Log are listed in the Visible Fields list. See the online help for descriptions of these fields. To change the column position of a field in the log, select the field and click Move Up or Move Down to move the field. The top field is displayed on the left side of the Packet Log, and the bottom field is displayed on the right side of the Packet Log.
Figure 38. Format Columns Dialog 2. The dialog defaults to the Packet Number tab, which you can use to format the Packet Number field. You can select the other tabs to format the other data fields in the Packet Log window. Fill in the fields on each tab, and then click OK to save your changes and close the dialog. Or, click Apply to save your changes and continue formatting data fields. See the online help for more information about how to use each tab. 3.
Figure 39. Colors Dialog 2. To enable transaction color-coding, select the Color Code Transactions checkbox. When you enable this feature, the log entries for all the packets involved a single transaction have the same color. Click the Transaction Color 1, Transaction Color 2, and Transaction Color 3 buttons to select the three transaction colors. The LonScanner tool uses transaction colors 1, 2, and 3 in a rotation as new transactions begin.
Figure 40. Print Selection Dialog 2. Select the packets that you want to print and click OK. The Windows Print dialog appears, from which you can select a printer and print the selected log entries. You can also print any of the statistics tabs described in Viewing Channel Statistics and Trend Graphs on page 22. To print one of the statistics tabs, select the tab that you want to print, and select File → Print to open the Windows Print dialog.
each log entry is written to the output file as a single line of plain ASCII text, followed by an end-of-line terminator. If you are exporting a text file, choose what character will be used to separate the fields of a single log entry from the Delimiter options. Enter the name of the file to contain the exported log in the Output file field. By default, the file is created in the LONWORKS LonScanner directory. To select a different directory, click Browse. 4. Click OK to export the selected log entries.
4 Example Logs This chapter describes the example log files that are included with the LonScanner software.
Example Packet Logs Two example logs are included with the LonScanner software. One of the example log files is taken from a channel without any names defined. The second example log file is taken from a channel that has imported a set of names from an LNS database. Sample 1: Channel without Assigned Names The first example log file is shown in Figure 42. There are no names defined for this log file.
variable. In this example, the network variable index is 6. At packet 13, device 1/2 responds to device 1/1. The success response code is 0x33, and the returned data is “0 0” in raw format. Figure 43. Example Log File One – Packet 16 Selected In Figure 43, packet 16 is selected in the Packet Log. At packet number 16, device 1/1 sends an acknowledgement to device 1/2.
Figure 44. Example Log File Two – Packet 13 Selected In Figure 44, packet 13 is selected in the Packet Log. At packet number 13, device DI-1 is sending out a group acknowledged network variable update message (group number 0). The message data (Data field) is “100.0 1”, which is a SNVT_switch structure. At packets 14 and 15, device DO-1 and LNS Network Interface send acknowledgments back to device DI-1.
Figure 45. Example Log File Two – Packet 24 Selected At packet number 22, device DI-1 is sending out an acknowledged network variable update message to device AO-1, but device AO-1 fails to respond. Packets 23 through 25 are retry messages (see Figure 45). The alternate path attribute is set on the last two attempts, packet number 24 and 25, of an acknowledged transaction. This concept also applies to a request/response transaction.
A Network Interfaces This appendix lists the Echelon network interfaces that you can use with the protocol analyzer, and describes any special considerations for using each type of network interface.
Network Interfaces Overview You can use any of the following Echelon network interfaces with the LonScanner FX Protocol Analyzer: U10 USB Network Interface and U20 USB Network Interface — LONWORKS network interfaces for any computer with a USB interface, which includes most desktop, laptop, and embedded computers. These network interfaces are ideal for use in applications that require a computer to monitor, manage, or diagnose a network.
See the IP-852 Channel User's Guide (078-0312-01A) for more information about creating an IP-852 channel with an i.LON server or an LNS server. i.LON 600 LONWORKS/IP Server —IP-852 router and a LONWORKS remote network interface (RNI) that can be accessed through an Ethernet or dial-up IP connection. You can use the IP-852 router to connect a LONWORKS channel to an IP-852 backbone. The LonScanner tool can either be used with an IP-852 channel created using the IP-852 routing of the i.
2. Select the network interface that you want to configure in the Device Selected dropdown list box. 3. For the NI Application dropdown list box: a. If you are using a PCC-10, select PCC10VNI. b. If you are using a PCLTA-20 or a PCLTA-21, select PCL10VNI. 4. Click OK to save your changes and close the dialog. You can now use your PCC-10, PCLTA-20 or PCLTA-21 with the protocol analyzer.
B LonScanner FX Protocol Analyzer Software License Agreement To successfully install the LonScanner FX Protocol Analyzer software, you must agree to the terms of the software license agreement. This appendix shows the agreement.
LONSCANNER™ FX PROTOCOL ANALYZER 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.
• “You(r)” means Licensee, i.e. the company, entity or individual who has rightfully acquired the Licensed Software.
(e) except for the limited rights granted above, distribute, rent, loan, lease, transfer or grant any rights in the Licensed Software or modifications thereof or accompanying documentation in any form to any person without the prior written consent of Echelon. This license is not a sale. Title, copyrights and all other rights to the Licensed Software, Activation Key, Documentation, and any copy made by You remain with Echelon. TERMINATION This license will continue in effect until terminated.
DAMAGES, LOSSES, COSTS OR EXPENSES OF ANY KIND ARISING FROM THE SUPPLY OR USE OF THE LICENSED SOFTWARE OR ACCOMPANYING DOCUMENTATION, HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY (INCLUDING WITHOUT LIMITATION NEGLIGENCE). THIS LIMITATION WILL APPLY EVEN IF ECHELON OR AN AUTHORIZED DISTRIBUTOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND NOTWITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY.
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 You and Echelon and supersedes any other communications or advertising with respect to the Licensed Software and accompanying documentation.
www.echelon.
