diff --git a/docs/integrations/lidars/slamtec-rplidar-s3.mdx b/docs/integrations/lidars/slamtec-rplidar-s3.mdx index 2f975b2b..7fb47e02 100644 --- a/docs/integrations/lidars/slamtec-rplidar-s3.mdx +++ b/docs/integrations/lidars/slamtec-rplidar-s3.mdx @@ -13,27 +13,20 @@ keywords: description: >- Learn how to connect an RPLiDAR S3 sensor to your Leo Rover for 2D mapping and more. Detailed tutorial mechanical and software integration. +# TODO: Replace with a proper image of Leo Rover with mounted RPLIDAR S3 image: /img/robots/leo/integrations/rplidar-s3/rplidar-s3.webp --- -# SLAMTEC RPLIDAR S3 Integration - -import Product from '@site/src/products/powerbox.mdx'; +import Product from '@site/src/products/slamtec-rplidar-s3.mdx'; +import Powerbox from '@site/src/products/powerbox.mdx'; import LiteYouTubeEmbed from 'react-lite-youtube-embed'; -This tutorial will guide you through the process of connecting a LiDAR sensor to -your Leo Rover. - -Light Detection and Ranging devices, or lidars for short, are mechanisms used -for mapping the environment, object detection, tracking the speed of vehicles -and in a wide range of other applications. In robotics 2D lidars, like A2M8 / -A2M12, are used for things such as indoor SLAM -([Simultaneous localization and mapping](https://en.wikipedia.org/wiki/Simultaneous_localization_and_mapping)) -or safety systems. +{/* TODO: Replace with a proper image of Leo Rover with mounted RPLIDAR S3 */} +# SLAMTEC RPLIDAR S3 Integration + +This tutorial will guide you through the process of connecting a LiDAR sensor to +your Leo Rover. + +Light Detection and Ranging devices, or lidars for short, are mechanisms used +for mapping the environment, object detection, tracking the speed of vehicles +and in a wide range of other applications. In robotics 2D lidars, like A2M8 / +A2M12, are used for things such as indoor SLAM +([Simultaneous localization and mapping](https://en.wikipedia.org/wiki/Simultaneous_localization_and_mapping)) +or safety systems. + ## What to expect? After finishing the tutorial you should be able to both gather the lidar data @@ -49,54 +54,103 @@ and visualize it using RViz. Just like in the image below: +The robot will publish +[LaserScan messages](https://docs.ros2.org/latest/api/sensor_msgs/msg/LaserScan.html) +on the `/scan` topic. + ## Prerequisites +Below is the list of all additional tutorials required to complete the +integration. + + + + -## List of components +### Referenced products + + + +## Hardware integration + +### Mounting + +If you bought the integration kit, you can use the mounting adapter included in +the kit. It is designed to mount the sensor on top of the rover's mounting +plate, providing a wide field of view with minimal obstructions. + +Required components: - RPLidar S3 -- RPLidar S3 adapter plate (can be found here: - [Addon adapters](../addon-adapters#rplidar-s3-adapter)) -- M5x10 Allen head screw x4 -- M2.5x6 Allen head screw x4 +- RPLidar S3 adapter plate (included in the integration kit) +- M5x10 Allen head screws x4 +- M2.5x6 Allen head screws x4 + +To mount the sensor: -## Mechanical integration +1. Align the RPLIDAR S3 with the adapter plate and secure it using 4 x M2.5x6 + Allen head screws — one in each corner of the sensor base. +2. Place the assembled sensor on the top of the Leo Rover's mounting plate. +3. Fasten the adapter plate to the rover using 4 x M5x10 Allen head screws. -We developed 3D printable models of mechanical interfaces that allow you to -mount the aforementioned sensor to the mounting plate of the rover. Locating the -sensor at the top of the robot provides a wide field of view with not many -obstacles for the laser beam to get caught on. Get the files from here: -[Addon Adapters](../addon-adapters/). +:::tip + +If you don't have the integration kit, you can also 3D print the adapter plate +yourself. Get the files from the +[Addon Adapters](../addon-adapters#rplidar-s3-adapter) page. + +::: + +:::info + +When positioning the sensor, make sure the laser beam's 360° field of view is +not obstructed by cables, antennas, or other parts of the rover. -- With 4 x M2.5x6 Allen screws, connect the sensor to the printed interface - plate. -- Use 4 x M5x10 Allen screws to fasten the sensor to the Leo Rover. +::: -## Wiring and electronics connection +### Wiring -The sensor can be connected to the robot's main computer via the USB socket -positioned at the top of the rover. If your USB cable is long it might get into -lidars field of view if it sticks up too much. try to hide it in the empty space -inside Leo Rovers back frame. Just like on the photo below: +The RPLIDAR S3 uses a TTL interface and comes with a TTL-to-USB adapter. To +connect it to Leo Rover 1.9, use the following chain: + +1. Plug the TTL cable from the sensor into the **TTL-to-USB adapter** (included + with the lidar). +2. Connect the **micro USB to USB-A cable** (included with the lidar) to the + micro USB port on the adapter. +3. Use the **USB-A to USB-C adapter** (included with Leo Rover) to connect the + cable to the **USB-C port** on top of the rover. + +:::tip + +To avoid the cable getting in the way of the sensor's field of view, you can use +a right-angle adapter for the USB-C port or use the +[easy access cover for the main electronics box](/leo-rover/addons/additional-meb-covers#00188_dev---easy-access-cover) +and wire the cables without using the USB-C port on top of the rover. + +::: -:::info +If the cable is long, try to tuck it into the empty space inside Leo Rover's +back frame to keep it away from the lidar's field of view. -When mounting the sensor, you should be particularly careful not to obstruct the -field of view by other parts of the Rover. +This connection provides both power and data transfer to the sensor, so no +external power source is necessary. However, if you want a cleaner and more +reliable connection, we recommend using the Powerbox addon: -::: - -USB connection provides power to the sensor and allows the data transfer. This -means that no external power sources are necessary. Some lidars might need -external power connections, that's when [Powerbox](/leo-rover/addons/powerbox) -might come in handy. - - + With everything connected, you are ready to try out your new sensor. ## Software integration +:::info + +Perform these steps on the Leo Rover computer. + +::: + The first thing you can do is to make sure your device has the correct permissions and is available at the fixed path on your system. To do this, you -can add the following rule to the udev service: +can add the following rule to the udev service by creating a file named +`lidar.rules` in the `/etc/udev/rules.d/` directory with the following content: ```xml title="/etc/udev/rules.d/lidar.rules" KERNEL=="ttyUSB*", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", MODE="0666", GROUP="dialout", SYMLINK+="lidar" ``` -Paste these lines to `/etc/udev/rules.d/lidar.rules` file and reload udev rules -by typing: +After creating the file, reload udev rules by typing: ```bash sudo udevadm control --reload-rules && sudo udevadm trigger @@ -139,12 +194,10 @@ sudo udevadm control --reload-rules && sudo udevadm trigger Your device should now be available at the `/dev/lidar` path. -We want the sensor functionality to be available in the ROS ecosystem, so you -should install a ROS package that provides a node for the sensor you are trying -to integrate. +Next, install a ROS package that provides a node for the sensor: ```bash -sudo apt install ros-${ROS_DISTRO}-rplidar-ros +sudo apt update && sudo apt install ros-${ROS_DISTRO}-rplidar-ros ``` Now, create a launch file that would start the node with a fitting @@ -160,18 +213,36 @@ configuration. ``` -Include your launch file in the `robot.launch.xml` file, so that your node will -start at boot. +Include your launch file in the `/etc/ros/robot.launch.xml` file, so that your +node will start at boot. -In `/etc/ros/robot.launch.xml`: +Insert the following line between the `` tags of the file: -```xml +```xml title="/etc/ros/robot.launch.xml" ``` +The last step is to either reboot the robot or restart the nodes with: + +```bash +ros-nodes-restart +``` + +### Modifying the URDF model + Your robot should be aware of where the sensor is located and what space it occupies. You can ensure it does that by creating a URDF model of the sensor. +:::note + +The URDF model provided in this guide assumes the sensor is mounted using our +adapter plate in the default position on top of the rover. If you mount the +sensor in a different position, you will need to adjust the origin values in the +URDF file accordingly so that the sensor is correctly positioned in the robot +model. + +::: + ```xml title="/etc/ros/urdf/laser.urdf" @@ -241,7 +312,8 @@ occupies. You can ensure it does that by creating a URDF model of the sensor. ``` -And including it in the description that is uploaded at boot. +And include it in the description that is uploaded at boot in between the +`` tags. ```xml title="/etc/ros/urdf/robot.urdf.xacro" @@ -255,13 +327,13 @@ STL or COLLADA format. ::: -The last step is to either reboot the robot or restart the nodes. +To apply the changes, restart the nodes again. ```bash ros-nodes-restart ``` -## Examples +## Example usage ### Reading and visualizing the data @@ -284,23 +356,23 @@ guide: Step-by-step guide for beginners." /> -Now, open RViz by typing `rviz2` in the terminal, or, if you have the `leo_viz` -package installed, type: +To open RViz, type: ```bash -ros2 launch leo_viz rviz.launch +rviz2 ``` -This will start RViz with visualization of the current robot model. - -:::info +:::note -You can easily install the `leo_viz` package with this command +Make sure that ROS is sourced on your computer, if not you can do it by typing: ```bash -sudo apt install ros-${ROS_DISTRO}-leo-desktop +source /opt/ros//setup.bash ``` +and replacing `` with the name of your ROS distribution, for +example `jazzy`. + ::: On the Displays panel click **Add** -> **By topic** and search for the `/scan` @@ -308,13 +380,14 @@ topic. Choose the **LaserScan** display and click **Ok**. :::info -Sometimes the scan data might not be visible as it will melt with the +Sometimes the scan data might not be visible as it will blend in with the background. To fix this you need to change the color of the displayed laser. To do so, use the drop down arrow option from added **LaserScan** and set **Color Transformer** to **FlatColor**. As you do so, there will appear **Color** option @@ -322,6 +395,7 @@ which you can use to change the displayed laser. @@ -336,6 +410,7 @@ display. @@ -344,6 +419,7 @@ Be sure to select `/camera/image_color` as the Image Topic. @@ -355,18 +431,19 @@ Here's an example end result: id="oD5Sp7T0Ki0" params="autoplay=0&autohide=1&showinfo=0&rel=0" poster="hqdefault" - title="Leo Rover Unboxing and Getting Started" + title="Leo Rover with RPLIDAR S3" webp /> -## What next? +## What's next? Lidars are commonly used in projects involving [autonomous navigation](/leo-rover/advanced-guides/autonomous-navigation), you might be interested in a tutorial about it. -They are however, not the only way of teaching a Leo Rover how to move on it's -own. Check out our [line follower](/leo-rover/1.8/leo-examples/line-follower) +They are however, not the only way of teaching a Leo Rover how to move on its +own. Check out our [line follower](/leo-rover/leo-examples/line-follower) tutorial if you want to learn more. You can also check our -[Integrations page](/integrations) for more instructions. +[Integrations page](/integrations) for other sensors that might complete your +setup. diff --git a/src/products/slamtec-rplidar-s3.mdx b/src/products/slamtec-rplidar-s3.mdx new file mode 100644 index 00000000..6b298135 --- /dev/null +++ b/src/products/slamtec-rplidar-s3.mdx @@ -0,0 +1,12 @@ +import ProductPreview from '@site/src/components/ProductPreview'; + +{/* TODO: Replace imageSrc with a proper product image when available */} + +