> For the complete documentation index, see [llms.txt](https://docs.hello-robot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello-robot.com/stretch4_pyhesai_wrapper/readme.md).

# README

## pyhesai\_wrapper

This repository holds code that is intended to provide a Python interface to the Hesai JT128 hemispherical LiDAR.

## How to Build and Run

#### Prerequisites:

* A C++17 compiler (like g++).
* cmake (version 3.14 or higher, e.g., `sudo apt install cmake`).
* Python 3.12+ and pip (or uv).
* Git (for cloning the Hesai SDK).
* The Hesai SDK's system dependencies: `libpcap-dev`, `libssl-dev` (e.g., `sudo apt install libpcap-dev libssl-dev`).

#### Setup:

```bash
python3 -m venv .venv
source .venv/bin/activate
```

The build process is now fully automated. Simply run:

```bash
pip install .
```

This will:

1. Read pyproject.toml
2. Use scikit-build to run CMakeLists.txt.
3. CMake will find pybind11, the SDK headers, and the SDK libraries.
4. It will compile pybind\_hesai\_sdk.cpp and link it against all the .a and .so files.
5. It will create a Python module file (e.g., pyhesai\_wrapper\_cpp.cpython-310-x86\_64-linux-gnu.so) and install it into your Python environment.
6. If the build is successful, the pyhesai\_wrapper module is now installed and available to all Python scripts in your environment.

#### Use in your python code

```python
from pyhesai_wrapper import stream_lidar_left

def main():
    # Continually yields LidarPointCloudFrame objects as long as it's running
    for frame in stream_lidar_left():
        if frame is not None:
            print(f"Points shape: {frame.points.shape}, timestamp: {frame.timestamp}")

if __name__ == "__main__":
    main()
```

**The `LidarPointCloudFrame` Dataclass**

When you fetch points using `lidar.get_next()` or via the streaming generators, the system returns a `LidarPointCloudFrame` object (or `None` if no new data is available yet). The properties of this object are:

* `points`: A NumPy array of shape `(N, 3)` containing the X, Y, and Z Cartesian coordinates of the captured points (`dtype=float32`).
* `intensity`: A NumPy 1D array of shape `(N,)` containing the return intensity values (`dtype=uint8`).
* `timestamp`: A NumPy 1D array of shape `(N,)` containing the microsecond tick timestamps for each point (`dtype=float64`).
* `confidence`: A NumPy 1D array of shape `(N,)` containing the confidence values (`dtype=uint8`).
* `ring`: A NumPy 1D array of shape `(N,)` containing the laser ring IDs (`dtype=uint16`).

#### Tools:

**Live Lidar test (`tools/stretch_lidar_show.py`):**

1. Edit `pyhesai_wrapper/config.yaml` to configure your lidar settings:
   * Update `device_ip_address` to match your lidar's IP (default: `192.168.1.201`)
   * Update `correction_file_path` to point to your lidar's correction file
   * Optionally update other parameters like `udp_port`, `ptc_port`, etc.
2. Make sure your machine is on the same network as the lidar.
3. Run the script:

   ```bash
   stretch_lidar_show --left
   ```

   or

   ```bash
   stretch_lidar_show --right
   ```
4. You should see point cloud data streaming from the lidar. Press Ctrl-C to stop.

**Download calibration (`tools/REx_hesai_download_calibration.py`):**

1. Edit `pyhesai_wrapper/config.yaml` to configure your lidar settings:
   * Update `device_ip_address` to match your lidar's IP (default: `192.168.1.201`)
   * Update `ptc_port` to match your lidar's PTC port (default: `9347`)
2. Make sure your machine is on the same network as the lidar.
3. Run the script:

   ```bash
   REx_hesai_download_calibration --left
   ```

   or

   ```bash
   REx_hesai_download_calibration --right
   ```
4. You should see calibration data being downloaded from the lidar to the `$HELLO_FLEET_PATH/$HELLO_FLEET_ID/calibration_hesais`directory.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hello-robot.com/stretch4_pyhesai_wrapper/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.