SDI-12 for Arduino

Introduction

This is an Arduino library for SDI-12 communication with a wide variety of environmental sensors. It provides a general software solution, without requiring any additional hardware, to implement the SDI-12 communication protocol between an Arduino-based data logger and SDI-12-enabled sensors.

SDI-12 is an asynchronous, ASCII, serial communications protocol that was developed for intelligent sensory instruments that typically monitor environmental data. Advantages of SDI-12 include the ability to use a single available data channel for many sensors.

This work is motivated by the EnviroDIY community vision to create an open source hardware and software stack to deliver near real time environmental data from wireless sensor networks, such as the Arduino-compatible EnviroDIY™ Mayfly Data Logger.

Getting Started

Learn more, below, about this library's:

• Origins and Inherited Limitations;
• Compatibility Considerations;
• Variants and Branches we created to overcome some limitations.

Try running our Example sketches with your Arduino board and SDI-12 sensor.

Full details on the library functionality can be found on github pages: https://envirodiy.github.io/Arduino-SDI-12/

Origins and Inherited Limitations

This library was developed from the SoftwareSerial library that is a built-in standard Arduino library. 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.

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, NeoSWSerial, EnableInterrupt, PinChangeInt, Servo, and quite a number of other libraries. See the notes under 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 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 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. The pre-scaler values needed for the SDI-12 functionality are set in the begin() function and reset to their original values in the end() function.

Compatibility Considerations

This library has been tested with an Arduino Uno (AtMega328p), EnviroDIY Mayfly (AtMega1284p), Adafruit Feather 32u4 (AtMega32u4, identical to Arduino Leonardo), an Adafruit Feather M0 (SAMD21G18, identical to Arduino Zero), the ESP8266, and the ESP32. It should also work on an Arduino Mega (AtMega2560), Gemma/AtTiny board, and most other AVR processors running on the Arduino framework.

The Arduino Due, Arduino 101, and Teensy boards are not supported at this time. If you are interested in adding support for those boards, please send pull requests.

Due to the use of pin change interrupts, not all data pins are available for use with this SDI-12 library. Pin availability depends on the micro-controller. These pins will work on those processors:

This library requires the use of pin change interrupts (PCINT).

Not all Arduino boards have the same pin capabilities. The known compatibile pins for common variants are shown below:

AtMega328p / Arduino Uno:

• Any pin

AtMega1284p / EnviroDIY Mayfly

• Any pin

ATmega2560 / Arduino Mega or Mega 2560:

• 0, 11, 12, 13, 14, 15, 50, 51, 52, 53, A8 (62), A9 (63), A10 (64), A11 (65), A12 (66), A13 (67), A14 (68), A15 (69)

AtMega32u4 / Arduino Leonardo or Adafruit Feather:

• 8, 9, 10, 11, 14 (MISO), 15 (SCK), 16 (MOSI)

SAMD21G18 / Arduino Zero:

• Any pin (except 4 on the zero)

ESP8266:

• Any GPIO, except GPIO16

ESP32:

• Any GPIO

Note that not all of these pins are available with our Variants and Branches, below.

Variants and Branches

As we've described, the default "master" branch of this library will conflict with SoftwareSerial and any other library that monopolizes all pin change interrupt vectors for all AVR boards. To allow simultaneous use of SDI-12 and SoftwareSerial, we have created additional variants of these libraries that we maintain as separate branches of this repository. For background information, my be helpful to read our Overview of Interrupts wiki page or this Arduino Pin Change Interrupts article.

Contribute

Open an issue to suggest and discuss potential changes/additions.

For power contributors:

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: ‘git commit -am 'Add some feature’
4. Push to the branch:git push origin my-new-feature`
5. Submit a pull request :D

License

The SDI12 library code is released under the GNU Lesser Public License (LGPL 2.1) – See LICENSE-examples.md file for details.

Example Arduino sketches are released under the BSD 3-Clause License – See LICENSE-examples.md file for details.

Documentation is licensed as Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) copyright.

Credits

EnviroDIY™ is presented by the Stroud Water Research Center, with contributions from a community of enthusiasts sharing do-it-yourself ideas for environmental science and monitoring.

Kevin M. Smith was the primary developer of the SDI-12 library, with input from S. Hicks and Anthony Aufdenkampe.

Sara Damiano is now the primary maintainer, with input from many other contributors.

This project has benefited from the support from the following funders:

• National Science Foundation, awards EAR-0724971, EAR-1331856, ACI-1339834
• William Penn Foundation, grant 158-15
• Stroud Water Research Center endowment