More manual updates.

MANUAL.md

@@ -38,6 +38,34 @@ Configuration
 
 Default Configuration
 ---------------------
+By default the radio is configured to be interoperable with standard TinyOS
+radio stacks. It's configured with most optional features turned on. Feature
+parameters can be found in <code>cc2520.h</code> and are set by default as follows:
+
+```
+// Defaults for Radio Operation
+#define CC2520_DEF_CHANNEL 26
+#define CC2520_DEF_RFPOWER 0x32 // 0 dBm
+#define CC2520_DEF_PAN 0x22
+#define CC2520_DEF_SHORT_ADDR 0x01
+#define CC2520_DEF_EXT_ADDR 0x01
+
+// All these timing parameters are in microseconds.
+#define CC2520_DEF_ACK_TIMEOUT 2500 
+#define CC2520_DEF_MIN_BACKOFF 320
+#define CC2520_DEF_INIT_BACKOFF 4960
+#define CC2520_DEF_CONG_BACKOFF 2240
+#define CC2520_DEF_CSMA_ENABLED true
+
+// We go for around a 1% duty cycle of the radio
+// for LPL stuff. 
+#define CC2520_DEF_LPL_WAKEUP_INTERVAL 512000
+#define CC2520_DEF_LPL_LISTEN_WINDOW 5120
+#define CC2520_DEF_LPL_ENABLED true
+```
+
+These parameters are better explained in the relevant feature sections below
+and correspond to the members of the ioctl data structures.
 
 Character Driver Interface
 --------------------------
@@ -57,12 +85,28 @@ packet size it will overrun.
 other radio specific error codes.
   * **Our driver is not fully thread-safe.** Although you can certainly
 send and receive packets simultaneously (this is recommended), you may
-not send multiple packets from separate threads. Only a single packet
-may be sent or received at any time from all processes. 
+not send multiple packets simultaneously from separate threads. Only a 
+single packet may be sent or received at any time from all processes. 
   * Our driver does not implement nonblocking IO currently. The low
 data rates really don't make this something we need to do, although
 it might be supported in the future. 
 
+**<code>write()</code> Calls**
+Calling write with a data frame as specified below will return in most
+cases the length of the data written, as typical of Linux character
+drivers. It will never perform an incomplete write, but the maximum
+buffer size that is allowable is 128 bytes, 1 byte for the PHY length
+field, and 127 for the MAC datagram. 
+
+The write call will block until the entire transmission has been
+completed by the radio. This can be 10s of milliseconds depending
+on how you configure radio features such as LPL.
+
+When the write call returns the caller should examine the return
+value. If it is negative this indicates an error in transmission
+and should be handled appropriately. The error codes are listed
+below. 
+
 **Error Codes**
 
 The following error codes can be returned from calls to <code>write</code>:
@@ -74,6 +118,14 @@ be transmitted.
 send an ACK within the timeout period.
   * **CC2520_TX_FAILED** - A general error has occurred.
 
+**<code>read()</code> Calls**
+Calling read will block indefinitely until a packet arrives. When a packet
+does arrive it will write the packet to the specified buffer and return the
+length of the packet.
+
+Because receive is only valid when an appropriate packet has been received
+it has no error codes. Read should always be called with a 128 byte buffer.
+
 Frame Format
 ------------
 We use pseudo-802.15.4 frames for this radio that preserve some of the
@@ -100,7 +152,7 @@ packet reception.
 	</tr>
 	<tr>
 		<td>2</td>
-		<td>FCS</td>
+		<td>FCF</td>
 		<td>Frame control sequence, ACK bit will be checked.</td>
 	</tr>
 	<tr>
@@ -111,7 +163,7 @@ packet reception.
 	<tr>
 		<td>multiple</td>
 		<td>Address Info</td>
-		<td>Depending on the FCS bits, this will contain some variation of PAN-ID and short
+		<td>Depending on the FCF bits, this will contain some variation of PAN-ID and short
 			or extended addresses for the source and destination.</td>
 	</tr>
 	<tr>
@@ -141,7 +193,7 @@ from the packet itself.
 	</tr>
 	<tr>
 		<td>2</td>
-		<td>FCS</td>
+		<td>FCF</td>
 		<td>Frame control sequence, ACK bit will be checked.</td>
 	</tr>
 	<tr>
@@ -152,7 +204,7 @@ from the packet itself.
 	<tr>
 		<td>multiple</td>
 		<td>Address Info</td>
-		<td>Depending on the FCS bits, this will contain some variation of PAN-ID and short
+		<td>Depending on the FCF bits, this will contain some variation of PAN-ID and short
 			or extended addresses for the source and destination.</td>
 	</tr>
 	<tr>
@@ -169,6 +221,8 @@ from the packet itself.
 	</tr>
 </table>
 
+Please see the original MAC specification for more information on how to set the FCF
+fields for different addressing modes. 
 
 Carrier Sense Multi-Access/Collision Avoidance (CSMA/CA)
 --------------------------------------------------------
@@ -220,7 +274,7 @@ parameter is the timeout, in microseconds, that the driver will wait for
 other radios to send an acknowledgment. It defaults to 2.5ms. 
 
 Soft-ACK is always enabled, but acknowledgment is controlled on a per-packet
-basis. Check the 802.15.4 MAC frame control sequence (FCS) header for more
+basis. Check the 802.15.4 MAC frame control field (FCF) header for more
 information on how to request software acknowledgments on an individual packet.
 The driver will always acknowledge packets received requesting an acknowledgment.