Merge pull request #44 from EnviroDIY/develop

Develop

.gitignore

@@ -57,3 +57,5 @@ Temporary Items
 .gcc-flags.json
 lib/readme.txt
 platformio.ini
+
+examples/debug_print/

README.md

@@ -16,18 +16,24 @@ Learn more, below, about this library's:
 
 Try running our [Example sketches](https://github.com/EnviroDIY/Arduino-SDI-12/tree/master/examples) with your Arduino board and SDI-12 sensor.
 
-Dive into the details of how this library works by reading the documentation in our [Arduino-SDI-12 wiki](https://github.com/StroudCenter/Arduino-SDI-12/wiki).s
+Dive into the details of how this library works by reading the documentation in our [Arduino-SDI-12 wiki](https://github.com/StroudCenter/Arduino-SDI-12/wiki).  [Note:  this is currently somewhat out of date.  Sorry!]
 
 
 ## Origins and Inherited Limitations
 
-This library was developed from the [SoftwareSerial](https://github.com/arduino/Arduino/tree/master/hardware/arduino/avr/libraries/SoftwareSerial) library that is a built-in [standard Arduino library](https://www.arduino.cc/en/Reference/Libraries). As such, it also shares many of the [limitations of SoftwareSerial](https://www.arduino.cc/en/Reference/SoftwareSerial).
+This library was developed from the [SoftwareSerial](https://github.com/arduino/Arduino/tree/master/hardware/arduino/avr/libraries/SoftwareSerial) library that is a built-in [standard Arduino library](https://www.arduino.cc/en/Reference/Libraries). It was further modified to use a timer to improve read stability and decrease the amount of time universal interrupts are disabled using logic from [NeoSWSerial](https://github.com/SlashDevin/NeoSWSerial).
 
-A primary limitation is that all [pin-change interrupts](https://thewanderingengineer.com/2014/08/11/arduino-pin-change-interrupts/) are disabled during transmission, which can interfere with other processes and libraries that also use interrupts. This is particularly problematic for Arduino-SDI-12, because SDI-12 operates at a very slow baud rate (only 1200 baud). This translates to ~8.3 mS of "radio silence" from the processor for each character that goes in or out via SDI-12, which adds up to ~380-810ms per command! For that reason, avoid using the default "master" branch of this library to send and receive data via SDI-12 while also transmitting other serial data or while looking for other pin change interrupts. We have created [Variants and Branches](https://github.com/EnviroDIY/Arduino-SDI-12#variants-and-branches) of this library (read below) to overcome such limitations when used in combination with alternate variants of SoftwareSerial.
+The most obvious "limitation" is that this library will conflict with all other libraries that make use of pin change interrupts.  You will be unable to compile them together.  Some other libraries using pin change interrupts include [SoftwareSerial](https://github.com/arduino/Arduino/tree/master/hardware/arduino/avr/libraries/SoftwareSerial), [NeoSWSerial](https://github.com/SlashDevin/NeoSWSerial), [EnableInterrupt](https://github.com/GreyGnome/EnableInterrupt/), [PinChangeInt](https://playground.arduino.cc/Main/PinChangeInt), [Servo](https://www.arduino.cc/en/Reference/Servo), and quite a number of other libraries.  See the notes under [Variants and Branches](https://github.com/EnviroDIY/Arduino-SDI-12#variants-and-branches) below for advice in using this library in combination with such libraries.
+
+Another non-trivial, but hidden limitation is that _all_ interrupts are disabled during most of the transmission of each character, which can interfere with other processes. That includes other pin-change interrupts, clock/timer interrupts, external interrupts, and every other type of processor interrupt.  This is particularly problematic for Arduino-SDI-12, because SDI-12 operates at a very slow baud rate (only 1200 baud). This translates to ~8.3 mS of "radio silence" from the processor for each character that goes out via SDI-12, which adds up to ~380-810ms per command!  Interrupts are enabled for the majority of the time while the processor is listening for responses.
+
+For most AVR boards, this library will also conflict with the [tone](https://www.arduino.cc/reference/en/language/functions/advanced-io/tone/) function because of its utilization of timer 2.  There will be no obvious compile error, but because SDI-12 and the tone library may use different clock-prescaler functions, the results for both might be rather unexpected.  All 8MHz AVR boards will also have unresolvable prescaler conflicts with [NeoSWSerial](https://github.com/SlashDevin/NeoSWSerial).
 
 ## Compatibility Considerations
 
-This library has been tested with an Arduino Uno (AtMega328p), EnviroDIY Mayfly (AtMega1284p), Adafruit Feather 32u4 (AtMega32u4, identical to Arduino Leonardo), and an Adafruit Feather M0 (SAMD21G18, identical to Arduino Zero).  
+This library has been tested with an Arduino Uno (AtMega328p), EnviroDIY Mayfly (AtMega1284p), Adafruit Feather 32u4 (AtMega32u4, identical to Arduino Leonardo), and an Adafruit Feather M0 (SAMD21G18, identical to Arduino Zero).  It should also work on an Arduino Mega (AtMega2560), Gemma/AtTiny board, and most other AVR processors with running on the Arduino framework.
+
+The Arduino Due, Arduino 101, Teensy, and ESP8266/ESP32 boards are not supported at this time.  If you are interested in adding support for those boards, please send pull requests.
 
 Not all data pins are available for use with this Arduino-SDI-12 library. Pin availability depends on the micro-controller. These pins will work on those processors:
 
@@ -47,12 +53,12 @@ As we've described, the default "master" branch of this library will conflict wi
 EnviroDIY_SDI12 is the default master branch of this repository. It controls and monopolizes all pin change interrupt vectors, and can therefore have conflicts with any variant of SoftwareSerial and other libraries that use interrupts.
 
 #### EnviroDIY_SDI12_PCINT3
-EnviroDIY_SDI12_PCINT3 is in the Mayfly branch of this repository, and was historically was called "SDI12_mod".  It's been cropped to only control interrupt vector 3, or PCINT3 (D), which on the Mayfly (or Sodaq Mbili) corresponds to Pins D0-D7. 
-It is designed to be compatible with EnviroDIY_SoftwareSerial_PCINT12 library, which which has been modified to only control interupt vectors 1 & 2, which on the Mayfly corresponds to pins PCINT1 (B) = Pins D08-D15; PCINT2 (C) = Pins D16-D23. 
-Note that different AtMega1284p boards have a different mapping from the physical PIN numbers to the listed digital PIN numbers that are printed on the board. For more infomation, see the [Pin/Port Bestiary wiki page for the Enable Interrupt library](https://github.com/GreyGnome/EnableInterrupt/wiki/Usage#PIN__PORT_BESTIARY).
+EnviroDIY_SDI12_PCINT3 is in the Mayfly branch of this repository, and was historically was called "SDI12_mod".  It's been cropped to only control interrupt vector 3, or PCINT3 (D), which on the Mayfly (or Sodaq Mbili) corresponds to Pins D0-D7.
+It is designed to be compatible with [EnviroDIY_SoftwareSerial_PCINT12](https://github.com/EnviroDIY/SoftwareSerial_PCINT12) library (which controls interrupt vectors PCINT1 (B) & PCINT2 (C) / Mayfly pins D08-D15 & D16-D23) and [EnviroDIY PcInt PCINT0](https://github.com/EnviroDIY/PcInt_PCINT0) (which controls interrupt vectors PCINT0 (A) / Mayfly pins D24-D31/A0-A7).
+Note that different AtMega1284p boards have a different mapping from the physical PIN numbers to the listed digital PIN numbers that are printed on the board. One of the most helpful lists of pins and interrupts vectors is in the the [Pin/Port Bestiary wiki page for the Enable Interrupt library](https://github.com/GreyGnome/EnableInterrupt/wiki/Usage#PIN__PORT_BESTIARY).
 
 #### EnviroDIY_SDI12_ExtInts
-EnviroDIY_SDI12_ExtInts is the ExtInt branch of this repository. It doesn't control any of the interrupts, but instead relies on an external interrupt management library (like [EnableInterrupt](https://github.com/GreyGnome/EnableInterrupt)) to assign the SDI-12 receive data function to the right pin.  This is the least stable because there's some extra delay because the external library is involved.  It's also the easiest to get working in combination with any other pin change interrupt based library. It can be paired with the  EnviroDIY_SoftwareSerial_PCINT12 or the EnviroDIY_SoftwareSerial_ExtInts libraries.
+EnviroDIY_SDI12_ExtInts is the ExtInt branch of this repository. It doesn't control any of the interrupts, but instead relies on an external interrupt management library (like [EnableInterrupt](https://github.com/GreyGnome/EnableInterrupt)) to assign the SDI-12 receive data function to the right pin.  This is the least stable because there's some extra delay because the external library is involved, but the use of timers in the SDI-12 library greatly increases it's stability.  It's also the easiest to get working in combination with any other pin change interrupt based library. It can be paired with the [EnviroDIY_SoftwareSerial_ExtInts](https://github.com/EnviroDIY/SoftwareSerial_ExternalInts) libraries (which is, by the way, extremely unstable).
 
 If you would like to use a different pin change interrupt library, uncomment the line ```#define SDI12_EXTERNAL_PCINT``` in SDI12.h and recompile the library.  Then, in your own code call `SDI12::handleInterrupt()` as the interrupt for the SDI12 pin using the other interrupt library.  Example j shows doing this in GreyGnome's [EnableInterrupt](https://github.com/GreyGnome/EnableInterrupt) library.
 

examples/d_simple_logger/d_simple_logger.ino

@@ -61,7 +61,7 @@
 
 #include <SDI12.h>
 
-#define SERIAL_BAUD 57600  // The baud rate for the output serial port
+#define SERIAL_BAUD 115200  // The baud rate for the output serial port
 #define DATA_PIN 7         // The pin of the SDI-12 data bus
 #define POWER_PIN 22       // The sensor power pin (or -1 if not switching power)
 
@@ -279,8 +279,8 @@ void setup(){
   for(byte i = 0; i < 62; i++){
     if(isTaken(i)){
       found = true;
-      Serial.print("Found address:  ");
-      Serial.println(i);
+      Serial.print("First address found:  ");
+      Serial.println(decToChar(i));
       break;
     }
   }

examples/e_simple_parsing/e_simple_parsing.ino

@@ -71,7 +71,7 @@ Other notes:
 
 #include <SDI12.h>
 
-#define SERIAL_BAUD 57600  // The baud rate for the output serial port
+#define SERIAL_BAUD 115200  // The baud rate for the output serial port
 #define DATA_PIN 7         // The pin of the SDI-12 data bus
 #define POWER_PIN 22       // The sensor power pin (or -1 if not switching power)
 
@@ -330,8 +330,8 @@ void setup(){
   for(byte i = 0; i < 62; i++){
     if(isTaken(i)){
       found = true;
-      Serial.print("Found address:  ");
-      Serial.println(i);
+      Serial.print("First address found:  ");
+      Serial.println(decToChar(i));
       break;
     }
   }

examples/j_external_pcint_library/j_external_pcint_library.ino

@@ -244,8 +244,8 @@ void setup(){
   for(byte i = 0; i < 62; i++){
     if(isTaken(i)){
       found = true;
-      Serial.print("Found address:  ");
-      Serial.println(i);
+      Serial.print("First address found:  ");
+      Serial.println(decToChar(i));
       break;
     }
   }

library.json

@@ -1,6 +1,6 @@
 {
   "name": "Arduino-SDI-12",
-  "version": "1.1.2",
+  "version": "1.3.1",
   "keywords": "SDI-12, sdi12, communication, bus, sensor, Decagon",
   "description": "Arduino library for SDI-12 communications to a wide variety of environmental sensors.",
   "repository":

library.properties

@@ -1,5 +1,5 @@
 name=Arduino-SDI-12
-version=1.1.2
+version=1.3.1
 author=Kevin M. Smith <[email protected]>, Shannon Hicks <[email protected]>
 maintainer=Sara Damiano <[email protected]>
 sentence=Arduino library for SDI-12 communications to a wide variety of environmental sensors.