Home
Welcome to the Robotics @ Maryland Wiki! This wiki should serve as an introduction to most of the things you’ll need to know if you want to learn and contribute to our software system.
If you’re interested in the electrical team, you can find their repository here.
If you’re interested in the mechanical team, you should check out our website, ram.umd.edu, and come to one of our meetings with your laptop.
Our robot is powered by a Jetson TX1, running Ubuntu 16.04. We use ROS and program primarily in Python and C++. For our embedded system, we’re currently using a Teensy 3.1 Arduino-compatible board, but we’ve already done extensive development for and might use a TI Tiva C running FreeRTOS.
If you didn’t understand most of that, don’t worry. Most of our members didn’t understand most of that before they joined, either. We’ll teach you most of the things you need to know.
If you’re interested in working on our software system, you’ll first need an install of Ubuntu 16.04. There are a couple of ways you can do this. We usually recommend you either:
- Install a virtual machine, like VMWare (which you can get from TERPware), or VirtualBox. Most of our members have found that VMWare runs a bit better, but a few have found that VMware causes their computer to blue screen on install, or that the version on TERPware doesn’t support the most recent Linux kernels as host.
- Run Ubuntu natively, replacing or installing it alongside your current operating system. Running it natively will give you a much smoother experience, but you might run into trouble if you screw something up or we make a decision that requires a lot of backend changes.
For new members, we recommend installing and running everything in a virtual machine. If things go wrong, they’re much easier to fix, and they won’t break anything else on your computer. Whichever you choose, you’ll need an Ubuntu 16.04 image, which you can get here. If you’re new to Linux, make sure to get the ‘desktop’ image instead of ‘server.’
If you’ve chosen to use a virtual machine, you’ll need to install and configure your new Ubuntu install. We’ve found that both VMWare and VirtualBox provide a moderately easy to use install interface, but if you’re stuck, you can find the instructions for VMWare here, and VirtualBox here. For VirtualBox, you’ll also need to install the VirtualBox guest additions Important:
- Make sure you give your virtual machine more than 2GB of RAM! If you don’t, some things won’t compile correctly.
- Give your virtual machine a significant amount of your CPU. You’ll be compiling things on it, so you’ll want as much power as you can spare.
Once you’ve installed Ubuntu and set it up, you’ll need to configure our repository. If you’re new to git, we strongly recommend you go through a tutorial, like this one, or this one. After you’re comfortable with git, you should open a terminal and run:
$ git clone https://github.com/robotics-at-maryland/qubo.git(To open a terminal in Ubuntu, you can hit the Windows/Command key and begin typing “terminal” until you see it)
After that, you’ll need to run the install script install_dependencies.bash located in scripts. This script will download and install all the other software and libraries you’ll need to compile our code. This may take a while (check the Troubleshooting section below if you run into problems). To run the script, run the following in a terminal:
$ cd qubo
$ bash ./scripts/install_dependencies.bashOnce you’ve run the install script, you should execute catkin_make in the root folder of the repository to compile and build our software. If there are no errors, everything should be installed correctly. From the same terminal, run:
$ catkin_makeOnce you’ve gotten our software to compile, you can start looking through our code and begin to familiarize yourself with some of the libraries we use. Things you may be interested in looking into might be:
If you’re interested in working on the high level software of the robot, we recommend everyone create a basic ROS publisher and subscriber, and then submit the code to us as a pull request. It’s a great way to learn the basics of the high level system.
We use ROS catkin to build our software. If you have everything configured/sourced correctly, you should only need to run:
$ catkin_makein the top level of the repository to build it. If something goes wrong, you may have forgotten to source a couple of files needed to get everything to compile correctly. Make sure your .bashrc has the variables/sources set up by the install script, it should contain:
Our high level software uses the ROS framework to pass messages and information between different components of the system. The system is currently split into three parts: planning, vehicle layer, and controls.
The planning subsystem uses Python and rospy to interface with the vision/controls subsystem to determine where our robot is, and what it wants to do next.
The vehicle layer is our ROS interface between drivers and the rest of the system. It receives values from various hardware and interprets/publishes them to ROS topics for the other subsystems.
The controls subsystem takes the information from the vehicle layer, and uses it to figure out our heading/velocity/acceleration. It also takes the desired movement/position form the planning subsystem, converts it to specific motor/thruster commands, and relays that information to the vehicle layer.
Once you’ve written a ROS node, you’ll need to specify its dependencies and how to build it in the CMakeLists.txt file that should exist a directory above your source file. ROS uses the CMake build system to build nodes, and CMake uses this file to figure out what it should build. If you’re having issues with things not getting build or missing dependencies, this is where you should look first.
To start testing things you’ve written with ROS, or just to make sure everything you just built runs, you’ll need to know how to correctly start our system.
If you want to just manually run a few specific nodes, you should first call roscore to start an instance of the main ROS server on your machine. After that, you can either background the ROS process or open a new terminal and run rosrun $package $node, where $package is your package (like vl_qubo, vision, etc) and $node is an executable you’ve built (like qubo_ahrs_node, vision_node, etc).
The other, and probably easier option, is to use roslaunch. roslaunch takes a .launch XML file, and parses it to run multiple nodes with set parameters. It will also start/kill roscore in the background, so you don’t have to worry about running it first. All of our current launch files exist in src/launch, and can be used to launch various parts of the system, or the entire thing.
Here are some common things to try to resolve problems.
- Close your terminal and reopen it (or source your ~~/.bashrc~ file again)
- Give your virtual machine more RAM
pip install catkin_pkg rospkg empy- Make sure the simulator builds in ~
/catkin_ws(runcatkin_makein it)
The embedded system handles the safety, monitoring, and thruster control of the robot.
The main computer and the embedded system communicate to each other over a UART interface using a protocol called Qubobus. The endpoints that implement this communication are called the QSCU(Qubo System Control Unit). Both endpoints use the same code to assemble and disassemble messages from a generic bytestream.
We’re currently using a TM4C123GXL. The system runs on FreeRTOS, which is an open source real time operating system. The toolchain used to compile the code is the GNU ARM Embedded Toolchain. To flash to the microcontroller you can use lm4tools.
To get started, run the scripts/embedded_install_deps.bash file to install all the dependencies required. Ubuntu 16.04 is recommended. We have a book about getting started with FreeRTOS, email software@ram.umd.edu if you want it. Read the embedded/README.md and embedded/guide.md for more information on the Tiva embedded software.