Home - MatthewMArnold/taproot GitHub Wiki

Contents

Software Function Introduction

Welcome to the taproot wiki! This repository stores ARUW's hardware abstraction layer for the RoboMaster Type A and C boards (referred to as "MCB"s throughout the wiki and software).

Taproot is a friendly control library and framework for RoboMaster robots.

Taproot provides a comprehensive, convenient and well-tested set of APIs designed specifically for the RoboMaster robotics competition. Key functionality and features include:

  • Drivers for common RoboMaster/DJI hardware:
    • RoboMaster motors connected via CAN: C620, GM3508, GM3510 and others
    • DR16 Receiver
    • RoboMaster referee system via UART
  • An organizational framework and round-robin scheduler taking inspiration from FIRST's wpilib
  • Common building blocks such as:
    • Setpoint-based subsystems with jam detection logic and calibration
    • Closed-loop power limiting
    • Filtering, smoothing and ramping primitives
    • Computational helpers for wrapping measurements such as angles
    • Primitives for odometry computations, including multi-dimensional Kalman filters and odometry interfaces.
    • Primitives for ballistics computations that can be used for computer vision auto-aiming
    • Turret and chassis interfaces to provide guidance
  • Utilities for interacting with flash memory on the RoboMaster boards through a LittleFS file system to provide persistent memory.
  • Built-in error aggregation and reporting via optional UART terminal or OLED display
  • Monitoring of key subsystems and status information via optional UART terminal or OLED display
  • First-class support for unit and integration testing (no hardware required)
  • Primitives to make robot-to-robot communication and drawing UI elements through the referee system fast and easy.

Taproot is a C++ library targeting modern C++ (C++20).

We use:

  • modm, a C++-native HAL
  • the gcc compiler
  • openocd to deploy and debug
  • VSCode, an editor

Using taproot as their fundamental building block, the University of Washington has created a complex and high level robot development environment. Robot-specific control software is stored in aruw-mcb. With this software, ARUW was able to achieve first place in the RoboMaster University League 1v1 and 3v3 tournaments, during which time we never lost a match. Taproot allowed us to quickly develop high level control algorithms and focus on integrating computer vision-based auto aiming into our system instead of mucking around with low level embedded systems issues. This meant our CV solution heavily utilized the RoboMaster Type A board for odometry and ballistics computations, which could run far more frequently than if they were performed on the vision coprocessor.

Furthermore, the following North American teams are utilizing taproot:

In addition to taproot, a variety of ancillary tools exist to support the development of taproot-based software.

This repository is designed to replace the typical Keil MDK and CubeMX setup, which our team has used previously, with a custom VSCode setup and a bare bones open source C++ embedded HAL generator called modm. As a result, all of our code has been designed from the ground up in C++ since the end of last season.

Capabilities and Results (Software Effects Display)

Our embedded framework is set up with the following core design principles in mind:

This codebase has been set up with continuous integration (CI) and longevity in mind. We follow strict practices to ensure code is easy to read, modify, and interact with the codebase. While embedded code quality is not particularly interesting to display, a lot of time is spent adding or updating scripts used in our CI checks on GitLab. Below you can see what the output of a typical CI script that we use for automated verification when merging code into develop or master. As can be seen in the image, initial verification and an initial robot build is done in the first stage of the pipeline, and in the second, all other robot types are built. The first stage also checks to ensure that it matches the expected auto-formatting rules (enforced by clang-format).

Furthermore, we provide CI checks in the taproot template project for new users so they can also maintain a high code quality.

Additionally, the architecture has been designed with unit tests in mind. A key feature that makes this possible is the same code that is run on the embedded system can run in a Windows, Linux, or MacOS environment. This is especially important when much of the work we do now is done remotely. Now that this framework is in place, we can easily unit test a piece of software off-robot. This will lead to more robust robot code and will allow us to be more efficient when we are testing on the robot. Currently, taproot has 86.9% unit test code coverage.

The low level architecture has also been designed such that control systems engineers may work with high level APIs, allowing more focus to be spent on improving control system code as opposed to working with low level HALs. Below you can see some of the various high level systems that may be efficiently designed at a high level thanks to taproot. These systems are all open source and available in aruw-mcb.

Control system software in action

Hero beyblading: This clip shows our hero robot running aruw-mcb software. The chassis power limiting, beyblading logic, and turet gimbal stability are on display in this video.

Hero launching projectiles at base: This clip is from RMUL 2022. This clip highlights the custom HUD built in aruw-mcb on to of taproot HUD primitives. We send HUD messages to the server as well as custom sentry commands, which allows pilots to command the sentry to move, stop firing, or scan a new quadrant.

Standard CV'ing and Belbyadling: This clip demonstrates our ability to detect and track a robot using CV while moving.

Shot Timing: This clip shows our automated shot timing algorithm used to oppose spinning robots.

RMUL 1v1 Finals: This clip shows many of the control systems functioning in the RMUL 2022 1v1 championship match. Here you can see auto aiming, chassis control with beyblade enabled, and agitator control all on display.

Dependencies and Hardware/Software Environment

The following is a list of the hardware and software we use on our production standard (referred to as the "soldier" robot in this wiki and in the repository) robot. Miscellaneous hardware for other robots is not listed, but includes linear distance sensors and IMUs.

Hardware

  • Either Robomaster Type A Board or RoboMaster Type C Board.
    • taproot fully supports both boards using a code generation tool called lbuild.
    • Using a simple configuration file the user may generate code with various supported peripherals.
  • ST-Link V2 debugger or J-Link debugger
  • RoboMaster specific hardware:
    • DR16 remote/receiver
    • GM6020 gimbal motors
    • M3508 P19 brushless motors
    • M3510 gear motors
    • M2006 P36 brushless motors
    • C620 motor controllers
    • C610 motor controllers
    • 820R motor controllers
    • Referee system hardware, server, and client
  • Raspberry Pi for remote debugging and deployment to an MCB.
  • Vision coprocessor for plate detection and tracking (ARUW uses a Jetson Xavier).

Software

Installation and Compilation

See the template project's README for how to get started with using taproot. To summarize, you will need to install the various environment dependencies listed above. Then, you create a new template project and run the renaming script to customize the template project for your team. After renaming the project, you will be able to use taproot. The template project comes with taproot pre-generated for teams using the RoboMaster Type A board. The team may modify the project for the type C board by re-generating taproot.

To upgrade a project that utilizes taproot, you must update the taproot submodule and regenerate taproot. For detailed instructions refer to Upgrading a taproot Project.

Furthermore, ARUW has a remote debugging setup that we share with others to facilitate more efficient and effective testing of control systems on robots that are moving around. This guide can be found in Remote Debugging using the JLink.

File Directory Structure and Usage

Refer to the page named File Directory Structure for information on the directory structure.

Software and Hardware System Block Diagrams, Data Flow Diagrams

Refer to the following pages that include hardware and software system block diagrams, code generation flowcharts, and control flow diagrams.

Note: If the control flow diagrams are not clear, refer to the Control Flow Diagram Reference.

Principle Introduction and Theoretical Support Analysis

The main concepts on display in the following sections are the power and configurability of the developed framework. taproot provides generic and easy-to-use HALs whereby developers writing code for robots can quickly develop high-level software.

See the following pages:

Software Architecture or Hierarchy Diagram

Refer to the following pages:

Future Development

For up-and-coming software development projects for taproot see our GitLab issues. Here you will find defined goals for upcoming quarters. Furthermore, refer to our issues in aruw-mcb for more control and robot-specific goals that our team has.

Our general goals are as follows:

  • Reference frame library to make performing transformations easier. This is especially important for teams trying to implement CV and for any complex robotic arm engineer solutions.
  • Explicit support for snail ESCs. Our team does not use these; however, many new teams use these for their flywheels and it would be good to support them.
  • Improve aruw-edu. This is out of date with taproot and needs to be revamped to support better new member onboarding to taproot.
  • Minor code generation quality of life improvements and documentation. We use lbuild code generation, which can be daunting to people new to to technology.
  • Computations and power limiting for swerve robots.
  • Primitives for integrating with and fully utilizing a capacitor bank.