docs: n3xx: Add troubleshooting section and comments on MTU

1 files changed, 58 insertions, 9 deletions

diff --git a/host/docs/usrp_n3xx.dox b/host/docs/usrp_n3xx.dox
index bea250071..ca8ae49bd 100644
--- a/host/docs/usrp_n3xx.dox
+++ b/host/docs/usrp_n3xx.dox
@@ -264,7 +264,9 @@ that will request a network address from your DHCP server (if available on your
 network).
 
 The SFP+ (sfp0, sfp1) ports are configured with static addresses 192.168.10.2/24
-and 192.168.20.2/24 respectively.
+and 192.168.20.2/24, respectively. Their default MTU value is 8000. These
+settings are independent of the image type (HG vs. XG), i.e., the defaults are
+the same for 1 GigE and 10 GigE (unlike the X310!).
 
 The configuration for the sfpX port is stored in /etc/systemd/networkd/sfpX.network.
 
@@ -293,7 +295,7 @@ The factory settings are as follows:
         Address=192.168.10.2/24
 
         [Link]
-        MTUBytes=9000
+        MTUBytes=8000
 
     sfp1 (static):
 
@@ -304,14 +306,20 @@ The factory settings are as follows:
         Address=192.168.20.2/24
 
         [Link]
-        MTUBytes=9000
+        MTUBytes=8000
 
-Note: Care needs to be taken when editing these files on the device, since
-vi / vim sometimes generates undo files (e.g. /etc/systemd/networkd/sfp0.network~),
-that systemd-networkd might accidentally pick up.
 
-Note: Temporarily setting the IP addresses via ifconfig etc will only change the
-value until the next reboot or reload of the FPGA image.
+Additional notes on networking:
+
+- Care needs to be taken when editing these files on the device, since
+  vi / vim sometimes generates undo files (e.g.
+  `/etc/systemd/networkd/sfp0.network~`), that systemd-networkd might
+  accidentally pick up.
+- Temporarily setting the IP addresses or MTU sizes via `ifconfig` or other
+  command line tools will only change the value until the next reboot or reload
+  of the FPGA image.
+- If the MTU of the device and host computers differ, streaming issues can
+  occur.
 
 \subsection n3xx_getting_started_security Security-related settings
 
@@ -419,6 +427,28 @@ See also uhd::usrp::subdev_spec_t.
 
 \subsection n3xx_usage_sensors The sensor API
 
+Like other USRPs, the N3x0 series have daughterboard and motherboard sensors.
+When using uhd::usrp::multi_usrp, the following API calls are relevant to
+interact with the sensor API:
+
+- uhd::usrp::multi_usrp::get_mboard_sensor_names()
+- uhd::usrp::multi_usrp::get_mboard_sensor()
+- uhd::usrp::multi_usrp::get_tx_sensor_names()
+- uhd::usrp::multi_usrp::get_rx_sensor_names()
+- uhd::usrp::multi_usrp::get_tx_sensor()
+- uhd::usrp::multi_usrp::get_rx_sensor()
+
+The following motherboard sensors are always available:
+
+- `ref_locked`: This will check that all the daughterboards have locked to the
+  external reference.
+- `temperature`: The temperature of the die itself
+- `gps_lock`: GPS lock
+- `gps_time`: GPS time in seconds sin ce the epch
+- `gps_tpv`: A TPV report from GPSd serialized as JSON
+- `gps_sky`: A SKY report from GPSd serialized as JSON
+
+
 \section n3xx_rasm Remote Management
 
 \subsection n3xx_rasm_mender Mender: Remote update capability
@@ -532,7 +562,7 @@ FPGA must be loaded. SFP0 will not be available for data transport in this mode.
 The White Rabbit image is provided as a default image. To obtain the default
 images, simply run:
 
-    $ uhd_images_downloader
+    $ uhd_images_downloader -t n3xx -t fpga
 
 Then, you can install the WX (or WA) image using `uhd_image_loader`:
 
@@ -547,6 +577,25 @@ auto usrp = uhd::usrp::multi_usrp::make("type=n3xx,clock_source=sfp0,time_source
 For more information, refer to the [White Rabbit Homepage](https://www.ohwr.org/projects/white-rabbit),
 or the [Ettus Research Knowledge Base](https://kb.ettus.com/Using_Ethernet-Based_Synchronization_on_the_USRP%E2%84%A2_N3xx_Devices).
 
+\section n3xx_troubleshooting Troubleshooting
+
+\subsection n3xx_troubleshooting_seqerrs Errors while streaming
+
+If you are getting sequence or other errors while streaming, make sure the MTU
+settings of the network devices match up. UHD will try and do an automatic MTU
+discovery, but there are cases when the automatic MTU discovery will yield
+incorrect values. Often, the host computer MTU is set smaller than the device
+MTU, but the MTU discovery will detect a larger MTU than the host computer MTU
+in this error case.
+
+The default MTU for the N3x0 series is 8000. The simplest solution is often to
+set the host computer MTU to 8000 as well:
+
+    $ [sudo] ifconfig eth0 mtu 8000 # Replace eth0 with the device you're using
+
+Of course, you can also reduce the MTU on the device to match your host
+computer, see Section \ref n3xx_getting_started_connectivity.
+
 \section n3xx_theory_of_ops Theory of Operation
 
 The N3xx-series are devices based on the MPM architecture (see