Distance Detection with the TF-Luna LiDAR and Raspberry Pi
“As an Amazon Associates Program member, clicking on links may result in Maker Portal receiving a small commission that helps support future projects.”
The only parts used in this tutorial are the TF-Luna LiDAR module and a Raspberry Pi 4 computer. The TF-Luna can be wired directly to the RPi with the jumpers extending from the header of the module, and thus, jumper wires are not needed. We are using a longer set of wires that allow for free-range testing of the module without cable limitations. It is also a good idea to have a tape measure or another type of distance measurement tool to validate the measurements from the LiDAR module. The full parts list for the project is given below:
In the next section, the UART Serial port will be enabled on the Raspberry Pi, which is required for communicating with the TF-Luna module.
The TF-Luna communicates with the Raspberry Pi via the Universal Asynchronous Receiver-Transmitter (UART) serial port. The port that we will be using is the mini UART, which correlates to GPIO pins 14/15 (physical pins 8/10). First, the port needs to be enabled via the boot configuration file on the RPi. Screenshots of the step-by-step procedure to do this are given below:
Assuming the ‘ttyS0’ port (serial0) is showing up on the serial output shown above, we can run a test to verify that the TF-Luna is wired correctly to the Raspberry Pi. A note on the mini UART port: issues can arise specifically when using ‘/dev/ttyS0’ as a Bluetooth port. This is a particular case and may be rare for most users, however, when the issue arises it may be beneficial for the user to explore the extra UART ports on the Raspberry Pi 4. The RPi4 has 4 extra UART ports, which can be accessed using the boot configuration file (read about the specifics here). In short, in place of ‘enable_uart=1’ - the dtoverlay for a specific additional UART port can be enabled. For example, ‘dtoverlay=uart5’ enables UART port 5, which correlates to GPIO pins 14/15 on the RPi4. The specifics of the additional UART ports on the RPi4 can be found in the /boot/overlays/README file on every RPi4. The resulting port will change to /dev/ttyAMA1 or something similar, depending on the port being enabled. Going forward in this tutorial, the mini UART (default ‘enable_uart=1’) will be used on GPIO pins 14/15 (as wired above).
The TF-Luna can be tested by running several simple serial reader programs in Python. The product manual for the TF-Luna is a great resource for learning which commands configure sample rate, baud rate, and data output; and which commands read device info, ranging, chip temperature, and amplitude data. The codes developed here are based on the serial commands introduced in the product manual. All codes cited here can be found on this project’s GitHub page:
The simplest test we can do with the TF-Luna is to print out a test range, chip temperature, and signal amplitude at the module’s default baud rate (115200) and default sample rate (100Hz):
In the above script, the serial port is being accessed for serial0 at a baudrate of 115200. The serial port is first opened before reading or writing any commands [ser.Open()]. Then in the test script, 9-bytes are read and the first two bytes are checked for the correct data format (0x59 and 0x59 are cited as the data return in the product manual). Finally, the data is printed out as distance, signal strength, and chip temperature. This is the simplest test of the TF-Luna that will verify the functionality of the TF-Luna and its wiring to the Raspberry Pi computer. If an error arises - the wiring should be checked first.
Configuring the TF-Luna
The baudrate and sample rate can be changed on the TF-Luna using the configuration code below. The configuration also prints out the firmware version information for each specific TF-Luna module. The sample rate is also checked at the end of the script, in order to print out the approximate sample rate (whether it was changed or not). The sample rate can be tested from 1Hz - 250Hz using the script below.
The baudrate change is a bit more complicated. First, the old baudrate must be used to open the serial port and send a baudrate change command to the TF-Luna module. Next, the first serial port is closed and a second serial port must be opened at the new baudrate in order to communicate with the TF-Luna. This is also shown below:
Below is an example output from the Raspberry Pi Python configuration code ran for the TF-Luna:
Plotting TF-Luna Distance Ranging
Below is an addition to the configuration code above that plots the test ranging samples acquired to approximate the sample rate of the TF-Luna. The code sets the sample rate to 100Hz, baudrate to 115200, and acquires 100 samples to plot. The code then plots the 100 samples of a test range. The code is given below, followed by an example output plot:
The plot above is the result of a hand being placed near the TF-Luna module and quickly moving it away. A real-time plotter will be explored in the next section, where the timing behavior of the TF-Luna will be studied.
The behavior of the TF-Luna can be tested by visualizing the ranging and signal strength data in near real-time using matplotlib in Python. A visualization and handling of the real-time incoming data is given in the code below (and on GitHub):
The code uses blitting to speed up the visualization update. The distance detection is plotted on a time-series graph, while the signal strength is given in the form of a bar chart. This allows the user to see if a given object or scan routine is outputting poor signal strength. An example output of the real-time graph is given below:
Real-Time Ranging Output from the TF-Luna
A video demonstration of the real-time ranging is also given below:
The TF-Luna Light Detection and Ranging (LiDAR) module was introduced as a rapid distance detection time-of-flight sensor compatible with the Raspberry Pi computer. The module was wired to the RPi via the UART serial port on GPIO pins 14/15. The sensor was shown to update at a maximum rate of 250 detections per second (250Hz sample rate). The configuration of the LiDAR module was given for the sample rate and baudrate. Commands to read firmware version information and the general ranging data packet were also given. The data packet received from the TF-Luna outputs ranging distance, signal amplitude, and chip temperature. A plotter tool was introduced as a way of testing the functionality of the module and visualizing the behavior of the LiDAR. In the next entry of the TF-Luna series, specific characterization of the LiDAR will be explored again on the Raspberry Pi, with tests involving different surface types, distance accuracy, field-of-view (FoV) tests, and other analyses.
See More in Raspberry Pi and Sensors: