SDI-12 for Arduino > Topics > SDI-12 Library Configuration

SDI-12 Library Configuration topic

Configuration options for the SDI-12 library.

This group contains macros that control the behavior of the SDI-12 library, including interrupt handling and buffer sizes. *

Defines

#define SDI12_INTERNAL_PCINT
Use internal PCINT ISRs on AVR boards.
#define SDI12_PCINT0_ONLY
Use the PCINT0 interrupt vector on AVR boards.
#define SDI12_PCINT1_ONLY
Use the PCINT1 interrupt vector on AVR boards.
#define SDI12_PCINT2_ONLY
Use the PCINT2 interrupt vector on AVR boards.
#define SDI12_PCINT3_ONLY
Use the PCINT3 interrupt vector on AVR boards.
#define SDI12_BUFFER_SIZE = 82
The buffer size for incoming SDI-12 data.
#define SDI12_RECORDER_CONTEXT_SLOTS = 3
Maximum number of simultaneous pending sensor transactions retained by an SDI12Recorder.
#define SDI12_RECORDER_RESPONSE_BUFFER_SIZE = 82
Storage available for one complete ASCII sensor response.
#define SDI12_RECORDER_ALWAYS_BREAK
Require a break before the first attempt of every new recorder operation.
#define SDI12_TX_DISABLE_INTERRUPTS
Disable all interrupts while transmitting each character.
#define SDI12_RX_WINDOW_FUDGE = 433
Override the board-specific receive-window timing adjustment.

SDI-12 Timing Defines

Defines for SDI-12 protocol timing.

#define SDI12_WAKE_DELAY = 0 deprecated
Deprecated default extra sensor wake time for SDI12::sendCommand().
#define SDI12_LINE_BREAK_MICROS = static_cast(12100)
The time in microseconds for the "break" before sending commands. Per the protocol, this must be >= 12ms. The line level is HIGH for the break.
#define SDI12_LINE_MARK_MICROS = static_cast(8400)
The time in microseconds for the required mark before a command or response. Per the protocol, this must be >= 8.33ms. The line level is LOW for the marking.

Define documentation

#define SDI12_INTERNAL_PCINT
#include <src/SDI12Config.h>

Use internal PCINT ISRs on AVR boards.

#define SDI12_PCINT0_ONLY
#include <src/SDI12Config.h>

Use the PCINT0 interrupt vector on AVR boards.

#define SDI12_PCINT1_ONLY
#include <src/SDI12Config.h>

Use the PCINT1 interrupt vector on AVR boards.

#define SDI12_PCINT2_ONLY
#include <src/SDI12Config.h>

Use the PCINT2 interrupt vector on AVR boards.

#define SDI12_PCINT3_ONLY
#include <src/SDI12Config.h>

Use the PCINT3 interrupt vector on AVR boards.

#define SDI12_BUFFER_SIZE = 82
#include <src/SDI12Config.h>

The buffer size for incoming SDI-12 data.

The default is 82 characters, which should be sufficient for most SDI-12 responses, including high-volume ASCII responses:

  • address is a single (1) character
  • values take a maximum value of 35 characters for standard responses, or 75 characters for high-volume ASCII responses
  • CRC is 3 characters
  • CR is a single character
  • LF is a single character
  • reserve 1 empty space in the circular buffer

If you need to use high volume binary responses, you may need to increase the buffer size accordingly. If your hard-pressed for memory and will not use high-volume ASCII responses, you can drop this down to 42 characters.

#define SDI12_RECORDER_CONTEXT_SLOTS = 3
#include <src/SDI12Config.h>

Maximum number of simultaneous pending sensor transactions retained by an SDI12Recorder.

The default is three. Storage is allocated at compile time; no dynamic allocation is used. Increase this value only when more than three sensors must have pending measurements at the same time. The maximum is 255 slots.

#define SDI12_RECORDER_RESPONSE_BUFFER_SIZE = 82
#include <src/SDI12Config.h>

Storage available for one complete ASCII sensor response.

The default holds the maximum 81-character ASCII wire response (address, 75 value characters, three CRC characters, CR, and LF) plus a null terminator.

#define SDI12_RECORDER_ALWAYS_BREAK
#include <src/SDI12Config.h>

Require a break before the first attempt of every new recorder operation.

Leave this undefined to let SDI12Recorder omit the initial break only when known bus history makes that legal. This setting does not change the break and marking rules applied to retries within an operation.

#define SDI12_TX_DISABLE_INTERRUPTS
#include <src/SDI12Config.h>

Disable all interrupts while transmitting each character.

Use this option when another interrupt or task switch can stretch SDI-12 bit timing beyond the protocol tolerance.

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 this macro restores the pre-2.2.0 behavior of holding interrupts off for the time-critical part of every character.

#define SDI12_RX_WINDOW_FUDGE = 433
#include <src/SDI12Config.h>

Override the board-specific receive-window timing adjustment.

The value is in board-specific timer ticks. See the per-board timer sections in SDI12_boards.h for guidance. This is a tuning knob for an unusual bus (long cable, slow edges, a sensor with a sloppy baud rate); the defaults in SDI12_boards.h are right for a bus that meets the SDI-12 specification.

#define SDI12_WAKE_DELAY = 0
#include <src/SDI12Config.h>

Deprecated default extra sensor wake time for SDI12::sendCommand().

This option is used only as the default extraWakeTime argument for the deprecated SDI12::sendCommand() overloads. SDI12Recorder does not use it.

#define SDI12_LINE_BREAK_MICROS = static_cast(12100)
#include <src/SDI12Config.h>

The time in microseconds for the "break" before sending commands. Per the protocol, this must be >= 12ms. The line level is HIGH for the break.

#define SDI12_LINE_MARK_MICROS = static_cast(8400)
#include <src/SDI12Config.h>

The time in microseconds for the required mark before a command or response. Per the protocol, this must be >= 8.33ms. The line level is LOW for the marking.