# RPLIDAR A1 — LIDAR Container

ROS 2 container for the Slamtec RPLIDAR A1, built on top of a fork of the
official `sllidar_ros2` driver.

---

## How the build works

The driver source lives in `lidar/sllidar_ros2/` as a **git subtree** of this
repository.  The [Dockerfile](Dockerfile) copies it directly from the
workspace — no network access is required at build time.

```
Workspace repo                Docker build
──────────────────────────    ──────────────────────────────────────────
lidar/sllidar_ros2/      ───> COPY lidar/sllidar_ros2/ src/sllidar_ros2/
(git subtree of fork)         colcon build --packages-select sllidar_ros2
```

The upstream fork is maintained at:

    https://github.com/m5p3nc3r/sllidar_ros2

---

## Development workflow

### Pulling upstream changes into the workspace

```bash
git subtree pull --prefix=lidar/sllidar_ros2 sllidar_ros2 main --squash
```

This fetches the latest commits from the fork, squashes them into a single
merge commit, and updates `lidar/sllidar_ros2/` in the workspace.

### Making local changes

Edit files inside `lidar/sllidar_ros2/` as normal, then commit them to the
workspace repo:

```bash
git add lidar/sllidar_ros2/
git commit -m "lidar: describe the change"
```

### Pushing changes back to the fork

```bash
git subtree push --prefix=lidar/sllidar_ros2 sllidar_ros2 main
```

This replays only the commits that touched `lidar/sllidar_ros2/` and pushes
them to the fork's `main` branch.

### First-time setup on a fresh clone

The subtree files are committed in the workspace repo, so a `git clone` of
this repo is all that is needed — there is no separate step to initialise the
subtree.  To be able to pull or push to the fork later, add the remote:

```bash
git remote add sllidar_ros2 https://github.com/m5p3nc3r/sllidar_ros2.git
```

---

## Changes relative to upstream

| File | Change |
|---|---|
| `src/sllidar_node.cpp` | `/scan` publisher QoS set to `BEST_EFFORT` with depth 2. Required for compatibility with Nav2 and RViz2, which subscribe to `/scan` with `BEST_EFFORT`. The upstream default (`RELIABLE`) causes those consumers to receive no data. |

The upstream Slamtec repository is at:

    https://github.com/slamtec/sllidar_ros2

---

## Published topics

| Topic | Type | Description |
|---|---|---|
| `/scan` | `sensor_msgs/LaserScan` | 360° laser scan, `BEST_EFFORT` QoS, depth 2 |

## Device

The RPLIDAR A1 connects via USB serial at `/dev/ttyUSB0` (default), 115200 baud.
The container receives access to that device via the `devices` mapping in
[docker-compose.yml](../docker-compose.yml).  To use a different port, set
`LIDAR_PORT` in your `.env` file:

```bash
LIDAR_PORT=/dev/ttyUSB1
```