Planning Group Workshop notes (4 8 21)

Setup

Let's start by setting up the tools we'll use for development. These are:

• Git (here)
• Docker and Docker Compose
  • Windows users: Docker for Windows includes Compose already, but be sure to install WSL components during the Docker installation (here)
• Voltron Development Environment (VDE) files

For our demonstration today, you'll also want to download this ROS bag, which includes simulated Lidar data. Download the whole folder and unzip it.

Installing VDE

1. Create a folder in a convenient place on your system. This is where we'll store our VDE container files.
2. Open your system's command line. On Windows, you can navigate to your new folder in the File Explorer, then click File -> Open Windows PowerShell -> Open Windows PowerShell. This will open your command line within the folder.
3. Once your command line is in the new folder, type git clone https://github.com/Voltron-UTD/vde.git. This will (basically) download VDE.
4. Move into the new VDE folder using cd vde.
5. Finally, run the startup script.
   • On Windows, type .\start.bat (while in the VDE folder). You can also double-click "start.bat" in your File Explorer instead.
   • On Linux, run ./start.sh. You may need to first give the script execution permissions by running sudo chmod +x start.sh.

On first run of the startup script, Docker will download some more files for you. It will take some time. Afterwards startup is very quick.

Setting up your workspace

In ROS lingo, a "workspace" is simply a folder on your system where your code is built and stored. Workspaces follow a specific structure. All ROS packages, including Autoware.Auto, are stored in workspaces. A workspace can store multiple packages, and a package can store multiple executables ("nodes").

Let's set up our own workspace for Voltron. Luckily, we have scripts to do this for us.

1. Within VDE (Did you run the startup script? Your terminal will say docker@vde:~$), run git clone https://github.com/Voltron-UTD/luna_ws.git.
2. Run cd luna_ws to enter the new folder, then run python3 init.py to start the convenience script.
3. A warning will explain that any existing files in the folder will be cleared. We just created this folder, so there's nothing to clear. Type y then press enter.

Our ROS workspace, "Luna WS," is set up!

Creating our first package

Let's create a simple package that reads incoming Lidar data and calculates the "center" of the observed point cloud. These steps are mostly taken from the ROS2 docs.

1. Once again, make sure you're within VDE. If you aren't, run the start script.
2. "Source" your ROS installation by running source /opt/ros/foxy/setup.bash.
   • Sourcing makes all of the ROS code visible to the operating system. Without sourcing, your computer would not know where to find the programs that you ask it to run. Many ROS-related issues can be fixed just by sourcing things.
3. Move to the source code folder of the workspace by running cd ~/dev_ws/src. "src" is where we'll keep all the code we write.
4. Run ros2 pkg create --build-type ament_cmake --dependencies rclcpp sensor_msgs --node-name lidar_printer voltron_tutorial.
   • --build-type ament_cmake indicates that we're using C++, so that we'll build using CMake. Not important to understand that now.
   • --dependencies rclcpp sensor_msgs says that our package will depend on rclcpp (ROS Common Library for C++, basically the ROS API) and sensor_msgs (a C++ library that can interpret incoming sensor data, like Lidar point clouds).
   • --node-name lidar_printer generates a node named lidar_printer within our package.
   • voltron_tutorial is the name of our new package
5. Keep your command line with VDE open. You'll be using it in a bit.

The "pkg create" script is just for convenience. You can write all the necessary files that it generates yourself, but who has time for that?

Editing the package code

Now's a good time to mention that VDE (Docker) creates a link between the home folder within the container (everything under cd ~) and the user folder of the host PC (on Windows, C:\Users\[Your Username]\vdehome. As VDE is currently configured, only files stored in this linked folder persist across VDE sessions. All other files are reset once VDE is restarted.

The folder link is useful for, say, working on code in an IDE on your host PC. Let's do that.

Writing the node, "lidar_printer"

1. Open the workspace folder in your favorite IDE/text editor. On Windows, this folder is C:\Users\[Your Username]\vdehome\luna_ws.
2. Open ./src/lidar_printer.cpp in the editor.
3. We can go over this code together, but at the end of the day, lidar_printer.cpp needs to look like this. Be sure to save it.
4. In your VDE terminal, navigate to your workspace folder (cd ~/luna_ws).
5. Build the code we just wrote by running colcon build.
6. Source luna_ws by running source install/setup.bash in your workspace's root.
7. Finally, run our new node using ros2 run voltron_tutorial lidar_printer
   • Remember that voltron_tutorial is our package name and lidar_printer is our node name.

The node should throw an exception: Field x does not exist. The node is complaining that it can't find an Lidar data. Let's give it some.

ROS bag setup

"ROS bags," or simply rosbags, are files that allow us to record and reply sensor data, among other info. We'll use it here to play back some Lidar data.

1. Did you download the rosbag from the beginning? If not, do so here and unzip it.
2. You'll want to now move that rosbag (the whole folder) into our linked folder. It doesn't matter where, but VDE will need access to it.
3. Within VDE, navigate to the directory where you kept your rosbag (the parent of the rosbag folder) and run ros2 bag play -l lidar_rosbag
   • -l means "run on a loop"

Adding a launch file

1. In your text editor, create a new folder within luna_ws/src/voltron_tutorial called launch, create a new file called lidar_printer.launch.py and paste this into it.
2. Add

install(DIRECTORY
  launch
  DESTINATION share/${PROJECT_NAME}/)

to CMakeLists.txt line 36, above if(BUILD_TESTING). 3. Finally, rebuild your workspace by doing, in VDE, cd ~/luna_ws and colcon build.

Running the launch file

1. Source your workspace (since you've rebuilt and added a new file) by running source install/setup.bash within luna_ws.
2. We'll also now need to source Autoware since we'll be using some of their code. Run source /opt/AutowareAuto/install/setup.bash.
3. At last! Run ros2 launch voltron_tutorial lidar_printer.launch.py. It should start printing average points from the rosbag data.