This repo hosts lab materials for ECE 346: Intelligent Robotic Systems at Princeton University.
Note: If you are following this repository outside of ECE 346 or are refreshing your ECE 346 laptop, please skip to Set up ROS2 Environment via RoboStack after cloning the repository with
git clone --recurse-submodules https://github.com/SafeRoboticsLab/ECE346.git
First, you will need to connect your ECE 346 laptop to a Wi-Fi network. To connect to eduroam, open your terminal and run
python3 ~/Downloads/eduroam-linux-Princeton_University-Princeton_eduroam.py
If you don't see this file, you can temporarily connect to puvisitor using a non-Princeton email to download it. Click 'Yes' and enter one group member's username, i.e., netid@princeton.edu and corresponding password. Then navigate to your Wi-Fi networks by clicking the top right of your screen, selecting the Wi-Fi logo followed by 'Select Network', 'eduroam', 'Connect'.
Next, you will connect your laptop to one group member's GitHub account using an SSH key. In your terminal, run
# Install packages to use GitHub and copy/paste
sudo apt install git xclip
# Replace with your GitHub email address
ssh-keygen -t ed25519 -C "your_email@example.com"
Press enter three times to skip requiring a password for each push/pull. Then run,
# Start the ssh-agent and add your private key to it
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
Open Google Chrome and log into GitHub using the same email from previous steps. In the upper-right corner of any page on GitHub, click your profile photo, then click 'Settings'. In the "Access" section of the sidebar, click 'SSH and GPG keys'. Click 'New SSH key'. In your terminal, run this command to copy your SSH key
# Copy public ssh key to your clipboard:
cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard
Now in your browser, enter 'ece346-XX' for 'Title', where XX is your group number. For 'Key', simply paste the SSH key that you just copied.
Finally, complete your GitHub configuration in your terminal
# Replace with your GitHub email address and full name or a fun alias ;). Note this will appear on GitHub
git config –global user.email “your_email@example.com”
git config –global user.name “Your Name”
Setting up GitHub on VSCode
In VSCode, log into GitHub. Click the settings icon, then 'Back up and sync settings', 'Sign in', 'Sign in with GitHub'.
If you've never used git before, we recommend this introductory tutorial.
-
In the upper-right corner of any page on GitHub, select '+', then click New repository.
-
Type ECE346_GroupXX as the name for your repository, and an optional description.
-
Choose 'Private' as your repository visibility.
-
Click 'Create repository'.
-
In your terminal, run the following command. Important:
--recurse-submodulesis neccessary to get all submodules, i.e., linked specific commits of separate GitHub repositories!git clone --recurse-submodules https://github.com/SafeRoboticsLab/ECE346.git -
From inside the cloned directory, rename the original 'ECE346' GitHub repo to 'upstream' (default is 'origin'), which you'll use to fetch future lab assignments and updates.
cd ECE346 git remote rename origin upstream git remote set-url --push upstream DISABLE -
Add your new private repository as a new remote named 'origin'. Note, this is just typical name for the 'primary' remote (online repository). To locate your private repo's URL, navigate to its main page on GitHub, select the green <>Code icon, select SSH and copy this URL to your clipboard.
git remote add origin <URL of your private Repo> -
Push the 'SP2025' branch of your local cloned repository to your new private remote one, which has now become a private fork of 'ECE346'.
git push -u origin SP2025
When working on the labs and making changes to your code, you can push the code to your private repo on GitHub by simply doing:
git push origin
Not sure about merge? It is never a bad idea to keep a copy locally before merging.
- Commit all of your changes
git add . git commit -m "Updates for Lab X" - Create a temporary local branch on your computer.
git checkout -b temp - You can now merge the original 'upstream' repo into your temporary local branch.
This will create a merge commit for you. If you encounter any conflicts, this tutorial can help you take care of them.
git pull upstream SP2025 - Inspect all changes that you have made in the temporary branch, then checkout your
SP2025branch.git checkout SP2025 git merge temp git branch –-delete temp # Update submodules in case there are any git submodule update --init --recursive
Once you are fully comfortable with the git merge workflow, you may want to skip steps 1 and 3 and git pull directly into your local SP2025 branch.
One crucial component of ECE346 is the Robot Operating System (ROS) by Open Robotics. Even though most your robot's computation will be handled on board, it's very useful to set up ROS on your computer for development, testing, and visualization. We use ROS2 Humble on RoboStack for portability across Linux and MacOS and to easily manage packages with conda/mamba. To set up our environment, cd to the ECE346 directory in a terminal, then run
sudo apt install curl
cd Host_Setup
chmod +x ros_conda_install_unix.sh
./ros_conda_install_unix.sh
This process should take ~5 minutes. If you already have conda (anaconda/miniconda/miniforge, etc) installed, it will install miniforge in parallel with your current conda, and then create a new python3.11 environment with ROS2 Humble installed.
If you do not have conda installed, the script will first install miniforge, and then create a new ROS Noetic environment.
We create an alias for activating the new environment called start_ros. You can activate the environment by running either start_ros or conda activate ros_base.
Open a new terminal, and run activate your ROS environment by start_ros.
Then run rviz2 to start RViz, a 3D visualization tool for ROS2. If everything works, you will see
"Unable to contact my own server at [http://xxxx]" You will typically see this error on Mac OS. This is because the default ROS master is not set to localhost. To fix this, you need to run following lines to in your terminal.
export ROS_HOSTNAME=localhost
export ROS_MASTER_URI=http://localhost:11311
export ROS_IP=localhost
We also provide a script to automate this process. Simply run source local_ros.sh in your terminal.
Important: You need to run these lines every time you open a new terminal. Or, you can export them to your shell profile by running
proile= # choose from ~/.bash_profile, ~/.zshrc, and ~/.bashrc
echo "export ROS_HOSTNAME=localhost" >> $profile
echo "export ROS_MASTER_URI=http://localhost:11311" >> $profile
echo "export ROS_IP=localhost" >> $profile
We have a ROS2 cheat sheet for you! Check it out here.
Please check out our FAQ page for common questions.
@article{FischerRAM2021,
title={A RoboStack Tutorial: Using the Robot Operating System Alongside the Conda and Jupyter Data Science Ecosystems},
author={Tobias Fischer and Wolf Vollprecht and Silvio Traversaro and Sean Yen and Carlos Herrero and Michael Milford},
journal={IEEE Robotics and Automation Magazine},
year={2021},
doi={10.1109/MRA.2021.3128367},
}