Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
a bit more docs
  • Loading branch information
jcw committed Oct 6, 2012
1 parent f57da01 commit 9e7f658
Show file tree
Hide file tree
Showing 5 changed files with 81 additions and 32 deletions.
16 changes: 16 additions & 0 deletions Ports.cpp
Expand Up @@ -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) {
Expand All @@ -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) {
Expand Down
44 changes: 38 additions & 6 deletions Ports.h
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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;
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion README.md
Expand Up @@ -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].
Expand Down
49 changes: 25 additions & 24 deletions RF12.h
Expand Up @@ -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;
Expand All @@ -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);
Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion 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 {
Expand Down

0 comments on commit 9e7f658

Please sign in to comment.