Lab 1.1: Setting Up Your Environment

Before we can get started in class, you will need to set up a few things on your computer. If something goes wrong during the semester, you may need to repeat some of these steps. If you have any trouble while installing please reach out on the class slack workspace.

The commands below assume you are using something like a Linux terminal (e.g. a Bash Shell). If you use MacOS, most of these will work as is or with very minor changes.  For Windows Systems: we highly recommend using Ubuntu on Windows Subsytem for Linux 2: https://documentation.ubuntu.com/wsl/stable/howto/install-ubuntu-wsl2/, however, you may find other ways to do this if you wish.

Commands below that should be put in a terminal are preceded by $. Required variable components are in <> brackets and optional are in []. Example:

$ some_command <required_component_to_fill_in> [some_option]

Setup Your Docker Workflow

Most assignments in this class can be completed on any system that can run Docker Desktop: https://docs.docker.com/desktop/. For the few assignments that cannot be run like this, you can use a lab computer in DAN-407, a loaner laptop, or a labmate’s computer. Many of the instructions below are highly system dependent, so you will be referred to the developers’ websites for installation instructions.

1. Scroll down to “Install Docker Desktop” on this website and follow the instructions for your system: https://docs.docker.com/desktop/
2. For MacOS:
   1. You will need to install something to support graphical interfaces. The easiest is usually XQuartz. Download and install here: https://www.xquartz.org
   2. EACH TIME YOU BOOT UP YOUR COMPUTER:
      1. Start the XQuartz app
      2. In a terminal, run:

         $ xhost +

3. You may now proceed to the next section.

Setup Your git Repo

We will use git to manage code in this class. This will be the way that you submit solutions to assignments and receive class code from the instructor. This step only needs to be performed ONCE for the semester. You will use the same git repo for all assignments and labs (except possibly the final project).

These instructions are designed for use on github.com. They may work using other git services, but for simplicity, only instructions for GitHub are provided. Please let the instructor know if you use a service besides GitHub.

1. If you do not have one already, create an account on github.com 
2. If you have not already done so, create an SSH key using these instructions: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
   NOTE: make sure to select the correct operating system from the top of the page!
3. A template is provided for you to create your own repo. GitHub has an easy way to create your own repo in the form of this template. Go to: https://github.com/UML-EECE-5560/student-jazzy-base and click the green “Use This Temple” button.
   
4. Come up with a name for your repo using ONLY lowercase letters, numbers, and dashes. If you are in class, see the TAs to ensure this is a UNIQUE REPO NAME for the class. If not, use the spreadsheet found in Blackboard for the same purpose.
5. Continue following the GitHub prompts to name your repo. Make sure to set it to PRIVATE. You may name your repo whatever you like as long as it follows these requirements. Creating a private repo should be free. If GitHub tries to charge you, associate your university email address with your GitHub account and it should become an educational account.
   
6. Share the repository with:
   1. The instructor, username: paulrobinette
   2. The TAs, usernames: Noothoot and Alexander-MacConnell
7. Now, we need to clone your git repo. You can find your repo URL on the top right of the page on GitHub. Click the green “Code” button, click the “ssh” tab and copy that URL, then run in a terminal:

   
   $ git clone <repo_url>

   Note that this will clone your repo into your current folder as a new folder with whatever name you gave your repo on GitHub. You may need to clone your repo a few times in class. It is fairly easy to break your local copy, but it is even easier to download a fresh copy from GitHub and try again! Just run the clone command again.

8. If you have not used git before on this system, setup your name and email address:

   $ git config --global user.name "<your-name>"
   $ git config --global user.email "<your-email>"

Using ROS2

You are now ready to use ROS2! First, let’s talk about the difference between your regular terminal and your docker container. Your regular terminal is whatever comes with your system. Take a look at the command prompt (the text shown when you start a new terminal). Yours is likely different, but mine looks like this:

Pauls-MBP-2024:student-jazzy-base paulrobi$

This shows my laptop’s name (Pauls-MBP-2024), my current working directory (student-jazzy-base), and my username (paulrobi) followed by something that shows commands will follow: $

1. Let’s get set up to start your Docker container. Change directory to your git repo. If you have just cloned it, this should look like:

   $ cd <your-git-repo-directory>

2. There is a script in this directory to build your docker image. Run:
   $ ./build.sh
   If this gives any error, report it to the instructor or TAs either in person or on Slack.
   For MacOS: you may receive the following warning if your computer uses Apple Silicon. It is ok for you to proceed.
   

    1 warning found (use docker --debug to expand):
   
    - InvalidBaseImagePlatform: Base image paulrobinette/eece5560-jazzy-class-image:v1 was pulled with platform "linux/amd64", expected "linux/arm64" for current build (line 1)

3. Now that your image is built, we can start your container. You should see several “run” scripts in this directory (hint: use the command “ls” to see the files in the directory). Choose the one that is the best option for your system and run it: $ ./run-<your_OS>.sh
4. You should now see a DIFFERENT command prompt. Mine looks like:

   paulrobi@7c7136f7bf6e:/$ 

   This time, it starts with my username, then gives some sort of system name (this is internal to Docker and you don’t need to worry about it), then the current directory (/ or root) and finally the familiar $ indicating you may type a command.

5. Note the difference between this and your normal terminal! It likely looks different than mine, but it will be distinct. This is now your DOCKER CONTAINER. Some of the commands given should be run in your DOCKER CONTAINER and some should be run in your terminal. Knowing the difference will save you effort!
6. In your docker container, run the following command to source your environment. Note that you need to run a command like this in any new container or connection to a container (more on that later).

   $ source /opt/ros/jazzy/setup.bash

7. Now let’s start up turtlesim so we can play with ROS2:

   $ ros2 run turtlesim turtlesim_node

8. You should see a new window with an icon of a turtle in the center of it. If not, check your container terminal for any errors and report those to the instructor/TA or on Slack.
9. Start up another terminal and connect it to your container using the following script:

   $ ./attach.sh

10. Now you have a new connection to your container! You should see the same sort of command prompt as in your other container. You will often need multiple terminal connections to your container. We need to source our environment first:

    $ source /opt/ros/jazzy/setup.bash

11. Now, let’s start up a controller so we can move the turtle around:

    $ ros2 run turtlesim turtle_teleop_key

12. Move the turtle around using the instructions on the screen. It should mark where it has been.
13. Now, start up a third terminal, connect it to your container, and source your environment.
14. In this third terminal, let’s see what topics are used to make the turtle move. A topic is a pathway between ROS programs (“nodes”) that allows one to communicate to another.

    $ ros2 topic list

15. You should see three topics that start with “/turtle1/”. Pick one of them to start with. Use the following command to see what is being sent over the topic. Note that there may not be anything sent unless you move the turtle with the keyboard control. Record what happens when you do so.

    $ ros2 echo <topic_name>

16. Do the same for the other two topics that start with “/turtle1/”. You can start additional terminals or end the current echo by pressing ctrl-c and running a new one.
17. What do you think each of these topics do? Which control(s) the turtle and which report(s) information about the turtle?
18. Now let’s see what nodes are running. Run:
    $ ros2 node list
19. You should see a node called “/turtlesim” or something very similar. Let’s take a look at the details of this node with:

    $ ros2 node info /turtlesim

20. Towards the top of this output you should see a listing of “publishers” and “subscribers”. Publishers are topics that the node sends messages out on, subscribers are topics that the node listens to. You should see the three topics you used above here. Does this agree with what you think each one does?
21. Once you are done experiments, run

    $ exit

    in each terminal connected to your container and your original container terminal. You may now close the terminal windows if you wish.

Submission

To complete this assignment, submit the Lab1.1 survey on Qualtrics (link on Blackboard) with the following information:

1. The URL of your repository (starts with “git@github.com”) (10 points)
   NOTE: the URL should be for the SSH version, not HTTP(S), it should start with “git@github.com”
2. Upload a screenshot of your profile on the class Slack to prove that you made an account there. The link to join is on Blackboard. (4 points)
3. List the name of the two topics published by the turtlesim node. (4 points)
4. What was the name of the topic that the turtlesim node listened to? (4 points)
5. Briefly describe what each topic reports based on your experiments. (10 points)
6. What is the late policy for assignments in this class? (4 points)
7. What is the late policy for demos in this class? (4 points)