document network capture

ArduPilot/ardupilot#30637

Author: tridge

common/source/docs/common-advanced-configuration.rst

@@ -55,6 +55,7 @@ tuning options for the vehicle.
     EKF Affinity & Lane Switching <common-ek3-affinity-lane-switching>
     EKF Sources and Selection <common-ekf-sources>
     Ethernet/Network Setup <common-network>
+    Network Capture <common-network-capture>
 [site wiki="copter,rover,sub"]
     Fence Failsafes  <common-geofencing-landing-page>
 [/site]

common/source/docs/common-network-capture.rst

@@ -0,0 +1,47 @@
+.. _common-network-capture:
+
+=====================
+Network Packet Capture
+=====================
+
+ArduPilot can capture on-target network traffic for troubleshooting Ethernet and PPP links. Captures are written in standard ``pcap`` format and can be opened in tools such as Wireshark or tcpdump.
+
+Overview
+--------
+
+When enabled, packets handled by the networking stack are written to capture files on the microSD card:
+
+- **Ethernet:** ``eth0.cap``
+- **PPP:** ``pppN.cap`` (e.g. ``ppp0.cap`` for the first PPP interface)
+
+Capture can be enabled or disabled at runtime by toggling a bit in the :ref:`NETWORK_OPTIONS <parameter-NETWORK_OPTIONS>` parameter — no reboot required.
+
+Build Requirement
+-----------------
+
+This feature must be included in your firmware build:
+
+1. Use the `ArduPilot Custom Build Server <https://custom.ardupilot.org/>`__.
+2. Under **Networking**, enable **NetworkCapture**.
+3. Download and flash the resulting firmware to your flight controller.
+
+Enabling Capture
+----------------
+
+1. Confirm your firmware was built with **NetworkCapture** enabled.
+2. Set bit **7** of the :ref:`NETWORK_OPTIONS<NETWORK_OPTIONS>` bitmask.
+3. Capture starts immediately; **no reboot is required**.
+4. To stop capture, **unset** bit 7.
+
+Files & Formats
+---------------
+
+- **Location:** Root of the flight controller’s microSD card (e.g. ``eth0.cap``, ``ppp0.cap``).
+- **Format:** ``pcap`` (compatible with Wireshark/tcpdump).
+
+Notes & Caveats
+---------------
+
+- Capturing can increase CPU and I/O load; enable only when debugging.
+- Ensure the microSD card has sufficient free space and is functioning reliably.
+- PPP captures are per-interface (``ppp0.cap``, ``ppp1.cap``, …).

common/source/docs/common-network.rst

@@ -166,3 +166,7 @@ Example Ethernet Connected Vehicle System
 
     Ethernet Connected ArduPilot Vehicle Example <common-ethernet-vehicle>
 
+Network Capture
+===============
+
+In ArduPilot 4.7.x and later you can enable :ref:`network capture <common-network-capture>`