> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Network packets

> Record network traffic with Wireshark, inspect protocols and bytes in the Monitor's Packets tab, and ask Embedder to capture and analyze traffic.

Record traffic from a network interface and inspect it in the Monitor's **Packets** tab. You can also ask Embedder to start and stop a recording, read the packets, and follow a TCP or UDP conversation. Use it to check what a networked board sends: DHCP and DNS at boot, connections to a server, MQTT or HTTP payloads, and retransmissions or resets.

## Prepare

Embedder uses your installed Wireshark and TShark. Wireshark isn't bundled with Embedder.

1. Install [Wireshark](https://www.wireshark.org/download.html), including TShark.
2. Set up capture permissions for your operating system:
   * **Windows:** Install Npcap from the Wireshark installer. Embedder finds Wireshark under Program Files without a `PATH` entry.
   * **macOS:** Install Wireshark's ChmodBPF package. Embedder finds `Wireshark.app` in `/Applications` or `~/Applications`.
   * **Linux:** Install your distribution's Wireshark and TShark packages, and give `dumpcap` capture permissions.
3. For a custom install location, set `EMBEDDER_TSHARK_PATH` to the TShark executable. Restart Embedder after you change it.

If Wireshark or a capture permission is missing, the **Packets** tab shows the setup steps. For a missing permission, it also offers **Open Npcap download** on Windows, **Install ChmodBPF** on macOS, or **Copy setcap command** on Linux. On macOS, the button reads **Open capture privilege docs** when Embedder can't find the ChmodBPF installer. After you finish the steps, restart Embedder and select **Refresh interfaces**.

In VS Code, the first time the tab finds a setup problem, it also sends **Fix Packet Monitor setup** to your chat so Embedder can help you finish the setup.

Opening and analyzing saved captures needs TShark but doesn't need capture permissions.

## Record from the Packets tab

Run **Embedder: Open Embedder Monitor**, select **+**, then choose **Packets** under **Views**.

Embedder selects the interface that carries your computer's default route, and the tab shows **Start capture**. If it can't pick one, the tab shows **Set up packet capture** instead: choose an interface under **Choose the entry interface**. If the project already has recordings, the tab opens on a saved one.

A recording holds only the traffic that reaches the selected interface. On a switched network, traffic between the board and another device doesn't reach your computer unless you use port mirroring, monitor mode, or an extcap source.

1. Check the interface chip at the start of the toolbar. It must name the interface that carries the board's traffic. Select the chip to choose another one.
2. Optional: enter your board's IP address or hostname in **Target** to record only traffic to and from the board.
3. Select **Start capture**, then make the board generate traffic, for example by resetting it.
4. Select **Stop capture** to save the recording.

While recording, the packet table follows the newest packets and shows **Live**. The table is a preview that samples busy traffic; the saved recording is complete. Select **Pause follow** to hold the table still and look at a packet. Select **Resume follow** to jump back to the latest traffic. Recording continues while follow is paused.

Only one packet capture runs at a time. If you ask Embedder to capture while a recording you started from the tab is running, Embedder's capture takes over. Packet capture doesn't hold the board, so Embedder can flash or debug the target while traffic is recorded.

### Choose another interface

The interface chip lists connected Wi-Fi and Ethernet interfaces under **Recommended** and **Available hardware**. To show the rest, including loopback, disconnected adapters, and Wireshark extcap sources, choose **More interfaces** from the **⋯** (**More packet actions**) menu. Choose **Refresh interfaces** from the same menu after you plug in an adapter.

### Narrow the capture

Set these before you start:

* **Target** takes the board's IP address or hostname, and a port after a colon. Leave the port empty to record every port.
* **Find devices**, in the **More packet actions** menu, fills the **Target** list with the devices seen on the selected Wi-Fi or Ethernet interface. Choose one to make it the target.
* **Scan ports**, in the same menu, checks the target for open TCP ports and lists them in the port field. Choosing a found device, or pressing `Enter` in **Target**, also scans its ports. A scan connects to about a thousand TCP ports on the target, so scan only devices you're allowed to test.
* A capture filter limits what's recorded. Select **Capture settings**, the sliders button in the toolbar, and enter a Wireshark capture filter in **Filter**, such as `tcp port 443`. Embedder combines it with the target and port.

### Capture settings

**Capture settings** opens the **Settings** panel. Set it up before you start, because the panel can't be changed while recording.

| Section | Use |
| - | - |
| **Capture** | **Filter** takes the capture filter. To reuse one, name it in **Save as** and select **Save capture filter**, then load it later from **Saved**. **Profile** chooses where saved filters and coloring rules are kept: **Workspace** or **Global**. |
| **Display** | Saves the filter that's in the display filter box. See [Inspect a capture](#inspect-a-capture). |
| **Coloring** | Wireshark coloring rules kept with the profile, for when you open a capture in Wireshark. They don't color the Monitor's packet table. |
| **Extcap source** | Settings for the selected extcap source. Appears only for an extcap interface. Fill in the fields marked `*` before you start. |

The **Workspace** profile is saved in `.embedder/wireshark` in your project, in Wireshark's own filter and coloring file formats.

## Inspect a capture

Select the history icon (**Saved captures**) in the toolbar and choose a recording. The views across the top show the capture from different angles:

| View | Shows |
| - | - |
| **Overview** | Packets, bytes, duration, connections, and issues such as retransmissions, TCP resets, and unreachable hosts, above the timeline and the packet table. |
| **Timeline** | Traffic over time. |
| **Endpoints** | Each host with its protocols, packets sent and received, total traffic, and role, and the connections between hosts. |
| **Streams** | TCP and UDP conversations and their payloads. |
| **Packets** | The packet table with number, time, source, destination, protocol, length, and info. |

**Statistics** and **Compare** are in the **More packet actions** menu. **Statistics** shows traffic over time, protocols, conversations, and Wireshark's expert information. **Compare** shows the difference in each protocol's packets and bytes between two saved captures, so it needs at least two. Selecting it opens the **Settings** panel, where you choose the second capture in **Compare with**.

To narrow the packet table, enter a Wireshark display filter in the display filter box beside the views, such as `mqtt || dns`, and press `Enter` or select **Apply**. Display filters apply to saved captures. To keep a filter, open **Capture settings**, name it in **Save as** under **Display**, and select **Save display filter**. Use the **Saved** menu in the box to reapply it.

To search the loaded packets by text instead, use **Search loaded packets…** below the table. The table shows 500 packets at a time. Select **Show more packets** to load more.

### Protocol and hex details

Select a packet to open its details, headed **Packet #** and the packet number. They show the protocol layers with their decoded fields, such as Ethernet addresses, IP TTL, and TCP sequence numbers and flags. The bytes pane below shows the raw frame in hex. When a packet looks like a retransmission, reset, or error, the details show **Expert information** above the fields.

Full protocol details and bytes are available after you stop and save the recording.

### Streams

Select **Follow** in the packet details to open the packet's TCP or UDP conversation in **Streams**, or open **Streams** and choose one under **Connections**. Choose **Text** or **Hex** for the **Payload** format. Text works well for HTTP, JSON, and other readable protocols, and replaces the values of HTTP authorization and cookie headers with `[redacted]`. Hex shows binary protocols byte for byte.

Stop the recording before you decode stream payloads.

### Playback

Use the playback bar in the **Overview**, **Timeline**, or **Packets** view to replay a saved capture at its original timing. You can rewind, step back or forward 5 seconds, and play or pause. Set **Playback speed** from 0.25× to 4×. The views update to the traffic up to the current playback position.

## Where captures are saved

Embedder saves each recording as a `capture.pcapng` file in its own folder under `.embedder/captures` in your project. Recordings you start from the **Packets** tab and recordings Embedder starts for you are saved in the same place. Both appear under **Saved captures**, and Embedder can analyze either kind. Open a PCAPNG file in Wireshark when you need its full feature set.

## Ask Embedder to capture traffic

Embedder can list interfaces, start a recording, check its status, and stop it. It can also read, filter, and summarize saved captures, inspect a single frame, and follow a TCP or UDP stream. Packet capture counts as a hardware action, so Embedder asks for [approval](https://docs.embedder.com/core-concepts/approvals.md) before it uses it.

Name the interface, what to filter on, how long to record, and what you want to learn:

```text theme={"theme":"css-variables"}
List the capture interfaces, then record on the Ethernet adapter with the
filter "host 192.168.1.50" while I reset the board. Stop after 20 seconds and
tell me whether it got a DHCP lease and resolved the broker hostname.
```

```text theme={"theme":"css-variables"}
Open the latest packet capture and follow the MQTT TCP stream. Show the
CONNECT and SUBSCRIBE packets and whether the broker accepted them.
```

```text theme={"theme":"css-variables"}
Get statistics for the last capture filtered to tcp.analysis.flags. List any
retransmissions or resets and the frames where they happen.
```

### Analyze captures in a script

For a repeated check, ask Embedder to write a [hardware script](https://docs.embedder.com/debug-mode/hardware-scripts.md) that reads saved captures. Embedder prepares a capture for script analysis before it runs the script; this doesn't happen when a recording stops. If you run the script yourself and it reports that the capture needs analysis sidecars, ask Embedder to prepare that capture, then run the script again.

## Troubleshoot

| Symptom | Check |
| - | - |
| No interfaces listed | Wireshark and TShark are installed, or `EMBEDDER_TSHARK_PATH` points to TShark. Then select **Refresh interfaces**. |
| **Start capture** is unavailable | Finish the permission setup the tab shows, then choose a capture interface. Read the message under the toolbar: the target must be on the selected interface's subnet and can't be this computer's own address, and the port must be between 1 and 65535. |
| "A packet capture is already running." | Only one capture runs at a time. Stop the current recording, or wait for Embedder's capture to finish. |
| No packets while recording | You picked the interface that carries the board's traffic, and the target and filter match it. On a switched network, traffic between the board and another device doesn't reach your computer unless you use port mirroring, monitor mode, or an extcap source. |
| Stream payload is empty | Stop the recording first, and choose a TCP or UDP conversation with payload data. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.