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.
Extensive documentation on the SDI-12 functions and classes is available here: https://envirodiy.github.io/Arduino-SDI-12/index.html
Important
As of version 2.0.0 this library was renamed from "Arduino-SDI-12" to simply "SDI-12" to comply with requirements for inclusion in the Arduino.cc's IDE and Library Manager.
- SDI-12 for Arduino
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/
This library is available through both the Arduino and PlatformIO library registries.
Within the Arduino IDE, you can find the library in the library registry using the library manager. The build and ingest logs for this library into the Arduino library registry are available.. The Arduino library registry should show newly available versions of this library within a few hours of a new release.
The library is also available in the PlatformIO registry page..
It can be installed using the PlatformIO command pio pkg install --library "envirodiy/SDI-12",
You can also include this SDI-12 library as a dependency for a project by adding envirodiy/SDI-12 to the lib_deps section of your platformio.ini configuration file.
The PlatformIO library registry will should newly available versions of this library within minutes of a new release.
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 ATmega168, ATmega328P, ATmega644, and ATmega644P 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. For ATmega1280, ATmega1284, ATmega1284P, and ATmega2560 boards, this library will silently conflict with the Arduino Servo library when Servo uses Timer 3. 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.
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 compatible 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 32u4:
- 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
- Particle (Boron LTE):
- Any digital GPIO
Note that not all of these pins are available with our Variants and Branches, below.
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.
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) 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 libraries (which is, by the way, extremely unstable).
The only difference between the SDI12_ExtInts and the master version of this library is the name and the uncommented build flag SDI12_EXTERNAL_PCINT in the SDI12Config.h configuration header.
SDI12_PCINT3 is in the PCINT3 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 controls interrupt vectors PCINT1 (B) & PCINT2 (C) / Mayfly pins D08-D15 & D16-D23) and 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.
The only difference between the SDI12_PCINT3 and the master version of this library is the name and the uncommented build flag SDI12_PCINT3_ONLY in the SDI12Config.h configuration header.
This library can be configured through the SDI12Config.h header in the src folder of the library.
If you are using PlatformIO, you can also configure the library through build flags
In the Arduino Command Line Interface (CLI), the --build-property option of the compile command also allows you to add build flags.
AVR interrupts can be handed off to an external pin change interrupt managing library by removing the two comment slashes at the start of the line // #define SDI12_EXTERNAL_PCINT in the SDI12Config.h header or by compiling with the build flag -D SDI12_EXTERNAL_PCINT.
In your own code call SDI12::handleInterrupt() as the interrupt for your SDI12 bus pin using the other interrupt library.
Example j shows doing this in GreyGnome's EnableInterrupt library.
The ExtInts branch is has this enabled by default
You can also allow this library to manage the interrupt handling, but restrict the pin change interrupts it can manage to a specific interrupt vector using the configuration options or defining build flags SDI12_PCINT0_ONLY, SDI12_PCINT1_ONLY, SDI12_PCINT2_ONLY, or SDI12_PCINT3_ONLY.
The PCINT3 branch uses only vector 3.
The response buffer size can be modified using the SDI12_BUFFER_SIZE value in SDI12Config.h or via a build flag.
The default size is large enough for all standard and high volume ASCII SDI-12 commands and responses.
If you are extremely space limited, you can decrease the size of the buffer.
If you need high volume binary responses, you will probably need to increase the size of the buffer.
Processors running at 48MHz or faster are fast enough that a typical interrupt service routine cannot shift the bit timing past the SDI-12 tolerance, so since version 2.2.0 interrupts are left enabled while transmitting on those boards.
On a board running an RTOS - an ESP32 running FreeRTOS alongside WiFi or a cellular modem, for instance - a task switch or another driver's long ISR can still stretch a bit far enough to garble a command.
Defining SDI12_TX_DISABLE_INTERRUPTS restores the pre-2.2.0 behavior of holding interrupts off for the time-critical part of every character.
Important
Don't change these options without good reason!
You can modify the default delay to wait for a sensor to wake, the exact length of the break, and the exact length of the mark using the SDI12_WAKE_DELAY, SDI12_LINE_BREAK_MICROS, and SDI12_LINE_MARK_MICROS options, respectively.
The defaults should be correct for almost all uses.
Warning
Don't change this unless you really know what you're doing!
You can tweak the reception bit timing using the SDI12_RX_WINDOW_FUDGE.
See the configuration file and the boards files for details.
Open an issue to suggest and discuss potential changes/additions.
For power contributors:
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature - Commit your changes:
git commit -am 'Add some feature' - Push to the branch:
git push origin my-new-feature - Submit a pull request :D
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.
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 funding sources:
- National Science Foundation, awards EAR-0724971, EAR-1331856, ACI-1339834
- William Penn Foundation, grant 158-15
- Stroud Water Research Center endowment