ARUW's "Main Control Board" (MCB) code for the RoboMaster competition.
The MCB is a RoboMaster Development Board Type A which directly operates all major systems on our robots. Among these are drive, turret, launcher wheels, and human input.
Software we use:
modm, a C++-native HAL- The GCC compiler
- OpenOCD to deploy and debug
- VSCode, an editor
- Taproot, a RoboMaster controls framework
In addition to this readme, check out our GitLab wiki and generated documentation!
If you have any questions please contact us at [email protected].
aruw-mcb is covered under the GPL-3.0-or-later with the following exceptions:
/modmand/aruw-mcb-project/modmare licensed under MPL 2.0 by the modm project. We are not the license holder for these files. See/modm/LICENSEfor license information.aruw-mcb-project/src/taproot/algorithms/MahonyAHRS.hand/aruw-mcb-project/src/taproot/algorithms/MahonyAHRS.cppare licensed under the GPL by SOH Madgwick. The repo containing this code can be found here.
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.
- Linux
- 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
Then, install pipenv with pip3 install pipenv.
Make sure you have followed the above setup instructions.
Run the following to clone this repository:
git clone --recursive https://gitlab.com/aruw/controls/aruw-mcb.git
If you use the Docker container, or have already cloned the repository yourself, you should instead run:
git submodule update --init --recursive
Then go into the aruw-mcb/aruw-mcb-project directory and set up the build tools:
cd aruw-mcb/aruw-mcb-project/
pipenv install
The following will then activate the virtualenv in the project directory and run some builds to confirm functionality:
pipenv shell
# Build for hardware
scons build
# Run automated tests
scons run-tests
Go to the VSCode extension marketplace and install "Auto Snippets" by andreasxp. This will help with creating new files in our codebase.
You will need to run pipenv shell from this directory every time you open a new terminal,
before using scons or lbuild.
- When you create a new branch, always branch off of
develop(notmaster) - Names should follow the format
FirstL/{Issue Number}/short-description - Example:
RyanT/0/linter-integration
Microsoft provides a helpful website that has a number of helpful shortcuts for getting around VSCode. There are many shortcuts that make programming faster. It is much appreciated when someone asks for help and can quickly navigate through the codebase while we work through a code bug.
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
aruw-mcb(notaruw-mcb-project) - Connect an ST-Link to the MCB and your computer.
- In VSCode, open the Command Palette (Ctrl+shift+P)
- Find
Tasks: Run Task. You should see the options below
- Open the folder
aruw-mcbin 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.
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.
With the root directory opened in VSCode, type Ctrl+Shift+P. Type "ARUW: Select Robot Type" and hit enter. A dropdown menu should appear. Select the robot type from the dropdown.
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 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 "MCB"
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.
We use an embedded library generator called modm in our codebase. It will eventually be important that you understand how modm works. For now, you can just think about it as handling lower level IO on our MCB. You should read modm's homepage so you have a general idea of what it does.
The modm website provides a great number of examples that can be very useful when interacting with modm's hardware architecture layer for the first time. The examples are located on modm's website here.
Look up the fully-qualified name of the module from the modm website.
The name will look like :platform:gpio. Open aruw-mcb-project/project.xml and add an entry to the dependencies section like the following:
<module>modm:platform:gpio</module>Now open the terminal and run lbuild build.
The below commands require that your working directory is aruw-mcb/aruw-mcb-project (where the SConstruct and project.xml files are).
lbuild build: Re-generates our copy of modm according to the modules specified inproject.xml. Note that there is a separate instance used for the unit tests, which can be build by runnint the same command from within thesim-modmsubdirectory.scons build: Builds the firmware image for the hardware target. Creates a "release" folder located inbuild/hardware/which contains the final.elffile as well as the intermediate object files (.o).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 withscons 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.
Note that all scons commands have optional profile and target options; the former controls whether performance and size optimizations are applied to the output, and the latter specifies which robot to build for. The default is to build in release mode for the Soldier.
Usage: scons <target> [profile=<debug|release>] [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.
- "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_SPIDER, STANDARD_ORION, STANDARD_CYGNUS, DRONE, ENGINEER, SENTRY_HYDRA, HERO_PERSEUS