Setup
To start off, you'll first have to set up the Pathfinder project in your workspace. Before you begin, you will need to have an account set up on the Avocado server. This should have been provided to you when you joined the team, but if you haven't received your credentials yet, go bug somebody on Slack!
In this section, you'll become familiar with the remote development environment that we use on Rover. You'll probably be doing most of your work on this machine during your time on the team, so you'll need to become familiar with the steps to get connected!
Avocado is nothing more than the small rectangular computer tower that humbly sits atop the CS bench in our ELL space. Everybody on the CS subteam has their own account on this device with administrator access, which you can access remotely from anywhere in the world. Its primary job is to let you work on rover stuff without having to set the entire environment up on your own hard drive, which can take up a metric butt ton of space and is marred by cross-platform compatibility issues (indeed, in the dark days before the introduction of Avocado, our unfortunate Windows-using comrades couldn't do anything without running a slow, resource-intensive virtual machine).
You should never try to log into your account on the actual physical machine; rather, we use our Avocado accounts by connecting via SSH. SSH stands for Secure Shell, and it's a network protocol that lets two devices connect to each other and share data. Its most basic and common use case is to open up a shell (a terminal session) over the network, which grants you full access to use the computer remotely. Don't worry, though; you won't have to rely solely on a command line shell to use Avocado! We'll talk about how to actually use Avocado throughout this guide. If you want to learn more about SSH, this resource gives a good overview.
You will need your personal device with an Internet connection. You do not have to be connected to Cornell's WiFi network to use Avocado.
In order to connect to Avocado, you need to connect to Cornell University’s VPN. You need to do this even if you’re connected to Cornell’s network. Visit IT@Cornell’s official CU VPN page: it.cornell.edu/cuvpn. Follow the instructions under “Install CU VPN” and “Connect to CU VPN.”
Important: You must connect to the VPN each time you want to use Avocado!
All major operating systems come with SSH out of the box, but you will need to do a quick configuration step to save Avocado in its settings since you'll be accessing it often.
Open up the SSH configuration file on your computer. If it doesn't exist yet, you can just create it. For Windows users, this will be located at C:\Users\[your username]\.ssh\config. For macOS and Linux users, it'll be located at ~/.ssh/config (~ represents your user's home directory). If the .ssh folder doesn't exist yet, you should create it, but make sure you include the leading dot (.) or it will not work!
Next, type the following few lines into the file. Change [your username] to your username on Avocado (this is usually your first name, all lowercase).
Host avocado
HostName cmr.mae.cornell.edu
User [your username]
Save the file. Now, you can open up a Terminal session and type ssh avocado to connect. If all goes well, you'll be greeted by a big green banner that screams "AVOCADO."
Avocado allows you to remotely view graphical programs, not too different from Zoom's remote control screen share feature (but way more pleasant to use #shotsfired @zoom). This is called X Forwarding, and it communicates via SSH. When you open a graphical program on Avocado, it'll pop up on your computer's screen, as if it were running on your device!
A note for the pedantic: Alright, technically we're using a variation of the X Forwarding protocol called Xpra, which has support for some fun graphics acceleration stuff that lets us run robotic simulation software. Same gist though.
First, you need to install the Xpra client. This is the software that runs on your computer that shares the graphical programs to your desktop. Follow the setup instructions for your operating system at this link. It supports Windows, macOS (both Intel and M1), and Linux. If the latest release gives you trouble on macOS, try one of the macOS betas at the link on the same page.
Once that's installed, you'll see something like this:
Click Connect. You'll see a pop-up box that you must fill in to let Xpra know which computer you want to remotely connect to. Again, you must be connected to the CUVPN to do this. Make it look like the following image. In particular, change the Mode to SSH (people often forget this step), enter your Avocado username as the username, enter "cmr.mae.cornell.edu" as the host, leave the port number as 22, and for the last field on that line, you must input your X server port number (shown as "TODO" in the example image). To find this, open an Avocado shell in your terminal (ssh avocado), log in, and run echo $DISPLAY. It will spit out a number; put it in that field!
If the connection fails, you may need to start up the X server on your account. Go back to your Avocado shell terminal and type startx to start up the X server. Try connecting again, and you should be good to go!
To test your connection, go to your Avocado shell terminal and type xeyes. If all is well, a pair of eyes will pop up on your screen.
In this section, you'll set up Git on your Avocado workspace and use it to clone your own copy of the Pathfinder project to put your code in.
Git is a version control system that makes it easy for many people to work on a project, collaborate on changes, and make sure those changes don't conflict with those of others. It's an incredibly important tool for all software engineers and computer scientists, and you'll definitely encounter it during your time at Cornell (most likely in CS 211x/3110). If you're not familiar with it yet, that's OK! I recommend skimming this guide from freeCodeCamp to get the rundown before proceeding.
The first thing you must do is create an SSH key that you can use to authenticate with GitHub. This takes the place of a traditional username and password, and is GitHub's required method for authenticating so that you can access repositories under your account. Within your Avocado terminal session, run the command ssh-keygen. Leave everything default and enter a password that you will remember. Once it's done, type cat ~/.ssh/id_rsa.pub. This will print the contents of your public key to the terminal, which is the copy of the key you can give to GitHub so that it can authenticate your requests. Copy the entire block, from "ssh-rsa" all the way down to the end. Now, open a web browser and go to github.com/settings/keys. Click "New SSH Key," name it whatever you want, and paste in that public key you copied. Hit "Add" and you're all set.
Now, you need to tell the Git tool the name of your account and your email address so that it can correctly attribute your contributions to you. Inside the Avocado terminal session, type the following two commands (each line is its own command):
git config --global user.name "Your Name"
git config --global user.email "Your GitHub Account Email"
You've now set up Git!
The Pathfinder project repository comes with some starter code that configures all of the boilerplate for you so that you can dive right into the individual modules. However, you need to clone (Git lingo for "download") the repository to your Avocado workspace first. Inside the Avocado terminal session, run the following command:
git clone git@github.com/CornellMarsRover/Pathfinder.git
Once that's done, if you type the command ls, you will see that a folder called "Pathfinder" has been created in your Avocado workspace, and if you change directories into it (cd Pathfinder) and run ls again, you will see all the files ready for you!
One important step that we need to do now is to build the Docker image in which we will run the code. Docker is essentially a virtualization platform that lets you run a container that holds all the system requirements and tools that we need in order to run all of our robotics development tools. We use Docker extensively on the team to make sure that every single person running the rover's code, including the rover itself, has the exact same versions of all the required software. If you're curious to learn more, this page gives a nice summary.
Lucky for you, the project comes with a script that will build the Docker image for you!
cd docker
bash build.sh
This may take a few minutes, but when it's done, you'll have everything you need to move on to the next step.
In order to make a bunch of development tasks easier, the CS subteam has preconfigured a development environment that enables things like inline error and warning highlighting, documentation editing tools, and preconfigured automatic code formatting. You will use this development environment for the Pathfinder project, as well as afterwards when you work on the rover codebase itself.
Our officially supported editor, in which this development environment is preconfigured, is Visual Studio Code. It's one of the most popular code editors and is wildly popular in industry, and it's also rather easy to use. Download it from the official download link. Once it's installed, open it up and proceed to the next step.
One of the really nice things about VS Code is that it has great support for running the editor over an SSH connection. This means that you can edit your Pathfinder workspace from VS Code, as if it were running locally on your computer.
In VS Code, open up the Extensions panel (it looks like a stack of blocks on the leftmost sidebar) and search for "Remote SSH." Click on it and then click Install. It will look like this:
Once it's installed, you will see a new blue icon with two arrows facing each other in the bottom-leftmost corner of the window. Click it, and you will see a menu in the top-center of the screen that has a few options to pick from. Click "Connect to Host" and then select "avocado."
It will prompt you for a password; this is your Avocado password. Once it connects, open up the File Explorer (the topmost icon, that looks like two pieces of paper, in the leftmost sidebar of the window). Then, click "Open Folder." In the prompt that opens up, enter "~/Pathfinder". It should look something like this:
Click "OK." It will then open up the project in your editor!
This next step is crucial: in the bottom right of the screen, it will tell you that the workspace has "extension recommendations" and ask you if you want to install them. Click "Install All" to automatically set up the editor with all the extensions used in the CS development environment. There may also be some other popups in that same area asking you about things such as automatic project configuration (you can click yes); answer them using your best judgement, or ask for help if you are unsure.
Now, you have a perfectly functional CS development environment set up with your Pathfinder project workspace! One feature that you'll find really useful is that you can open up Avocado terminal sessions within this VS Code window without having to open your operating system's terminal and log in every single time (which can get annoying when you want to run and manage multiple sessions at once, as we often do on Rover). To open a terminal, you can click "Terminal -> New Terminal" in the menu bar (located at the top of the window on Windows and Linux, or at the top of the screen in macOS). You can do this as many times as you want, and terminals will open in separate tabs within the editor.
At this point, you have set up connection to the Avocado workspace with graphical program support, set up your GitHub account to accept changes from this workspace, cloned a copy of the Pathfinder project to put your own code into, and set up a remote VS Code developer environment to make your changes inside. Move onto the next module to start diving into some ROS fundamentals!