intona IN3032UG User manual

IN3032UG: Ethernet Debugger User Guide
The information disclosed to you hereunder (the “Materials”) is provided solely for the selection and use
of Intona products. To the maximum extent permitted by applicable law: (1) Materials are made available
”AS IS” and with all faults, Intona hereby DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS,
IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
NON-INFRINGEMENT, OR FITNESS FOR ANY PARTICULAR PURPOSE; and (2) Intona shall not be liable
(whether in contract or tort, including negligence, or under any other theory of liability) for any loss or damage
of any kind or nature related to, arising under, or in connection with, the Materials (including your use of the
Materials), including for any direct, indirect, special, incidental, or consequential loss or damage (including
loss of data, profits, goodwill, or any type of loss or damage suffered as a result of any action brought by
a third party) even if such damage or loss was reasonably foreseeable or Intona had been advised of the
possibility of the same. Intona assumes no obligation to correct any errors contained in the Materials or to
notify you of updates to the Materials or to product specifications. You may not reproduce, modify, distribute,
or publicly display the Materials without prior written consent. Intona products are not designed or intended
to be fail-safe or for use in any application requiring fail-safe performance.
© Copyright Intona Technology GmbH, Germany.
Intona and other designated brands included herein are trademarks of Intona in Germany and other countries.
All other trademarks are the property of their respective owners.
Website: https://intona.eu

Contents
1 Introduction 4
1.1 Features.............................................. 4
1.2 Requirements........................................... 4
1.3 Restrictions............................................ 4
1.4 Firmware Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4.1 Firmware 1.09 (unreleased) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4.2 Firmware 1.08 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4.3 Firmware 1.06 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4.4 Firmware 1.00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5 Host Tool Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5.1 Host tool git master . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5.2 Host tool v1.4 (60a3f48, windows build 66) . . . . . . . . . . . . . . . . . . . . . . 6
1.5.3 Host tool v1.3 (cfbdb79, windows build 64) . . . . . . . . . . . . . . . . . . . . . . 7
1.5.4 Host tool v1.2 (ff97f53) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.5.5 Host tool v1.1 (686fe4f) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.5.6 Host tool v1 (f5eed9c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2 Hardware Setup 8
2.1 LEDMeaning ........................................... 8
2.1.1 PortLEDs......................................... 8
2.1.2 MainLED ......................................... 8
3 Software Installation 9
3.1 Linux................................................ 9
3.2 macOS .............................................. 9
3.3 Windows ............................................. 9
3.4 Verifying Device Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.5 Wireshark extcap Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.5.1 Linux,macOS....................................... 10
3.5.2 macOS (app bundle) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.5.3 Windows ......................................... 11
3.6 Firmware Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.6.1 Unix-like ......................................... 11
3.6.2 Windows ......................................... 12
4 Capturing 13
4.1 Wireshark extcap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.1 Capturing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.2 Wireshark extcap Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2 Directly Starting Wireshark from Host Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.3 Statistics ............................................. 14
4.4 Capturing to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.5 Selecting the Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.6 Configuring the Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5 Other Features 15
5.1 PoE Passthrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2 PTPTimestamps......................................... 15
5.3 Supported Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.4 Interactive Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.5 Scripting.............................................. 16
5.6 Supported Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.7 IPCInterface ........................................... 17
5.7.1 Windows ......................................... 17
2

Contents
5.7.2 UNIX (Linux/Mac) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.7.3 Protocol.......................................... 18
5.8 Identify Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.9 LatencyTester .......................................... 20
5.9.1 Introduction........................................ 20
5.9.2 Instructions........................................ 20
5.10 Packet Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.11BlockingPorts .......................................... 24
5.12 Packet Disruption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.13MDIOAccess........................................... 25
5.13.1 Raw MDIO access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.13.2 Changing PHY Ethernet Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.14 Device Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6 Known Problems 26
7 Further Readings 26
7.1 WhitePapers........................................... 26
7.1.1 Ethernet Debugger Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
7.2 Statements ............................................ 26
7.2.1 Letter of Volatility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3

1 Introduction
1 Introduction
The Intona Ethernet Debugger is a device to capture packets between two Gigabit Ethernet devices. It
provides two ethernet ports, and each port forwards all traffic to the other port, as well as to a PC con-
nected via USB. The intended purpose is low level debugging of anything above the ethernet physical
layer, mainly using Wireshark and similar protocol analyzers. It helps when developing your own proto-
cols layered on top of ethernet, developing your own MAC, or just for observing what is going on on your
network.
1.1 Features
This device can log complete ethernet packets as received by the PHY. There is no processing of captured
packets – preamble, SFD, and FCS are all left intact. Packets with incorrect CRC sums are not discarded.
Ethernet packets which violate the specification are captured as far it is possible. Some normally invisible
low level details are explicitly logged, such as interpacket gaps and CRC errors. Jumbo frames (ethernet
packets longer than 1500 bytes) are supported and fully captured up to 16KB size.
Capture output is directly streamed to the PC. There is no kernel device driver. The device is accessed
through a libusb userspace driver. You do not necessarily need elevated privileges. Installing the device
will not destabilize your system. In particular, the device is not exposed as network device. This has the
advantage that your OS will not mess with it. Neither will it attempt to drop or filter packets received
through it, nor will it attempt to send random packets to it (ARP etc.). The latter would show up in
Wireshark, and confuse your development efforts.
Capture can be directly started from Wireshark (if installed correctly). The userspace driver also provides
a command line interface, which can be used to access advanced feature. An IPC interface is provided
for use cases like scripting.
The debugger can block packets in one or both directions, corrupt packets, inject new packets. This is
interesting for development and security research. (For example, you can test resilience of your ethernet
connected device or software against random packet drops, test its behavior on flooding, or implement a
network stack fuzzer.)
There are many other features. See Other features section.
1.2 Requirements
The software works on Windows, Linux, and macOS. We provide an installer for Windows. Windows 10
64 bit is required, but Windows 7 may work as well. For macOS, a homebrew tap is provided1. For Linux,
source code and build instructions are provided2, which should work on any Linux distro.
USB 3.0 or later host and cable are recommended. USB 2.0 may work in low bandwidth scenarios. Us-
ing an USB hub, and/or connecting multiple USB devices to an USB hub/host may reduce the maximum
bandwidth at which capture is possible without capture overflows.
1.3 Restrictions
Ethernet is intercepted by putting two PHYs between the two ports. There is no direct connection between
the ethernet TX/RX wires of the ports. Each PHY negotiates the ethernet connection separately. No link
can be established without USB power.
1https://github.com/intona/homebrew-ethernet-debugger
2https://github.com/intona/ethernet-debugger#build-instructions
4

1 Introduction
Old firmware (before 1.06) requires the user to set the ethernet speed manually if the devices connected
to the debugger’s ports negotiated different ethernet standards (for example 100 MBit vs. 1 Gb).
The PC needs to be fast to capture at full speed. Capturing in real time with maximum ethernet bandwidth
directly to Wireshark or a slow hard disk may not be possible. (This is due to host performance problems
outside of our control.) Packet buffer overflows should be expected when operating near maximum band-
width. There is no hardware packet filter.
1.4 Firmware Changelog
The firmware version is reported in the bcdDevice field in the USB device descriptor, or can be determined
by using the ”hw_info” command in the host tool.
1.4.1 Firmware 1.09 (unreleased)
Updating to host tool v1.5 is recommended.
Bug xes
•Fix hardware FIFO overow problems with high bandwidth and very small packets (possibly
out-of-spec)
•Fix capture corruption problems in some rare low bandwidth capture scenarios
1.4.2 Firmware 1.08
Updating to host tool v1.3 is recommended.
Bug xes
• Fix occasional packet corruption with some links in 100 MBit mode (this affects both packet capture
and ethernet communication)
• Hopefully fix 10 MBit mode
• Improve speed settings handling (always enable auto negotiation and control advertisings instead)
• Work around a FX3 issue that made firmware updates under USB 2 very slow
Potential incompatibilities and problems
• The ”inject” command now works only if both links are connected and use the same speed mode
1.4.3 Firmware 1.06
Updating to host tool v1.2 is recommended.
Bug xes
• Fix device becoming unable to capture packets on FIFO overflows
Potential incompatibilities and problems
• This is compatible down to host software v1, but host software v1.2 is recommended; there may be
strange behavior with host software v1 in certain cases
• The device accesses some MDIO registers automatically now, instead of leaving the host software
in full control
New features
• Add autospeed mode (do not require user to manually adjust each PHY’s speed if they have negoti-
ated different speeds)
• The autospeed setting is persistently stored on the device
5

1 Introduction
• Improved packet timestamp accuracy
1.4.4 Firmware 1.00
• Initial release.
1.5 Host Tool Changelog
The host tool’s version can be determined with the ”hw_info” command, or simply running ”nose
--version”.
Note: you can also look at the public git repository’s commit log.
1.5.1 Host tool git master
Unreleased, but publicly available. (Also picked up by Homebrew formulae.)
May be referenced as host tool v1.5 in this document.
Potential incompatibilities and problems
•Improvements to packet parsing (including rmware v1.09 specics), which should not cause
any problems, but could
•Change ”Bytes captured” display in the capture stats, uses different rounding
Bug xes
•Skip possibly old data when starting capture
•Fix description of some hw_info elds
•Fix undened behavior in USB error handling path
New features
•Add --nopad, --bw-bytes, --bw-packets parameters to ”inject” command
•Add --update parameter to ”hw_info” command
•Add --capture-speed-test command line option
1.5.2 Host tool v1.4 (60a3f48, windows build 66)
Potential incompatibilities and problems
• Change auto-exit behavior (should be mostly the same for most users, but use with scripting might
be affected)
• Change --exit-on option in an incompatible way
Bug xes
• Fix sporadic hangs when nose exits (these could even hog the USB device and prevent restarting
capture)
• Handle unusual preamble lengths better (for example, do not cut off data bytes at the start of the
packet on short preamble)
New features
• Option to strip FCS (CRC field) from captured data (--strip-fcs)
6

1 Introduction
1.5.3 Host tool v1.3 (cfbdb79, windows build 64)
Bug xes
• Correct doubled injector packet count reported by hw_info command
• Work around problems with libreadline 8.1
• Fix ”inject” command (may need firmware 1.08 for larger packets)
• Adjust maximum packet size capture limits
New features
• Latency tester feature
• Tab completion (if built with readline; dysfunctional on Windows)
• New options: --cmd, --run, --exit-on, --exit-timeout
1.5.4 Host tool v1.2 (ff97f53)
Updating to firmware 1.06 is recommended.
Potential incompatibilities and problems
• Firmware update is now invoked differently
• Changes to inject and disrupt command parameters
Bug xes
• In Wireshark extcap mode, terminate properly if no packets were captured
New features
• Full support for firmware 1.06
• Slightly improved link status reporting
• Extend capabilities of inject and disrupt commands
• Change USB device name format and include device address (allows distinguishing multiple devices
connected to chained hubs)
• Accept device serial number as device name and report it via extcap to Wireshark
• Add quoting/escaping and named arguments to command parser
• Perform more parameter validation in command/option parser
• Unify PHY/port names to A/B/AB/none (a mix of conventions was used before)
1.5.5 Host tool v1.1 (686fe4f)
• Add ”speed” convenience command
• Improve capture stats log behavior
• Note that this used to be untagged in the public git repository
1.5.6 Host tool v1 (f5eed9c)
• Initial release
• Note that this used to be untagged in the public git repository
7

2 Hardware Setup
2 Hardware Setup
The ethernet debugger needs to be powered via USB to forward any packets. Without power, communica-
tion between the two ports is blocked. Make sure USB cable and host port are at least USB 3.0 compliant.
If you use USB hubs or USB isolators, make sure they all support USB 3.0. USB 2.0 will work, but will
provide degraded functionality, as USB 2.0 bandwidth is lower than that of Gigabit Ethernet.
Attach the ethernet cables to the ports. Make sure you are breathing regularly. As soon as both port LEDs
indicate a connection, and the negotiated ethernet speed matches between both ports, communication
is possible.
2.1 LED Meaning
2.1.1 Port LEDs
The LED in use indicates the ethernet speed mode. If packets are sent or received, the corresponding
LEDs will blink.
Speed LED L LED R
1000 MBit off on
100 MBit on on
10 MBit on off
no link off off
Note that it’s possible for one port to have a link, while the other port does not. They also can have
mismatched speed. In both cases, capture will not work.
2.1.2 Main LED
Normally, the main LED should be blue. It will blink if capturing is in progress. The following states exist:
LED state Meaning
Blue USB super speed connection is up
Green USB high speed connection is up (slow, but functional)
Cyan USB power only (will not work)
Blue blinking capturing at USB super speed is in progress
Green blinking capturing at USB high speed is in progress (will drop packets)
Blue/green blinking the blink_led command is being used (only for a short moment)
Red initial bootloader failed (probably flash problem)
Red blinking bootloader failed (probably flash problem)
Off low level bootloader/firmware crash, or no USB power
Red/yellow blinking fatal higher level firmware error
Red/blue or Red/green blinking firmware update failed; running factory firmware version
(The blue/green color indicates USB speed, see above.)
When you experience problems, it is useful to describe the LED state exactly in support requests, even if
the observed variant is not listed above.
8

3 Software Installation
3 Software Installation
The software consists of a host tool, called ”nose”. It performs the following roles:
• userspace driver for the device
• Wireshark integration via Wireshark extcap
• command line tool for explicit access
3.1 Linux
No binaries or packages are provided. You can build it from the public git repository. Binary builds or
packages for popular Linux distributions may be provided if there is enough demand.
• build the host tool from the git repository (see https://github.com/intona/ethernet-debugger#build-
instructions)
• create a symlink for Wireshark extcap (see Wireshark section for details)
You may need to install an udev rule to get access to the USB device as normal user:
sudo cp udev.rules /etc/udev/rules.d/50-intona-ethernet-debugger.rules
sudo udevadm trigger
3.2 macOS
No binaries are provided. Hence the software is provided as source code, you can automatically download
and build it using Homebrew.
brew install --HEAD intona/ethernet-debugger/nose
Homebrew is a 3rd party project for installing freely available software on macOS. See https://brew.sh/
for details and how to install Homebrew itself.
You need to setup Wireshark extcap manually. See below.
We decided to not provide binaries for macOS because it is quite impossible to deliver unified, stable
executables that will work on various releases of both software API and CPU types. Think of the platform
change to ARM. This is no issue when compiling from sources using Homebrew.
3.3 Windows
• make sure that Wireshark is installed before you proceed
• double-click the installer
• press next a lot of times
It does not matter whether the device is connected during installation. In fact, the installer does not try to
access the device at all.
You can reinstall any time. Updating Wireshark might remove the Ethernet Debugger Wireshark integra-
tion. Reinstalling the Ethernet Debugger will restore it.
9

3 Software Installation
3.4 Verifying Device Access
A simple way to verify whether the software works is by simply running the host tool. It is a command
line program. On Windows, double-clicking nose.exe will open a terminal window, while on Unix, you
need to open a terminal window manually, and then run nose in it.
If the installation succeeded, and the device is connected, you should see the following:
Device 2:3:7 opened.
PHY A: link=down speed=0MBit
PHY B: link=down speed=0MBit
Warning: no link.
The example above has the device on USB bus 2, port 3, device address 7.
If the device could not be found or accessed, the following is shown:
No devices found.
You can stop the host tool by closing the terminal or by entering the ”exit” command.
3.5 Wireshark extcap Setup
Wireshark is the recommended way to use the Ethernet Debugger. It is 3rd party software and not devel-
oped by Intona. Download and install it from Wireshark’s website: https://www.wireshark.org/download
.html
Normally, the Windows installation procedure installs our host tool as a Wireshark ”extcap”. In short,
”extcap” allows external programs (such as our host tool) to provide a capturing source. See the Wireshark
extcap section for details. If the host tool is not correctly installed as extcap source, you will not be able
to start capture from the Wireshark GUI (but other methods of capturing will still work.)
The host tool supports extcap directly via special command line parameters. It must be located in the
”extcap” sub directory within the Wireshark installation directory or the user’s Wireshark configuration
directory. The paths depend on the operating system and the Wireshark installation location.
You can confirm whether it’s installed correctly by opening the Wireshark about dialog, and switching to
the ”Plugins” tab. There should be an entry named ”nose”.
Old Wireshark versions
The non-global/user-specific extcap paths below require at least Wireshark 3.1.1. Older
releases support global paths only.
3.5.1 Linux, macOS
It is recommended to create a symlink to the host tool. The global path is something like /usr/lib/wireshark/extcap/
or /usr/lib/x86_64-linux-gnu/wireshark/extcap/. The exact path depends on the Linux distro. The user-
specific path is usually ~/.config/wireshark/extcap/.
The following should install it locally, assuming ”nose” is already installed:
mkdir -p ~/.config/wireshark/extcap/
ln -s `which nose` ~/.config/wireshark/extcap/nose
10

3 Software Installation
3.5.2 macOS (app bundle)
The following is useful if you want to install the extcap globally, or on older Wireshark versions, assuming
”nose” is already installed via Homebrew:
ln -s `which nose` /Applications/Wireshark.app/Contents/MacOS/extcap/nose
The /Applications/Wireshark/ part of the path can be different, depending on where exactly Wireshark
is installed. Check the Wireshark about dialog (”Folders” tab) if you are unsure.
You need to start Wireshark at least once before you run the above command. Otherwise,
macOS may show a security warning, and it won’t work.
3.5.3 Windows
Since Windows does not support symlinks properly, it is recommended to create a .bat file in the Wire-
shark extcap sub-directory. The installer creates a file named intona-ethernet-debugger.bat with the
following contents (assuming default paths and English locale):
"C:\Program Files\Intona\Ethernet Debugger\nose.exe" "%*"
This ”redirects” all invocations to the actual installation location.
The user-specific path is C:\Users\USERNAME\AppData\Roaming\Wireshark\extcap\. Replace USERNAME
with the actual username. You may need to create the last component of the path. The installer does not
try to use this.
Updating Wireshark tends to remove and recreate the Wireshark installation directory. This
will also remove the intona-ethernet-debugger.bat file created by the Ethernet Debug-
ger installer. You could run the installer again to fix this. Manually moving the .bat to the
Wireshark user-specific configuration path mentioned above avoids this.
3.6 Firmware Update
Firmware updates may be required to get new features and to apply bug fixes. Normally they are not
necessary. Applying such an update must be done explicitly. The update process rewrites the device’s
flash memory, and should not be interrupted. Make sure the device is connected via USB 3.0, as the
update will take a long time with USB 2.x. Firmware downloads are available here3.
3.6.1 Unix-like
Plug in the device, and ensure it’s using USB 3.0 (main LED is blue). Then run the following command on
the terminal:
nose --firmware-update Downloads/firmware.dat
Where Downloads/firmware.dat is the path to the firmware binary you downloaded.
If the firmware file is accepted, and the device is accessible, something like this will appear:
3https://www.intona.eu/products/ethernet-debugger#downloads
11

3 Software Installation
Firmware file: version 1.08
Select firmware update action:
Choice Address Serial Firmware version
-------------------------------------------------------
4 2:7:12 08900037 1.06
-------------------------------------------------------
a Update all devices with outdated firmware
b Force update all devices (dangerous)
c Do nothing and exit
-------------------------------------------------------
Enter your choice:
If you type 4 followed by the enter key, the device 08900037 will be updated. The tool will exit when
the update is finished or aborted. On success, the device restarts on its own, and runs the new firmware
immediately.
If update fails, the device will boot from a fallback factory image, and indicate the failure by flashing the
main LED red. You should retry the update, or if the tool fails again, contact support. If update is slow and
takes longer than at most 1 minute, make sure the device is connected via USB 3 instead of USB 2.
You can confirm successful update by comparing the device version number (bcdDevice or checking the
output of the hw_info command) with the version indicated by the update.
If the --device option is provided, the tool will update the given device without asking for confirmation.
--firmware-update-all will update all detected devices without asking for confirmation. In both cases
(at least with v1.2) the firmware is written only if it’s newer than the firmware on the device, unless --
firmware-update-force is provided.
Old host tool versions (before release v1.2) do not ask for a choice, but start the update with
the first device found without confirmation. It is recommended to download and install the
newest host tool before performing a firmware update.
3.6.2 Windows
The same instructions as with Unix apply. You can double-click ”firmware-update.bat” in Explorer in the
Ethernet Debugger installation folder to avoid constructing a command line. This will use the firmware
file that came with the installer (it’s in the same folder). The latest installer usually comes with the latest
release of the firmware. Installers for host tool v1.0 (build 53) do not have this yet; download a newer
version here4.
(The host tool never ”phones home”, and there is no automatic update over internet.)
4https://intona.eu/en/products/ethernet-debugger#downloads
12

4 Capturing
4 Capturing
The main purpose of the ethernet debugger is to capture packets. The following methods are available.
4.1 Wireshark extcap
If you open Wireshark, it should display any plugged in Intona Ethernet Debuggers as Ethernet Debugger
USB (08900037) in the list of capture interfaces. The 08900037 in the brackets is the serial number (as in
the USB device descriptor). (Some versions of Wireshark also show the device address in the format used
by the host tool.) Double click this entry, and Wireshark should start capturing. The Ethernet Debugger’s
main LED will start blinking.
There is no hotplug mechanism for Wireshark extcaps. If you connect or disconnect devices
while Wireshark is running, you may need to press F5 or restart Wireshark to update the
device list of Ethernet Debugger capture devices.
Note that if the bandwidth utilization is high, the internal FIFO may overrun, leading to lost packets. The
host tool adds a packet comment to the first packet after a run of dropped packets.
It may also happen that Wireshark freezes if the amount of data is too large, because the GUI requires
a large amount of resources to deal with packet input. (Capturing to disk via the ”nose” tool may help
reducing packet drop. You can open the capture file with Wireshark afterwards.)
Various error conditions may deadlock Wireshark and the host tool on capture start.
4.1.1 Capturing Options
Wireshark lets you set some Ethernet Debugger specific options before starting capture. Click on the
gear-like symbol left of the Ethernet Debugger interface in Wireshark’s Capture interface list.
4.1.2 Wireshark extcap Toolbar
The host tool provides a toolbar in Wireshark. This is implemented through the extcap mechanism. It is
slightly clunky due to Wireshark restrictions (all GUI code is provided by Wireshark, and not everything can
be realized). The toolbar can be shown by enabling it in the Wireshark ”View” menu, ”Interface Toolbars”
sub-menu.
4.2 Directly Starting Wireshark from Host Tool
You may use the --wireshark option of the host tool to start Wireshark and capturing in one go. It
attempts to find the installation path of Wireshark, sets up a named FIFO, and starts a new Wireshark
process.
Example
nose --wireshark
Lifetime of Wireshark process on Unix
Since host tool version v1.2, Wireshark is not terminated anymore if capturing ends or nose
is exited. Older versions always terminated it due to being in the same process session.
13

4 Capturing
4.3 Statistics
The host tool --capture-stats option can be used to enable regular statistic updates on the terminal.
The ”set capture-stats true” command can be used to do this at runtime. (You can enter this command on
the Wireshark extcap toolbar, for example.)
4.4 Capturing to a File
The host tool --fifo option can be used to capture either to a real file on disk, or a named FIFO. The
capture_start command is similar, and can be used to start capturing via the host tool command line or
IPC interface. The format of the output is PcapNG (see https://pcapng.github.io/pcapng/). You may use
the third party open source libpcap library to parse such files. If you use an actual FIFO, you can stream
in real time.
Note that if you capture to disk, overruns can happen due to waiting on disk I/O. The host tool tries to
avoid this by using decoupled memory buffers, but these may be slowly filled up, until a software overrun
happens.
Example
# Capturing to a file until Ctrl+C is hit, and log capture statistics to stdout.
nose --capture-stats --fifo target_file.pcapng
# Manually starting Wireshark.
# On terminal 1:
mkfifo /tmp/fifo
nose --fifo /tmp/fifo
# On terminal 2:
wireshark -k -i /tmp/fifo
4.5 Selecting the Device
If you have multiple Ethernet Debuggers, the --device option can be used to pick a specific device. Pass-
ing the special value help to this option lists all devices that were found.
Multi-Capture
Selecting multiple devices at once is not possible. However, if extcap is correctly installed,
you can select multiple capture devices in Wireshark. This will provide a merged view of
data coming from multiple devices and host tool instances.
4.6 Conguring the Buffer Size
The --capture-soft-buffer and --capture-usb-buffer can be used to fine-tune the sizes of the fixed
size buffers allocated on the host. Raising them may reduce buffer overruns on the host PC.
14

5 Other Features
5 Other Features
5.1 PoE Passthrough
Both ethernet ports are capable of handling Power over Ethernet (PoE) as specified in IEEE
802.3af, 802.3at and 802.3bt. Power is passed through in both directions without interception.
5.2 PTP Timestamps
The device provides high resolution timestamps for packets. This can help to debug PTP related issues,
or any other timing issues. These timestamps are in nanoseconds with 10 ns resolution.
Each PHY has its own FIFO, which may affect accuracy. In addition, device-internal CDC may affect the
accuracy. Internally, the timestamps are generated by a 100 MHz clock and are passed to the ethernet
PHY’s (RGMII) clock domain, which introduces jitter. The timestamps are relative to device start.
The host tool capture output adds a start offset to the timestamps to make them roughly line up with wall
clock times. However, this offset is not precise, and there is no time correction. The absolute time of a
packet event might be slightly different from real time. The longer the capture is running, the higher the
deviation will be.
IN3083WP has additional information.
5.3 Supported Command Line Options
You can list supported options as follows:
nose --help
Current list of options:
Name Description
--verbosity 0|1|2 Set verbosity log level: 0 silent, 1 normal/default, 2 verbose
messages
--version Print host software version and exit
--selftest Run internal self-test. (Requires a loop between the two ports.)
--selftest-serial Internal.
--wireshark Start wireshark and dump packets to it. Terminate once done.
--device name Open this device. (Pass ”help” to get a list. ”none” prevents
automatic opening of a device.)
--firmware-update file Perform a firmware update using this file.
--firmware-update-all Update firmware of all devices that have been found. (Since v1.2.)
--firmware-update-force Update firmware even for devices which have the current or newer
firmware version. (Since v1.2.)
--fifo file Start capture and write to the given file or fifo. (Overwrites the
target if it’s a file.)
--ipc-connect path Connect IPC to this socket/named pipe. Terminate on disconnect.
--ipc-server name Host IPC on this socket/named pipe.
--capture-soft-buffer num Capture soft buffer (in bytes, accepts kib/mib/gib suffix)
--capture-usb-buffer num Capture libusb buffer (in bytes, accepts kib/mib/gib suffix)
--capture-stats Show capture statistics every 1 seconds.
--extcap-* Various options for use by the Wireshark extcap mechanism.
15

5 Other Features
Name Description
--capture Used by Wireshark; ignored by host tool.
--strip-frames Strip preamble, SFD, and FCS from ethernet frames. (Changes
pcapng output to LINKTYPE_ETHERNET.)
--cmd commands Run commands on opening. (Must be a single string, separate
commands with ; ) (Since v1.3.)
--run commands Run commands after opening. (Syntax like --cmd.) (Since v1.3.)
--exit-on Control when exactly the tool should exit automatically. (Since v1.3.)
--exit-timeout Always exit after the given time of seconds has expired. (Since v1.3.)
--capture-speed-test Test how much USB bandwidth capture needs (discards capture
data). (Since v1.5.)
5.4 Interactive Command Line
The host tool has an interactive command line interface. When starting the host tool without commands,
it will wait for commands from the terminal. You can use the ”help” command to list available commands
and their parameters. Many advanced features (such as listed below) are accessible only through this
interface.
By default, the host tool will read from stdin and accept commands. It will terminate if stdin is closed or
returns EOF. If run on the terminal, it offers an interactive command line using libreadline. (If the host tool
was built without libreadline, or you can use the rlwrap53rd party tool to get comfortable line editing and
history:
rlwrap nose <arguments for nose>
5.5 Scripting
The host tool can be used for scripting. The --run and --exit-on options (available since host tool v1.3)
can be used to run individual host tool commands.
Example
nose --run 'inject A --file mypacket.dat' --exit-on always
(The --exit-on is needed to make the tool exit after running the command.)
For more complicated use cases, the IPC interface offers and out-of-process API. (See IPC Interface sec-
tion.)
5.6 Supported Commands
Name Description
blink_led Flash main LED
block_ports Block or unblock all packets
capture_start Start capturing to a file or FIFO
capture_stop Stop current capture
cfg_packet Send internal command to device
5https://github.com/hanslub42/rlwrap
16

5 Other Features
Name Description
device_close Close the current device
device_list List all Ethernet Debuggers connected to this PC
device_open Open a device
disrupt Setup packet disruption and port blocking
disrupt_stop Disable packet disruption and port blocking
exit Exit the host tool
help Show all commands
hw_info Show device information (including firmware version etc.)
inject Setup packet injector
inject_stop Disable packet injector
mdio_read Read a PHY’s MDIO register
mdio_write Write a PHY’s MDIO register
reset_device_settings Restore default settings on the currently opened Ethernet Debugger
set Set a command line parameter
set_device_phy_wait Configure PHY speed negotiation delay time
speed Configure PHY speed negotiation mode
latency_tester_sender Setup device as latency tester sender (Since v1.3)
latency_tester_receiver Setup device as latency tester receiver (Since v1.3)
Some commands are described in further detail in the following sections. The help command lists param-
eters accepted by each command.
5.7 IPC Interface
The command line interface is available via IPC (unix domain sockets on UNIX, named pipes on Windows).
This may be useful for scripting or creating GUI frontends. For example, you could inject or drop packets
under specific situations, or start/stop capturing at specific times
The IPC server created with --ipc-server is available as long as the host tool runs. The path, at which the
IPC communication channel is available, depends on the OS. (The tool prints the full path when it starts
the server.)
The --ipc-connect option makes the host tool initiate the IPC connection to the given path. This con-
nection behaves the same as a connection made to a server started with --ipc-server. This mode may
be more convenient with certain frameworks, for example when the framework makes it easy to start a
server.
5.7.1 Windows
The IPC communication channel is a local win32 named pipe (CreateNamedPipeA()). For example, ”nose
--ipc-server foo” will create the named pipe \\.\pipe\foo, which can be accessed by other programs
in read/write mode. (Starting with host tool v1.3 you can simply pass a full path.) For testing, a third party
program such as PuTTY can be used (enter the full named pipe path as a serial device; unfortunately,
configuring the terminal to act decently is hard: by default there is no local echo, and CTRL+j must be
used to send the required \n ASCII 10 line terminator).
With --ipc-connect, the argument is a full path, which will be passed to CreateFileA(). In theory it can
be anything, as long as access with FILE_FLAG_OVERLAPPED works.
17

5 Other Features
5.7.2 UNIX (Linux/Mac)
The IPC communication channel is a Unix domain socket located on /tmp. For example, ”nose --ipc-
server foo” will create the socket /tmp/too.socket. (If the filesystem entry already exists, it will be
deleted, even if it’s a normal file.) Since host tool v1.3, the argument can be a full path too (if /or \
appears in the argument, it’s considered a full path). For testing, the third party program so cat can be
used to interactively send commands:
socat /tmp/foo.socket -
--ipc-connect takes a full path. Both sockets are supported (connect() is used) and other types of files
(open() is used).
5.7.3 Protocol
You can send commands in text or JSON form (the help command lists available commands and shows
the basic syntax). The protocol uses 1 JSON object per line (in both directions of communication). A line
is terminated with \n (ASCII line feed, byte 10). It is fairly self-describing:
IPC example
{"command":"mdio_read", "phy":1,"address":1,"id":1} // client to host tool
{"id":1,"result":31049,"success":true} // host tool to client
The id field is an arbitrary integer chosen by the client, and can be used to associate requests with replies.
The C-style comments are for illustration, and not part of the protocol.
For example, on the shell and with socat, you could do the above by:
Terminal 1
$ nose --ipc-server test
Terminal 2
$ echo '{"command":"mdio_read","phy":1,"address":1,"id":1}' | socat - /tmp/test.socket > /tmp/output.txt
$ cat /tmp/output.txt
{"id":1,"result":31081,"success":true}
A proper client can send multiple commands to the same connection. Replies are always sent immediately,
though certain conditions like USB communication failing will block replies until a timeout. Replies are
always sent back in order (it cannot happen that the reply for the first request comes after the reply for
the second request). Events (such as log messages) can appear at any time, even between request/reply
messages.
Log messages (such as output when PHY links change their state) are wrapped into special JSON mes-
sages:
Log message example
{"type":"log","msg":"PHY 1: link=up speed=1000MBit\n"}
18

5 Other Features
5.8 Identify Function
The blink_led command will flash the device main LED blue/green for a moment. This is helpful to
determine which device is opened on a host tool instance if multiple Ethernet Debuggers are connected
to a PC.
19

5 Other Features
5.9 Latency Tester
5.9.1 Introduction
This feature (available since host tool v1.3) involves sending generated ethernet packets from one Ethernet
Debugger to a second one, and measuring the delay. This can be used to test the latency if a 3rd device,
using a setup like this:
Ethernet Debugger 1 is the sender, Ethernet Debugger 2 is the receiver. The sender generates packets
that get sent out of port A and B at the same time. DUT is expected to propagate the packet unchanged
to the receiver. The receiver measures the difference in arrival time between port A and B.
The Latency Tester feature takes care of generating/sending the packets and analyzing them on the re-
ceiver side. It writes the computed delay time to a text file. The packets use a (hopefully) unused EtherType
(0xBEEF). The feature as currently implemented can test at most Layer 2 devices (like ethernet switches).
Testing devices that operate on a higher layer (such as IP routers) are not supported, as that would require
implementing parts of ARP and IP (though it’s theoretically possible).
5.9.2 Instructions
Connect the devices as in the diagram above. On the PC, open two ”nose” instances, one for the sender,
one for the receiver. Use the device_list command to confirm whether the correct device is opened (change
it with the device_open command). Then run the latency_tester_sender command on the sender instance,
and latency_tester_receiver on the receiver instance. By default the sender starts sending continuously
with 1 packet per 1 ms, with a test sequence that lasts 10 seconds. The receiver ignores the packets until
a start packet is detected, and then logs the status every 10 packets (it logs the delay for only the 10th
packet, use file output to retrieve all data points).
Sender setup
20