prod/doc/: cleanup and clarifications after proofreading

prod/doc/analysis.hmac

@@ -106,7 +106,8 @@ components as shown in this table:
 </TABLE>
 <P>
 Ground can be accessed at the cover of the crystal.
-Note that the fiducials are not connected to ground.
+Note that the fiducials, while looking like test points,
+are not connected to anything.
 <P>
 This image shows the location of the measurement points:
 <P>
@@ -131,7 +132,7 @@ components as shown in this table:
 <P>
 Ground can be accessed at the cover of the crystal, at the shield of the
 USB connector, or at the test point P11.
-Note that the fiducials are not connected to ground.
+Note that the fiducials are not connected to anything.
 <P>
 This image shows the location of the measurement points:
 <P>
@@ -144,9 +145,15 @@ This image shows the location of the measurement points:
 <SECTION ref="clock" title="Clock frequency">
 
 The precision of the crystal oscillator is crucial for
-operation. Anomalies are easy to detect with even a low-cost oscilloscope
-and pinpoint specific problems and help to select further analysis steps.
-<P>
+operation. Anomalies are easy to detect with even a low-cost oscilloscope.
+This can pinpoint specific problems and help to select further analysis steps.
+
+
+<!-- ---------------------------------------------------------------------- -->
+
+
+<SUBSECTION title="Oscillator tolerances">
+
 The crystal used in <B>atben</B> and <B>atusb</B> has a nominal tolerance
 of +/&minus; 15 ppm at 22-28 C. Low-cost oscilloscopes typically have a timing
 accuracy of
@@ -154,8 +161,12 @@ accuracy of
 measuring the clock output with such an instrument. Full-speed USB only
 requires an accuracy of +/&minus; 2500 ppm.
 We can therefore consider all results within a range of +/&minus; 1000 ppm as
-sufficient, and perform more precise measurements by other means. This
+sufficient for an initial assessment, and perform more precise measurements
+by other means. This
 applies to <B>atben</B> as well as to <B>atusb</B>.
+<P>
+IEEE 802.15.4 requires the transceiver frequency to be accurate
+within +/&minus; 40 ppm.
 
 
 <!-- ---------------------------------------------------------------------- -->
@@ -197,7 +208,7 @@ the right:
 
 The transceiver provides the clock for the microcontroller in <B>atusb</B>.
 A clock signal is therefore always available. Immediately after reset,
-the transceiver generates a 1 MHz clock. When the microcontrolled comes out
+the transceiver generates a 1 MHz clock. When the microcontroller comes out
 of reset, it raises the transceiver's clock output to 8 MHz and then
 enables USB.
 <P>
@@ -222,7 +233,7 @@ filter.
 <TR><TD>0.999-1.001 MHz, ~3.3 Vpp<TD>Check presence of firmware; check for
   shorts on SPI signals; check connectivity of SPI signals
 <TR><TD>7.992-8.008 MHz, ~3.3 Vpp<TD>Perform precision measurement with
-  atrf-xtal
+  atrf-xtal (@@@)
 <TR><TD>Other<TD>Check voltages; check for contamination around crystal
 </TABLE>
 <P>

prod/doc/flash.hmac

@@ -56,7 +56,7 @@ To flash the boot loader,
     <A href="atusb-programming.jpg"><IMG
       src="atusb-programming.jpg" width="250"></A>
     <P>
-  <LI>finally, run
+  <LI>finally, <SAMP>cd</SAMP> to <SAMP>ben-wpan/prod/</SAMP> and run
     <PRE>
     make flash
     </PRE>

prod/doc/index.hmac

@@ -32,8 +32,8 @@ actual testing.
 The testing serves two purposes:
 <OL>
   <LI>Ascertain the correctness of the preceding production steps, and
-  <LI>identify suffering from random production flaws and either discard
-    them or prepare them for repair.
+  <LI>identify boards suffering from random production flaws and either
+    discard them or prepare them for repair.
 </OL>
 The results of testing and fault analysis also provide feedback for the
 SMT process and steps preceding it.
@@ -43,7 +43,7 @@ The following diagram illustrates the workflow:
 <IMG src="flow.png">
 <P>
 Only <B>atusb</B> boards contain firmware and need flashing (which is
-a two-step process, see below). The functional tests and further fault
+a two-step process, see below). The functional tests and fault
 analysis are largely the same for <B>atben</B> and <B>atusb</B>.
 <P>
 Devices accepted for further use can then be packaged for shipping.
@@ -69,13 +69,15 @@ Defective devices can be discarded or retained for a deeper analysis.
     three roles, with the board in its 8:10 card slot changed as
     the role requires.
   <DT><B><I>PC</I></B></DT>
-  <DD>a device capable of connecting to a Ben via USB, and of hosting an
+  <DD>a device running Linux. Capable of connecting to a Ben via USB, and
+    of hosting an
     <B>atusb</B> board. In the production process, a PC can perform three
     different roles:
     <OL>
       <LI> Host an <B>atusb</B> board acting as DUT
       <LI> Host an <B>atusb</B> board acting as reference
-      <LI> Control a Ben via USB (for convenience)
+      <LI> Control a Ben via USB (for convenience and to coordinate tests
+        involving a sender and a receiver)
     </OL>
     In this document, we assume that a single PC is used in all
     three roles, with one USB host port permanently connecting to the

prod/doc/setup.hmac

@@ -37,7 +37,7 @@ and configuration process.
 
 <SECTION ref="pcsw" title="PC software installation">
 
-For a DUT and reference device role, the ben-wpan utilities
+For a DUT and reference device role, the ben-wpan tools
 and the test scripts have to be installed on the PC. For flashing the
 <B>atusb</B> application
 firmware, also dfu-util and the firmware binary are required.
@@ -131,8 +131,8 @@ Instructions for building the binary from sources are
 <SUBSECTION title="Register Ben host name">
 
 To simplify accessing the Ben via TCP/IP, its IP address should be
-registered in the hosts file on the PC. If the Ben is running OpenWrt,
-use the following command:
+registered in the <SAMP>/etc/hosts</SAMP> file on the PC. If the Ben is
+running OpenWrt, use the following command:
 <PRE>
 echo 192.168.254.101 ben >>/etc/hosts
 </PRE>
@@ -235,7 +235,7 @@ Finally, upload the tools to the Ben and install them under
 <SAMP>/usr/bin/</SAMP> with
 
 <PRE>
-make HOST=ben install
+make HOST=ben upload
 </PRE>
 
 Where <SAMP>ben</SAMP> is the host name or IP address assigned to the Ben.
@@ -248,7 +248,7 @@ Where <SAMP>ben</SAMP> is the host name or IP address assigned to the Ben.
 
 The <B>atusb</B> boot loader is flashed using avrdude. A pre-compiled
 static binary (suitable for OpenWrt and Jlime) can be installed by running
-the following two command on the Ben:
+the following two commands on the Ben:
 
 <PRE>
 wget http://downloads.qi-hardware.com/people/werner/wpan/bindist/avrdude-5.10-de72af351f661b538add81cbc9965278a2f8c40c.tar.gz
@@ -282,8 +282,8 @@ Instructions for building the binary from sources are
 
 <SECTION ref="bensys" title="Ben system setup">
 
-The configuration setting described in this section are lost on each
-reset or reboot and either need to be entered again. Alternatively,
+The configuration settings described in this section are lost on each
+reset or reboot and need to be entered again. Alternatively,
 a setup script running at boot time can be written.
 
 
@@ -323,6 +323,10 @@ the place of the MMC driver. To disable it, run
 <PRE>
 echo spi2.0 >/sys/bus/spi/drivers/at86rf230/unbind
 </PRE>
+Note that the above command only has the desired effect if used
+before running any of the user-space tools. If the kernel driver and
+the user-space tools have already clashed over access to the board, the
+driver will not unbind and a reboot is needed.
 
 
 <!-- ---------------------------------------------------------------------- -->
@@ -354,7 +358,8 @@ in the actual test environment.
 
 Insert a known to be good <B>atben</B> board and run the following
 command directly on the Ben to record the reference value for the
-clock count with an accuracy of about +/&minus;20 ppm:
+clock count with an accuracy of roughly +/&minus;20 ppm:
+
 <PRE>
 atrf-xtal 1000 >ben.xtal
 </PRE>
@@ -372,7 +377,7 @@ Ben, and if a stable temperature is maintained.
 
 <SUBSECTION title="Signal strength">
 
-The signal strength of a DUT is assesses by comparing it with
+The signal strength of a DUT is assessed by comparing it with
 measurements previously obtained in the same setup, with a known to
 be good device taking the role of the DUT. It is therefore necessary
 to establish a reference profile each time the test environment changes,
@@ -391,8 +396,9 @@ make spectrum
 </PRE>
 Then place the devices appropriately and press <B>D</B> in the measurement
 window to use the displayed spectrum as the reference. Multiple spectra
-can be merged into the reference, e.g., if environmental conditions cause
-significant variations. Spectra included in the reference are shown in blue.
+can be merged into the reference, e.g., if unavoidable environmental
+variations cause
+significant changes. Spectra included in the reference are shown in blue.
 <P>
 After a obtaining the reference spectrum, press <B>Q</B> to exit. The
 Makefile will then record the signal strength limits for an <B>atben</B>

prod/doc/test.hmac

@@ -29,8 +29,10 @@ the PC, insert the <B>atben</B> board into the Ben, and place both devices
 at the same location and with the same orientation used when acquiring the
 signal strength profile.
 <P>
-The two devices should be about 1 m apart, with as few metal or watery
-objects between or near them as possible. Location and orientation should
+The two devices should be about 1 m apart. Their vicinity should be free
+from obstructions and items that can reflect or absorb RF signals. Such
+items include metal chairs and human bodies.
+Location and orientation should
 be easily reproducible, e.g., by marking the device's edges on the table
 with tape. Other transmitters in the 2.4 GHz band will interfere with
 measurements and should be kept as far away and as inactive as possible.
@@ -56,7 +58,8 @@ DUT and reference device roles are reversed.
 
 <SECTION ref="procedure" title="Test procedure">
 
-The test process is started with
+The test process is started from the directory <SAMP>ben-wpan/prod/</SAMP>
+with
 <PRE>
 make ben
 </PRE>
@@ -162,8 +165,8 @@ frequency-dependent anomalies.
 <P>
 This test depends on numerous external factors, like the exact position
 and orientation of the two devices with respect to each other, and the
-presence of any items that can reflect or absorb RF signals. Such items
-include metal chairs and human bodies. Because of the test's sensitivity
+presence of obstacles and conductive items (metal, people, etc.).
+Because of the test's sensitivity
 to environmental factors, the operator needs to decide when the result
 represents a valid measurement and then confirm the result shown.
 <P>