watonomous.github.io

  1. Software Division
  2. Software Division Home
  3. Tutorials

[ Software Division : Software Pipeline Integration Tutorial (OUT OF DATE) ]

Created by [ Rowan Dempster], last modified by [ Charles Zhang] on Jan 04, 2021

Since the dawn of WATO, the term "integration" has struck fear into the bravest of hearts.

"Always do what you are afraid to do." -Ralph Waldo Emerson

Integration refers to the process of running your code in conjunction with all the other modules on the team (driver, perception, processing, path planning) on the car's rugged computer (often called rugged, crystal). In other words, integration is the final boss before your code can be used by the car.

Software

Software Integration refers to compiling perception, prediction (processing), decision (path planning), ros_msgs git repos together in the same catkin workspace. Assuming you've already had your development environment (Ubuntu 16.04, ROS installed, additional ROS packages) setup properly according to Software Onboarding Tutorial, the first step would be to download the required gitlab repos. None of this steps below should feel foreign once you're acquainted with C++, bash, git and ROS, this document expedites that process by showing one way (albeit less flexible) to get the software pipeline running on your computer.

1. Setup an integration catkin workspace

This can be anywhere, the important thing here is that running catkin_make will look for a folder called src in this directory and also create folders named devel and build. In this guide, I will assume that you create this in your home folder, i.e. ~/integration for simplicity.

For vagrant users, if you have setup watobox using the Software Onboarding Tutorial, your box comes with many VirtualBox additions pre-installed. One of them is the shared folder feature. On your host machine, the folder in which the watobox Vagrantfile is stored is mounted in the guest machine under /vagrant. This means that if you can create your catkin workspace in that shared folder, which I personally use /vagrant/integration, and use code editors from your host machine rather than in the VM. If so, please mentally replace all instances of ~/integration with /vagrant/integration as you read through this guide.

So I would run: mkdir -p ~/integration/src

[2. git clone *]

zMake sure that you're in the catkin workspace folder name of choice.

So I would run: cd ~/integration/src.

And clone the repositories (I put the HTTPS links, but I personally use SSH):
git clone https://git.uwaterloo.ca/WATonomous/perception-year-2.git #contains perception code
cd perception-year-2; git checkout integration-exercise; cd .. #use the exercise branch
git clone https://git.uwaterloo.ca/WATonomous/prediction.git #contains processing code
cd prediction; git checkout integration-exercise; cd .. #use the exercise branch
git clone https://git.uwaterloo.ca/WATonomous/decision.git #contains path planning code
cd decision; git checkout integration-exercise; cd .. #use the exercise branch
git clone https://git.uwaterloo.ca/WATonomous/ros_msgs.git #contains ROS messages used across perception, processing and path planning
cd ros_msgs; git checkout integration-exercise; cd .. #use the exercise branch
After this step, my catkin workspace would look like:

integration/
  src/
    perception/
    prediction/
    decision/
    ros_msgs/

3. catkin_make

catkin_make is a ros command which wraps around cmake, which wraps around g++. You need to invoke it at the root of your catkin workspace (i.e. the directory which contains the src folder). If you've followed this guide, that folder is ~/integration.

So I would run:
cd ~/integration #we are now in the same directory as the src folder
catkin_make #compile our C++ code as well as the ros wrappers around it
source devel/setup.sh #sets many environment variables for ROS to know where our build is

If catkin_make outputted errors, it's likely that you're not on the following branches for each repository:
perception: integration-exercise
prediction: integration-exercise
decision: integration-exercise
ros_msgs: integration-exercise

After this step, my catkin workspace would look like:

integration/
  src/
    ...
  devel/
    ...
  build/
    ...

For the curious, feel free to explore the content of the build folder. Not only will it contain C++ code that we have written, but we clearly see the implementation of ROS pub-sub pattern in C++. This is what our code would look like if ROS didn't provide us with a library of helper classes. Each catkin_make will also use the existing build folder as a cache, thus sometimes if you run into obscure scenarios of your code not building, consider rm -rf ~/integration/build and run catkin_make from a cacheless state.

If you went with the /vagrant/integration shared folder path. You may run into many warning messages about clock skew. Feel free to ignore this, or to fix it by googling how to use ntp clients on both your host and guest machines.

4. roslaunch software.launch

Now that we've compiled successfully. We are ready to launch our pipeline. Save this file somewhere. I personally put it in the src folder.

A command line way of saving the file to my personal catkin workspace:
curl https://phabricator.watonomous.ca/file/data/etqw4zdxoxxwh3zltcwq/PHID-FILE-6jmfarspbf6vfhghw3rf/software.launch > ~/integration/src/software.launch

Roslaunching the file, using ~/integration/src/software.launch as its location:
roslaunch ~/integration/src/software.launch

For the curious, the step above can be run anywhere on your system. The reason is because ROS uses environment variables (which were sourced earlier with source devel/setup.sh). While it might seem convenient at first, it also means that you should roslaunch from the terminal window from which you ran source devel/setup.sh. Using another terminal window would require you to source it again. No other ros command will require the sourcing, so they are free to be run from other terminal windows.

4.1 Group specific launch files

Path Planning: roslaunch path_planning planner_main.launch
Possible issues: path planning freezes (green car is stopped), rosrun path_planning local_planner

5. rosbag play some sensor data

At this point, your screen may look something like this:

[{.confluence-embedded-image .confluence-external-resource}]

And nothing happens...

This is because the software pipeline runs on a callback basis. Path Planning is waiting for environment publishings (currently passed through the /environment_prediction rostopic) from Processing. Processing is waiting on the Novatel IMU's odometry data (passed as /navsat/odom by the Novatel driver, environments can be published without detections) and detections from Perception (currently passed through the /stopline_detection_output, /bounding_boxes, /lane_detection_output). Perception is waiting on camera data (published by the pointgrey camera driver as /camera/image_color for the purpose of this guide, we now further differentiate them as we use more than 1 camera).

When we run this on the car, we also run all the sensor drivers which publish to the topics required to execute the software pipeline. On our own laptops, we can't do that. To develop and test our changes, we then need to somehow publish to those topics. Perception in the past has built a rosnode to publish images to /camera/image_color to run algorithms on any picture. However, data for some topics are easier to fake than others.

rosbag is a package developed by ROS which can solve this problem. The set of rosbag commands allow us to record and playback rostopics. When we take the car for a manual drive, we will often call it rosbagging. By rosbagging sensor data, we can then play them back in chronological order and effectively get software pipeline outputs as if we had ran the pipeline at the time of recording.

Most of our uncompressed rosbags are located on the Rugged. See Rosbag Tutorial for how to get access to the RosBag server.

You can download it anywhere, I personally like to keep it at the same level as the catkin workspace, under ~/rosbags:

integration/
  ...
rosbags/
  ...

Roslaunch again using the previous step. Once all the nodes have been started, we will playback this rosbag in a new terminal:
rosbag play 2018-05-02-13-29-18_first15s.compressed.bag # you can add -l to loop the bag as it is only 15s long

At this point, your rosbag playback terminal should look something like:

[{.confluence-embedded-image .confluence-external-resource}]

And your roslaunch terminal should look something like:

[{.confluence-embedded-image .confluence-external-resource}]

All stdout will be outputted to this screen. What you're witnessing here is path planning code not removing their debug statements before merging. To find all their occurrences, you can grep for ROS_INFO, which is a wrapper function around std::cout.

For the curious of what info might be contained in the rosbag, I recommend reading Rosbag Tutorial and Sensor Data Collection (a.k.a. Rosbagging) Tutorial.

For the efficient workflow enthusiast, I recommend using tmux. While it is not strictly necessary to launch the pipeline, as you could simply open many terminal windows or use some terminal multiplexer, you will find that tmux reduces the pain points of many WATO workflows. For vagrant users, it becomes possible to detach from tmux sessions on the guest machine, suspend the VM, resume it later, reattach to the tmux session and continue without having to set up your terminals again. This also applies to users who often SSH into computers in the bay.

Conclusion

If you've made it this far, you have all the tools necessary to change the code, log using ROS_INFO, rebuild it and test it on sample data. Now go make WATO great again.

Comments:

+———————————————————————–+ | [] | | | | I still think we should finish setting up git submodule configs so we | | don't need to manually clone repos, it would also formally define a | | proper vehicle deployment file structure. | | | | {.smallfont align=”left” style=”color: #666666; width: 98%; margi | | n-bottom: 10px;”} | | | | Posted by henry.wang at Jan 01, 2020 12:59 | | | +———————————————————————–+

Document generated by Confluence on Dec 10, 2021 04:02

Atlassian