Delta-2A works

Author: Ilia O.

POST.md

@@ -0,0 +1,120 @@
+# See what your LiDAR sees: a live browser plot for `lds2d`
+
+*Draft — announcement / blog post*
+
+A spinning LiDAR is one of those parts that feels like magic right up until you
+plug it in and get… a wall of numbers. `angle 182.40  dist_mm 1043  quality 71`,
+forty thousand times a second. You believe it's working. You can't *see* that
+it's working.
+
+So the latest `lds2d` release adds a way to see it. One command, any browser:
+
+```
+pip install 'lds2d[viz]'
+lds2d viz
+```
+
+Open `http://<your-pi>:8080` from your laptop and the room draws itself — a
+live polar plot of every return, the walls and furniture sweeping into place at
+5–6 Hz. No desktop on the Pi, no X11, no ROS, no rviz. Just a web page.
+
+![the live plot]( ) <!-- TODO: drop in a screenshot of the polar view -->
+
+## What `lds2d` is
+
+If you're new here: [`lds2d`](https://github.com/kaiaai/lds2d) is a small,
+pure-Python driver for 2D LiDARs on Linux and the Raspberry Pi — a Pythonic port
+of the [kaiaai/LDS](https://github.com/kaiaai/LDS) C++ library. Where the C++
+side targets Arduino with registered callbacks, `lds2d` gives you plain
+iterators:
+
+```python
+from lds2d import Lidar
+
+with Lidar.open("LD14P", "/dev/serial0") as lidar:
+    for scan in lidar.scans():            # one full rotation at a time
+        pts = scan.valid_points
+        print(f"{scan.scan_freq_hz:.1f} Hz  {len(pts)} points")
+```
+
+It speaks **23 LiDAR models** today — across LDROBOT (LD14P/LD19/LD06/STL19P),
+YDLIDAR (X2/X3/X4/SCL/T-mini), RPLIDAR (A1/C1), 3irobotix (Delta-2A/2B/2D/2G,
+LDS08RR), Neato/Xiaomi (XV11, LDS01RR, LDS02RR), Camsense X1 and the Hitachi-LG
+HLS-LFCD2 (TurtleBot3 LDS-01) — including running the PID + PWM motor loop for
+the ones that have no onboard speed control and need the Pi to spin them. Each is
+a faithful port of the kaiaai/LDS C++ driver, unit-tested against recorded byte
+streams; the models we haven't yet re-checked on physical hardware are flagged as
+such.
+
+## The visualizer, end to end
+
+The browser view is deliberately boring on the inside, which is the point. Three
+small pieces:
+
+- **A background reader thread** pulls full rotations off whatever driver you
+  opened — `lidar.scans()` — and hands each one to a buffer.
+- **A thread-safe latest-scan buffer** holds exactly one rotation, converted to a
+  compact JSON-ready dict of valid points. The web request thread reads it; the
+  reader thread writes it; a lock keeps them from tearing.
+- **A tiny Flask app** serves two routes: `/scan.json` (the latest scan) and `/`
+  (a single, dependency-free HTML page). The page polls every ~120 ms and redraws
+  a `<canvas>` in polar coordinates — points coloured by signal strength, a range
+  ring that auto-scales to the room, and a HUD with the live scan rate and point
+  count.
+
+Because the visualizer reads through the same `scans()` iterator every driver
+already exposes, it works with *all 23* sensors for free — including the
+host-driven-motor ones, where simply iterating keeps the motor spinning:
+
+```
+lds2d --model LDS02RR --pwm software viz
+```
+
+Prefer to wire it into your own app? The Python entry point is one call:
+
+```python
+from lds2d import Lidar
+from lds2d.viz import serve
+
+with Lidar.open("LD14P", "/dev/serial0") as lidar:
+    serve(lidar, port=8080)
+```
+
+## Tested without touching hardware
+
+`lds2d` has a rule: every driver is unit-tested against recorded byte streams, so
+the whole suite runs on a laptop with no sensor attached. The visualizer keeps
+that rule.
+
+The serial port and the spinning motor are pushed to the edges; the logic in the
+middle is plain, testable code. The scan→JSON conversion is a pure function. The
+buffer is exercised by four threads hammering it at once to prove it never tears.
+The reader is driven by a *fake* LiDAR that yields a fixed list of scans, and a
+deliberately exploding one to prove a yanked cable ends the thread quietly instead
+of crashing the server. The Flask routes are checked with Flask's test client —
+no browser, no port. And an end-to-end test feeds real LD14P packet bytes through
+the actual parser, through the buffer, out of the HTTP endpoint, and asserts the
+points that come back.
+
+The hardware-dependent surface is small enough to eyeball; everything else has a
+test. That's the whole bet.
+
+## Get it
+
+```
+pip install 'lds2d[viz]'
+lds2d viz
+```
+
+It pairs with the step-by-step Raspberry Pi tutorials this library grew out of:
+
+- [Connect & read the LD14P on a Raspberry Pi](https://makerspet.com/blog/tutorial-connect-ldrobot-ld14p-lidar-to-raspberry-pi-python/)
+- [Control the LD14P motor](https://makerspet.com/blog/tutorial-control-ldrobot-ld14p-lidar-motor-raspberry-pi-python/)
+
+The driver architecture is built to grow — and it has: from three models to 23 in
+one pass, each ported from the kaiaai/LDS C++ and verified. If you've got a 2D
+LiDAR and a Pi, there's a good chance it's already supported — give it a spin and
+watch the room appear.
+
+*`lds2d` is Apache-2.0. The LiDAR that inspired it lives at
+[makerspet.com](https://makerspet.com/product/ldrobot-ld14p-lidar/).*

README.md

@@ -6,8 +6,11 @@ Where the C++ library targets Arduino with registered callbacks, `lds2d` targets
 Linux / Raspberry Pi and gives you plain iterators: loop over individual points
 or over full 360° scans.
 
-> **Supported: LDROBOT LD14P, Xiaomi LDS02RR, and 3irobotix Delta-2A.** The driver
-> architecture is built to grow — more models from the LDS family (YDLIDAR, …) are planned.
+> **23 models supported** across LDROBOT, YDLIDAR, RPLIDAR, 3irobotix, Neato /
+> Xiaomi, Camsense and Hitachi-LG — see the [model table](#supported-models)
+> below. Every model is ported from [kaiaai/LDS](https://github.com/kaiaai/LDS)
+> and unit-tested against recorded byte streams; the ones not yet checked on real
+> hardware are flagged.
 
 ## Install
 
@@ -16,6 +19,9 @@ pip install lds2d
 
 # for host-driven-motor LiDARs (the LDS02RR needs the Pi to spin it):
 pip install 'lds2d[pwm]'
+
+# for the live browser visualizer:
+pip install 'lds2d[viz]'
 ```
 
 ## Quick start
@@ -71,12 +77,53 @@ with Lidar.open("DELTA-2A", "/dev/serial0", pwm="software", pwm_pin=18) as lidar
 # the 230400-baud Delta-2A variant: add baud=230400
 ```
 
+## Supported models
+
+Open any of these with its name, e.g. `Lidar.open("YDLIDAR-X4", "/dev/serial0")`.
+**Motor** is how the LiDAR spins: *onboard* (self-spinning or started by a serial
+command — nothing extra needed), or *host PWM* (the Pi must drive the motor —
+needs the `[pwm]` extra and a driver board; `lds2d` runs the PID for you). **HW**
+marks whether the port has been confirmed on real hardware yet.
+
+| Model | `open(...)` name | Baud | Motor | HW |
+|---|---|---|---|---|
+| LDROBOT LD14P | `LD14P` | 230400 | onboard (serial cmd) | ✅ |
+| LDROBOT LD19 | `LD19` | 230400 | onboard | spec¹ |
+| LDROBOT LD06 | `LD06` | 230400 | onboard | spec¹ |
+| LDROBOT STL19P | `STL19P` | 230400 | onboard | spec¹ |
+| 3irobotix Delta-2A | `DELTA-2A` | 115200 | host PWM | ✅ |
+| 3irobotix Delta-2B | `DELTA-2B` | 230400 | host PWM | spec¹ |
+| 3irobotix Delta-2D | `DELTA-2D` | 115200 | host PWM | spec¹ |
+| 3irobotix Delta-2G | `DELTA-2G` | 115200 | host PWM | spec¹ |
+| 3irobotix LDS08RR | `LDS08RR` | 115200 | host PWM | spec¹ |
+| Xiaomi LDS02RR | `LDS02RR` | 115200 | host PWM | ✅ |
+| Xiaomi LDS01RR | `LDS01RR` | 115200 | host PWM | spec¹ |
+| Neato XV11 | `XV11` | 115200 | host PWM | spec¹ |
+| YDLIDAR X4 | `YDLIDAR-X4` | 128000 | onboard | spec¹ |
+| YDLIDAR X2 / X2L | `YDLIDAR-X2` | 115200 | onboard | spec¹ |
+| YDLIDAR X3 | `YDLIDAR-X3` | 115200 | onboard | spec¹ |
+| YDLIDAR X3-PRO | `YDLIDAR-X3-PRO` | 115200 | onboard | spec¹ |
+| YDLIDAR X4-PRO | `YDLIDAR-X4-PRO` | 128000 | onboard | spec¹ |
+| YDLIDAR SCL | `YDLIDAR-SCL` | 115200 | onboard | spec¹ |
+| YDLIDAR T-mini | `YDLIDAR-TMINI` | 230400 | onboard | spec¹ |
+| RPLIDAR A1 | `RPLIDAR-A1` | 115200 | onboard (serial cmd) | spec¹ |
+| RPLIDAR C1 | `RPLIDAR-C1` | 460800 | onboard (serial cmd) | spec¹ |
+| Camsense X1 | `CAMSENSE-X1` | 115200 | onboard | spec¹ |
+| Hitachi-LG HLS-LFCD2 (TurtleBot3 LDS-01) | `HLS-LFCD2` | 230400 | onboard (serial cmd) | spec¹ |
+
+¹ **spec** = faithfully ported from the kaiaai/LDS C++ and unit-tested against
+synthetic packets, but not yet confirmed on physical hardware. If you run one of
+these, a report (success or bug) is very welcome. Most models carry several
+aliases (`LDROBOT_LD14P`, `DELTA_2A`, `YDLIDAR_X4` …); `lds2d.available_models()`
+lists them all.
+
 ## Command line
 
 ```
 lds2d read                 # summarized: one line per full scan
 lds2d read --raw           # one line per measurement
 lds2d --port /dev/ttyUSB0 read
+lds2d viz                  # live polar plot in your browser (needs [viz])
 
 lds2d motor status
 lds2d motor stop
@@ -87,6 +134,33 @@ lds2d motor speed 6        # set 6 Hz
 lds2d --model LDS02RR --pwm software --pwm-pin 18 read
 ```
 
+## Live visualizer
+
+Want to *see* the sweep? `lds2d viz` serves a live polar plot you can open in any
+browser on your network — no GUI on the Pi required.
+
+```
+pip install 'lds2d[viz]'
+lds2d viz                                   # LD14P on /dev/serial0, port 8080
+lds2d --model LDS02RR --pwm software viz    # host-driven-motor models work too
+lds2d viz --port 9000
+```
+
+Then open `http://<your-pi>:8080`. Points are coloured by signal strength and the
+range ring auto-scales to the room; the HUD shows the live scan rate and point
+count. Under the hood it's a background reader thread feeding a thread-safe
+latest-scan buffer that a tiny Flask app exposes as JSON — and like every other
+moving part in `lds2d`, the buffer and scan→JSON conversion are
+[unit-tested without any hardware](tests/test_viz.py).
+
+```python
+from lds2d import Lidar
+from lds2d.viz import serve
+
+with Lidar.open("LD14P", "/dev/serial0") as lidar:
+    serve(lidar, port=8080)
+```
+
 ## Wiring & setup (Raspberry Pi)
 
 See the step-by-step tutorials, which this library grew out of:

pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lds2d"
-version = "0.3.0"
-description = "Python driver for 2D LiDARs (LDROBOT LD14P, Xiaomi LDS02RR, 3irobotix Delta-2A) — a Pythonic port of kaiaai/LDS"
+version = "0.5.0"
+description = "Python driver for 2D LiDARs (LDROBOT, YDLIDAR, RPLIDAR, 3irobotix, Neato/Xiaomi, Camsense, Hitachi-LG) — a Pythonic port of kaiaai/LDS"
 readme = "README.md"
 requires-python = ">=3.8"
 license = { text = "Apache-2.0" }
 authors = [{ name = "Ilia O.", email = "ilya@ovsy.com" }]
-keywords = ["lidar", "ld14p", "lds02rr", "delta-2a", "ldrobot", "xiaomi", "3irobotix", "robotics", "ros2", "raspberry-pi", "slam"]
+keywords = ["lidar", "ld14p", "ld19", "lds02rr", "delta-2a", "ydlidar", "rplidar", "neato", "xv11", "camsense", "ldrobot", "xiaomi", "3irobotix", "robotics", "ros2", "raspberry-pi", "slam", "visualization"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",

src/lds2d/__init__.py

@@ -16,7 +16,7 @@
 )
 from . import drivers  # noqa: F401,E402  — register bundled drivers on import
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "Lidar",

src/lds2d/cli.py

@@ -1,7 +1,7 @@
 # Copyright 2026 KAIA.AI
 #
 # Licensed under the Apache License, Version 2.0 (the "License").
-"""Command-line interface: ``lds2d read`` and ``lds2d motor``."""
+"""Command-line interface: ``lds2d read``, ``lds2d viz``, and ``lds2d motor``."""
 from __future__ import annotations
 
 import argparse
@@ -50,6 +50,21 @@ def _cmd_read(args) -> int:
     return 0
 
 
+def _cmd_viz(args) -> int:
+    from .viz import serve
+    lidar = _open(args)
+    shown = "localhost" if args.host in ("0.0.0.0", "") else args.host
+    print(f"{lidar.MODEL_NAME}: live plot at http://{shown}:{args.port}  "
+          f"(Ctrl-C to stop)", file=sys.stderr)
+    try:
+        serve(lidar, host=args.host, port=args.port)
+    except KeyboardInterrupt:
+        print("\nStopped.", file=sys.stderr)
+    finally:
+        lidar.close()
+    return 0
+
+
 def _cmd_motor(args) -> int:
     import time
     lidar = _open(args)
@@ -101,6 +116,11 @@ def build_parser() -> argparse.ArgumentParser:
     r.add_argument("--raw", action="store_true", help="one line per measurement")
     r.set_defaults(func=_cmd_read)
 
+    v = sub.add_parser("viz", help="live polar plot in your browser")
+    v.add_argument("--host", default="0.0.0.0", help="bind address (default all interfaces)")
+    v.add_argument("--port", type=int, default=8080, help="HTTP port (default 8080)")
+    v.set_defaults(func=_cmd_viz)
+
     m = sub.add_parser("motor", help="control the motor (command-driven models)")
     m.add_argument("action", choices=["start", "stop", "speed", "status"])
     m.add_argument("hz", nargs="?", type=float, help="scan rate in Hz (for 'speed')")

src/lds2d/drivers/__init__.py

@@ -5,5 +5,21 @@
 from . import ldrobot_ld14p  # noqa: F401
 from . import xiaomi_lds02rr  # noqa: F401
 from . import threeirobotix_delta_2a  # noqa: F401
+from . import threeirobotix_delta_variants  # noqa: F401
+from . import neato_xv11  # noqa: F401
+from . import ydlidar  # noqa: F401
+from . import camsense_x1  # noqa: F401
+from . import rplidar  # noqa: F401
+from . import hitachi_lg_hls_lfcd2  # noqa: F401
 
-__all__ = ["ldrobot_ld14p", "xiaomi_lds02rr", "threeirobotix_delta_2a"]
+__all__ = [
+    "ldrobot_ld14p",
+    "xiaomi_lds02rr",
+    "threeirobotix_delta_2a",
+    "threeirobotix_delta_variants",
+    "neato_xv11",
+    "ydlidar",
+    "camsense_x1",
+    "rplidar",
+    "hitachi_lg_hls_lfcd2",
+]