Browse files

a bit more docs

  • Loading branch information...
1 parent f57da01 commit 9e7f658845cba249db4fd95348bdfbcc81ef89a5 @jcw committed Oct 6, 2012
Showing with 81 additions and 32 deletions.
  1. +16 −0 Ports.cpp
  2. +38 −6 Ports.h
  3. +1 −1 README.md
  4. +25 −24 RF12.h
  5. +1 −1 RF12sio.h
View
16 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) {
View
44 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
View
2 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].
View
49 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.
View
2 RF12sio.h
@@ -1,7 +1,7 @@
// 2009-05-07 <jc@wippler.nl> 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 {

0 comments on commit 9e7f658

Please sign in to comment.