added usrp2 networking notes, tweaked style and build

3 files changed, 89 insertions, 7 deletions

diff --git a/host/docs/CMakeLists.txt b/host/docs/CMakeLists.txt
index e90f1e9a1..52376fe8c 100644
--- a/host/docs/CMakeLists.txt
+++ b/host/docs/CMakeLists.txt
@@ -31,16 +31,24 @@ MESSAGE(STATUS "Checking for rst2html (docutils)")
 FIND_PROGRAM(RST2HTML rst2html)
 IF(${RST2HTML} STREQUAL "RST2HTML-NOTFOUND")
     MESSAGE(STATUS "Checking for rst2html (docutils) - not found")
+    MESSAGE(STATUS "  Disabled generation of HTML manual.")
 ELSE(${RST2HTML} STREQUAL "RST2HTML-NOTFOUND")
     MESSAGE(STATUS "Checking for rst2html (docutils) - found")
+    MESSAGE(STATUS "  Enabled generation of HTML manual.")
+    SET(stylesheet ${CMAKE_CURRENT_SOURCE_DIR}/style.css)
+    SET(rst2html_options
+        --stylesheet=${stylesheet}
+        --no-toc-backlinks
+        --date
+        --time
+    )
     FOREACH(rstfile ${manual_sources})
         SET(rstfile ${CMAKE_CURRENT_SOURCE_DIR}/${rstfile})
         GET_FILENAME_COMPONENT(rstfile_we ${rstfile} NAME_WE)
         SET(htmlfile ${CMAKE_CURRENT_BINARY_DIR}/${rstfile_we}.html)
         ADD_CUSTOM_COMMAND(
-            OUTPUT ${htmlfile} DEPENDS ${rstfile} ${CMAKE_CURRENT_SOURCE_DIR}/style.css
-            COMMAND ${RST2HTML} ${rstfile} ${htmlfile}
-                --stylesheet=${CMAKE_CURRENT_SOURCE_DIR}/style.css --no-toc-backlinks
+            OUTPUT ${htmlfile} DEPENDS ${rstfile} ${stylesheet}
+            COMMAND ${RST2HTML} ${rstfile} ${htmlfile} ${rst2html_options}
             COMMENT "Generating ${htmlfile}"
         )
         LIST(APPEND manual_html_files ${htmlfile})
@@ -57,6 +65,7 @@ INSTALL(FILES ${manual_sources} DESTINATION ${PKG_DOC_DIR}/manual/rst)
 INCLUDE(FindDoxygen)
 
 IF(DOXYGEN_FOUND)
+    MESSAGE(STATUS "  Enabled generation of Doxygen documentation.")
     SET(CMAKE_CURRENT_BINARY_DIR_DOXYGEN ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
     CONFIGURE_FILE(
         ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
@@ -68,4 +77,6 @@ IF(DOXYGEN_FOUND)
     )
     ADD_CUSTOM_TARGET(doxygen_html ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN})
     INSTALL(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR_DOXYGEN} DESTINATION ${PKG_DOC_DIR})
+ELSE(DOXYGEN_FOUND)
+    MESSAGE(STATUS "  Disabled generation of Doxygen documentation.")
 ENDIF(DOXYGEN_FOUND)
diff --git a/host/docs/style.css b/host/docs/style.css
index a50dce04a..7bd84c9c7 100644
--- a/host/docs/style.css
+++ b/host/docs/style.css
@@ -4,7 +4,7 @@ font-size:10pt;
 color:black;
 background-color:#FEFEFE;
 width:90%;
-margin:0 auto;
+margin:0 auto 0 auto;
 }
 
 div.document div.contents{
@@ -45,7 +45,7 @@ background-color:inherit;
 
 div.document h2.subtitle, div.section h1{
 margin-top:50px;
-border-top:1px solid #333333;
+border-bottom:1px solid #333333;
 font-size:140%;
 text-align:center;
 padding:20px 0px 10px 0px;
@@ -56,13 +56,13 @@ background-color:inherit;
 div.section h2{
 font-size:110%;
 text-align:left;
-padding:15px 0px 5px 10px;
+padding:15px 0px 5px 0px;
 text-decoration:underline;
 color:#333333;
 background-color:inherit;
 }
 
-div.document pre{
+div.document pre.literal-block{
 border:1px inset #333333;
 padding:5px;
 margin:10px 5px 10px 5px;
@@ -94,3 +94,9 @@ text-align:center;
 color:inherit;
 background-color:#FCFCFC;
 }
+
+div.footer{
+margin:50px auto 30px auto;
+text-align:center;
+font-size:85%;
+}
diff --git a/host/docs/usrp2.rst b/host/docs/usrp2.rst
index 1de61b734..48ef60683 100644
--- a/host/docs/usrp2.rst
+++ b/host/docs/usrp2.rst
@@ -61,3 +61,68 @@ Load the firmware image:
 
     cd <uhd-repo-path>/firmware/microblaze directory
     sudo ./u2_flash_tool --dev=/dev/sd<XXX> -t s/w -w <path_to_firmware_image>
+
+------------------------------------------------------------------------
+Setup networking
+------------------------------------------------------------------------
+The USRP2 only supports gigabit ethernet, and
+will not work with a 10/100 Mbps interface.
+Because the USRP2 uses gigabit ethernet pause frames for flow control,
+you cannot use multiple USRP2s with a switch or a hub.
+It is recommended that each USRP2 be plugged directly into its own
+dedicated gigabit ethernet interface on the host computer.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Setup the host interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The USRP2 communicates at the IP/UDP layer over the gigabit ethernet.
+The default IP address of the USRP2 is **192.168.10.2**
+You will need to configure the host's ethernet interface with a static IP address to enable communication.
+An address of **192.168.10.1** is recommended.
+
+**Note:**
+When using the UHD, if an IP address for the USRP2 is not specified,
+the software will use UDP broadcast packets to locate the USRP2.
+On some systems, the firewall will block UDP broadcast packets.
+It is recommended that you change or disable your firewall settings. 
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Change the USRP2's IP address
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You may need to change the USRP2's IP address for several reasons:
+
+* to satisfy your particular network configuration
+* to use multiple USRP2s on the same host computer
+* to set a known IP address into USRP2 (in case you forgot)
+
+**Method 1:**
+To change the USRP2's IP address
+you must know the current address of the USRP2,
+and the network must be setup properly as described above.
+Run the following commands:
+::
+
+    cd <prefix>/share/uhd/utils
+    ./usrp_burner --addr=192.168.10.2 --new-ip=192.168.10.3
+
+**Method 2 (Linux Only):**
+This method assumes that you do not know the IP address of your USRP2.
+It uses raw ethernet packets to bypass the IP/UDP layer to communicate with the USRP2.
+Run the following commands:
+::
+
+    cd <prefix>/share/uhd/utils
+    ./usrp2 recovery.py --ifc=eth0 --new-ip=192.168.10.3
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Debugging networking problems
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**Monitor the USRP2:**
+You can read the serial port on the rear of the USRP2
+to get debug verbose from the embedded microcontroller.
+Use a standard USB to tty-level serial converter at 230400 baud.
+The microcontroller prints useful information about IP addresses,
+MAC addresses, control packets, and fast-path settings.
+
+**Monitor the host network traffic:**
+Use wireshark to monitor packets send to and received from the USRP2.