SDI-12 for Arduino > Pages > SDI-12 for Arduino

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.

Renaming Notice

Getting Started

Learn more, below, about this library's:

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/

Library Installation

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.

Origins

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. In November of 2026, the EnableInterrupt library was made a required dependency for this library for AVR boards.

Compatibility Considerations

Tested Boards

This library has been tested and verified for:

  • EnviroDIY Mayfly (AtMega1284p)
  • EnviroDIY Stonefly (SAMD51)
  • Arduino Uno (AtMega328p)
  • Adafruit Feather 32u4 (AtMega32u4, identical to Arduino Leonardo)
  • Seeeduino Mega (ATmega2560)
  • Adafruit Feather M0 (SAMD21G18, identical to Arduino Zero)
  • Adafruit Feather M4 (SAMD51J19A)
  • Adafruit Feather Huzzah (ESP12S/ESP8266)
  • Adafruit Feather Huzzah32 (ESP-WROOM-32/ESP32)

Untested Boards

Other untested boards that should work:

  • Arduino Mega (AtMega2560)
  • Adafruit Gemma/AtTiny
  • Most other AVR processors
  • Other flavors of ESP8266 and ESP32
  • Arduino framework boards with clock speeds over ~48MHz

Unsupported Boards

These boards are currently unsupported. If you are interested in adding support for those boards, please send pull requests.

  • Arduino Due
  • Arduino 101
  • Teensy boards with speeds <48Mhz

Usable Pins

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

For AVR boards, the "Bestiary" of the EnableInterrupt library is one of the best lists of usable pins.

  • 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)
  • SAMD21xxx / Arduino Zero:
    • Any pin (except 4 on the zero)
  • SAMD51xxx / EnviroDIY Stonefly:
    • Any pin
  • ESP8266:
    • Any GPIO, except GPIO16
  • ESP32:
    • Any GPIO
  • Particle (Boron LTE):
    • Any digital GPIO

Hidden Conflicts

Disabled Interrupts

For boards < 48MHz, such as most AVR boards, 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.

Timer Prescaler Conflicts

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.

On SAMD21 and SAMD51 boards, this library could potentially conflict with other libraries that manage change timer prescalers. I am unaware of any other libraries that currently conflict with this library on SAMD21 or SAMD51 boards due to timer prescaler management.

Advanced Library Configuration

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 Interrupt Handling

By default, AVR interrupts are handed off to GreyGnome's EnableInterrupt library. The examples include EnableInterrupt.h explicitly, which is recommended when a sketch uses or configures EnableInterrupt directly. For backward compatibility, this library also supplies a link-time fallback implementation, so existing sketches that include only an SDI-12 header do not need to add #include <EnableInterrupt.h>. You can instead allow this library full control of the AVR interrupts (and avoid using EnableInterrupt at runtime) by removing the two comment slashes at the start of the line // #define SDI12_INTERNAL_PCINT in the SDI12Config.h header or by compiling with the build flag -D SDI12_INTERNAL_PCINT. EnableInterrupt remains a declared dependency in library.properties and library.json even when SDI12_INTERNAL_PCINT is defined.

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 the build flag SDI12_INTERNAL_PCINT and one of the build flags SDI12_PCINT0_ONLY, SDI12_PCINT1_ONLY, SDI12_PCINT2_ONLY, or SDI12_PCINT3_ONLY. Defining these flags has no effect on non-AVR boards.

You will not be able to compile this library along with any other library that manages pin change interrupt vectors on AVR boards. Some other libraries managing interrupts include SoftwareSerial, NeoSWSerial, PinChangeInt, and Servo. Within a sketch, you can manage pin change interrupts using the functions provided by the EnableInterrupt library, such as enableInterrupt() and disableInterrupt().

Response Buffer Size

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.

Global Interrupts During Communication

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.

Timing Options

You can modify the exact length of the break and mark using the SDI12_LINE_BREAK_MICROS and SDI12_LINE_MARK_MICROS options, respectively. The defaults should be correct for almost all uses.

The deprecated SDI12_WAKE_DELAY option is used only as the default extra wake time for the deprecated SDI12::sendCommand() overloads. It is not used by SDI12Recorder.

The Fudge Factor

You can tweak the reception bit timing using the SDI12_RX_WINDOW_FUDGE. See the configuration file and the boards files for details.

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 funding sources: