Silicon Labs documentation on Network Analyzer version 1.0.0. Documentation source: https://docs.silabs.com/network-analyzer/1.0.0 # Network Analyzer ## Network Analyzer Overview Simplicity Studio's Network Analyzer enables debugging of complex wireless systems. This tool captures a trace of wireless network activity that can be examined in detail live or at a later time. ![net anal start](/network-analyzer-start/1.0.0/images/net-anal-start.png) More than simply a packet sniffer, the Network Analyzer works with the data sniffer interface on the Silicon Labs wireless chips to provide direct feedback from the baseband radio of each device, allowing any supported radio to report detailed packet transmission and reception data, such as timestamps, link quality (or LQI), receive sensitivity (or RSSI), and CRC pass/fail results, all without any software overhead. With Simplicity Studio, any PTI-enabled Silicon Labs platform can record the radio activity regardless of the application firmware that is being used, so there’s no need to have a dedicated sniffer device installed to catch the traffic. The Network Analyzer also enables capture from multiple sources simultaneously into the same log file without falsely duplicating packets. This enables the developer to compare how well different radios in the network heard the same transmission. In cases when detail is not desired, Network Analyzer makes it easier to understand the workings of a complex wireless protocol. Related packet events are automatically grouped into a Transactions pane within the capture view, allowing for quicker parsing of what’s happening during that portion of the traffic log. Quickly access statistics like total duration, number of related packets, number of point-to-point and end-to-end retries, and unexpected conditions like requests with missing responses or deliveries where expected acknowledgments are missing. In addition to capturing packet events, Network Analyzer also captures asserts, debug prints, and many other events. This guide contains the following sections: - [Network Analyzer Interface](../network-analyzer-interface/): Provides a guided tour of all elements of the Network Analyzer Perspective. - [Capturing Data and Managing Sessions](../network-analyzer-capturing-data-managing-sessions/): Describes how to perform live captures, and save and manage the resulting data. - [Viewing Data in Editors](../network-analyzer-viewing-data-in-editors/): Goes into detail about working with the data presented in both the Stream Editor and the Large File Editor. - [Filtering Captured Data](../network-analyzer-filtering-captured-data/): Explains how to focus on exactly what you need from a Network Analyzer session. - [Multinetwork Considerations](../network-analyzer-multinetwork-considerations/): Discusses how to manage nodes that belong to more than one network. - [Custom Decoder](../network-analyzer-custom-decoder/): Describes how to add custom decoder to Network Analyzer. - [Network Analyzer Preferences](../network-analyzer-preferences/): Provides a reference for the many ways you can customize Network Analyzer to meet your needs. ## Simplicity Network Analyzer Version 1.0.0 (Jun 23, 2026) Release Notes Capture and analyze wireless traffic with Network Analyzer, a powerful tool for debugging complex wireless systems using Silicon Labs' Packet Trace Interface. ### Release Summary The initial GA version of the standalone Network Analyzer. #### Key Features - Added support for exporting captures in PCAPNG format. - Added support for opening and analyzing PCAPNG capture files. - Added support for importing Custom Decoders to extend protocol decoding capabilities. - Added Capture with Options, allowing users to customize capture settings before starting a capture session. - Added live encryption handling for active captures. - Added MCP server support, enabling AI agents to directly discover and execute API operations without requiring interaction through the graphical user interface (GUI). - Added Silent Capture mode, allowing captures to be written directly to a file without opening the editor - Updated Zigbee decoders to support the latest protocol stack releases and decoding capabilities. - Updated Thread decoders to support the latest protocol stack releases and decoding capabilities. #### Bug Fixes Fixed Capture interface instability on Windows. #### Removed/Deprecated Features - None #### Known Issues and Limitations - None ## Network Analyzer Interface The Network Analyzer Interface is presented as a Network Analyzer perspective. ![Network Analyzer Perspective](/network-analyzer-interface/1.0.0/images/network-analyzer-ui.png) The Network Analyzer perspective contains the following work areas: - Device Manager view (1) - Lists all debug adapters and their connected hardware and capture interfaces that are accessible to Network Analyzer. - Capture sessions (2) - Contain data captured from a node or set of nodes, with each session shown as a tab, and a live session shown in a ***Live** tab. - [Editor Panes](#editor-panes) - Display the data of a selected capture session in the editor area with up to five different panes. Network Analyzer supports two types of capture sessions: - Live sessions - Display data as it is captured; the display is continuously refreshed as new data arrives. - Saved sessions - Contain captured data that has been saved to permanent storage in a named .isd file. You can load a saved session and play it back at any time. - [Toolbar and Menu](#toolbar-and-menu) (3) and [Supporting Views](#other-views) (11) - Provide options to control data capture and display. A filter Bar (4) allows you to enter data filters, as described in [Filtering Captured Data](../network-analyzer-filtering-captured-data#filter-bar/). A Timeline Bar (5) displays the statistics of the traffic over time, as discussed in [Viewing Data in editors](../network-analyzer-viewing-data-in-editors/) The [Views area](#other-views) (11) displays additional views in a tabbed interface. ### Editor Panes Editor panes provide different aspects of capture session data. Up to five editor panes can be open at any one time: - **Map** (6) provides a graphical view of the network, where nodes are displayed with their network identifiers. The map also displays network activity. - **Transactions** (7) displays high-level node interactions that might comprise multiple events. - **Events** (8) displays information about all events transmitted and received during a capture session. - **Event Detail** (9) displays the decoded contents of the event that is currently selected in the Events pane. - **Hex Dump** (10) displays the data of the selected event in raw bytes. Network Analyzer highlights bytes that map to the data currently selected in the Event Detail pane. It shows multiple "layers", so if the packet is decrypted, the "raw" layer shows encrypted data, but the higher-level layers show this data progressively decrypted. Using the editor is discussed in more detail in [Viewing Data in Editors](../network-analyzer-viewing-data-in-editors/) ### Toolbar and Menu The Network Analyzer Toolbar and Menu provides shortcuts to frequently-used features. Selections and controls are either enabled or disabled depending on what the user is doing. ![network analyzer menu](/network-analyzer-interface/1.0.0/images/network-analyzer-menu.png) On the toolbar, hover over any control to see a short description. The following describes the controls in order from left to right. Where the function is also available on the Network Analyzer menu, it is so noted. ![network analyzer toolbar first half](/network-analyzer-interface/1.0.0/images/net-anal-toolbar-1.png) **Open File**: Opens a file dialog from which the user may select one of the applicable extensions, such as .isd, or .log. Equivalent to File > Open Capture File (Network Analyzer Trace, Energy Profiler, etc.). **Open Capture Directory**: Opens the folder to which an output file has previously been saved. Equivalent to File > Open Capture Directory. **New**: Creates a new project or other file. Equivalent to File > New Live Capture Session/Quick Capture... **Save (Ctrl+S)**: Saves any changes to the currently opened file to disk. If the file has never been saved before, the user can say where they want it saved and what extension they want to give it. If the file was previously saved, Network Analyzer saves over the old file. **Save All (Ctrl+Shift+S)**: Saves all files that have been edited, including any files open elsewhere in Simplicity Studio. As with Save, the user has the option to indicate where and how to save any files that have never been saved. **Reopen Editor**: Closes and reopens the editor. When you have changed or added new decryption keys to the preferences, it is useful to be able to reopen the file and run it through the decryptors and decoders again. **Clear Events**: Clears the editor of all events. This is useful when you are capturing on a network and are waiting for some set of events to occur but do not want to keep everything else around. **Live Capture Options**: Opens the [Capture Options](../network-analyzer-capturing-data-managing-sessions/#capturing-with-options) dialog, used to tailor the condition under which events will be captured. **View and Modify Security Keys** (Toolbar and Menu): Opens the **Active live capture keys** dialog, where you can add security keys to be used during the current capture in progress. Any keys that are added will also be added to the list of security keys in the Network Analyzer preferences. **Pause Stream** (Toolbar and Menu): Pauses a capture without stopping it. This is useful to stop capturing for period of time, and then later continue as if nothing happened. Live events occurring during a pause are not retrievable. **Import**: Select files to import and the type of import. Additional fields allow you to specify characteristics of the import. Equivalent to File > Network Analyzer Import. **Export**: Select the exporter to use, and the output file name and location. Other options depend on the exporter. Equivalent to File > Network Analyzer Export. ![network analyzer toolbar second half](/network-analyzer-interface/1.0.0/images/net-anal-toolbar-2.png) **Show Short Id** (Toolbar and Menu): Displays a node's shortId on the map, if one is known for the currently selected time. **Show Long Id** (Toolbar and Menu): Displays a node's long Id (64 bit identifier) on the map, if one is known. **Show Pan Id** (Toolbar and Menu): Displays the pan Id on the map, if one is know for the currently selected time. **Show Node Label** (Toolbar and Menu): Displays the node's label. If the node is connected to Network Analyzer over the backchannel, this value will be the host name of the adapter connected to the node. **Show Signal Strength** (Toolbar and Menu) **Show All Connectivity** (Toolbar and Menu): Shows the quality of connections between nodes on the map. **Show all Simultaneous Events on Map** (Toolbar and Menu): During periods of heavy traffic, several simultaneous transactions may overlap. When enabled, the map shows all traffic. When it is disabled (default), the map shows only the traffic related to the currently selected transaction. **Show All Transactions on Map** (Toolbar and Menu): When enabled, all transactions that overlap with the currently selected one are shown on the map. **Filter Nodes** (Toolbar and Menu): Filters out nodes that are not involved with the filtered event. **Map Zoom In** and **Map Zoom Out** (Toolbar and Menu): Increases and decreases the size of the map in the map page. Zooming in can be useful if you are looking at a very large network where a large number of nodes are positioned very close together. **Edit Trace File Description** (Toolbar and Menu): Each saved Network Analyzer trace file contains a description. The description can be used to store information that is important to the trace but may not be included by default. Generally the description is used to provide context for the trace and any other information that may be of help to the viewer. A checkbox on the dialog determines if the description is shown when the file is loaded. **Go To Line** (Toolbar and Menu): Moves the event cursor directly to the event number entered. This is only enabled if the Stream preference "Show event numbers" is selected. To turn this feature on go to: Window > Preferences > Network Analyzer > Capture Configuration > Show event numbers. **Go to Time** (Toolbar and Menu): Moves the cursor to the transaction and event that match or immediately follow the specified time. **Go To Bookmark** (Toolbar and Menu): Moves the event or transaction cursor to the bookmark selected in the bookmark dialog. Assign bookmarks to events or transactions by right-clicking the event or transaction and selecting **Add Bookmark**. **Decrease Font Size** and **Increase Font Size** (Toolbar and Menu): Decreases and increases the size of the font used in the Event, Transaction and Detail panes. **Apply Row Coloring** (Toolbar and Menu): Turns coloring on and off in the Transaction and Event panes. Row colors are applied based on the pre-defined filters included in the [Filter Manager](../network-analyzer-filtering-captured-data/#filter-manager). **Lock To Bottom** (Toolbar and Menu): Locks the event cursor to the bottom of the Event pane. During a live capture, this causes the Map and Details panes to always show the latest event. To remove the lock, select any event or transaction during a live session, which causes a view to scroll as the events are captured. **Start Replay** (Toolbar and Menu): Begins scrolling forward through events from the current event selected. If no event is selected, the scrolling will begin from the start of the current trace file. Once replay has started, converts to a **Stop Replay** function. **Timeline Bar**: Toggles the [timeline](../network-analyzer-viewing-data-in-editors/#timeline-bar) shown at the top of the currently opened Stream Editor. **Toggle Filter Bar**: Toggles the [Filter Bar](../network-analyzer-filtering-captured-data/#filter-bar) at the top of the currently opened Stream Editor. **Show Filter Manager View**: Toggles the [Filter Manager View](../network-analyzer-filtering-captured-data/#filter-manager). The following are selections on the Network Analyzer menu that are not on the toolbar: **Show DAG**: Shows the connectivity DAG from the captured neighbor DAG events. Applies only in cases when the networking stack is instrumented with the correct abilities. **Load Background Image** and **Clear Background Image**: Loads and clears a background image on the map pane. Also available on the Map pane context menu. **Print map**: Prints the nodes as currently displayed in the map pane. **Organize map**: Organizes the nodes on the map into a Default, Random, Square, or Hexagonal placement. Also available on the Map pane context menu. ### Other Views Network Analyzer provides access to a wide range of functionality through the use of views. The views are all accessible in the menu **Window > Views...**. For a complete listing of all available Views, select **Window > Views... > Other...**. The following lists some of the most helpful views. The first three are open in the Views area by default. **Radio Info**: The Radio Info View shows data captured for each event, as discussed in [Radio Info View](../network-analyzer-viewing-data-in-editors/#radio-info-view). **Event Difference**: Event Difference view is a helper view that displays the specific differences between two packets, as discussed in [Event Difference View](../network-analyzer-viewing-data-in-editors/#event-difference-view). **Connectivity view**: (15.4 captures only) Displays a graph of network connectivity, using the neighbor information from the nodes. **Error Log** - Decoder, decryption, and other types of errors are displayed in a tabular format in the Error Log View. Each error is shown in a single row with its summary message, the plugin or component that reported the error, and the date and time the error was encountered. To view detailed information about the error, double-click it. The error will be displayed in an Event Details dialog that includes the date, severity, message, and, if available, stack trace. The navigation at the top of the view allows you to perform basic functions on the Error log itself, including Export, Import, Clear, Delete, Open, and Restore. ![Error Log View](/network-analyzer-interface/1.0.0/images/error-log.png) **Expression Manager** - Also known as the [Filter Manager](../network-analyzer-filtering-captured-data/#filter-manager), this tool is used to compose and edit custom filtering expressions. **Progress** - The Progress View shows the progress of user actions. Actions that take a long time to execute may be managed within the Progress View. For example, the application upload action can take several seconds. The Progress View provides a user interface for managing this action. If you wish to stop an action, you may do so in the Progress View. Other views of interest are: **Event Detail** - Event details are normally shown in the EventDetail Pane within the Stream Editor. If you want to see the event details in a separate window, you can open the Event Detail View. This view shows the details for the currently selected Event in the same format as the Event Detail Pane, but in a view that you can pull outside of Network Analyzer and resize to your liking. **Hex Dump** - Similar to event details, the hex dump information is shown the Hex Dump Pane within the Stream Editor. If you want to see the hex dump in a separate window, you can open the Hex Dump View. This view shows the hex dump of the currently selected Event in the same format as the Hex Dump Pane, but in a view that you can pull outside of Network Analyzer and resize to your liking. **Search** - Search data is displayed in the Search Pane within the Large File Editor. However, as with the Event Details and Hex Dump Panes, you may wish to see this data in a separate view. The Search View allows you to view search results in a window that you can pull outside of Network Analyzer and resize to your liking. ## Capturing Data and Managing Sessions Network Analyzer can display one or more network capture sessions. Each capture session displays the transaction and event data captured from one or more nodes. The captured data is shown in editor panes. In general, Network Analyzer captures all incoming and outgoing packet data via the selected adapters, regardless of whether the host nodes have sniffer applications. The captured data includes failed transmissions, as well as debug messages from node applications that are compiled in debug mode. This kind of capture is called a perfect trace session. The capture nodes of a perfect trace session are not sniffers but nodes that might be running your own application that you are trying to debug. The perfect trace session compiles all incoming and outgoing data from each node in chronological real time, providing a richly-layered display of all activity within a network. A perfect trace session can be especially useful for debugging a network in development as it allows you to see every packet on the network. Network Analyzer supports two types of capture sessions: - Live sessions display data as it is captured. The display is continuously refreshed as new data arrives. When a live session starts, it is unnamed and its data is maintained in temporary storage until you save it to a named file. Network Analyzer can capture live session data from multiple sets of adapters into the same session. You cannot, however, capture from one adapter into different sessions at the same time. You can run more than one live session at the same time. - Saved sessions contain captured data that has been saved to permanent storage in a named .isd file. You can load a saved session and analyze it at any time. Network Analyzer displays each session in an editor with its own tab. The tab of each saved session is labeled with the session's file name; the first live session is labeled **Live**, the second **Live1**, the third **Live2**, and so on. You can capture data from the node of any connected Debug Adapter, from one node at a time or multiple nodes simultaneously. You can also capture all network traffic over the current channel by capturing data from a connected sniffer node. Note: The types of data captured from a node depend primarily on the software protocol running on the node, and also the capabilities of the node's radio chip and Debug Adapter. ### Starting a Capture Before starting a capture, open **Window > Preferences > Network Analyzer > Decoding > Stack Versions** and make sure that the protocol running on the adapters is selected. If you are working in a multiprotocol environment, select 'Auto-detecting decoder stack'. A change here will not affect any active capture sessions but will apply to the next capture you start. To start a capture: 1. Create a capture interface with Simplicity Device Manager or with Network Analyzer. 2. Right-click the selected capture interface. 3. On the context menu, select **Start Capture**. ![capture menu](/network-analyzer-capturing-data-managing-sessions/1.0.0/images/start-capture.png) Alternatively, left-click the **Play** button on the right of the capture interface. Alternatively, select **File > New > Quick Capture...** and select the desired capture interface. Alternatively, select **File > New > New Live Capture**. This creates a new live capture session and puts it on top of the editor list. When you start a capture on an capture interface, the live session used for the capture is assigned in one of the following ways: - If no live sessions are currently active, a new live session is created and used. - If live sessions are active, but they are not on top of the editor stack (for example, another file is opened and currently on top), a new live session is created and used. - If a live session is active and it is also on top of the editor stack, then this session will be used for capture. ### Capturing with Options You can filter packets out of the stream during a capture. For example, you can choose to see only packets from a certain PAN ID and drop all other packets. 1. Select one or more connected adapters. 2. Select **Edit > Capture options**. 3. Configure options in the resulting dialog, and click **OK**. ![capture options dialog](/network-analyzer-capturing-data-managing-sessions/1.0.0/images/capture-options.png) In the capture options dialog, you can set the following: - Capture only PANs: (15.4 protocols only) This filter, based on PAN ID, allows a comma-separated list of hexadecimal values. - Aggressive mode: Filters out all events that may not be or definitely are not packets. - Enable advanced energy measurement: This enables AEM packet filtering. AEM packets are used with Energy Profiler. If you turn this option on and later look at the data in Energy Profiler, you will not see any packets. - Enable PC sample data: If selected, captures diagnostic events. - Enable exception sample data: If selected, captures Java framework exceptions, which are used for deep diagnostics of possible Network Analyzer bugs. - Enable debug channel: If selected, enables capturing all other non-packet events. - Enable logic analyzer sample data - Silent capture to file: If selected, performs a lengthy capture as a background task. Traffic will not show in the GUI until the capture is stopped and the file is opened. The silent capture enables you to run a capture over several days, as it does not consume memory resources, only disk space. - The start capture options specify the trigger for delayed start of capture. - immediately: No automation, capture starts right away. - after: Capture starts after a certain time or after a certain number of events. - upon: Capture starts upon Node reset, or upon an event containing a specified ASCII or byte pattern. The triggers for starting and stopping capture on node reset work only if you have DEBUG level NORMAL turned on for the node that you are capturing from. With the debug level set to Normal, the chip will send debug information, including node resets, over the back channel to Network Analyzer. Network Analyzer uses these reset and other commands to trigger the start-and-stop capture process. If an image does not have debug turned on, it will not send reset information to Network Analyzer, and Network Analyzer has no basis for triggering start or stop capture. You can also modify some, but not all, capture options through the Live Capture Options toolbar control. ### Capturing from a Sniffer Node Any node connected to Network Analyzer through a Debug Adapter can be designated as a sniffer. A sniffer node captures over-the-air traffic transmitted between nodes on the configured channel. A sniffer node must have an application loaded that enables packet capture. When capture is started from a sniffer node, Network Analyzer receives the packets captured by that node on the selected channel. A sniffer node must have a sniffer application loaded. The sniffer application enables the node to capture over-the-air transmissions between nodes over the designated channel. When you start capturing from a sniffer node, the sniffer node captures all packets that are exchanged by the nodes on the designated channel. IIf a sniffer application is not currently loaded, you can manually configure a RAILtest-based sniffer application. To manually configure a RAILtest-based sniffer: 1. Create **RAIL - SoC RAILtest** project from Example Project & Demos 2. Build the project and flash it to the radio board. 3. Open the Simplicity Device Manager tool 4. Select the board and click **Configure** in the Device section 5. Open **Serial 1** terminal 6. Connect to the device 7. Configure the radio RX settings to match the protocol you want to capture 8. After RX is enabled, start the capture from Network Analyzer The following example configures the device for Zigbee packet capture: ```command status rx 0 config2p4GHz802154 enable802154 rx 100 192 864 setPtiProtocol 5 setPromiscuousMode 1 setChannel 11 setNotifications 0 rx 1 ``` The commands are described below: |Command|Description| |---|---| |`status`|Shows the current status of the sniffer before configuring it| |`rx 0`|Disables receive mode and puts the radio into an idle state so it can be configured| |`config2p4GHz802154`|Configures the radio for the 2.4 GHz IEEE 802.15.4 PHY| |`enable802154 rx 100 192 864`|Enables the required 802.15.4 receive configuration| |`setPtiProtocol 5`|Sets the PTI protocol. Common values are 0 = Custom, 2 = Thread, 3 = BLE, 4 = Connect, 5 = Zigbee, and 6 = Z-Wave| |`setPromiscuousMode 1`|Enables promiscuous mode so the device can capture packets not addressed to itself| |`setChannel 11`|Sets the radio channel to capture. Choose the channel that matches the target network.| |`setNotifications 0`|Disables CLI packet notifications so captured packet information is not printed to the terminal| |`rx 1`|Enables receive mode and starts listening for packets| More information about the commands is available in [Capturing Data and Managing Sessions](https://docs.silabs.com/network-analyzer/latest/network-analyzer-capturing-data-managing-sessions) and [Full Help Text](https://docs.silabs.com/rail/latest/railtest-users-guide/07-miscellaneous#full-help-text). > **Note**: The example was tested with RAIL 3.0. ### Stopping a Capture 1. Select one capture interface. 2. Right-click the selected capture interface. 3. On the context menu, select **Stop Capture**. To resume capture, select **Start Capture**. Alternatively, left-click on the **Stop** button on the right side of the selected capture interface. ### Pausing a Capture Pause a capture at any time by clicking **Pause** button on the right side of the selected capture interface or the toolbar. This is a convenient way to stop capturing from a device or devices without having to start a new capture at a later time. Events that occur during the pause are lost, and cannot be retrieved. ### Clearing Session Events Click **Clear Events** on the Network Analyzer menu or toolbar to purge all events and their associated transactions from the current session. **Caution!** You cannot retrieve cleared events. This is mostly used if you are working on a scenario on an embedded node, where you control some activity through command-line actions. You then simply "Clear" events between each retry, instead of having to do a complete "Start Capture / Stop Capture". Note: Network Analyzer is designed to stay connected and continue capturing, even when the firmware on the target node is uploaded and the node resets. That does not stop the capture session. ### Saving a Session When you start a capture, it is initially written to an unnamed live session. At any point during a live session, you can save the data thus far captured to a file by selecting File > Save. After you save a session file, Network Analyzer continues to append capture data to it; however, you must save again in order to retain this data in the session file. Network Analyzer saves session data to an .isd file, which is a compressed file that stores session data and the network state. Network state includes display settings such as map modifications, which Network Analyzer restores when you reload the session file. Network Analyzer closes a saved session from further captures after you explicitly stop the capture, or when you start another live session. After a saved session is closed, it cannot be reopened to capture more data. If you modify a saved session file - for example, set bookmarks or reposition icons in the Map pane - Network Analyzer asks whether to save or discard those changes before you close the session. Note: For security reasons, Security Keys that you may use to decrypt captured data are not included in saved .isd files by default. If you wish to share security keys with your files, you should turn on the option "Save decryption keys in Network Analyzer files" on the Security Keys preference page, which you can access by selecting Window > Preferences > Network Analyzer > Decoding > Security Keys. #### Saving Multiple Sessions If multiple open capture sessions have unsaved data, you can save all of them at once by selecting **File > Save All**. #### Exporting to Other File Formats To export a capture session to another file format: 1. Select **File > Network Analyzer Export** or click the toolbar **Network Analyzer Export** control. 2. Select the export format. 3. Name the output file. 4. Click **Save**. #### Extracting Individual Events You can extract specific events from the Transactions pane, Events pane, or Hex Dump pane, and save them into a separate text log file. To extract specific events to a text file: 1. Right-click the event in the Transactions, Events, or Hex Dump panes that you want to extract. 2. On the menu, select **Extract to**. 3. Name the output file with a text extension. 4. Click **Save**. Once you specify a file, you can append additional events to it by right-clicking the event that you want to append and selecting **Append to **. ### Open and Close Options To open a capture file, select **File > Open Recent File** or click the toolbar control. To close a single capture session, close the session tab. To close all capture sessions, right-click any session tab and select **Close All**, or select **File > Close All Editors**. To close all but the current capture session, right-click its session tab and select **Close Others**. ### Replaying a Session (Rarely used) Replay events of the current session, whether live or saved, by selecting **Start Replay** on the Network Analyzer menu or the toolbar. Network Analyzer replays the session from the selected event at a constant speed. Replaying events in a live session has no effect on the capture in progress. Once replay has started, both the toolbar control and the menu selection convert to a **Stop Replay** function. ## Viewing Data in Editors On the File menu, select **Open Capture File...** or **Open Recent File** to open data in an editor. If the file is smaller than the size set in **Preferences > Network Analyzer > Capture File Storage** for a file to be considered large, Network Analyzer opens it in the Stream Editor. Otherwise, Network Analyzer opens it in the Large File Editor. - **[Stream Editor](#stream-editor)**: The Stream Editor decrypts, decodes, and displays details of individual events. - **[Large File Editor](#large-file-editor)**: The Large File Editor does not offer any detailed decoding and presentation of events. Instead, it provides a high-level overview of a file and allows users to open their points of interest in the Stream Editor. The Stream Editor provides details about individual events. However, in the case of really large captures, this may tax system resources. The Large File Editor shows an overall timeline and node statistics. It allows you to scan very large captures for areas of interest, which you can then open in Stream Editor. ### Stream Editor ![stream editor showing HA demo](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor.png) The Stream Editor contains five editor panes, each of which provides a different view of the captured session data: - [Map pane](#map-pane): Provides a map of the network, with nodes displayed with their network identifiers. The map also displays network activity. - [Transactions pane](#transactions-pane): Displays high-level node interactions that might comprise multiple events. - [Events pane](#events-pane): Displays information about all packets transmitted and received during a capture session. - [Event Detail pane](#event-detail-pane): Displays the decoded contents of the packet that is currently selected in the Events pane. - [Hex Dump pane](#hex-dump-pane): Displays the data of the selected event in raw bytes. Network Analyzer highlights bytes that map to the data currently selected in the Event Detail pane. All five editor panes may be open at once. Live captured data is continuously updated and displayed in the editor panes. A [Timeline Bar](#timeline-bar) displays the statistics of the traffic over time. Views are presented in a tabbed interface in the lower left of the default Network Analyzer perspective. - [Radio Info View](#radio-info-view): Shows the information from the radio of all the receivers in the network that have heard the currently selected event. - [Event Difference View](#event-difference-view): Displays the differences between two packets. - Connectivity View: (15.4 captures only) Displays a graph of network connectivity, using the neighbor information from the nodes. For more information about using the Stream Editor panes, see the [Editor navigation tools](#editor-navigation-tools). #### Map Pane The following information is applicable to 15.4 networks only. The Map pane shows all interaction between nodes at a high level. As events occur or are replayed, the Map pane refreshes to show the pattern of network communication. Debug messages issued from a node also display next to the node. ![stream editor map pane](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-map.png) Each node in the map pane is given a different color depending on its capabilities within the network as they are understood by Network Analyzer based on captured data. - RED: The node is a network coordinator. - BLACK: The node is a router. - GREEN: Default color for network nodes. The following figure shows the graphical elements that appear in the Map pane to depict network activity. Thick lines depict transactions, while thin lines depict single packets. ![stream editor codes in the map pane](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-map-code.png) Note: The colors shown vary according to the transaction or event type, and can be configured through the [Filter Manager](../network-analyzer-filtering-captured-data/#filter-manager) The data that is shown for each node is managed through menu/toolbar options: - **Show Short ID** toggles display of the node's 16-bit address that is unique within the personal area network (PAN). - **Show EUI64** toggles display of the node's unique 64-bit IEEE address. - **Show PAN ID** toggles display of the PAN identifier of the node's network. This label can be useful when the map displays multiple networks. - **Show Node Label** displays the custom label that you create for map display only. - **Show LQI** toggles display of link quality data that pertains to the quality of connection between nodes. This is available with perfect trace captures, but not with sniffer captures. - **Show Connectivity** shows the neighbor relationships between nodes in the network. - **Simultaneous Events** displays on the Map pane all events that occurred at the same time as the transaction or event that is currently selected. The currently selected event is in color and any other events display in gray. - **Zoom Map In** and **Zoom Map Out** enlarge and shrink the space that the map uses to display nodes. Zoom options have no effect on the size of node icons. You can move node icons within the Map pane display. This has no effect on network functionality. However, it can help to highlight certain node interactions and relationships. When you move node icons in a session, Network Analyzer asks whether to save those changes before you close the session. Right-click anywhere in the map pane to bring up a context menu. - **Organize Map** establishes the layout of all nodes on a map. You can also modify individual node positions as needed. The following layouts are available: - Default Placement aligns nodes in a linear pattern. - Random Placement scatters the nodes across the map randomly. - Square Grid aligns the nodes in a grid. - Hexagonal Grid aligns the nodes in a hexagonal, offset pattern. - **Load Background Image** and **Clear Background Image** manage the display of a background image in the Map pane. Right-click on a node to bring up a context menu. - **Assign EUI64** lets you assign a EUI64 to a node (not available if Network Analyzer obtains the EUI64). Network Analyzer obtains a node's EUI64 only when that node associates with a network. If the node already belongs to a network when a session begins, its EUI64 is unknown. This option lets you display a known EUI64 for a node; the node's actual EUI64 is unaffected by this label. The Multinetwork checkbox can be used to indicate that the node is operating on multiple networks. See [Multinetwork Considerations](../network-analyzer-multinetwork-considerations/) for more information. - **Multinetwork** toggles the multinetwork property. See [Multinetwork Considerations](../network-analyzer-multinetwork-considerations/) for more information. - **Label** lets you customize the node's adapter (device) label with any string up to 25 characters long. This string appears in brackets after the node's device name. (By default, the Map pane labels each node that is undergoing capture with its device name.) You can also make the labels time-dependent by entering a start time. This lets you supply multiple names for the same node. This can be useful while debugging applications, by indicating the node's current state. - **Icon** and **More Icons** allow you to display the node as an icon. #### Transactions Pane The Transactions Pane displays higher-layer protocol events that consist of multiple packet transmissions. For example, a Zigbee broadcast is retransmitted by every node in the network. By analyzing packet headers, Network Analyzer determines which packets belong to the same transaction and groups them accordingly. ![stream editor transactions pane](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-transactions.png) Typical 15.4 transactions include: - **802.15.4 association**: Involves a request-response protocol that consists of at least 6 packet transmissions. - **APS unicast**: Can contain the following events: - A MAC layer unicast packet and its MAC retries - Acknowledgements for each hop along the route - An end-to-end APS acknowledgement message, which itself consists of multiple MAC unicast packets - Multiple end-to-end APS retries - **Zigbee route discovery**: Involves a broadcast route request followed by unicast route-reply packets across multiple hops. In the case of Bluetooth Low Energy (and Bluetooth mesh), a “transaction” refers to an actual Bluetooth Low Energy transaction as defined in the core specification. This corresponds most of the time to a Bluetooth Low Energy procedure. Equally, the event pane displays the actual Bluetooth Low Energy events corresponding to the transaction or procedure. For more details, refer to the Bluetooth Core specification document. Network Analyzer understands the protocol semantics for many transaction types. Therefore it can group multiple packets in real time to facilitate high-level analysis. All transactions are listed in chronological order, using transaction start times. Each selection maps to one or more events in the Events Pane, which are marked accordingly. Clock icons indicate concurrent transactions with the current selection. All transactions and their events are uniquely numbered. However, the transaction numbers may not be in sequence, and various factors will result in number gaps. For example, only top-level transactions and the lowest-level packets are shown. Intermediate transactions are not shown. Also, number gaps are likely to occur if filters are turned on. When you click on a transaction, the information shown in the Event Detail Pane and the Hex Dump Pane corresponds to the first packet in the transaction. However, if filters are turned on, the first transaction might not be shown in the Event Pane. In that case, the event detail information in the transaction display will not be consistent with the first packet shown in the Event Pane. In fact, with a filter expression such as `show(transaction.summary != null, SELF)` only transactions are displayed and the Event Pane will be blank. In that case, click the transaction to see the first events in the transaction in the Event Detail and Hex Dump Panes. #### Events Pane The Events pane displays information about packets received by the current session. All events are displayed in chronological order. ![serial editor events pane](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-events.png) Events that belong to the currently selected transaction in the [Transactions pane](#transactions-pane) are marked by one of the following icons: ![transaction icons](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-transaction-codes.png) Clock icons mark unrelated events that are concurrent with the selected transaction in the Transactions pane. #### Event Detail Pane The Event Detail pane displays the decoded contents of the event that is currently selected in the [Events pane](#events-pane). The content of this pane varies according to the event type. If a transaction is selected on the [Transactions pane](#transactions-pane), the Event Detail pane shows the details of the first event in the transaction. Pane options include: - **Expand Bitfield**: Shows the bitfields in an expanded mode, like Wireshark. - **Use Fixed Fonts**: Can improve readability as information is presented aligned. When capturing from multiple devices, Network Analyzer may capture the same packet as heard by several different sources. In order to reduce confusion, Network Analyzer automatically performs duplicate detection on all packets captured. If the transmission is captured over the backchannel, only the transmitted packet is kept. Otherwise the first receive packet is kept. All duplicate packets are dropped after extracting their RadioInfo data. Only the radio info frame for each duplicate packet is kept. The radio info for each individual instance of a packet captured by Network Analyzer is visible in the [Radio Info View](#radio-info-view) ![Event detail pane in the stream editor](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-event-detail.png) **Pinning a field**: The Event Detail pane has the ability to "pin" a field into view. When you double-click on a specific field, the Pin icon in the top left of the pane turns bright red, indicating that it is active. Now, as you move through events, this field is always visible when it is present in the currently selected packet. This is useful if you are interested in a specific field across multiple events in a trace file. In the above figure, the Zigbee Application Support Delivery Mode is "pinned" into view. The pin can be deactivated at any time by either double-clicking on the pinned field, or by clicking the Pin icon itself. #### Hex Dump Pane The Hex Dump pane displays data in raw bytes of a selected event in the [Events pane](#events-pane). Clicking on bytes in the Hex Dump pane selects the corresponding field in the [Event Detail pane](#event-detail-pane). Alternatively, selecting a field or a frame in the Event Detail pane highlights the corresponding bytes in the Hex Dump pane. The pane shows multiple "layers", so if the packet is decrypted, the "raw" layer shows encrypted data, but the higher-level layers show this data progressively decrypted. ![Stream editor hex dump pane](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-hex-dump.png) #### Timeline Bar The Timeline bar displays the statistics of the traffic over time. The Timeline bar function on the Network Analyzer toolbar toggles the Timeline Bar on and off. ![Stream editor timeline bar](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-timeline-bar.png) Available actions are: - Click on the Timeline bar to move the cursor to the event closest to the time selected. - Click and drag on the Timeline bar to filter the display to only the time within the selected area. - Right-click to display a timeline menu. The Timeline bar shows bookmarks as yellow flags. You can click a bookmark to jump to it in the Transaction and Event panes. It shows red flags for errors, such as out-of-sequence problems. #### Radio Info View The Radio Info view is a helper view that shows the information from the radio of all the receivers in the network that have heard the currently selected event. It is available in the tabbed **Views** interface in the lower-left corner of the default Network Analyzer perspective. If it's not visible, add it by selecting **Window > Views**. The view displays in a tree all the information that has been gathered from the receiver nodes. Displayed information includes LQI value, CRC value, and the status bits that show several states of the radio. ![Stream Editor radio info view](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-radio-info.png) The event that supplied radio information in the figure above was captured from both the sending and receiving nodes. This is possible because the trace that contains this event was created by capturing from both the sending and receiving nodes simultaneously using Network Analyzer's Perfect Trace capability. While the original events were merged into a single event by Network Analyzer's duplicate detection mechanism, the radio information was retained for each event and is shown in the Radio Info view with the time that the event was captured by Network Analyzer. #### Event Difference View Event Difference view is a helper view that displays the specific differences between two packets. It is available in the tabbed **Views** interface in the lower-left corner of the default Network Analyzer perspective. If it is not visible, add it by selecting **Window > Views**. ![Stream Editor Event Difference View](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-event-diff.png) Once the view is shown, it tracks the selected events. The view will by default show the difference between the last two events selected. If you select event 1, and then click on event 2, the view shows the difference between those two events. If later you select event 3, the view shows the differences between event 2 and 3. Packet frames that do not have any differences are shown in green. Frames that contain differences are shown in red. Expand the frame to see which portions of the frames are different. The menu at the top of the view supports additional functions. ![Stream editor event difference view icons](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-event-diff-icons.png) - **Show traffic counts**: Opens a window showing the statistics for the events between, but not including, the two selected event. - **Show byte differences**: Enables viewing of individual bytes in the view. - **Pin last selected event**: Changes the way events are tracked. If this is enabled, then the first event for diffing stays the same, and only the second event changes. You can use this if you wish to always differentiate events against a certain static event, rather than always viewing last two selected events. - **Include fields that are same**: Enables filtering out fields that are same in both events. #### Editor Navigation Tools Some of the Network Analyzer Toolbar functions are specific to working in the Stream Editor. ![stream editor navigation toolbar options](/network-analyzer-viewing-data-in-editors/1.0.0/images/stream-editor-toolbar-options.png) - **Edit description of trace file**: Opens a simple dialog which allows you to view and edit overall description of the captured data. This is helpful if you need to pass on some information others for analyzing the contents of the trace file. - **Go to Line**: Moves the cursor to the event or transaction having the specified event number. This is only enabled if the Stream preference "Show event numbers" is selected. To turn this feature on go to: Window > Preferences > Network Analyzer > Capture Configuration > Show event numbers. - **Go to Time**: Moves the cursor to the transaction and event that match or immediately follow the specified time. - **Go to Bookmark**: Moves the cursor to the selected bookmark. Assign bookmarks to events or transactions by right-clicking the event or transaction and selecting **Add Bookmark**. - **Lock to Bottom**: Locks the cursor on the latest event during a live session. To remove the lock, select any event or transaction during a live session, which causes a view to scroll as the events are captured. ### Large File Editor If the file is larger than the size set in **Window > Preferences > Network Analyzer > Capture File Storage**, Network Analyzer opens it in the Large File editor. The Large File Editor allows you to find and select a region of interest, which you can then open and analyze with the Stream Editor. ![large file editor](/network-analyzer-viewing-data-in-editors/1.0.0/images/large-file-editor.png) The Large File Editor consists of three component panes: - [Large File Timeline](#large-file-timeline): Shows a high-level view of a large file's traffic over time. - [Large File Search pane](#large-file-search): Provides a mechanism for searching across very large files. - [Large File Network Nodes pane](#large-file-network-nodes): Shows all of the network devices included in a large file. #### Large File Timeline The Large File Timeline shows a high-level view of a large file's traffic over time. It works similarly to the [Stream Editor's](#stream-editor) timeline. In fact, the Large File and the Stream Editor timelines use the same widget. **Large File Timeline Segments**: The entire set of events shown in the Large File Timeline is broken into segments. By default, each segment includes up to 5,000 events. Segments boundaries are shown in the Large File Timeline by horizontal grey lines. **Large File Timeline Time Markers**: The Large File Timeline shows the actual time during which a file was captured. The capture start-time appears in the bottom left corner of the Timeline. The capture end-time appears in the bottom right corner. Moving the cursor to any point on the timeline displays the time for that point. **Large File Intervals**: A Large File Interval is a subset of an entire trace. You can create an interval by clicking and dragging. Click on the Large File Timeline at the desired start-point, and then drag the cursor along the timeline to the desired end-point. The click and drag operation creates the interval you defined, and zooms the timeline view into that interval. To clear the interval, click the Clear Selection button in the toolbar under the timeline, or right-click on the timeline and select **Clear interval**. Once you have created an interval, you can open that interval in the Stream Editor by clicking the Open Interval button, or right-clicking in the timeline and selecting **Open Interval**. **Timeline Flags**: Search results and errors are displayed in the Large File Timeline by flags. Search results are displayed as a yellow flag. Errors are displayed as a red flag. When you move the mouse over the flag, the Timeline displays the Summary of the Event or Transaction that is associated with the flag. #### Large File Search Use the Large File Search mechanism to search for events across very large files. The entire filter language is supported in the Large File Search. For more information, see [Filter Language](./network-analyzer-filtering-captured-data#filter-language). To run a search in the Large File Editor, enter the filter expression into the Filter Expression text box and click the Start Search control. The search progress is shown in the Large File Timeline. Options allow you to limit the search within a time interval or to limit the number of search results. It is useful to limit the number of search results, as the system can become slow if the search expression matches an extremely large number of events. Filter results are shown in the Search Results table. Search results are grouped into results trees and labeled with the time and date that the search was performed. To view search result details, double-click an individual search result. This opens three segments in a Stream Editor: one before the selected event, one that contains the event, and one after the event. Note: The expressions and search results are saved into the Network Analyzer file. Thus they will be seen by other users who open the same Network Analyzer file. Controls to the right of the search results allow you to delete, tag, open, and assign decorative icons to the searches and search results. #### Large File Network Nodes The Large File Network Node pane shows all of the network devices included in a large file. The information provided about each node in a trace includes: - EUI64 address - Short address - PAN ID - Node type Since each of these values is subject to change over time, the summary also includes the time at which each value was discovered. ## Filtering Captured Data By default, the Events pane displays all session events. You can build and apply filters that constrain Network Analyzer to show only events that are of interest. By filtering events, you can analyze results more efficiently. Each capture session has its own filter settings. A filter can be used either to search for the next matching event or to display only the events that match the filter. In the latter mode, when you change a session's filters, Network Analyzer immediately refreshes the display. When you exit Network Analyzer, all session filters are cleared and must be reapplied when you restart. Network Analyzer provides two ways to edit filters: - [Filter Manager](#filter-manager): Maintains a set of saved filters that you can review and edit. You can also add new filters. You specify any of the saved filters for display on the Filters menu, accessed through the **n saved filters** button on the filter bar, so that they are available for use in one or more sessions. - [Filter Bar](#filter-bar): An editor that attaches to a given session, where you can enter one or more filter expressions on the fly. Network Analyzer discards filter bar expressions for all sessions when it exits. [Quick filters](#quick-filters) are available when you right-click on events and transactions. They provide an easy way to create common expressions for the filter bar. [Filter Language](#filter-language) is a powerful syntax used to create filters. ### Filter Manager The Filter Manager lets you: - Use filter expressions to customize display of entries in the Events pane. - Specify which filters appear in the Filters menu. The Filter Manager is available through menu and toolbar selections as well as through **Window > Views... > Expression Manager**. ![Expression Manager](/network-analyzer-filtering-captured-data/1.0.0/images/expression-filter-manager.png) > **Note**: The older **Expression Builder** feature is deprecated. #### Maintaining Filters To add a filter to the Filters menu, check the Menu checkbox. This makes the filter available to the current sessions. To restore filters to installation settings, click **Reset**. To rename a filter, click on the name field and edit. You can also create new, delete, export and import filters. #### Setting Filter Color Schemes You can associate a color scheme with each filter. If an event evaluates as true for a given filter expression, Network Analyzer applies the filter's color scheme to that event. An event can be configured with a color scheme for two display levels: - For the Map pane, the color used by the graphic representing the event type. - For the Events pane, the foreground and background colors used by event type instances. Note: Setting a color scheme on a filter expression does not specify whether to display events; it only determines how to display certain event types. Note: If a filter's foreground color is the same as its background color you will not be able to read the text in the event and it will effectively disappear from view. To set a filter color scheme, in the Filter Manager: 1. Next to the filter of interest, check the Color checkbox to enable the controls for Map (Map color), and Fg (Foreground color) and Bg (background color) for event instances. 2. Click the control you want to set to enable the color selector control. 3. Click the color selector control, set the filter's color, and click **OK**. If you have changed Foreground or Background colors you will see the change on the Name field. 4. For each filter, set the color scheme's Priority level by assigning a positive or negative integer value. If an event evaluates as true for multiple filters, Network Analyzer uses the color scheme with the highest precedence. In the case where there is no clear precedence, Network Analyzer randomly chooses one of the matching color schemes. 5. To refresh the Map pane and Events pane with the new color scheme, click **Reapply**. A filter whose menu checkbox is selected is shown in the Filters menu. The order in which the filters are displayed in the Filters menu is determined by their order in the filter manager table. ### Filter Bar A session's Filter Bar provides the same level of functionality as the Filter Manager for building expressions. Any filter expression that appears in a session's Filter Bar is combined with the saved filter expressions that are already in effect for that session. ![Filter Bar](/network-analyzer-filtering-captured-data/1.0.0/images/filter-bar.png) The Filter bar is displayed by default, but can be toggled on and off using the **Show Filter Bar** menu control. You can compose a Filter Bar expression in the following ways: 1. Enter the expression directly in the filter edit field, and press Enter. 2. Create a Quick filter. To apply a Filter Bar filter, enter an expression into the filter edit field and press Enter. To find an event that matches the filter, click the Find icons on the Filter Bar. To remove a filter, select it and press Enter. Note: A history of filter expressions is maintained in the drop-down list. ### Quick Filters Network Analyzer provides several filters that are available from the Transactions pane, Events pane, Event Detail pane, and Hex Dump pane. To access a quick filter, right-click an item and choose a quick filter pop-up menu option. #### Hide or Show Events/Transactions Access these filters by right-clicking an event (Events pane) or transaction (Transactions pane) and selecting a pop-up menu option to hide or show specific information. The filter options that are available depend on the selected transaction or event. You can specify to hide all events/transactions of the selected type, or to show only that type. In addition if you select an event of type APITrace, the pop-up menu displays two filter options: - Hide type: APITrace - Show only type: APITrace Further, if you select an event such as a neighbor exchange that has a source and/or destination address, the pop-up menu also contains these two filter options: - Show only destination: short-ID - Show only source: short-ID In all cases, Network Analyzer enters the corresponding filter expression in the session's Filter Bar. This can help you to understand the filter language. For example, if you specify to show only route discovery transactions, this expression is set in the filter bar: `isType(Route)` #### Frame Byte Pattern Filtering A frame pattern filter matches a specific byte-array pattern. For example, you could filter for packets in a payload whose frame has the third byte equal to 0x33. (Many more complex combinations are possible.) To create a frame pattern filter: 1. Right-click a frame in the Event Detail pane or Hex Dump pane. 2. Select Filter by frame pattern from the pop-up menu. 3. In the Byte Pattern dialog, check the byte pattern match desired and click OK. The filter is added to the Filter Bar for this session. ![Byte Pattern](/network-analyzer-filtering-captured-data/1.0.0/images/frame-pattern.png) ### Filter Language Filter language enables you to construct logical expressions, based on decoded fields in events. The following are some examples: - `fifteenFour.sequence == 0x52`: Matches events where 15.4 sequence number equals hex 0x52. - `fifteenFour.ackRequired == true && fifteenFour.source == 0x035f`: Matches events where 15.4 ack required flag is set, and source shortId is 0x035f. - `isPresent(zigbeeSecurity.frameCounter)`: Matches events that contain the Zigbee security frame, and the frameCounter field within it. - `event.summary | "string"`: Matches events where a string is a substring of the summary. - `isType(Packet)`: Matches events that are packets. - `frameMatch(fifteenFour,"**88**EF/**********")`: Matches events where 15.4 frame contains second byte equal to 0x88 and fourth byte equal to 0xEF. A good way to learn the filter language is by first using the **Add to filter** context menu option in the Event Detail Pane. This option will add a filter expression for the chosen field. You can use most standard logical operators (&&, ||) and standard comparison operators ( ==, !=, |, <, >, <=, >=, etc.) in filter expressions. #### Event and Transaction Filter Extensions In addition to filtering on decoded packet fields, you can filter on several other Event and Transaction values. ##### Event Extensions - event.summary: A String value of the summary shown in the Event Pane. - Example: event.summary == "APS Ack" - event.linkStatus: True if the packet is a Link Status packet. - Example: event.linkStatus == true - event.ack: True if the packet is an 802.15.4 ack. - Example: event.ack == true - event.time: The time that the event was transmitted (tx) or received (rx). - Example: event.time >= 75.78 - event.originator: The adapter that saw and reported the event. - Example: event.originator == "ewb-unit04" - event.status: The event status, listed in the righthand column of the event status window - Example: event.status == "ZCL: ReportEventStatus" - event.type: The type of event, shown in the Type column of the Event and Transaction Panes. - Example: event.type == "Packet" - event.corrupt: The event corruption string, empty if event is not corrupt - Example: event.corrupt < "crypt" ##### Transaction Extensions - transaction.summary: Filters on the transaction summary field shown in the Summary column of the Transaction Pane. - Example: transaction.summary == "ZCL: LoadControlEvent" - transaction.packetCount: Filters on the number of packets in the transaction shown in the P# column of the Transaction Pane - Example: transaction.packetCount == 4 - transaction.macRetries: Filters on the number of MAC retries in the transaction shown in the M# column in the Transaction Pane. - Example: transaction.macRetries == 2 - transaction.endToEndRetries: Filters on the number of end to end retries shown in the E# column in the Transaction Pane. - Example: transaction.endToEndRetries == 3 - transaction.status: Filters on the status of the transaction shown in the Status column of the Transaction Pane. - Example: transaction.status == "CRC failed" - transaction.dest: Filters on the network destination of the transaction shown in the NWK Dest column of the Transaction Pane. - Example: transaction.dest == 0x05c7 - transaction.source: Filters on the network source of the transaction shown in the NWK Src column of the Transaction Pane. - Example: transaction.source == 0x0000 #### How Network Analyzer Applies a Filter When Network Analyzer captures an over-the-air message, it runs the message through a processing stream. The processing stream is made up primarily of Decoders and Groupers. **Decoders:** Decoders are responsible for making sense of the message based on its format so that it may be displayed to the user. Each over-the-air message captured becomes a single Event of type Packet. This Event is displayed to the user in the Event view. **Groupers:** The groupers are responsible for making sense of a series of packets and grouping them into a hierarchy under a single Transaction. The Transaction is displayed in the Transaction view. ##### Using `show(expression, SELF|PARENT|CHILD|SIBLING)` Events exist within a hierarchical structure where Transactions represent the top of the hierarchy and Events are at the bottom. The hierarchical nature of trace data creates something of a problem for filtering. In most cases, you wish to see Transactions associated with filter-matching Events, and vice versa. For instance, if you use a filter like: "transaction.summary == Association", you probably do not want to see only the transactions in the Transaction Pane. You probably also want to see the events contained within the Association displayed in the Event Pane. You can solve this problem by using the optional `show(expr, args)` syntax in your filters. The show syntax allows you to explicitly indicate the conditions under which an event or transaction should match your filter. The arguments for the show syntax are as follows: **SELF** - The Event or Transaction matches if it contains data that matches the expression provided. **PARENT** - A Transaction should be shown if any one of its child Events matches the filter. **CHILD** - An Event should be shown if the Transaction to which it belongs matches the filter. **SIBLING** - An Event matches if its PARENT transaction contains another Event which itself matches the filter. **Filter display defaults**: Filter expressions that do not explicitly contain the optional `show(expr, args)` syntax are implemented as though they contain one of two default syntaxes. Which default syntax is used depends on where the filter is executed, in the Stream Editor or in the Large File Editor. - Stream Editor default: `show(expression, SELF|PARENT|CHILD)` By default, filter expressions that do not explicitly contain the show(expr, args) syntax are implemented as though they were wrapped in the following syntax: `show(expression, SELF|PARENT|CHILD)` The SELF|PARENT|CHILD arguments provide what Silicon Labs believes a user expects to see when a filter is run in the Stream Editor. The filter display includes the events and transactions that match the filter itself. If an Event matches the filter, you also see an associated Transaction (PARENT) regardless of whether that Transaction matches the filter. Likewise, if a Transaction matches the filter, you also see its associated Events (CHILD) regardless of whether those Events match the filter. - Large File Editor default: `show(expression, SELF)` By default, the search mechanism in the Large File Editor returns only those Events and Transactions which themselves match the filter expression provided. This behavior makes it very easy to run a filter to search for all the Transactions with a given summary without having the search results bogged down with hits for their associated Events. ##### Expression Validation **Lexical validation** - When you enter a filter expression, the filter engine validates whether the expression is lexically correct. If an expression is not lexically correct, Network Analyzer gives you an error message with a suggestion about where there may be a problem in the expression. **Event Key validation** - When you enter a lexically correct expression, Network Analyzer also runs an event key validation. It checks that any identifier provided represents a real entity within an Event or Transaction. If the filter engine is not able to find any associated data for an event key within the expression, Network Analyzer will warn you that you are using an unverified identifier. For example, in the expression `fifteenFour.dest == 0xffff` fifteenFour.dest is a verifiable event key in that Network Analyzer knows that it represents real data in an event. Here are two examples to illustrate the validation of expressions in Network Analyzer. Consider this expression: `foo == bar` The filter mechanism has no way of knowing what foo and bar represent, or that they even represent any type of data within an Event or Transaction. While this expression is lexically correct, Network Analyzer will warn the user that foo and bar could not be verified, and that the expression may provide unexpected results. In fact, this expression will not show anything, since foo may very well equal bar, but the filter engine has no way of knowing that. Consider also this expression: `foo == foo` This expression also displays a warning. However, when run, it will return ALL events, because while Network Analyzer does not know what foo is, it knows it definitely equals foo. **Special identifiers** - Several special identifiers are not mapped to an event key. - payload.xxx, which evaluates into the payload bytes for a given layer xxx, for example payload.raw or payload.tcp_stream. You can form expressions like `payload.raw == {001122aabbcc}` to match payloads - flag.xxx, which evaluates into the value of the event flag for a given event, for example: `flag.neighbor_exchange` or `flag.fragment`. ## Multinetwork Considerations If your application uses nodes operating on multiple networks, this information can be reflected when reviewing capture sessions. Currently, however, Network Analyzer cannot auto-detect multinetwork nodes. At the onset, unless all traditional, conceptual nodes constituting the multinetwork node are assigned EUI64s, each conceptual node shows up as a separate node in the Map editor pane. Each such node must be assigned the same EUI64 by right-clicking on the node in the Map editor pane and selecting **Assign EUI64...** A dialog pops up that facilitates the assignment, and the **Multinetwork EUI64** checkbox must be checked to inform Network Analyzer that the node is indeed a multinetwork node. This sequence is illustrated in the following figure. ![net anal multinetwork](/network-analyzer-multinetwork-considerations/1.0.0/images/net-anal-multinetwork.png) Once all the constituent conceptual nodes have been assigned the same EUI64, Network Analyzer coalesces them into one node in the Map editor pane. Alternatively, if the all the conceptual nodes know the EUI64 or all have been coalesced but Network Analyzer has not been informed that the node is multinetwork, the **Multinetwork node** menu item in the figure above can be toggled. Once a node is known to Network Analyzer to be multinetwork, it is indicated as such by being colored magenta in the Map editor pane. ## Custom Decoder Extend Network Analyzer with custom protocol decoders. A decoder is an Eclipse plug-in that reads raw packet payload bytes and converts them into meaningful, structured fields that Network Analyzer can display. Custom decoders are useful for proprietary or application-specific protocols that the standard Network Analyzer decoders don't fully interpret. The extension template in the repository is designed for creating custom Network Analyzer payload decoders. Use a custom decoder to: - Inspect proprietary packet formats without manually decoding raw bytes. - Display protocol fields with clear names and values. - Make packet traces easier to debug, review, and share. - Add application-specific protocol knowledge to Network Analyzer. Network Analyzer supports custom decoders through Eclipse plug-ins. A custom decoder implements the `IPayloadDecoder` interface and registers with the `com.silabs.na.extension.payloadDecoder` extension point. After you install the plug-in, Network Analyzer discovers the decoder automatically. ### Add a Custom Decoder to Network Analyzer Complete these setup, implementation, export, and installation steps to make a custom decoder available in Network Analyzer. #### Step 1: Install the Required Eclipse IDE Install **Eclipse IDE for RCP and RAP Developers** from the [Eclipse packages page](https://www.eclipse.org/downloads/packages/). This version includes the plug-in development tools that you need to build a Network Analyzer extension. #### Step 2: Clone and Import the Extension Project 1. Clone the [Network Analyzer Extension](https://github.com/SiliconLabsSoftware/network-analyzer-extension) repository: ```sh git clone git@github.com:SiliconLabsSoftware/network-analyzer-extension.git ``` 2. In Eclipse, select **File** > **Import** > **General** > **Existing Projects into Workspace**. 3. Select the `network-analyzer-extension` directory, and then finish the import. ![Select the Network Analyzer extension project](/network-analyzer-custom-decoder/1.0.0/images/custom-dec-select-project.png) #### Step 3: Configure the Network Analyzer Target Platform 1. In Eclipse, select **Window** > **Preferences** > **Plug-in Development** > **Target Platform**. 2. Select **Add**. Then select **Nothing: Start with an empty target definition** as the starter target definition. 3. Browse to the Network Analyzer installation directory. Typical installation paths are: - **macOS**: `Macintosh HD/Users/USERNAME/.silabs/slt/installs/archive/network-analyzer/Network Analyzer.app/Contents/Eclipse/` - **Windows**: `C:\Users\USERNAME\.silabs\slt\installs\archive\network-analyzer` - **Linux**: `/opt/network-analyzer/` ![Add the Network Analyzer target platform](/network-analyzer-custom-decoder/1.0.0/images/custom-dec-added-network-analyzer.png) > **Note**: On macOS, select the `Eclipse` folder inside the `.app` bundle. The selected directory must contain the `plugins` and `features` folders. 4. After you add the target platform, activate it. ![Activate the Network Analyzer target platform](/network-analyzer-custom-decoder/1.0.0/images/custom-dec-activate-target-platform.png) 5. After you add and activate the target platform, project errors should be resolved. ![View the imported project in Project Explorer](/network-analyzer-custom-decoder/1.0.0/images/custom-dec-project-explorer.png) #### Step 4: Implement the Protocol Decoding Logic 1. In Eclipse **Project Explorer**, open the sample decoder in the custom decoder project: `com.customer.na.custom/src/com.customer.na.custom.decoder/CustomPayloadDecoder.java` ![Open the custom payload decoder](/network-analyzer-custom-decoder/1.0.0/images/custom-dec-payload.png) 2. Update the decoder logic for your protocol by modifying these methods: - `accept()` - `decode()` Use `accept()` to decide whether the decoder should process a packet. Use `decode()` to parse the packet payload into fields that Network Analyzer can display. #### Step 5: Export the Decoder Plug-In 1. In Eclipse, select **File** > **Export** > **Plug-in Development** > **Deployable Features**. 2. Select the feature project, choose an export destination, and then finish the export. #### Step 6: Install the Decoder in Network Analyzer 1. In Network Analyzer, select **Help** > **Install New Software** > **Add** > **Local**. 2. Browse to the export location. Select the folder that contains the generated p2 metadata, including `content.jar` and `artifacts.jar`. 3. If the feature list is empty, clear **Group items by category**. 4. Select the feature, continue through the installation wizard, and then restart Network Analyzer when prompted. ![Install the custom decoder in Network Analyzer](/network-analyzer-custom-decoder/1.0.0/images/custom-dec-install-new-software.png) ### Test the Custom Decoder After installation, verify that Network Analyzer discovers the decoder and displays the expected fields from the sample capture. #### Step 1: Confirm That the Decoder Is Installed After Network Analyzer restarts, select **Window** > **Preferences** > **Network Analyzer** > **Decoding**. The custom decoder should appear in the decoder list. ![Confirm that the custom decoder is installed](/network-analyzer-custom-decoder/1.0.0/images/custom-dec-check-decoder.png) #### Step 2: Open the Example Capture Use the `docs/custom-decoder-sample.log` or `docs/custom-decoder-sample.isd` sample capture files, which are provided in the repository. Open the selected file in Network Analyzer. The sample log exercises several decoder cases, including bitmasks, command nibbles, a string tail, a length-prefixed chunk, and an unknown command case with `opaqueTail`. For more information, see the comments in the sample log file. #### Step 3: Enable the Custom Decoder 1. In Network Analyzer, select **Window** > **Preferences** > **Network Analyzer** > **Decoding**. 2. Find **Custom Protocol Decoder**, enable it, and then select **Apply** or **OK**. #### Step 4: Verify Decoded Packet Fields Return to the capture view, and then expand a packet. The decoded custom fields should appear under **Application Payload** or under the custom decoder frame. For the sample decoder, expected fields include: - `demoMagic` - `frameControl` - `deviceId` - `sequenceNumber` - `temperature` If these fields are visible, the decoder is installed, enabled, and running successfully. ![Verify decoded packet fields](/network-analyzer-custom-decoder/1.0.0/images/custom-dec-event-detail.png) ## Network Analyzer Preferences To access Network Analyzer preferences, select Window > Preferences > Network Analyzer. The preferences you set apply to all capture sessions. Network Analyzer saves your preferences and uses them each time Network Analyzer restarts. Preference categories include: - [Capture Configuration](#capture-configuration-preferences) - [Capture File Storage](#capture-file-storage-preferences) - [Connectivity Display](#connectivity-display-preferences) - [Decoding](#decoding-preferences) - [MCP Server](#mcp-server) - [Node Icons](#node-icons-preferences) - [Optional Dialogs](#optional-dialogs-preferences) - Stream Visualization (deprecated function) - [Timeline](#timeline-preferences) - [Wireshark](#wireshark-preferences) ### Capture Configuration Preferences ![Capture configuration preferences](/network-analyzer-preferences/1.0.0/images/prefs-capture-configurations.png) These preferences offer general, time management, and user interface configuration options. Changes take effect in the next new capture session. Some options are: - Sorting and duplicate match window: Specifies in microseconds a time span in which duplicate packets can be detected. If identical packets arrive within the specified time span, Network Analyzer detects the duplication and allows only one to display. - Perform drift correction in network Analyzer: Allows drift for autocorrection. - Drift Threshold: Specifies the amount of time-drift that Network Analyzer will tolerate between the absolute PC clock and the adapter clocks before it resets its "time-correction" factor. In most situations you should not change this value. In a typical situation, adapter clocks are more precise than PC clocks, but they do not provide absolute time, just relative time against an arbitrary reference. ### Capture File Storage Preferences ![Capture file storage preferences](/network-analyzer-preferences/1.0.0/images/prefs-capture-file-storage.png) These preferences determine, among other things, what is considered a large file, which in turn determines the default editor used. Changes take effect in the next new capture session. Some of the options are: - Monitor the timestamp and optionally reload: Monitors whether the file has changed on the disk, and prompts to reload if so. - Monitor files for appending after opening: Enables Network Analyzer to detect new packet data appended by an external program to an open session file, and read it in for display. - Preserve open files across sessions: Instructs Network Analyzer to automatically reopen files from previous session - Enable large file handling: Enables Network Analyzer to handle large files in the Large File Editor. Files are considered large if they contain more events than the number entered in "Number of events for a file to be large." ### Connectivity Display Preferences ![Connectivity display preferences](/network-analyzer-preferences/1.0.0/images/prefs-connectivity-display.png) These preferences customize how device connectivity is displayed. ### Decoding Preferences ![Decoding preferences group level](/network-analyzer-preferences/1.0.0/images/prefs-decoding-group.png) The **Decoding** preferences group affect how decoding is handled. Changes take effect in the next new capture session. On the Decoding dialog, some options are: - Selected stack: The stack selected for decoding newly captured data. Links allow you to make changes in other preference interfaces. This setting has no effect on a previously captured trace. The decoding stack for a trace file is stored in the file itself. - Security level: The security level set for the MAC and network layers. Valid values include 1 through 5. #### Security Keys ![Decoding preferences security keys](/network-analyzer-preferences/1.0.0/images/prefs-decoding-security-keys.png) Specifies the security decryption keys. To enable a key, select the Decryption key checkbox. To edit a key, select its name or key values. All enabled decryption keys are run against each incoming packet until one is successful. Successful keys are automatically moved to the top of the key list to improve performance. Decryption keys can also be obtained from network traffic for future use. Buttons on the right of the dialog provide the following features: - New: Creates a new key for editing. - Import: Opens a dialog from which you can import a key file. - Clone: Creates a copy of the currently selected key. - Delete: Removes the currently selected key. - Invert swaps the order of the key values. - Clear All: Removes all security keys. - Run HMAC: Opens a dialog that allows you to manually calculate the HMAC authenticated key from trust key and IEEE EUI64 address. - ASCII edit...: Converts a human-readable ASCII string into a binary security key. The checkboxes at the bottom of the keys list provide the following options: - Save decryption keys in ISD files (unchecked by default): Saves the security keys that you have specified into the capture file along with your traffic. Note: If you are sharing the Network Analyzer file with users who have a right to know your key, this may make the opening of the file easier for them, as they will not have to separately enter the key. However, by doing this, you create a security risk. Never enable this option, if your keys must remain secure and known to you only. - Disable keys when not used for n days (checked by default): You can configure the number of days unused keys should be kept. #### Stack Versions ![Decoding preferences stack versions](/network-analyzer-preferences/1.0.0/images/prefs-decoding-stack-versions.png) A list of profiles representing Gecko SDK Suite stack versions. Check the stack that is deployed on the network you are using. If you are working with Dynamic Multiprotocol projects, select 'Auto-detecting decoder stack'. #### Transaction Groupers ![Decoding preferences transaction groupers](/network-analyzer-preferences/1.0.0/images/prefs-decoding-transaction-groupers.png) A table of all the groupers loaded into Network Analyzer. Transaction groupers are responsible for making transactional sense out of a trace of network data. Groupers watch for batches of events and record them as a transaction. ### MCP Server ![MCP Server](/network-analyzer-preferences/1.0.0/images/prefs-mcp-server.png) The MCP server exposes Network Analyzer tools to AI assistants via the Model Context Protocol over Streamable HTTP. To use this feature, the MCP server must be enabled. ### Node Icon Preferences ![Node Icon Preferences](/network-analyzer-preferences/1.0.0/images/prefs-node-icon.png) Network Analyzer provides several predefined icons. The Node Icons dialog displays all icons that are available for customizing display of nodes in the map pane. You can also add icons of your own. ### Optional Dialog Preferences ![Optional Dialog Preferences](/network-analyzer-preferences/1.0.0/images/prefs-optional-dialog.png) Some dialogs can be turned off if you prefer not to interact with them. ### Timeline Preferences ![Timeline Preferences](/network-analyzer-preferences/1.0.0/images/prefs-timeline.png) Among other options, you can choose the colors and fonts for features of the Timeline. ### Wireshark Preferences If you are using the Wireshark open source packet analyzer, these options configure the integration. ![Wireshark Preferences](/network-analyzer-preferences/1.0.0/images/prefs-wireshark.png)