Getting Started in Week 1

Before you get started on Assignment #2 (as detailed in the pages that follow), you should work through the following tasks in your teams during the first lab in Week 1.

Set Up Your Team's ROS Package¶

As discussed on the Assignment #2 Overview, everything that your team submit for this lab assignment must be contained within a single ROS package. Inside this you will develop all the necessary nodes to make a TurtleBot3 Waffle (real or simulated) complete each of the assignment tasks. Each task will be assessed by the Teaching Team via launch files that you must also provide within your package. You'll therefore need to create one launch file per task (we'll talk more about this later).

The first step however is to create your team's ROS Package.

Only one member of your team needs to actually do this bit, and it's best to do this from within your own ROS installation (or WSL-ROS), rather than on the robotics laptop that you will use to work with the real robots in the lab. Select a team member who has access to their own ROS installation in the lab now (i.e. via a personal laptop), or access WSL-ROS using one of the "WSL-ROS laptops" that are also available in the lab.

Follow the steps below to create your team's ROS package, initialise it as a Git repo, and push it to GitHub to allow for sharing and collaboration amongst your team¹. You should then be able to transfer your package to one of the robotics laptops easily in the lab when required (we'll provide further details on how to do this later).

Configure Git¶

Warning

Only do this bit on your own personal ROS installations (or in WSL-ROS), NOT on one of the robotics laptops!

If you haven't done so already, you'll need to make sure Git is configured properly in your local ROS installation before you do anything else.

From a terminal instance located in your home directory (cd ~) run the following commands to update your personal details in the global Git config file on your machine:
```
git config --global user.name "{your name}"
```
...replacing {your name} with your actual name! E.g.: git config --global user.name "John Smith"
```
git config --global user.email "{your email address}"
```
...replacing {your email address} with your actual email address!
If you're working in WSL-ROS on a University machine, don't forget to run wsl_ros backup to save these changes to your external WSL-ROS backup file, so that they will always be restored whenever you run wsl_ros restore in a fresh WSL-ROS instance on another machine.

Note

All team members will actually need to do this bit before interacting with Git!

Regardless of which team member is setting up your team's ROS package to begin with, you'll all need to interact with Git for this assignment, and you should therefore each set up your own individual Git configurations (via the steps above) before working individually on your team's ROS package.

Create Your Team's Assignment #2 ROS package¶

Remember

Only one team member needs to do this next bit! But you'll then need to share it with the rest of your team members via an online code repository (e.g. GitHub), by making the rest of your team members collaborators.

In your local ROS installation, navigate to the catkin_ws/src directory:
```
cd ~/catkin_ws/src/
```
Use the catkin_create_pkg tool to create a new ROS package (as covered in Assignment #1):
```
catkin_create_pkg com2009_team{} rospy
```
...replacing the {} with your team number!

Warning

It's really important that you follow the naming conventions that we specify when defining your package (and creating your launch files). If you don't then you could receive no marks!
Run catkin build and then re-source your environment:
```
catkin build com2009_team{}
```
```
source ~/.bashrc
```
WSL-ROS Tip

Use the src alias for this command!
Then navigate into the package directory that should have just been created:
```
cd com2009_team{}/
```
This should already contain a src folder for you to populate with all your Python ROS nodes. Create a launch folder in here too, which you will use to store all your launch files:
```
mkdir launch
```
Create a placeholder file in the src and launch directories, just to make sure that these folders both get pushed to GitHub when we get to that part in the following section:
```
touch src/placeholder && touch launch/placeholder
```
(you can delete these later on, once you start creating your own Nodes and launch files.)
Then follow the steps in the next section to import this project to GitHub (other online code repositories should work similarly)...

Push Your Package to GitHub¶

Remember

Only one member of your team needs to do this bit too!

These instructions are taken from this GitHub Docs page. Instructions may vary if you are using other online code repositories (such as GitLab for instance), so check with your target provider.

Create a new (private) repository on GitHub.com, but DON'T initialise the new repository with a README, license, or gitignore (you can do this later, it'll cause issues if you do it at this stage).

From docs.github.com

Call this repository com2009_team{} to match the ROS package that you've just created.
Head back to your local ROS installation, where you created your ROS package in the previous section. Make sure your terminal is located in the root of your new package directory:
```
roscd com2009_team{}
```
Initialise the package as a Git repo:
```
git init -b main
```
Stage all the initial files in your package (including the placeholders) for an initial commit:
```
git add .
```
Warning

Don't forget the . at the end there!
Then commit them:
```
git commit -m "First commit"
```
Head back to GitHub on the web. At the top of your repository on GitHub.com's Quick Setup page, click the button to copy the remote repository URL (HTTPS).

From docs.github.com
Then, go back to your local terminal and add the URL to the remote repository:
```
git remote add origin {REMOTE_URL}
```
Change {REMOTE_URL} to the URL that you copied in the previous step, and get rid of the curly brackets ({})!

Then verify the new remote URL:
```
git remote -v
```
Finally, push the changes from your package (your "local" repo), to your "remote" repository on GitHub:
```
git push origin main
```
You'll then be asked to enter your GitHub username, followed by a password. This password is not your GitHub account password!

Warning

Your GitHub account password won't work here! You'll need to generate a personal access token (classic) and use this instead!
Back on GitHub, add your team members to the repo as collaborators. All team members should then be able to pull the remote repo into their own Catkin Workspaces (cd ~/catkin_ws/src/ & git clone {REMOTE_URL}), make contributions and push these back to the remote repo as required (using their own GitHub account credentials and personal access tokens).

You'll need to copy your ROS package onto the Robot Laptops when working on the Real-Robot based tasks, which we'll cover in more detail later.

Getting to Know the Real Robots¶

All the Assignment #2 Tasks will be assessed using real robots, and you'll therefore have access to the robots for every lab session so that you can work on these tasks as you wish. All the details on how the robots work, how to get them up and running and start programming them can be found in the "Waffles" section of this course site. You should proceed now as follows (in your teams):

Everyone must complete a health and safety quiz (on Blackboard) before you (or your team) work with the real robots for the first time. Head to Blackboard and do this now, if you haven't already.
Each team has been assigned a specific robot (there's a list on Blackboard). When you're ready, speak to a member of the teaching team who will provide you with the robot that has been assigned to you.
Work through each page of the "Waffles" section of this site (in order):
1. Read about the hardware.
2. Learn how to launch ROS and get the robots up and running.
3. Have a go at the initial exercises on the Basics of ROS & the Waffles, which will help to get you started and understand how ROS and the robots work.
4. Review the Shutdown Procedures and follow the steps here to shut down the robot and power off the robotics laptop at the end of each lab session.
5. Finally, there are some Fact-Finding Missions which are also really important, but you'll need to have completed certain parts of Assignment #1 before you can complete them all. Either way, have a read through them at this stage and work through the bits that you can (if any).
  
  Important
  
  Make sure (as a team) you have completed ALL the Fact-Finding Missions before the end of Week 6.

As a University of Sheffield student, you can apply for the GitHub Student Developer Pack, which gives you access to a range of developer tools including GitHub Pro. GitHub Pro allows you to have unlimited collaborators on your repositories, which might help you to collaborate on your ROS package with your team. ↩