DTS6012M_UART

KO | EN

gitlite — search

#llm #go #machine-learning #rust #docker #java #awesome #kubernetes #awesome-list #vue #pytorch #ios #mcp #open-source

(★ 22)

DTS6012M_UART Arduino Library

DTS6012M_UART Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# DTS6012M_UART Arduino Library

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Description

This library provides an interface for the DTS6012M single-point dToF (direct Time-of-Flight) distance sensor module using UART communication.

The DTS6012M is a compact sensor capable of measuring distances up to 20 meters with features like dual-target detection and good ambient light resistance. This library handles the UART protocol (frame parsing, CRC checking) required to communicate with the sensor and retrieve measurement data like distance and signal intensity.

This library is based on the DTS6012M User Manual V1.6 (dated 2024-07-26).

## Features

* Initializes UART communication with the sensor.
* Starts and stops the sensor's continuous measurement stream with `enableSensor()` and `disableSensor()`.
* Parses incoming data frames according to the datasheet protocol.
* Performs Modbus CRC-16 checksum validation for data integrity (can be optionally disabled for performance).
* Supports CRC byte-order modes: `MSB_THEN_LSB` (default, per datasheet), `LSB_THEN_MSB`, and `AUTO` failover.
* In `AUTO` mode, can switch CRC byte order automatically after repeated CRC failures.
* Provides easy-to-use functions to retrieve:
    * Primary Target Distance (mm)
    * Primary Target Intensity
    * Secondary Target Distance (mm)
    * Secondary Target Intensity
    * Sunlight Base Level
    * Correction Values (Primary & Secondary)
* Allows disabling the CRC check via `enableCRC(false)` for potentially faster updates, at the risk of accepting corrupted data.
* Sensor enable/disable control for power management and measurement control.
* Preserves source compatibility with `main`/v1 command symbols (`DTS_CMD_*`) and `sendCommand(byte, ...)`.
* Includes example sketch demonstrating usage with enable/disable functionality.

## Hardware Requirements

* **DTS6012M Sensor Module:** The sensor this library is designed for.
* **Arduino Board:** An Arduino board with at least one available **HardwareSerial** port (e.g., `Serial1`, `Serial2`). Examples include Arduino Mega, Arduino Due, ESP32, STM32-based boards, etc.
    * **Note:** The default sensor baud rate (921600 bps) is generally **too high** for SoftwareSerial libraries. Using a HardwareSerial port is strongly recommended.
    * **8-bit AVR caveat (Uno/Mega/Nano):** A 16 MHz AVR UART **cannot** reach 921600 baud (the nearest divisor is ~1 Mbaud, an 8.5% error — every byte corrupts), so the default configuration will not work on those boards and `update()` will only ever report `TIMEOUT`. Use a 32-bit host (ESP32, STM32, RP2040, Due) for the default rate, or first lower the sensor's rate from a 32-bit host with `setBaudRate()` before wiring it to an AVR. There is no divisor that makes 921600 usable at 16 MHz.
* **3.3V Power Supply:** The sensor requires a 3.3V supply for both Pin 1 (3V3_LASER) and Pin 2 (3V3). Ensure your Arduino can supply sufficient current or use an external 3.3V regulator.
* **Jumper Wires:** For making connections.
* **(Optional)** Logic Level Shifter (if connecting 5V Arduino TX to 3.3V sensor RX).

## Software Requirements

* **Arduino IDE:** Version 1.8.10 or later recommended.
* **This Library:** `DTS6012M_UART`

## Installation

1.  **Library Manager:**
    * Open the Arduino IDE.
    * Go to `Sketch` -> `Include Library` -> `Manage Libraries...`
    * Search for `DTS6012M_UART`.
    * Click `Install`.
2.  **Manual Installation:**
    * Download the latest release ZIP file from the repository.
    * In the Arduino IDE, go to `Sketch` -> `Include Library` -> `Add .ZIP Library...`
    * Select the downloaded ZIP file.
    * Alternatively, unzip the file and copy the `DTS6012M_UART` folder into your Arduino `libraries` directory (usually found in your Sketchbook location).
    * Restart the Arduino IDE.

## Wiring (UART Mode)

**Crucially, connect the sensor's GPIO pin (Pin 5) to GND *before* powering on the sensor to select UART mode.**

**Logic Level Shifting:** If using a 5V Arduino board (like Uno, Nano), you **must** use a logic level shifter between the Arduino's TX pin (5V) and the sensor's RX pin (Pin 4, 3.3V tolerant) to avoid damaging the sensor. The sensor's TX output (3.3V) might be readable by a 5V Arduino RX pin, but check your Arduino board's specifications. Using a level shifter on both TX/RX lines is the safest approach.

## Basic Usage

```cpp
#include <Arduino.h>
#include "DTS6012M_UART.h" // 1. Include the library

// 2. Select the HardwareSerial port connected to the sensor
HardwareSerial &SensorSerial = Serial1; // Use Serial1, Serial2, etc.

// 3. Create an instance of the sensor library
DTS6012M_UART dtsSensor(SensorSerial);

void setup() {
  Serial.begin(115200); // For printing results
  while (!Serial);

// 4. Initialize the sensor library (starts Serial1 at 921600 default)
  if (!dtsSensor.begin()) {
    Serial.println("Failed to initialize sensor!");
    while (1); // Halt
  }
  Serial.println("Sensor initialized.");

// --- Optional: Disable CRC Check ---
  // For maximum performance, you can disable the CRC check.
  // This reduces processing overhead but increases the risk of using corrupted data if transmission errors occur.
  // dtsSensor.enableCRC(false); // CRC is ENABLED by default. Uncomment this line to disable it.

// --- Optional: CRC Byte-Order Mode ---
  // Default is MSB_THEN_LSB (per datasheet).
  // dtsSensor.setCRCByteOrder(DTSCRCByteOrder::LSB_THEN_MSB);
  // dtsSensor.setCRCByteOrder(DTSCRCByteOrder::AUTO); // starts with MSB_THEN_LSB
  // dtsSensor.setCRCAutoSwitchErrorThreshold(100);    // switch after 100 consecutive CRC failures
  
  // --- Optional: Control sensor enable/disable ---
  // dtsSensor.disableSensor(); // Stop measurements
  // dtsSensor.enableSensor();  // Resume measurements
}

void loop() {
  // 5. Call update() frequently to process incoming data
  bool newData = dtsSensor.update();

// 6. Check if new data was received
  if (newData) {
    // 7. Get the data
    uint16_t distance = dtsSensor.getDistance(); // in mm
    uint16_t intensity = dtsSensor.getIntensity();

Serial.print("Distance: ");
    if (distance == 0xFFFF) {
      Serial.print("Invalid/OOR");
    } else {
      Serial.print(distance);
      Serial.print(" mm");
    }
    Serial.print("\t Intensity: ");
    Serial.println(intensity);
  }

// Do other things...
  delay(10); // Keep loop running reasonably fast
}
```

## API Reference

### Enhanced Configuration

```cpp
// Sensor configuration structure
struct DTSConfig {
  unsigned long baudRate = 921600;        // UART baud rate
  unsigned long timeout_ms = 1000;        // Communication timeout
  bool crcEnabled = true;                  // Enable CRC validation
  uint16_t maxValidDistance_mm = 18000;    // Conservative default validity cap (see note)
  uint16_t minValidDistance_mm = 20;       // Minimum valid distance
  uint16_t minIntensityThreshold = 100;    // Minimum signal strength
  DTSCRCByteOrder crcByteOrder = DTSCRCByteOrder::MSB_THEN_LSB; // CRC byte order (datasheet default)
  uint16_t crcAutoSwitchErrorThreshold = 100; // AUTO mode threshold
  uint16_t intensityNoiseFloor = 8;        // Absolute floor for the distance-scaled intensity threshold
  uint16_t maxSunlightBase = 0;            // 0 = off; if >0, frames with higher ambient are graded POOR
};
```

> **Distance range note.** The DTS6012M is specified to a **20 m** maximum
> range (public datasheet Docdt22 Rev1.2). `maxValidDistance_mm` defaults to a
> conservative **18000** so readings in the least-accurate top band are graded
> `POOR` by default; set it to `20000` to use the sensor's full specified range.
> The 20 mm minimum is the library default; adjust `minValidDistance_mm` to your
> optics.

```cpp

// Constructor with configuration
DTS6012M_UART sensor(Serial1, config);
```

### Error Handling

```cpp
// Enhanced error codes
enum class DTSError : byte {
  NONE = 0x00,                    // No error
  SERIAL_INIT_FAILED = 0x01,      // Serial port initialization failed
  FRAME_HEADER_INVALID = 0x02,    // Invalid frame header
  FRAME_LENGTH_INVALID = 0x03,    // Invalid frame length
  CRC_CHECK_FAILED = 0x04,        // CRC validation failed
  BUFFER_OVERFLOW = 0x05,         // Buffer overflow detected
  TIMEOUT = 0x06,                 // Communication timeout (no valid frame in timeout_ms)
  INVALID_COMMAND = 0x07,         // Invalid command parameter
  UNSUPPORTED_OPERATION = 0x08,   // Feature not implemented by sensor firmware
  NO_NEW_DATA = 0x09              // Benign: no complete frame available this update() call
};

// Error handling example
DTSError result = sensor.update();
if (result == DTSError::NONE) {
  // New measurement is ready.
} else if (result != DTSError::NO_NEW_DATA) {
  // NO_NEW_DATA is benign (loop() polls faster than frames arrive); everything
  // else is a real fault worth handling.
  Serial.print("Error: ");
  Serial.println(static_cast<int>(result));
}
```

### CRC Byte-Order Modes

```cpp
enum class DTSCRCByteOrder : byte {
  LSB_THEN_MSB = 0,  // Alternate sensor variants
  MSB_THEN_LSB = 1,  // Default (per datasheet)
  AUTO = 2           // Auto-switch after repeated CRC failures
};

// Fixed CRC order
sensor.setCRCByteOrder(DTSCRCByteOrder::LSB_THEN_MSB);
sensor.setCRCByteOrder(DTSCRCByteOrder::MSB_THEN_LSB);

// Auto mode: starts with MSB_THEN_LSB and flips after threshold failures
sensor.setCRCByteOrder(DTSCRCByteOrder::AUTO);
sensor.setCRCAutoSwitchErrorThreshold(100);

// Inspect configured and currently active mode
DTSCRCByteOrder configured = sensor.getCRCByteOrder();
DTSCRCByteOrder active = sensor.getActiveCRCByteOrder();
```

### Data Quality Assessment

```cpp
// Data quality levels
enum class DataQuality : byte {
  EXCELLENT = 0,    // High signal strength, optimal conditions
  GOOD = 1,         // Good signal strength, reliable measurement
  FAIR = 2,         // Moderate signal strength, acceptable
  POOR = 3,         // Low signal strength, use with caution
  INVALID = 4       // Invalid measurement, do not use
};

// Quality assessment example
if (sensor.isDataValid()) {
  DataQuality quality = sensor.getDataQuality();
  switch (quality) {
    case DataQuality::EXCELLENT:
    case DataQuality::GOOD:
      // Use measurement with confidence
      break;
    case DataQuality::FAIR:
      // Use with additional validation
      break;
    case DataQuality::POOR:
    case DataQuality::INVALID:
      // Discard measurement
      break;
  }
}
```

### Measurement Data Structure

```cpp
// Complete measurement data
struct DTSMeasurement {
  uint16_t primaryDistance_mm;      // Primary target distance
  uint16_t primaryIntensity;        // Primary target signal strength
  uint16_t primaryCorrection;       // Primary target correction value
  uint16_t secondaryDistance_mm;    // Secondary target distance
  uint16_t secondaryIntensity;      // Secondary target signal strength
  uint16_t temperatureCode;         // Sensor temperature code (datasheet: 温度码)
  uint16_t sunlightBase;            // Ambient light level
  unsigned long timestamp;          // Measurement timestamp
  DataQuality primaryQuality;       // Primary target quality
  DataQuality secondaryQuality;     // Secondary target quality
  DTSError lastError;               // Last error code
};

// Get complete measurement
DTSMeasurement measurement = sensor.getMeasurement();
```

### Statistics and Analytics

```cpp
// Measurement statistics
struct DTSStatistics {
  uint16_t minDistance;        // Minimum measured distance
  uint16_t maxDistance;        // Maximum measured distance
  uint32_t avgDistance;        // Average distance
  uint32_t measurementCount;   // Total measurements
  uint32_t errorCount;         // Total errors
};

// Get statistics
DTSStatistics stats = sensor.getStatistics();
// measurementCount = valid frames, errorCount = failures (incl. timeouts).
// They are disjoint counts, so the success rate is valid / (valid + errors).
uint32_t total = stats.measurementCount + stats.errorCount;
if (total > 0) {
  Serial.print("Success rate: ");
  Serial.print(100.0 * stats.measurementCount / total);
  Serial.println("%");
}

// Reset statistics
sensor.resetStatistics();
```

### Calibration System

```cpp
// Distance calibration
sensor.setDistanceOffset(10);      // Add 10mm offset
sensor.setDistanceScale(1.05f);    // Apply 5% scaling

// Calibration is applied automatically to all measurements
uint16_t calibratedDistance = sensor.getDistance();
```

### Resetting Library State

```cpp
// Clear calibration tweaks, rolling statistics, and error history
sensor.resetState();

// Compatibility helper: still performs a soft reset but returns UNSUPPORTED_OPERATION
DTSError factoryResult = sensor.factoryReset();
if (factoryResult == DTSError::UNSUPPORTED_OPERATION) {
  Serial.println("Sensor firmware exposes no factory-reset command; local state was cleared instead.");
}
```

### Advanced Control

```cpp
// Sensor control with error handling
DTSError result = sensor.enableSensor();
if (result != DTSError::NONE) {
  // Handle enable failure
}

result = sensor.disableSensor();
if (result != DTSError::NONE) {
  // Handle disable failure
}

// Performance optimization
sensor.enableCRC(false);  // Disable CRC for speed
// Use with caution - reduces reliability

// CRC byte order (default: MSB_THEN_LSB per datasheet)
sensor.setCRCByteOrder(DTSCRCByteOrder::LSB_THEN_MSB);

// AUTO failover for mixed sensor populations
sensor.setCRCByteOrder(DTSCRCByteOrder::AUTO);
sensor.setCRCAutoSwitchErrorThreshold(100); // Switch after repeated CRC failures
```

### Legacy API Compatibility (main/v1)

```cpp
// Legacy command constants are still available
sensor.sendCommand(DTS_CMD_START_STREAM, NULL, 0);
sensor.sendCommand(DTS_CMD_STOP_STREAM, NULL, 0);

// Legacy bool-style usage still works
if (sensor.begin()) {
  if (sensor.update()) {
    uint16_t distance = sensor.getDistance();
    (void)distance;
  }
}
```

## Examples

The library includes comprehensive examples:

- **BasicRead**: Simple distance measurement
- **DTS6012M_UART_Example**: Enhanced basic usage with all features
- **AdvancedFeatures**: Comprehensive feature demonstration
- **ErrorHandlingDemo**: Robust error handling and recovery
- **CompileTest**: Minimal sketch that exercises the API surface for CI compile checks

## Testing

The unit tests run on a desktop host (no Arduino toolchain needed) — see
[TESTING.md](TESTING.md). In short:

```bash
mkdir -p build
g++ -std=c++17 -DDTS6012M_TEST_MODE -I. -Itests \
    tests/test_DTS6012M_UART.cpp DTS6012M_UART.cpp -o build/dts_tests
./build/dts_tests
```

The test file defines `DTS6012M_TEST_MODE`, which swaps in a `HardwareSerial`
stub; it is a host program (`main()` returns non-zero on failure), not an
Arduino sketch, so it will not compile on-target.

Test coverage includes:
- ✅ Frame parsing and validation
- ✅ CRC byte-order modes and AUTO failover
- ✅ Legacy API compatibility (`DTS_CMD_*`, `sendCommand(byte, ...)`)
- ✅ Error handling and recovery  
- ✅ Data quality assessment
- ✅ Statistics calculations
- ✅ Calibration accuracy

## Performance

### Measurement Rates
The measurement rate is set by the **sensor**, not by host-side CRC checking.
The DTS6012M streams at its configured frame rate (datasheet: typ. 100 fps, up
to 1000 fps); change it with `setFrameRate()` / read it with `getFrameRate()`.
Disabling CRC (`enableCRC(false)`) only saves a little parse time on very slow
MCUs and does **not** raise the frame rate — leave CRC on unless you have
measured a need.

### Memory Usage
- **RAM**: ~0.5KB per sensor instance (128-byte circular buffer, 10-frame history, command/frame buffers, statistics)
- **Flash**: ~8KB (including lookup tables)

## Migration from v1.x

The v2.0 library maintains backward compatibility:

```cpp
// v1.x code (still works)
DTS6012M_UART sensor(Serial1);
if (sensor.begin()) {  // Now returns DTSError, but converts to bool
  // ...
}

// v2.0 enhanced code (recommended)
if (sensor.begin() == DTSError::NONE) {
  DTSMeasurement measurement = sensor.getMeasurement();
  if (sensor.isDataValid()) {
    // Use measurement with confidence
  }
}
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Changelog

### v3.0.0 (Latest)
Major robustness, safety, and correctness release from a multi-reviewer audit.
Public method signatures, `DTSError` values, and `DTSMeasurement`/`DTSStatistics`
layouts are unchanged, and two new `DTSConfig` fields are appended (designated
initializers keep compiling). Several **runtime behaviours changed**, so review
before upgrading a pinned integration:

Correctness / safety fixes:
- **Timeout livelock fixed.** `update()` no longer wipes the ring and any
  partial frame on every timed-out call, so a frame that spans several `update()`
  calls (low baud) can complete and the driver recovers instead of staying in
  `TIMEOUT` forever.
- **Stale data invalidated on timeout.** After a comms timeout, `isDataValid()`
  returns false and `getDistance()`/`getFilteredDistance()` return their
  sentinels instead of reporting the last good frame indefinitely. *(Behaviour
  change: consumers now correctly see "no valid data" during a stall.)*
- **AVR out-of-bounds read fixed.** `sendOneShot()` frame-size math is computed
  in 32-bit, so a corrupted response length no longer wraps 16-bit `int` on AVR
  and drives an out-of-bounds read; it reports `TIMEOUT` instead.
- **Frame resync.** A false `0xA5` from line noise is rejected within a couple of
  bytes (incremental header validation) instead of consuming a full 23-byte
  window and swallowing a genuine frame behind it.
- **`enableSensor()` refreshes the timeout clock**, so re-enabling after a
  standby longer than `timeout_ms` no longer produces a spurious `TIMEOUT`.
- **AUTO CRC** adopts the alternate byte order only when it actually validates,
  so a burst of genuine corruption no longer flips a correctly-configured sensor.
- **`begin(baud)` records the baud**, so `setBaudRate()`'s failure-revert returns
  to the rate the link is really running at.
- **Timeouts and batched parse errors are now counted** in `errorCount` /
  `getConsecutiveErrors()`. *(Behaviour change: `errorCount` now includes
  timeouts.)*
- **`sendOneShot()` restores the host's stream state** instead of always
  restarting the stream, so a one-shot query while disabled no longer re-enables
  the laser.
- **`avgDistance`** is an exact 64-bit running mean (it no longer freezes), and
  `getFrameRate()` uses a 64-byte response buffer (no false `TIMEOUT` on a large
  ACK).

Quality / robustness improvements:
- Data-quality grading gains an absolute intensity noise floor
  (`intensityNoiseFloor`) so weak long-range returns are no longer graded
  EXCELLENT, plus an opt-in ambient-light gate (`maxSunlightBase`). Statistics
  and the median filter now include only quality-valid, in-range readings.
  *(Behaviour change: `measurementCount` excludes POOR/out-of-range frames.)*
- `update()` interleaves reading and parsing, so a serial FIFO larger than the
  128-byte ring (e.g. ESP32) is fully parsed instead of overwriting intact bytes.
- Response wait loops call `yield()` (no more ESP8266 watchdog resets on long
  timeouts).
- Blocking response loops and the legacy large-payload command path are now
  heap-free; identity calibration skips floating point; `DTS_CIRCULAR_BUFFER_SIZE`
  and `DTS_HISTORY_BUFFER_SIZE` are overridable to shrink RAM.

API additions (all source-compatible):
- `getConfig()`, `getDistanceOffset()`, `getDistanceScale()` — read back what
  the setters configured.
- `peekNewData()` — non-destructive companion to `newDataAvailable()`.
- `waitForSensor(timeout)` — confirm a sensor is actually connected after
  `begin()`.
- `getMeasurement().lastError` is now populated (was always `NONE`).

Other:
- `getSecondaryDistance()` reports `DTS_INVALID_DISTANCE` for a no-return
  secondary (established in 2.8.0); gate on `hasSecondaryTarget()`, not a raw
  `> 0` comparison.
- Distance-range default clarified: the sensor is specified to 20 m;
  `maxValidDistance_mm` defaults to a conservative 18000 (set to 20000 for full
  range).
- Docs and examples corrected (ErrorHandlingDemo quality comparison, BasicRead
  poll cadence, host build instructions, success-rate formula, AVR baud caveat).
- Added `keywords.txt`; 142 host tests, all passing.

### v2.8.0
Accuracy fixes from an MRF2 firmware accuracy review. Backward compatible; no public API changes, but three behavioural corrections callers should know about:
- Raw distance 0 (a no-return frame; the sensor's minimum valid distance is 20 mm) is now reported as `DTS_INVALID_DISTANCE` instead of being scaled and offset into a plausible-looking reading at exactly the configured `setDistanceOffset()` distance.
- `resetState()` and `clearError()` no longer wipe the AUTO CRC byte-order detection streak. Hosts that call them from error-recovery paths (typically every few CRC errors) could otherwise never reach the auto-switch threshold on an LSB-first sensor variant, recovery-looping forever. Byte-order detection now resets only in `begin()` and `setCRCByteOrder()`.
- `resetState()` and `disableSensor()` clear the median-filter history, so `getFilteredDistance()` returns `DTS_INVALID_DISTANCE` until fresh frames re-prime it instead of reporting the pre-standby subject's median for the first frames after wake.
- Added tests for all three (86 tests, all passing).

### v2.7.0
Robustness and diagnostics cleanup from the firmware-library review (all backward compatible; public API only gains `getConsecutiveErrors()`).
- Ring-buffer overflow in `update()` (more bytes arrive than the 128-byte buffer holds in one call, e.g. on ESP32 with infrequent polling) is now reported via `getLastError()` / statistics `errorCount` instead of silently dropping the oldest bytes.
- Added `getConsecutiveErrors()` — exposes the consecutive-parse-error counter the library already tracks (resets on any valid frame), so sketches can drive recovery logic without re-counting.
- Legacy `sendCommand(byte, ...)` large-payload (malloc) path now reports a short write, matching the enum overload.
- Removed dead `_lastUpdateTime` bookkeeping.
- Silenced the `-Wmacro-redefined` warning in the host test build; the harness now exits non-zero on failure (from v2.6.0).
- Documentation: corrected the RAM figure (~0.5KB per instance, not ~2KB) and clarified the even-count median and `avgDistance` overflow bound.

### v2.6.0
Frame-handling and one-shot correctness fixes, plus robustness follow-ups from a firmware-library review. Backward compatible: the public API is unchanged and every non-`NONE` result still converts to `false` for the v1.x `bool` API.

Core bug fixes:
- Fixed `update()` drain loop keeping the oldest frame instead of the freshest: `processCircularBuffer()` now uses a parse-only reset (`resetParseState()`) that clears the frame parser without wiping the circular buffer, so a single `update()` drains all queued frames and `_currentMeasurement` holds the newest. Restores the v2.4.0 drain behavior that the v2.5.3 `resetFrameState()` refactor regressed. Under load this stops frame drops, cuts latency, and fixes what `getFilteredDistance()`'s median spans.
- Fixed `sendOneShot()` returning success on a truncated response: a read that ends before the full `7 + dataLen + 2` bytes now returns `TIMEOUT` instead of `NONE`, so `getFirmwareVersion()` / `getFrameRate()` / `readIICRegister()` no longer parse a partial buffer as valid.
- Fixed `getFrameRate()` returning `NONE` when it could not parse the rate: a response with `dataLen < 2` now returns `FRAME_LENGTH_INVALID` (previously left `fps` untouched and reported success).
- Enlarged the `setFrameRate()` and `writeIICRegister()` response buffers (16 → 64 bytes) so an ACK frame larger than 16 bytes is read in full instead of tripping the new truncation guard and returning a false `TIMEOUT`.

Robustness follow-ups:
- Added `DTSError::NO_NEW_DATA` (0x09) so `update()` distinguishes the benign "no complete frame yet this call" case from a real comms `TIMEOUT`. Previously the benign case returned `TIMEOUT`, which made the `AdvancedFeatures` and `ErrorHandlingDemo` examples treat a healthy sensor as failing. `NO_NEW_DATA` converts to `false` like the old return, so `bool`-style callers are unaffected; both examples now handle it explicitly.
- `sendOneShot()` now applies the same AUTO CRC byte-order switch/retry as the streaming path, so one-shot commands work on `LSB_THEN_MSB` sensor variants in `AUTO` mode instead of always returning `CRC_CHECK_FAILED`.
- Custom RX/TX pins passed to `begin()` are now stored and reused by `configure()` and `setBaudRate()` (via a shared `applySerialBegin()` helper), so re-opening the port on ESP32 no longer reverts to the default pins.
- The host test harness now exits non-zero when any test fails (previously always exited 0), matching TESTING.md so CI actually catches regressions.
- Added tests for all of the above: freshest-wins drain, truncated one-shot, unparseable frame rate, oversized ACKs, `NO_NEW_DATA` vs real `TIMEOUT`, one-shot AUTO CRC switch, and ESP32 pin persistence (72 tests, all passing).

### v2.5.4
- 🔧 Aligned default distance limits with datasheet: `maxValidDistance_mm` 20000→18000 (max range 18m), `minValidDistance_mm` 30→20 (min range 0.02m)

### v2.5.3
- 🐛 Moved circular buffer reset into `resetFrameState()` — fixes stale-buffer bugs in `begin()`, `update()` timeout, `setBaudRate()` fallback, not just `sendOneShot()`
- 🐛 Fixed `setBaudRate()` fallback paths: now resets frame state and updates `_lastValidFrameTime`

### v2.5.2
- 🐛 Fixed `sendOneShot()` not resetting circular buffer — stale bytes caused garbled frames after one-shot commands
- 🐛 Fixed `sendOneShot()` not updating `_lastValidFrameTime` on timeout/error paths — a timed-out `getFirmwareVersion()` would starve `update()` into a false timeout

### v2.5.1
- 🔧 `setFrameRate()` and `writeIICRegister()` now route through `sendOneShot()` to prevent ack frames from polluting the measurement stream
- 📝 Documented `setBaudRate()` timeout edge case (sensor may accept while library reverts)

### v2.5.0
- 🐛 Fixed response interleaving: one-shot commands (`getFirmwareVersion`, `readIICRegister`, `getFrameRate`) now stop the stream, skip non-matching frames, validate CRC, and restart — prevents measurement data from being parsed as command responses
- 🐛 `setBaudRate()` now verifies communication at the new rate and falls back to the old baud rate on failure
- 🔧 `configure()` only restarts serial when baud rate actually changes
- 🧪 Added partial frame delivery test (52 tests, all passing)

### v2.4.1
- 🔧 Removed deprecated `getSecondaryCorrection()` and `DTS_IDX_SEC_CORR` — use `getTemperatureCode()` / `DTS_IDX_TEMP_CODE`

### v2.4.0
- 🐛 Fixed error double-counting in `update()` — `errorCount` is now reliable
- 🐛 Calibration (offset/scale) now applied to secondary distance, not just primary
- ⚡ `update()` drains all queued frames so `_currentMeasurement` is always the freshest
- ⚡ Circular buffer doubled to 128 bytes (5+ frames, resilient to ~55ms stalls)
- ⚡ CRC lookup table moved to file-scope `constexpr` — saves 512 bytes RAM on ARM/ESP32
- ✨ Added `setFrameRate()`, `getFrameRate()`, `setBaudRate()` convenience methods

### v2.3.1
- 🧪 Added tests for `newDataAvailable()`, `hasSecondaryTarget()`, `getFilteredDistance()`
- 🔧 Fixed `-Wsign-compare` warning in `sendCommand()`
- 49 tests, all passing

### v2.3.0
- ✨ Added `getFilteredDistance()` — median filter over the 10-sample history buffer
- ✨ Added `hasSecondaryTarget()` — convenience check for dual-peak detection
- ✨ Added `newDataAvailable()` — edge-triggered flag, true once per new frame
- ✨ Added `getFirmwareVersion()` — query sensor firmware version (command 0x0A)
- 🐛 Fixed statistics overflow: `measurementCount`/`errorCount` widened to `uint32_t`
- 🐛 Fixed `avgDistance` unsigned underflow when new reading < current average

### v2.2.1
- 🐛 Fixed compile error: `DTSError::FRAME_HEADER_ERROR` → `FRAME_HEADER_INVALID` in `readIICRegister()`
- 🐛 Fixed `isDataValid()` contradicting distance-aware quality assessment (was using flat intensity threshold)
- 🐛 Fixed `secondaryQuality` always using primary distance/intensity instead of secondary target data
- 🧹 Removed dead `commandToByte` helper

### v2.2.0
- 📋 Verified library against manufacturer datasheet (Docdt22 Rev1.2)
- 🔧 Renamed `secondaryCorrection` → `temperatureCode` to match datasheet field 温度码
- 🔧 Changed default CRC byte order to `MSB_THEN_LSB` per datasheet spec
- ✨ Added IIC register access: `writeIICRegister()`, `readIICRegister()` (commands 0x03/0x04)
- ✨ Added diagnostic streams: `startHistogramStream()`, `startSPADHeatmapStream()` (commands 0x07/0x09)

### v2.1.2
- 🔧 Distance-aware data quality assessment: intensity threshold now scales with distance squared (inverse square law), preventing valid long-range returns from being incorrectly scored as POOR

### v2.1.1
- 🔧 Reduced default `crcAutoSwitchErrorThreshold` from 200 to 100 for faster AUTO CRC byte-order failover

### v2.1.0
- 🚀 Version bump to supersede broken v2.0.0 package in registry

### v2.0.0
- ✨ **Major enhancement release**
- 🛡️ Added comprehensive error handling and recovery
- 📊 Added data quality assessment and validation
- 🔧 Added calibration system with offset and scaling
- 📈 Added statistics tracking and analytics
- ⚡ Added performance optimizations
- 🧪 Added comprehensive test framework
- 📚 Maintained backward compatibility with v1.x

DTS6012M_UART

DTS6012M_UART Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

DTS6012M_UART

DTS6012M_UART Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README