a bit more docs

Author: jcw

Ports.cpp

@@ -22,6 +22,12 @@
 #define PWM_CHANGE  0x30    // an analog (pwm) value was changed on port 2..3
 #define ANA_MASK    0x0F    // an analog read was requested on port 1..4
 
+/// Shift a number of bites in to read them.
+/// @param bitOrder How to shift bits in or out: either LSBFIRST (0) or
+///                 MSBFIRST (1), where LSB stands for Least Significant
+///                 Bit and MSB for Most Significant Bit.
+/// @param count The number of bits to shift in or out. Must be in the
+/// range 1 .. 16, the default is 8.
 uint16_t Port::shiftRead(uint8_t bitOrder, uint8_t count) const {
     uint16_t value = 0, mask = bit(LSBFIRST ? 0 : count - 1);
     for (uint8_t i = 0; i < count; ++i) {
@@ -39,6 +45,16 @@ uint16_t Port::shiftRead(uint8_t bitOrder, uint8_t count) const {
     return value;
 }
 
+/// The shiftWrite() call is similar but more general than the shift() call
+/// in that it allows an adjustable number of bits to be sent, not just 8.
+/// @param bitOrder How to shift bits in or out: either LSBFIRST (0) or
+///                 MSBFIRST (1), where LSB stands for Least Significant
+///                 Bit and MSB for Most Significant Bit.
+/// @param value The value to shift out, with as many lower bits as needed.
+/// This argument is a byte for shift() and a word for the more general
+/// shiftWrite() function.
+/// @param count The number of bits to shift in or out. Must be in the
+/// range 1 .. 16, the default is 8.
 void Port::shiftWrite(uint8_t bitOrder, uint16_t value, uint8_t count) const {
     uint16_t mask = bit(LSBFIRST ? 0 : count - 1);
     for (uint8_t i = 0; i < count; ++i) {

Ports.h

@@ -25,6 +25,9 @@
 /// Interface for JeeNode Ports - see the wiki docs for
 /// [JeeNodes](http://jeelabs.net/projects/hardware/wiki/JeeNode) and
 /// [pinouts](http://jeelabs.net/projects/hardware/wiki/Pinouts).
+/// The Ports class is a thin wrapper around the Arduino's digitalRead(),
+/// digitalWrite(), analogRead(), etc. functions. It was designed to simplify
+/// the use of the four standard port headers on JeeNodes.
 class Port {
 protected:
 	/// The port number is a small integer mathing the hardware port used.
@@ -65,8 +68,9 @@ class Port {
 
     // DIO pin
 
-    /// Set the pin mode of a Port's D pin.
-    /// @param value Input or Output.
+    /// Set the pin mode of a Port's D pin. The mode() function member sets the
+    /// I/O data direction of the DIO pin associated with a specific port.
+    /// @param value INPUT or OUTPUT.
     inline void mode(uint8_t value) const
         { pinMode(digiPin(), value); }
     /// Reads the value of a Port's D pin.
@@ -81,14 +85,21 @@ class Port {
     inline void anaWrite(uint8_t val) const
         { analogWrite(digiPin(), val); }
     /// Applies the Arduino pulseIn() function on a Port's D pin.
+    /// Measure the length of a pulse in microseconds on the DIO (pulse) or
+    /// AIO (pulse2) line. The optional timeout value specifies how many
+    /// microseconds to wait for a pulse - of none is received, 0 is returned.
     /// See: http://arduino.cc/en/Reference/pulseIn for more details.
+    /// @param state Polarity of the pulse to wait for - HIGH (1) or LOW (0).
+    /// @param timeout Max number of microseconds to wait. \
+    ///                Default is 1,000,000, i.e. 1 second.
     inline uint32_t pulse(uint8_t state, uint32_t timeout =1000000L) const
         { return pulseIn(digiPin(), state, timeout); }
 
     // AIO pin
 
-    /// Set the pin mode of a Port's A pin.
-    /// @param value Input or Output.
+    /// Set the pin mode of a Port's A pin. The mode2() function member sets
+    /// the I/O data direction of the AIO pin associated with a specific port.
+    /// @param value INPUT or OUTPUT.
     inline void mode2(uint8_t value) const
         { pinMode(digiPin2(), value); }
     /// Reads an analog value from a Port's A pin.
@@ -110,8 +121,10 @@ class Port {
 
     // IRQ pin (INT1, shared across all ports)
 
-    /// Set the pin mode of the I pin on all Ports.
-    /// @param value Input or Output.
+    /// Set the pin mode of the I pin on all Ports. The mode3() function member
+    /// sets the I/O direction of the IRQ pin associated with a specific port.
+    /// Note that this is the same pin on all ports.
+    /// @param value INPUT or OUTPUT.
     static void mode3(uint8_t value)
         { pinMode(digiPin3(), value); }
     /// Reads the value of the I pin on all Ports.
@@ -130,6 +143,16 @@ class Port {
 
     /// Applies Arduino shiftOut() on a with data on the D and clock on A pin
     /// of the Port. See: http://arduino.cc/en/Tutorial/ShiftOut
+    /// This can be used to send out a pulse sequence of bits or to read such
+    /// a pulse sequence in. The AIO line is cycled while the value bits are
+    /// "shifted" and written out to (shift, shiftWrite) or read in from
+    /// (shiftRead) the DIO pin.
+    /// @param bitOrder How to shift bits in or out: either LSBFIRST (0) or
+    ///                 MSBFIRST (1), where LSB stands for Least Significant
+    ///                 Bit and MSB for Most Significant Bit.
+    /// @param value The value to shift out, with as many lower bits as needed.
+    /// This argument is a byte for shift() and a word for the more general
+    /// shiftWrite() function.
     inline void shift(uint8_t bitOrder, uint8_t value) const
         { shiftOut(digiPin(), digiPin2(), bitOrder, value); }
     uint16_t shiftRead(uint8_t bitOrder, uint8_t count =8) const;
@@ -189,6 +212,15 @@ class RemotePort : protected Port {
 };
 
 /// Can be used to drive a software (bit-banged) I2C bus via a Port interface.
+/// The PortI2C class is a special version of class Port implementing the I2C /
+/// Two-Wire Interface (TWI) protocol. Allows using any port as I2C bus master.
+/// When used for I2C, DIO is used as SDA and AIO as SCL.
+/// Unlike the Wire library for the Arduino, which is a more advanced solution
+/// for the hardware I2C lines of an ATmega, the PortI2C class is implemented
+/// entirely in software using "bit-banging". Another difference is that
+/// PortI2C does not use interrupts and will keep the microcontroller occupied
+/// while it is performing I/O transfers.
+/// @see DeviceI2C
 class PortI2C : public Port {
     uint8_t uswait;
 #if 0

README.md

@@ -2,7 +2,7 @@ JeeLib  {#index}
 ======
 
 JeeLib is an Arduino [IDE][1] library for the "ports" on [JeeNodes][2], the  
-%RF12 wireless driver library, timers, low-power code, and several interface  
+RF12.h wireless driver library, timers, low-power code, and several interface  
 classes. With examples for many sensor & interface boards made by [JeeLabs][3].
 
 The latest source code for this project is maintained on [GitHub][6].  

RF12.h

@@ -8,50 +8,51 @@
 
 #include <stdint.h>
 
-/// RF12 Protocol version.
+/// RFM12B Protocol version.
 /// Version 1 did not include the group code in the crc.
 /// Version 2 does include the group code in the crc.
 #define RF12_VERSION    2
 
-/// Shorthand for RF12 group byte in rf12_buf.
+/// Shorthand for RFM12B group byte in rf12_buf.
 #define rf12_grp        rf12_buf[0]
-/// Shorthand for RF12 header byte in rf12_buf.
+/// Shorthand for RFM12B header byte in rf12_buf.
 #define rf12_hdr        rf12_buf[1]
-/// Shorthand for RF12 length byte in rf12_buf.
+/// Shorthand for RFM12B length byte in rf12_buf.
 #define rf12_len        rf12_buf[2]
-/// Shorthand for first RF12 data byte in rf12_buf.
+/// Shorthand for first RFM12B data byte in rf12_buf.
 #define rf12_data       (rf12_buf + 3)
 
-/// RF12 CTL bit mask.
+/// RFM12B CTL bit mask.
 #define RF12_HDR_CTL    0x80
-/// RF12 DST bit mask.
+/// RFM12B DST bit mask.
 #define RF12_HDR_DST    0x40
-/// RF12 ACK bit mask.
+/// RFM12B ACK bit mask.
 #define RF12_HDR_ACK    0x20
-/// RF12 HDR bit mask.
+/// RFM12B HDR bit mask.
 #define RF12_HDR_MASK   0x1F
 
-/// RF12 Maximum message size in bytes.
+/// RFM12B Maximum message size in bytes.
 #define RF12_MAXDATA    66
 
-#define RF12_433MHZ     1
-#define RF12_868MHZ     2
-#define RF12_915MHZ     3
+#define RF12_433MHZ     1   ///< RFM12B 433 MHz frequency band.
+#define RF12_868MHZ     2   ///< RFM12B 868 MHz frequency band.
+#define RF12_915MHZ     3   ///< RFM12B 915 MHz frequency band.
 
 // EEPROM address range used by the rf12_config() code
-#define RF12_EEPROM_ADDR ((uint8_t*) 0x20)
-#define RF12_EEPROM_SIZE 32
-#define RF12_EEPROM_EKEY (RF12_EEPROM_ADDR + RF12_EEPROM_SIZE)
-#define RF12_EEPROM_ELEN 16
+#define RF12_EEPROM_ADDR ((uint8_t*) 0x20)  ///< Starting offset.
+#define RF12_EEPROM_SIZE 32                 ///< Number of bytes.
+#define RF12_EEPROM_EKEY (RF12_EEPROM_ADDR + RF12_EEPROM_SIZE) ///< EE start.
+#define RF12_EEPROM_ELEN 16                 ///< EE number of bytes.
 
-// shorthands to simplify sending out the proper ACK when requested
+/// Shorthand to simplify detecting a request for an ACK.
 #define RF12_WANTS_ACK ((rf12_hdr & RF12_HDR_ACK) && !(rf12_hdr & RF12_HDR_CTL))
+/// Shorthand to simplify sending out the proper ACK reply.
 #define RF12_ACK_REPLY (rf12_hdr & RF12_HDR_DST ? RF12_HDR_CTL : \
             RF12_HDR_CTL | RF12_HDR_DST | (rf12_hdr & RF12_HDR_MASK))
 
 // options for RF12_sleep()
-#define RF12_SLEEP 0
-#define RF12_WAKEUP -1
+#define RF12_SLEEP 0        ///< Enter sleep mode.
+#define RF12_WAKEUP -1      ///< Wake up from sleep mode.
 
 /// Running crc value, should be zero at end.
 extern volatile uint16_t rf12_crc;
@@ -64,13 +65,13 @@ extern long rf12_seq;
 /// Set to Dig10 by default for JeeNode. Can be Dig10, Dig9 or Dig8
 void rf12_set_cs(uint8_t pin);
 
-/// Only needed if you want to init the SPI bus before rf12_initialize does it.
+/// Only needed if you want to init the SPI bus before rf12_initialize() does.
 void rf12_spiInit(void);
 
 /// Call this once with the node ID, frequency band, and optional group.
 uint8_t rf12_initialize(uint8_t id, uint8_t band, uint8_t group=0xD4);
 
-/// Initialize the RF12 module from settings stored in EEPROM by "RF12demo"
+/// Initialize the RFM12B module from settings stored in EEPROM by "RF12demo"
 /// don't call rf12_initialize() if you init the hardware with rf12_config().
 /// @return the node ID as 1..31 value (1..26 correspond to nodes 'A'..'Z').
 uint8_t rf12_config(uint8_t show =1);
@@ -97,8 +98,8 @@ void rf12_sendWait(uint8_t mode);
 /// Use this only when the radio was initialized with a fake zero node ID.
 void rf12_onOff(uint8_t value);
 
-/// Power off the RF12, ms > 0 sets watchdog to wake up again after N * 32 ms.
-/// @note once off, calling this with -1 can be used to bring the RF12 back up.
+/// Power off the RFM12B, ms > 0 sets watchdog to wake up again after N * 32 ms.
+/// @note if off, calling this with -1 can be used to bring the RFM12B back up.
 void rf12_sleep(char n);
 
 /// @return true if the supply voltage is below 3.1V.

RF12sio.h

@@ -1,7 +1,7 @@
 // 2009-05-07 <[email protected]> http://opensource.org/licenses/mit-license.php
 
 /// @file
-/// Streaming I/O layer on top of RF12 driver
+/// Streaming I/O layer on top of the RF12.h driver.
 
 /// This class is NOT the %RF12 driver. It provides a way to construct packets.
 class RF12 {