This is a blank project fully configured for use of Taproot. It is designed to be a starting point for your own RoboMaster software projects. Be sure to check out Taproot for more information.
This template includes the following:
Code generated from the
modmrepositories. This generated code is located in
/mdev2021/taprootand includes the hardware abstraction layer provided by modm as well as Taproot library code that sits on top of modm.
See here for more information on code generation.
.vscodefolder with C++ configurations for developing in a simulated, test, and hardware environment. This also includes convenient VS Code tasks for building code and debug launch configuration for debugging the simulated, test, or hardware environment.
A Doxygen document generation configuration that renders a documentation webpage sourced from commented code.
Various linting scripts that are used for maintaining high quality source code.
A clang format configuration (see
.clang-format). This should be configured based on user preferences.
Build scripts supporting configurable target profiles, including environment (simulator, tests, hardware) and robot type (Standard, Hero, etc.).
A basic GitLab Continuous Integration (CI) Pipeline that lints the source code, builds all targets, and runs your tests (see
Instructions and a configuration file for deploying your software to hardware via the command line.
Usage of the template
This project is provided to reduce the configuration overhead when adopting Taproot. We recommend creating a new blank GitLab project and pushing the history of this repository there. This will be similar to a fork, but omit the "forked from..." badge, which you likely don't want.
Assuming your new project is at
https://gitlab.com/my-team/my-amazing-project, the setup process is as follows:
git clone --recursive https://gitlab.com/my-team/my-amazing-project.git cd my-amazing-project git remote add template https://gitlab.com/aruw/controls/taproot-mdev2021.git git pull template develop # replace "main" with your main branch name of choice git push --set-upstream origin main
If you visit the project's GitLab page, starter files should be present and GitLab will likely have kicked off a Continuous Integration (CI) Pipeline, indicated by the blue "waiting" icon or a green "checkmark".
Configuring your new project
By using this template, your project will start out with a fully-functional Taproot instance and build tools. The provided
/mdev2021/src/main.cpp) includes initialization of all core systems and drivers. This should allow you to develop control systems starting day one.
Note: Issue #3 tracks the desire to automate the below process. Let us know about your experiences there.
To get started, we suggest using Visual Studio Code to perform a find-and-replace across all files, swapping your own project name in place of
mdev2021. Furthermore, rename the directory
/mdev2021 accordingly. Feel free to call it the same name as your repo.
You should also update the license headers in your project. The above find-and-replace should have updated the project name references. However, you will also want to update the copyright line of each header:
Copyright (c) 2020-2021 Advanced Robotics at the University of Washington <[email protected]>
To refer to your own team, year and email. Do so in all template source files, excluding files in
**/taproot. Also update
A note on copyright headers: The above suggestions regarding copyright headers are purely for your convenience. You are free to decide how you would like to manage these, including omitting the license headers entirely if preferred, so long as you abide by the original license terms of the files. You may opt to disable the automated license header check; do so by removing the below line from
.gitlab-ci.yml:- python3 ./scripts/check_license_headers.py
To start developing software, place your source code in
/mdev2021/src and your tests in
/mdev2021/test. See the workflow guide for how to build, test, and deploy your code.
Finally, after you are done with it, we recommend removing the portion of this README between
<!-- ... --> comments. The rest of the file is intended to provide a starting point for your team.
(Optional) Using the RoboMaster Development Board Type C
By default, this project targets the RoboMaster Development Board Type A. However, Taproot also supports the newer Type C board. If you would like to use this board instead (replace
mdev2021 with the new name if it has been renamed):
- Commit any work so you don't lose it
mdev2021/project.xmlaccording to the included comment
rm -r mdev2021/taproot
cd mdev2021and then
- Commit the result:
git add . && git commit -m "Target RM Dev Board Type C"
If you have any questions please contact us at [email protected].
taproot-mdev2021 is covered under the GPL-3.0-or-later with the following exceptions:
/mdev2021/taproot/modmare licensed under MPL 2.0 by the modm project. We are not the license holder for these files. See
/modm/LICENSEfor license information.
/mdev2021/taproot/src/taproot/algorithms/MahonyAHRS.cppare licensed under the GPL by SOH Madgwick. The repo containing this code can be found here.
Other RoboMaster teams are invited, and encouraged, to utilize this library. We have licensed this template project and Taproot under the GPL to encourage collaboration and open publishing of RoboMaster controls codebases. We politely request that other teams choosing to utilize this library, or parts of it (including its design), open-source their own code in turn.
- The Taproot wiki. It has lots of content and we strongly recommend you browse through it to get a sense of what's there.
- aruw-edu: a hands-on tutorial for building robot code with Taproot
- aruw-mcb, ARUW's full robot code project available for reference
- The generated API documentation for Taproot
- The modm website and associated documentation
New user guide
Setting up a development environment
If you want the easiest setup experience and do not require deploying code to hardware, consider developing within the provided Docker container.
Otherwise, follow the guide appropriate for your operating system.
- Debian: https://gitlab.com/aruw/controls/taproot/-/wikis/Debian-Linux-Setup
- Fedora: https://gitlab.com/aruw/controls/taproot/-/wikis/Fedora-Linux-Setup
- Other: follow one of the above guides, substituting your distribution's package names in place of Debian or Fedora packages.
- macOS: https://gitlab.com/aruw/controls/taproot/-/wikis/macOS-Setup
- Windows: https://gitlab.com/aruw/controls/taproot/-/wikis/Windows-Setup
pipenv and set up the build tools:
pip3 install pipenv cd mdev2021/ pipenv install
Getting started with this repo
Make sure you have followed the above setup instructions.
Run the following to clone this repository:
git clone --recursive https://gitlab.com/my-team/my-amazing-project.git
If you use the Docker container, or have already cloned the repository yourself, you should instead run:
git submodule update --init --recursive
cd into the project directory, activate the virtualenv, and run some builds:
cd my-amazing-project/mdev2021 pipenv shell # Build for hardware scons build # Run automated tests scons run-tests
Returning to the development environment
You will need to run
pipenv shell from this directory every time you open a new terminal, before using
Getting around VSCode
Microsoft provides a helpful website with a number of shortcuts for getting around VSCode. There are many shortcuts that make programming faster.
Building code and programming the RoboMaster Development Board
If you would like to use the terminal instead, see the section "Building and running via the terminal" below.
- Make sure you have VSCode opened in the folder
- Connect an ST-Link to the RoboMaster Development Board and your computer.
- In VSCode, open the Command Palette (Ctrl+shift+P)
Tasks: Run Task. You should see the options below. Select
Program - Debugor
Program - Release.
Debugging with an ST-Link
- Open the folder
aruw-mdev2021in VSCode. Hit the debug tab on the left side or type Ctrl+shift+D.
- Hit the green play arrow on the left top of the screen.
- See this page for more information about using the ST-Link for programming the MCB and debugging.
Debugging with a J-Link
See the wiki for an explanation on the difference between an ST-Link and J-Link and a step-by-step procedure on how to use the J-Link.
Selecting and using robot types
Specify the robot type via the command line when compiling (see below). For vscode IntelliSense, navigate to
/mdev2021/robot-type/robot_type.hpp and change the macro defined in this file.
Each robot is signified by a unique macro which can be checked to special-case code:
#if defined(TARGET_STANDARD) // Only included if building for the Standard initializeStandard(); #endif
How to select an appropriate VSCode C/C++ configuration
This codebase has a number of different build targets (see this wiki page for more information). Because the build setup is different for the test, sim, and RoboMaster Development Board (aka MCB) environments, while working on a particular portion of code you may select an appropriate profile that provides optimal intellisense. To select a configuration, in VSCode, type Ctrl+Shift+P, then type "C/C++:Select a Configuration" and hit enter. A dropdown menu will appear where you may choose either the "Test", "Sim", or "Hardware" configuration.
The Taproot project recommends that user projects occasionally upgrade the version of Taproot that they depend on. The guide for doing so is here.
Building and running via the terminal
The below commands require that your working directory is
/mdev2021 (where the
project.xml files are).
lbuild build: Re-generates out copy of
scons build: Builds the firmware image for the hardware target. Creates a "release" folder located in
build/hardware/which contains the final
.elffile as well as the intermediate object files (
scons build-tests: Builds a program which hosts our unit tests. This executable can be run on your host computer (only supported on Linux) and prints results for each unit test run.
scons run: Builds as with
scons buildand then programs the board.
scons run-tests: Builds and runs the unit test program.
scons size: Prints statistics on program size and (statically-)allocated memory. Note that the reported available heap space is an upper bound, and this tool has no way of knowing about the real size of dynamic allocations.
Below is the full usage statement from our scons build environment. Note that you can select the robot, profile, or whether or not you want profiling to be on using the various options.
Usage: scons <target> [profile=<debug|release|fast>] [robot=TARGET_<ROBOT_TYPE>] [profiling=<true|false>] "<target>" is one of: - "build": build all code for the hardware platform. - "run": build all code for the hardware platform, and deploy it to the board via a connected ST-Link. - "build-tests": build core code and tests for the current host platform. - "run-tests": build core code and tests for the current host platform, and execute them locally with the test runner. - "run-tests-gcov": builds core code and tests, executes them locally, and captures and prints code coverage information - "build-sim": build all code for the simulated environment, for the current host platform. - "run-sim": build all code for the simulated environment, for the current host platform, and execute the simulator locally. "TARGET_<ROBOT_TYPE>" is an optional argument that can override whatever robot type has been specified in robot_type.hpp. - <ROBOT_TYPE> must be one of the following: - STANDARD, DRONE, ENGINEER, SENTRY, HERO: