-
Notifications
You must be signed in to change notification settings - Fork 0
3. Tutorials
This is not meant to be a cheat sheet, but more of an introduction to the most useful utilities and commands. So, it is not comprehensive, but it will be enough to get you started.
Git is a version control system that tracks versions of files. You start with a git repository with a single branch called "master" (which you want to rename to "main"). You then "stage" your changes into a "commit", which is a snapshot of your codebase on the branch you're on. Only staged changes will be present on your commit. You can have multiple branches in parallel, and branches branch from other branches. Once branches complete their purpose, whatever that purpose may be, they are merged into other branches, a process that mixes the codebase of the merging branch and the parent branch, into one codebase. Here is a video explaining git more graphically. GitHub hosts git repos and provides various other quality-of-life improvements, such as built-in wiki, GitHub Actions, insights, etc. More importantly, GitHub allows Pull requests, which are the preferred way of merging one branch into another, as it encourages peer reviews and discussions before pushing possibly broken code into an important branch (such as the "main" branch).
You need not do this for the drone repo, but if you want to have personal repos, this is how
Make a directory that will hold all your files and folders, cd into it and run git init. This will initialize the directory as a git repo. You then run git branch -M main to change the master branch to be called main (Not necessary but preferred).
Make a new GitHub repo, copy the repo's link, and run, from the git repo, git remote add origin <new_repo's_link> && git push -u origin main.
You navigate to the repo on a web browser and copy its URL. Then, from your terminal, run git clone <repo's_url> where you want your repo to reside.
Changes, such as deleting, adding, or modifying a file, need to be staged. You can see all the changes since the last commit by running git status. You then need to run git add <file_in_git_status> to stage those changes. Once staged, you can commit changes by running git commit -m "<Commit_message>", where commit_message is a description of the commit's changes, please give a good but concise description to your commits. The first time you try to commit, you will get an error asking you to configure an email and username, that's because those are needed for your commit's author. I recommend using your GitHub email address and username. You can also see the commits history by running git log, and entering "q" to exit the logs. You will notice, if you have a commit history, that each commit has an identifying string of alphanumeric characters, an author, a date, and a small description (the commit's commit_message). You use the identifying string to check out past commits, refer to Checkout commits and branches below.
Listing all current branches can be done with git branch for local branches and git branch -a for all branches. The current branch you're on is shown with the star ("*"). You can make a new branch that branches from your branch by running git branch <new_name>
You run git checkout <Branch_name_OR_commit_identifier> to either checkout a branch through its name or a specific commit through its identifier.
Once you have made at least a commit, you can push your commits to the GitHub repo. Simply running git push would have been enough at some point in the past but GitHub has transitioned away from password-based authentication for shell users, you need to create a classic personal access token which you will use as your "password" when you are prompted for your credentials. You can also retrieve the latest commits from a GitHub repo by running git pull. Pulling may be mandatory before pushing your commits if commits have been made in the same branch in the remote repo and those commits are not present in the local repo.
Sometimes, git throws errors. Please read the error messages carefully and try to understand them. I also recommend looking them up. If that doesn't work, ask one of the software leads.
The Robot Operating System (ROS) is a set of software libraries and tools for building robot applications. It facilitates interprocess communication through abstractions called nodes and topics. Please do the following tutorials: Using turtlesim, ros2, and rqt, Understanding nodes, Understanding topics, Understanding services. When you are ready to take a more practical approach, take a look at the Beginner: Client libraries tutorials.
A Terminal Multiplexer is software that allows multiple pseudoterminals to be opened from within a single real terminal. Tmux is one such software, Tmux also enables us to run a session and various programs on each pseudoterminal from a shell script, which will come in handy for launching and monitoring various ROS nodes and other programs. Additionally, Tmux sessions will not die even if you get disconnected. This means that if you use SSH to connect to a computer and launch a Tmux session, that session will still be active even if you lose SSH connection. If you have used the setup_tools.sh script to set up your environment, then it should be already installed on your system, otherwise a simple sudo apt install tmux will install it for you. You can launch a Tmux session by running tmux.
To start sending Tmux controls, you always start with the "leader" key combination, which tells Tmux that the next keys will be commands. The default leader key combination is <CTR>+b. After that, you input " to split a window horizontally. Input the arrow keys to jump from pane to pane. Input % to split a window vertically. Input x, then "y" when prompted at the bottom to close a pane. Input &, then "y" when prompted to kill the current window. Input d to detach from your Ttmux session, you can reattach by running tmux attach. You can also see more commands by running man tmux.
PX4 is the flight controller firmware we will be using. It is the software responsible for all flight-related tasks and offers an interface for sending flight commands and monitoring the drone. Since you want to simulate a drone, you need direct support from your flight controller for simulations, which PX4 offers.
The simulation has 2 parts, the virtual drone and the simulator. The simulator is Gazebo Classic, which is a physics simulator specialized in robotics. The newer version of Gazebo, Ignition, is currently broken on Windows machines, thus requiring the use of Gazebo Classic. PX4 is the firmware for our flight controller, but it also has code to allow for starting Gazebo and spawning a virtual drone inside the simulation, which you can then control through the PX4 shell, QGroundControl, or from an offboard program. To start a Gazebo simulation with PX4, change directories into the PX4 directory (If you used the setup_tools.sh script, the PX4 directory should be under your home directory) and run make px4_sitl gazebo-classic_standard_vtol. This will start the Gazebo server which runs the physics engine and the Gazebo client which will render all the objects as well as the GUI. This may work fine for you but most VMs don't have GPU passthrough (because the host OS doesn't share it), meaning the client has to use the CPU to render the graphics, which will result in subpar performance. Ideally, we would want to run the client and server separately, which is done by running HEADLESS=1 GAZEBO_MASTER_URI=<A URI reachable by both the host and guest OS, belonging to the guest OS> GAZEBO_IP=<IP reachable for both OSs, belonging to the guest OS> make px4_sitl gazebo-classic_standard_vtol instead and then running the client on the host OS by running GAZEBO_MASTER_URI=<same URI as above> GAZEBO_IP=<IP reachable for both OSs, belonging to the host OS> gzclient --verbose. Note that since the client and server are running on different OSs, they do not share the same file system, thus the Gazebo client won't be able to render the meshes that the server has. Consequently, we need to add those meshes manually to the meshes path of the client which is all detailed in the setup page. This will ensure the client will run smoothly, as it will have GPU access.