Introduction

This is FRC Team 971's main code repository. There are README* files throughout the source tree documenting specifics for their respective folders.

Contributing

All development of AOS is done on our gerrit instance at https://software.frc971.org/gerrit with github being a read-only mirror. We are happy to add external contributors. If you are interested, reach out to Austin Schuh or Stephan Massalt and we will help you get access. In case of disputes over if a patch should be taken or not, Austin has final say.

Submissions must be made under the terms of the following Developer Certificate of Origin.

By making a contribution to this project, I certify that:

    (a) The contribution was created in whole or in part by me and I
        have the right to submit it under the open source license
        indicated in the file; or

    (b) The contribution is based upon previous work that, to the best
        of my knowledge, is covered under an appropriate open source
        license and I have the right under that license to submit that
        work with modifications, whether created in whole or in part
        by me, under the same open source license (unless I am
        permitted to submit under a different license), as indicated
        in the file; or

    (c) The contribution was provided directly to me by some other
        person who certified (a), (b) or (c) and I have not modified
        it.

    (d) I understand and agree that this project and the contribution
        are public and that a record of the contribution (including all
        personal information I submit with it, including my sign-off) is
        maintained indefinitely and may be redistributed consistent with
        this project or the open source license(s) involved.

To do this, add the following to your commit message. Gerrit will enforce that all commits have been signed off.

Signed-off-by: Random J Developer <random@developer.example.org>

Git has support for adding Signed-off-by lines by using git commit -s, or you can setup a git commit hook to automatically sign off your commits. Stack Overflow has instructions for how to do this if you are interested.

Table of contents

• Pathway for new members
  • Learning C++
    • XRP
  • Gaining code access
  • The codelab
• Code Reviews
  • Creating SSH Aliases
• Codelab
• Other Information
  • Roborio Kernel Traces
  • Notes on troubleshooting network setup
  • LSP Setup for Rust
  • Other resources

Pathway for new members

1. Learning C++

C++ is what we use to program a majority of the code which runs on the robot. We generally recommend this course by codeacademy which goes over the basics of C++ as well as OOP.

1.1 XRP

If you are unsure what to work on yet you can start on the XRP Platform. Which basically lets you use smaller robots to learn about robotics through WPILib.

2. Gaining code access

You can follow these steps to access the code.

There is also a document which goes over the basics of using both gerrit and git here

3. The codelab

Once you have an understanding of C++ and have gone through using all the steps needed to access the code you can start on the codelab

Code reviews

We want all code to at least have a second person look it over before it gets merged into the main branch. Gerrit has extensive documentation on starting reviews. There is also a good intro User Guide and an intro to working with Gerrit and Gerrit workflows

TL;DR: Make and commit your changes, do git push origin HEAD:refs/for/main, and then click on the provided link to add reviewers. If you just upload a change without adding any reviewers, it might sit around for a long time before anybody else notices it.

git-review can make the upload process simpler.

To download a commit you can press d or click download on gerrit, then select fetch and paste the command in your terminal. Once you've done that you should switch to a new branch in order to make working on multiple commits easier. You can do this by doing git switch -c branch_name, the branch name can be anything, and will only be public for you, so organize in whatever way you find easy to model.

When programming in C++ we follow Google's C++ Style Guide

Furthermore, you can run bazel run //tools/lint:run-ci to fix linter errors which appear on buildkite.

Some other useful packages

These aren't strictly necessary to build the code, but Michael found the additional tools provided by these packages useful to install when working with the code on May 13, 2018.

Note: These are for local install, most of these tools will be available on the build server

apt install git
apt install yapf3
apt install python3
apt install bazel
apt install clang-format

Creating ssh aliases

It is also handy to alias logins to the raspberry pi's by adding lines like this to your ~/.ssh/config file:

Host pi-7971-2
    User pi
    ForwardAgent yes
    HostName 10.79.71.102
    StrictHostKeyChecking no

or, for the roborio:

Host roborio-971
    User admin
    HostName 10.9.71.2
    StrictHostKeyChecking no

This allows you to use the alias to ping, ssh, or run commands like:

# Download code to robot #7971's raspberry pi #2
bazel run --config=armv7 -c opt //y2020:download_stripped -- pi-7971-2

Codelab

The codelab is a directory living in frc971/codelab/. Which goes over a lot of the important introductory information that you need to know to get started when programming the robot. You can read the README, which gives you introduces you to the codelab as well as the concepts you need to understand first.

Other Information

Roborio Kernel Traces

Currently (as of 2020.02.26), top tends to produce misleading statistics. As such, you can get more useful information about CPU usage by using kernel traces. Sample usage:

# Note that you will need to install the trace-cmd package on the roborio.
# This may be not be a trivial task.
# Start the trace
trace-cmd start -e sched_switch -e workqueue
# Stop the trace
trace-cmd stop
# Save the trace to trace.dat
trace-cmd extract

You can then scp the trace.dat file to your computer and run kernelshark trace.dat (may require installing the kernelshark apt package).

Notes on troubleshooting network setup

If the roboRIO has been configued to use a static IP address like 10.9.71.2, set the laptop to have an IP address on the 10.9.71.x subnet with a netmask of 255.0.0.0. The ".x" is different than the .2 for the roboRIO or any other device on the network. The driver station uses .5 or .6 so avoid those. The radio uses .1 or .50 so avoid those too. A good choice might be in the 90-99 range. If you are at the school, disconnect from the student wireless network or try setting your netmask to 255.255.255.0 if you want to be on both networks. The student wireless network is on a 10.?.?.? subnet which can cause problems with connecting to the robot.

If running Bazel on the download_stripped target does not work for the IP address you're using for the roborio or the raspberry pi, it probably means that the robot and laptop are on different subnets. They need to be on the same subnet for the laptop to connect to the robot. Connecting can be confirmed by using ping.

ping roboRIO-971-frc.local

or

ping 10.9.71.2

If this does not work, perhaps the roboRIO has not been configured to have a static IP address. Use a USB cable to connect from a Windows laptop to the roboRIO and use a web browser (Chrome is preferred, IE/Edge is not-- see this technical note) to configure the roboRIO to have a static IP address of 10.9.71.2. Browse to http://roborio-971-frc.local or http://172.22.11.2. Click on the "Ethernet" icon on the left, select "Static" for the "Configure IPv4 Address" option. Set the "IPv4 Address" to 10.9.71.2. Set the "Subnet Mask" to "255.0.0.0". Finally click on "Save" at the bottom of the screen. If you have trouble using an Ethernet cable, try using a USB cable (USB A->B).

Another option is to configure the laptop to have a link-local connection by using the "Network Settings" GUI. The laptop will then be on the same subnet in the address range of 169.254.0.0 to 169.254.255.255. James thinks this will only work over Ethernet (i.e., not USB; he is not sure what will happen if you attempt this over USB), and if the robot does not have a static IP address set and there is no DHCP server assigning an IP address to the roboRIO. James says to also note that this implies that the roboRIO will also have a 169.254.. IP addresss, and that the only simple way to figure it out is to use mDNS.

LSP Setup for Rust

You can run bazel run //tools:gen_rust_project to generate a rust-project.json file which rust-analyzer will pick up. You will need to execute this rule periodically as it will be outdated whenever the BUILD files change.

Note that there's currently no way to tell rust-analyzer how to compile the code, so while it will give you completion support, go to definition, and other niceties, it won't show compilation errors or warnings at this point.

Other resources

1. Intro to AOS, our robot Operating System
2. Introductory example: ping/pong
3. Example of logging

TODOs:

1. Add more info about git
2. Add more robot debugging and networking troubleshooting