IEEE 802.15.4 sniffer
Overview
This sample turns a board with a built-in IEEE 802.15.4 radio into a packet sniffer. The
radio is driven directly through ieee802154_radio_api in raw mode, with no
network stack and no L2 above it, so every frame the hardware accepts is reported.
Each captured frame is printed on the console UART as a single line:
psdu: <hex> power: <rssi-dbm> lqi: <lqi> time: <us>
psduThe PSDU as lowercase hexadecimal, without separators and without an FCS. The radio drops frames whose checksum is wrong and overwrites the two checksum bytes with RSSI and LQI, so there is no checksum left to report.
CONFIG_IEEE802154_L2_PKT_INCL_FCS=nkeeps those two bytes off the wire.powerSignal strength in dBm, signed. An unavailable value is reported as
-32768(IEEE802154_MAC_RSSI_DBM_UNDEFINED) so that every line has the same shape.lqiLink quality indicator, 0 to 255.
timeMicroseconds since the device booted, as a 64-bit count. The host tool anchors it to UNIX time using the first frame it receives. It is the receive timestamp of the radio driver; for drivers that do not provide one, it is the time the frame reached the sample, which adds the driver’s receive latency.
The shell shares the same UART. Lines that do not match the pattern above, such as log messages and the shell prompt, are ignored by the host tool, so no second serial port is needed.
Requirements
Any board with a built-in IEEE 802.15.4 radio, that is, one whose devicetree gives a
zephyr,ieee802154 chosen node, and whose radio driver supports
CONFIG_IEEE802154_RAW_MODE. The radio is put into promiscuous mode when the
driver reports IEEE802154_HW_PROMISC; otherwise only frames the radio’s address filter
accepts are captured. The sample has been built and run on:
esp32c6_devkitc/esp32c6/hpcoreesp32h2_devkitmesp32c5_devkitc/esp32c5/hpcore
The host tool needs Wireshark 4.0 or later, Python 3.10 or later, and pySerial.
Building and running
west build -b esp32c6_devkitc/esp32c6/hpcore samples/net/ieee802154/sniffer
west flash
The console keeps the board’s own rate, normally 115200 baud, so a serial terminal and the
shell work as they do in any other sample. That rate is not enough for a busy channel: a
maximum-length frame takes about 26 ms to print at 115200 baud, which is slower than frames
arrive on a busy channel. The host tool therefore raises the console for the duration of a
capture and puts it back afterwards, which is what sniffer speed is for.
Shell commands
The capture starts at boot, on CONFIG_NET_CONFIG_IEEE802154_CHANNEL.
uart:~$ sniffer stop
stopped
uart:~$ sniffer channel 15
channel 15
uart:~$ sniffer start
started
psdu: 41881234567890abcdef power: -47 lqi: 103 time: 123456789
uart:~$ sniffer stats
enq=1 drop=0 tx_rec=1 tx_bytes=68 q_hwm=1 q_used=0/16
uart:~$ sniffer speed
speed 115200
The channel can only be changed while the radio is stopped. sniffer stats reports how
many frames were queued, how many were dropped because the queue or the UART could not keep
up, and the queue’s high-water mark. sniffer speed <baud> reconfigures the console:
everything after the reply comes out at the new rate, so a terminal has to be reopened there.
Capturing with Wireshark
samples/net/ieee802154/sniffer/scripts/ieee802154_sniffer.py is a Wireshark extcap plugin. It drives the shell, parses the capture lines and writes a pcap stream using the IEEE 802.15.4 TAP link type, which carries the channel, RSSI and LQI into Wireshark as per-packet metadata.
The plugin recomputes the two FCS bytes from the PSDU and appends them, so that the capture holds complete frames, and declares them through the TAP FCS Type field. The radio verified the checksum of every frame it reports before overwriting it with RSSI and LQI, so the regenerated value always matches the frame; it is not the checksum that arrived over the air.
Install it into Wireshark’s extcap directory, shown under :
$ mkdir -p <your_home_extcap_path>
$ cp samples/net/ieee802154/sniffer/scripts/ieee802154_sniffer.py <your_home_extcap_path>
$ chmod +x <your_home_extcap_path>/ieee802154_sniffer.py
Restart Wireshark, or use . The board appears in the interface list; the gear icon selects the channel, the two baud rates and the diagnostic log.
Note
The user running Wireshark needs read and write access to the serial port, for example
through the dialout group (uucp on some distributions).
Baud rate is the rate the console runs at when the capture starts, 115200 by
default. Capture baud rate is what the plugin raises it to for the capture, 921600
by default; the console is put back when the capture ends. Set it to 0 to leave the rate alone,
for a board whose console is already fast or one built without
CONFIG_UART_USE_RUNTIME_CONFIGURE.
The plugin also runs standalone, which is the quickest way to tell a firmware problem from a plugin problem:
$ ./samples/net/ieee802154/sniffer/scripts/ieee802154_sniffer.py --extcap-interfaces
$ ./samples/net/ieee802154/sniffer/scripts/ieee802154_sniffer.py --capture \
--extcap-interface /dev/ttyUSB0 \
--channel 15 --log-file sniffer.log --fifo capture.pcap
Add --metadata none to write bare frames without the TAP header, using the
IEEE802_15_4_WITHFCS link type, for checking that the frames themselves dissect.
Troubleshooting
An empty packet list means the plugin is not getting whole capture lines from the serial port:
Close any serial monitor on the same port before capturing. A monitor that is already attached keeps reading, the two readers then take turns on the incoming bytes, and every line the plugin sees is cut short while the monitor still looks healthy.
Check that the channel in the interface settings is the one the traffic is on. The plugin retunes the radio when the capture starts, so the channel the board booted with does not matter.
Check the baud rate. A capture that was killed outright leaves the console at the capture rate, and so does firmware built with a raised console. The plugin tries the other common rate on its own when the board does not answer, puts the rate back the next time a capture ends normally, and names the rate it settled on in the log, but setting the right one avoids the delay.
Fill in Diagnostic log in the interface settings, or pass
--log-file, and read the result. It holds the replies the board gave tosniffer speed,sniffer channel,sniffer startandsniffer stats, and the first lines that did not parse.enq=0in the stats line means the radio has not heard anything at all.
The shell commands are best effort, so a board that answers none of them is still captured from. The shell thread and the thread that prints the capture lines both run at the lowest application priority, so on a busy channel a command waits until the frame queue drains. Replies can also come out mixed into a capture line, which is why most commands are sent more than once. The log names the commands that went unanswered, and an unconfirmed channel means the radio kept the one it was last set to: set it from a terminal before starting the capture if the frames are not the ones expected.
Opening the port does not reset the board: the plugin leaves DTR and RTS deasserted, which keeps the auto-reset circuit of the devkits alone.