Teensy Networking Tool

There are obviously proper tools for inspecting networking gear, but they are prohibitively expensive, especially considering our primary use casefiguring out what's on the other end of an unmarked cable without having to chase tone. Our current solution is to use Wireshark and watch for LLDP frames matching our equipment's OUI. This works great, since our gear reports hostnames, port IDs, management addresses, and even firmware version. Even better would be a pocket-sized standalone device capable of sniffing LLDP. That is exactly what we intend to build with this project.

LLDP frames are of ethertype 0x88cc. Their payload consists of three mandatory TLVs (type-length-value structures) and a variable number of optional TLVs. Each TLV has a 7-bit type field, a 9-bit length field, and a variable-length value field. TLV types are given in the below table. For this project, we are primarily interested in TLV types 4 and 5.

Text-based TLVs (like the system name and port description) are not null-terminated.

ssilverman/QNEthernet is a networking library specifically designed for the Teensy 4.1. Though most of the library is geared toward building client-server applications, it does include a class for directly reading and writing Ethernet frames (appropriately called EthernetFrame). This class is derived from the Arduino Stream class and functions similarly to the EthernetUDP class. Reception is invoked by calling parseFrame() to read the next frame and data() to return a pointer to the frame data. parseFrame() returns the byte length of the frame, or -1 if no frame is available.

In order to access raw frames, some build macros must be set¹⁾. These cannot be done using simple #define macros in the sketch.

The Teensy 4.1 is a highly capable microcontroller the size of a stick of gum. We selected it for this application for its integrated DP83825I Ethernet PHY.

We are currently undecided as to how or if we should implement OUI filtering. Perhaps the code could check for a config file on the microSD card in setup()? How should such a file be formatted for efficient parsing? How should we store the filter list internally²⁾?

As currently envisioned, there is no need for the device to have any kind of user inputs (buttons, encoders, etc.)³⁾. Its sole UI element is a 20×4 character LCD. We utilize each row as follows:

1. link state/error messages
2. source MAC
3. port description (TLV type 4)
4. system name (TLV type 5)

Because the display is so small, our main loop code won't write to it directly. Rather, we will maintain four arrays as line buffers and call a separate function to update the display every so often. This allows us to buffer lines wider than the screen and scroll them if necessary. We implement the line buffers as a single 2-dimensional array so we can update the lines in any order. As a convention, we end each line with a null byte; this keeps us from having to waste time padding lines.

check link status
if down:
  clear display
  write "no connection" to display line 1
else:
  write "connected" to display line 1
  wait for new frame
  if ethertype is 0x88cc:
    write source MAC to display
    write port description to display
    write system name to display

The power board we have selected for prototyping has a few useful pins.

The LBO pin cannot be directly connected to the Teensy! It is pulled high to Vin⁴⁾, so it must be level shifted. Unfortunately, a simple voltage divider solution⁵⁾ will not suffice. This pin isn't pulled to ground until the battery voltage reaches 3.2 V, but the divider's output will drop below the microcontroller's high voltage threshold when the battery is just below 3.5 V⁶⁾. Given that the battery's dead voltage is 3.0 V (and its nominal voltage is 3.7 V), this is not an ideal transition point. A proper level shifter will be required.

Initial development began on the Teensy but shortly thereafter moved to the Feather platform for use in the field, where the project has already more than demonstrated its worth. The core Feather boards are completely interchangeable, regardless of microcontroller; have identical pinouts and on-board Li-Po battery chargers; and are programmed in a dialect of Python (CircuitPython) by default⁷⁾. For UI and networking, we added the ethernet and OLED FeatherWings. Unlike the Teensy's QNEthernet library, however, the existing ethernet implementation in CircuitPython does not allow for low-level frame access. We thus needed to compose our own partial driver for the WizNet W5500 PHY chip.