BreezyLidar – Simple, efficient, Lidar access in Python and C++

This repository contains everything you need to start working with the popular Hokuyo URG-04LX Lidar unit on your Linux computer. BreezyLidar works with Python 2 and 3 and C++. I am working on getting it to run on OS X and Windows, and in Matlab and Java.

BreezyLidar was inspired by the Breezy approach to Graphical User Interfaces developed by my colleague Ken Lambert: an object-oriented Application Programming Interface that is simple enough for beginners to use, but that is efficient enough to scale-up to real world problems. As shown in the following code fragment, the API is extremely simple: a constructor that accepts the port (device) name on which the unit is connected, and method for accessing the scans (range values):

    from breezylidar import URG04LX

    laser = URG04LX('dev/tty/ACM0')

    while True:

        scan = laser.getScan()

        # do something with scan, like SLAM

Installing for Python

The BreezyLidar installation uses the popular distutils approach to installing Python packages, so all you should have to do is download the repositry, cd to the directory where you put it, and do

sudo python install

For a quick demo, you can then cd to breezylidar/examples and do

make test

This will attempt to connect to the Lidar, print out some information about it, and read 20 scans. I’ve found that it can take up to half a minute for the URG-04LX to be ready after plugging in its USB cable, so it’s best to wait a little between plugging it in and running the program. Depending on how your system is configured, you may need to run the program as root:

sudo make test

or you may need to change the DEVICE specified at the top of to /dev/ttyACM1 or whatever file your URG-04LX maps to.If you have the Python Tkinter package installed, you can do


to see a real-time plot of the scans.

To see what other features are available, do

pydoc breezylidar

or check out the online documentation.

Installing for C++

Just cd to the cpp directory, and do

sudo make install

This will put the libbreezylidar shareable library in your /usr/local/lib directory. If you keep your shared libraries elsewhere, just change the LIBDIR variable at the top of the Makefile.

For a quick demo, you can then cd to breezylidar/examples and do

make cpptest

Again, you’ll need to change the LIBDIR variable at the top of the Makefile in this directory as well, if you don’t use /usr/local/lib. You should also have this lib directory in your LD_LIBRARY_PATH environment variable. I do this by putting the following line in my ~/.bashrcfile:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

To see what other features are available, go back to the cpp directory and do

make doc

and then open Documentation/html/index.html in a web browser.

Copyright, licensing, and questions

Copyright and licensing information (Gnu LGPL) can be found in the header of each source file. If you have another Lidar model and are interested using BreezyLidar with it, or have any other questions, please contact me.


This work was supported in part by a Commonwealth Research Commercialization Fund grant from the Center for Innovative Technology (CRCF #MF14F-011-MS).