Warmup Project

Objectives

Your goal in this project is to get comfortable programming the Turtlebot4 robot by programming it to perform several behaviors: driving in a square, following a person, and following a wall. Additionally, in the process, you'll learn about tools and strategies for debugging robot programs. If you have any questions about this project or find yourself getting stuck, please post on the course Slack or send a Slack DM to the teaching team. Even if you don't find yourself hitting roadblocks, feel free to share with your peers what's working well for you.

Learning Goals

Get comfortable with ROS2
Brush up on your Python programming
Learn about processing sensor data from the robot
Learn about programming robot behaviors
Learn ways to debug robot programs
Learn about reactive robot control

Logistics

This assignment is to be completed individually. You can get help from your fellow classmates setting up your programming environment and completing the ROS2 introduction. For the meat of this problem set (programming Turtlebot4 behaviors), you can ask your fellow classmates for general advice or tips on ROS2/robot programming, however, the work of programming the robot's behavior must be done by you (no use of genAI to generate code, no sharing code, no copying code, no looking at other people's code).

Deliverables

You'll set up your code repository using Github Classroom and submit your work on Gradescope (accessible via Canvas). You'll want to put the warmup_project git repo within your ~/intro_robo_ws/src/ directory (where ROS2 packages should be located).

Note: If you're new to Github, please make an account and familiarize yourself with the basics of Github. This is a link to the Hello World Github Guide, which presents the fundamentals of using Github. The free version of Github should be enough for the purposes of this course. However, if you would like, you can get the pro version as a student from here for free.

Code

Please use the following names for your python scripts, so we can easily identify them:

warmup_project/warmup_project/drive_square.py
warmup_project/warmup_project/person_follower.py
warmup_project/warmup_project/wall_follower.py

When grading your code, we'll be looking for:

Readable variable names
At minimum, light commenting of your code, for example:
- 1 comment per function
- 1 comment per conditional
- 1 comment per loop
- 1 comment per 5-10 lines of code

rosbags

For each of the behaviors you program for your robot, we ask that you record your robot performing that behavior in a rosbag. Please (1) record ONLY the /scan and /cmd_vel ROS2 topics and (2) MINIMIZE the time between when you run ros2 bag record and when you run your code so that your bagfiles aren't enormous and so the TAs don't have to wait 1-2 minutes for your bag file to play. Please put all of your rosbags in a bags directory within warmup_project with the following names:

warmup_project/bags/drive_square.bag
warmup_project/bags/wall_follower.bag
warmup_project/bags/person_follower.bag

You can record a rosbag using the following command:

$ ros2 bag record -o [rosbag-name] [topic-names]

To play back the rosbag (to check that it recorded properly), you can use the following command:

$ ros2 bag play [rosbag-name]

For more information on rosbags, please refer to the Recording and playing back data ROS2 resource page.

Writeup

Modify the README.md file as your writeup for this project. Also, feel free to checkout this Mastering Markdown Github Guide page for tips on how to style your README.md. Your writeup should include:

For each robot behavior, please provide the following:
- A high-level description (a few sentences): Describe the problem and your approach at a high-level. Include any relevant diagrams or pictures that help to explain your approach.
- Code explanation (a couple of sentences per function): Describe the structure of your code. For the functions you wrote, describe what each of them does.
  - Additionally, please specify what LiDAR models your code works with (LDS-01, RPLIDAR-A1, or both).
- A video: Record a video of the physical robot performing the behavior. Include this video in your writeup as either a gif (preferred) or embedded video (including a link to a video file will not be accepted, the video must be able to be viewed directly in the writeup).
Challenges (1 paragraph): Describe the challenges you faced programming these robot behaviors and how you overcame them.
Future work (1 paragraph): If you had more time, how would you improve your robot behaviors?
Takeaways (at least 2 bullet points with a few sentences per bullet point): What are your key takeaways from this project that would help you/others in future robot programming assignments? For each takeaway, provide a few sentences of elaboration.
Use of genAI statement(1 bullet point per use of genAI): Describe how you used any generative AI tools or techniques in your project with one bullet point for each use of genAI. If you did not use any genAI tools, simply state, "I did not use any genAI tools in my work on this assignment." As a reminder, the genAI policy is listed on the syllabus page and details acceptable and unacceptable uses of genAI in this course.

Note: We highly recommend that you do not leave the writeup of this project to the last minute. You will have a much better writeup if you write incrementally, as you progress through the project. Writing up your work as you go may even help you think through your robot programs and improve the implementation and organization of your robot programs.

Grading

The warmup project will be graded as follows:

29% Writeup
- 7% Driving in a Square Writeup & video/gif
- 7% Person Follower Writeup & video/gif
- 7% Wall Follower Writeup & video/gif
- 6% Challenges, Future Work, Takeaways
- 2% Use of genAI Statement
6% ROS2 Bag Recordings
65% Code
- 20% Driving in a Square Code
  - 17% Implementation
  - 3% Code Comments & Readability
- 22% Person Follower Code
  - 19% Implementation
  - 3% Code Comments & Readability
- 23% Wall Follower Code
  - 20% Implementation
  - 3% Code Comments & Readability

Deadlines & Submission

Deadlines

Monday, October 6 8:00pm - Complete the "driving in a square" robot behavior, rosbag recording, and writeup. For the writeup, you will need to complete the following sections:
- Driving in a Square
  - High-level description
  - Code explanation
  - Video/gif
- Use of genAI statement
Thursday, October 9 8:00pm - Complete all of the robot behaviors and the writeup.

Submission

You will use Gradescope to submit your warmup project deliverables:

To Submit Your Materials to Gradescope: Access the Intro Robo Gradescope site via Canvas, select the appropriate assignment, and choose GitHub as the submission method.
- The first time you submit your repository, you will need to authorize Gradescope to access your git repository. Select the appropriate repository and branch.
Multiple Submissions Allowed: You can submit multiple times before the deadline. Your last submission will determine your grade.
Viewing Grades & Feedback: Once assignments are completely graded, you will be able to see your grade and assignment feedback on Gradescope. Your grade will also automatically be uploaded to Canvas.

Getting Started

Before you're ready to program your robot, you'll need to take the following steps:

Follow the instructions on the Computer Setup resource page to set up your programming environment and configure your colcon workspace for programming the Turtlebot4 robot.
Complete the Introduction to ROS2, which includes a tutorial on how to write a simple ROS2 publisher/subscriber node in Python.
Accept the GitHub Classroom invite (accessible via Canvas on the Warmup Project assignment description) to access the starter git repo warmup_project, putting it within your ~/intro_robo_ws/src/ directory (where ROS2 packages should be located).

Running Your Code

Follow the steps on the Physical Turtlebot4 page to establish a connection to the robot. Once the robot is on and connected, you can run your code:

$ ros2 run [package-name] [name-of-your-script]

Where [package-name] is the name of your ROS2 package (e.g., warmup_project) and [name-of-your-script] is the name of the entry point for your Python script (e.g., drive-square).

To make it easier to grade everyone's code, please use the file names and entry point names as specified below. Your setup.py file should contain the following in the entry_points section:

entry_points={
    'console_scripts': [
        'drive-square = warmup_project_solutions.drive_square:main',
        'person-follower = warmup_project_solutions.person_follower:main',
        'wall-follower = warmup_project_solutions.wall_follower:main',
    ],
}

Turtlebot4 Behavior Programming

Driving in a Square

Your goal is to write a ROS2 node that commands the Turtlebot4 robot to drive a square path. The best way to do this is using a timing approach (e.g., move forward for a fixed amount of time then make a 90 degree turn four times). The following is an example of what you can expect your drive in a square behavior to look like:

Tips:

One thing you should notice right away is that there is noise in the environment and in the mapping of your commands to the robot and how it executes them. Your robot will not perfectly execute your commands due to friction, imprecise elements of controlling physical motors, etc.
Your driving in a square does not have to be "perfect". It should roughly drive in a square. If it ends up a few inches away from where it started, that's more than fine.
If you are spending hours on this, hitting mental walls, or feeling frustrated, reach out to the teaching team for help! This is your first time programming a robot, give yourself some slack, and reach out for help. That's what we're here for!

Person Follower

Your goal is to write a script that follows a person (or its closets object) while maintaining a safe distance. We recommend that you use the /scan rostopic, which contains the data from the robot's LiDAR to determine the robot's relative position to what's surrounding it. Pay close attention to how your robot determines where a person is and make sure your robot is facing the supposed person once it gets to the safe distance. The behavior should look somewhat like the following:

Tips:

You'll want to think about how to use the /scan ROS2 topic.
You'll need your Turtlebot4 to adjust to changes in the "person"'s location (e.g., the person may originally be at location x and the robot is heading towards x, and before the robot reaches x, the person's location may change to y, and the robot will need to immediately adjust its plan).
You'll want to be able to handle a scenario where the "person" is 3 meters directly behind the robot.

Wall Follower

Your goal with this robot behavior is to 1) have your robot navigate close to a wall, 2) drive alongside the wall at an approximately fixed distance, and 3) handle corners. If we were to put the robot in a square room, we would expect it to run around the room (following the walls) indefinitely. Here is an example of what your wall follower implementation may look like:

Tips:

Your robot should be able to follow walls and round corners in any environment with a wall and shouldn't be specifically programmed to follow walls in the square room provided (if we drop your robot anywhere in this square room, it should be able to find a wall and start following it).
You may find this diagram helpful when thinking about what the goal should be of your robot controller:

Acknowledgments

The design of this course project was influenced by Paul Ruvolo and his Fall 2020 A Computational Introduction to Robotics course taught at Olin College of Engineering. The gifs providing examples of the robot behaviors are used with permission from former students Ting-Han Lin, Samir Rajani, Emilia Lim, Josephine Passananti, and Elizabeth Singer.