Changes to the codelab
Adding and editing the documentation, comments and instructions to make it easier and more readable.
Change-Id: Ieca49bf2e89eb17b4fa5fae1682e4e5a139b799d
Signed-off-by: Sabina Leaver <100027607@mvla.net>
diff --git a/frc971/codelab/README.md b/frc971/codelab/README.md
index 2fdf08c..8c25cac 100644
--- a/frc971/codelab/README.md
+++ b/frc971/codelab/README.md
@@ -1,14 +1,63 @@
# FRC971 "Codelab"
-## Flatbuffers tutorial
-
-Flatbuffers has pretty good [tutorials](https://google.github.io/flatbuffers/flatbuffers_guide_tutorial.html) for how to use them. We recommend
-going through them for more information.
-
-## Basic control loop
-
Welcome! This folder contains a "codelab" where you can go through the process
of fleshing out a basic control-loop using the same infrastructure as we do for
the control loops that normally run on our robots. Currently, this just consists
-of a single codelab; the instructions for this are in the comments of the
-`basic.h` file in this directory.
+of a single codelab; the instructions can be found below.
+
+## Setup
+
+Before starting this codelab, you should already have set up your computer with all of the programs needed to build and run the robot code, or have an account on the build server. If you have not done this, follow the instructions in the [introduction](https://software.frc971.org/gerrit/plugins/gitiles/971-Robot-Code/+/refs/heads/master/README.md).
+
+## Flatbuffers tutorial
+
+Our code uses flatbuffers extensively. If you're unfamiliar with them, you can take a look at these [tutorials](https://google.github.io/flatbuffers/flatbuffers_guide_tutorial.html) for how to use them. This is optional but reommended if you are looking for more background on flatbuffers, and can be done before or after the codelab.
+
+## Instructions
+
+This codelab helps build basic knowledge of how to use 971 control loop
+primatives.
+
+When this codelab is run, it performs a series of tests to check whether the code is working properly. Your job is to add or make changes to the code to get the tests to pass.
+
+### Running the tests
+
+In order to run the tests, execute the following command in the terminal in the 971-Robot-Code folder:
+```
+bazel run frc971/codelab:basic_test -- --gtest_color=yes
+```
+
+In total, there are 7 tests, 3 of which will fail when you first run them. As each tests fails, it will print out the details of how each test result differed from the expected value. At the bottom, it will summarize the number of passed and failed tests.
+
+As you work through the codelab, you can run the tests to check your progress. Once they all pass, you are finished and can move on to submitting a code review.
+
+### Control loops
+
+A control loop is a piece of code that is repeatedly executed while the robot is running, recieiving input from the robot controllers and sensors and sending intructions to the motors that control the robot.
+
+Control loops all follow the same structure:
+There are 4 channels that send and recieve instructions. These channels are goal, position, output, and status. Goal and position are input channels, which recieve messages from the robot's sensors and input from the controller. Output and status are output channels, which send messages to the motors.
+
+::frc971::controls::ControlLoop is a helper class that takes
+all the channel types as template parameters and then calls
+RunIteration() whenever a Position message is received.
+It will pass in the Position message and most recent Goal message
+and provide Builders that the RunIteration method should use to
+construct and send output/status messages.
+
+The various basic_*.fbs files define the Goal, Position, Status, and Output
+messages. The code for the tests is in the basic_test.cc file, and the code you will edit is in the basic.cc file.
+
+In order to get the tests to pass, you'll need to fill out the RunIteration()
+implementation in basic.cc so that it uses the input goal/position to
+meaningfully populate the output/status messages. You can find descriptions
+of exactly what the fields of the messages mean by reading all the *.fbs
+files, and the tests below can be reviewed to help understand exactly what
+behavior is expected.
+
+### Submitting a code review
+
+Once you can get the tests to pass, follow the directions in [this file](https://software.frc971.org/gerrit/plugins/gitiles/971-Robot-Code/+/refs/heads/master/documentation/tutorials/submitting-code-for-a-review.md) for creating a
+code review of the change. We will not actually *submit* the change (since
+that would remove the challenge for future students), but we will go through
+the code review process.
\ No newline at end of file
diff --git a/frc971/codelab/basic.cc b/frc971/codelab/basic.cc
index 8019445..0393508 100644
--- a/frc971/codelab/basic.cc
+++ b/frc971/codelab/basic.cc
@@ -10,17 +10,23 @@
void Basic::RunIteration(const Goal *goal, const Position *position,
aos::Sender<Output>::Builder *output,
aos::Sender<Status>::Builder *status) {
- // TODO(you): Set the intake_voltage to 12 Volts when
+
+ // FIX HERE: Set the intake_voltage to 12 Volts when
// intake is requested (via intake in goal). Make sure not to set
// the motor to anything but 0 V when the limit_sensor is pressed.
- // Ignore: These are to avoid clang warnings.
+ // This line tells the compiler to to ignore the fact that goal and
+ // position are not used in the code. You will need to read these messages
+ // and use their values to determine the necessary output and status.
(void)goal, (void)position;
if (output) {
Output::Builder builder = output->MakeBuilder<Output>();
- // TODO(you): Fill out the voltage with a real voltage based on the
- // Goal/Position messages.
+
+ // FIX HERE: As of now, this sets the intake voltage to 0 in
+ // all circumstances. Add to this code to output a different
+ // intake voltage depending on the circumstances to make the
+ // tests pass.
builder.add_intake_voltage(0.0);
output->Send(builder.Finish());
@@ -28,10 +34,11 @@
if (status) {
Status::Builder builder = status->MakeBuilder<Status>();
- // TODO(you): Fill out the Status message! In order to populate fields, use
- // the add_field_name() method on the builder, just like we do with the
- // Output message above. Look at the definition of Status in
- // basic_status.fbs and populate the field according to the comments there.
+ // FIX HERE: Fill out the Status message! In order to fill the
+ // information in the message, use the add_<name of the field>() method
+ // on the builder, just like we do with the Output message above.
+ // Look at the definition of Status in basic_status.fbs to find
+ // the name of the field.
status->Send(builder.Finish());
}
diff --git a/frc971/codelab/basic.h b/frc971/codelab/basic.h
index 8748bc5..c0715a7 100644
--- a/frc971/codelab/basic.h
+++ b/frc971/codelab/basic.h
@@ -11,45 +11,6 @@
namespace frc971 {
namespace codelab {
-// This codelab helps build basic knowledge of how to use 971 control loop
-// primatives.
-//
-// For flatbuffers background, we recommend checking out
-// https://google.github.io/flatbuffers/flatbuffers_guide_tutorial.html
-//
-// The meat of the task is to make the tests pass.
-//
-// Run the tests with:
-// $ bazel run //frc971/codelab:basic_test -- --gtest_color=yes
-//
-// Control loops all follow the same convention:
-// There are 4 channels (goal, position, status, output).
-//
-// 2 channels are input channels: goal, position.
-// 2 channels are output channels: output, status.
-//
-// ::frc971::controls::ControlLoop is a helper class that takes
-// all the channel types as template parameters and then calls
-// RunIteration() whenever a Position message is received.
-// It will pass in the Position message and most recent Goal message
-// and provide Builders that the RunIteration method should use to
-// construct and send output/status messages.
-//
-// The various basic_*.fbs files define the Goal, Position, Status, and Output
-// messages.
-//
-// In order to get the tests to pass, you'll need to fill out the RunIteration()
-// implementation in basic.cc so that it uses the input goal/position to
-// meaningfully populate the output/status messages. You can find descriptions
-// of exactly what the fields of the messages mean by reading all the *.fbs
-// files, and the tests below can be reviewed to help understand exactly what
-// behavior is expected.
-//
-// Once you can get the tests to pass, follow the directions in the
-// documentation/tutorials/submitting-code-for-a-review.md file for creating a
-// code review of this change. We will not actually *submit* the change (since
-// that would remove the challenge for future students), but we will go through
-// the code review process.
class Basic
: public ::frc971::controls::ControlLoop<Goal, Position, Status, Output> {
public:
diff --git a/frc971/codelab/basic_status.fbs b/frc971/codelab/basic_status.fbs
index 0aa2938..58a29db 100644
--- a/frc971/codelab/basic_status.fbs
+++ b/frc971/codelab/basic_status.fbs
@@ -1,10 +1,12 @@
namespace frc971.codelab;
table Status {
- // Lets consumers of Status know if the requested intake is finished. Should
- // be set to true by the intake subsystem when the Goal message is requesting
- // the intake to be on and the limit sensor from the position message has
- // been enabled.
+ // This FlatBuffer lets consumers of Status know if the requested intake is
+ // finished. There is one field, intake_complete, which should be set to
+ // true by the intake subsystem when the Goal message is requesting the intake
+ // to be on and the limit sensor from the position message has been enabled.
+
+
intake_complete:bool (id: 0);
}
diff --git a/frc971/codelab/basic_test.cc b/frc971/codelab/basic_test.cc
index 9b22705..46226be 100644
--- a/frc971/codelab/basic_test.cc
+++ b/frc971/codelab/basic_test.cc
@@ -1,3 +1,6 @@
+// In this file, you can view the tests that are being run to determine
+// if the code works properly in different situations.
+
#include "frc971/codelab/basic.h"
#include <unistd.h>
@@ -53,6 +56,10 @@
builder.Send(position_builder.Finish());
}
+ // This is a helper function that is used in the tests to check
+ // if the output of the test is equal to the expected output.
+ // It takes in two expected values and ompares them to the values
+ // it recieves from the code.
void VerifyResults(double voltage, bool status) {
output_fetcher_.Fetch();
status_fetcher_.Fetch();
@@ -210,6 +217,9 @@
}
// Tests that the control loop handles things properly if disabled.
+// Note: "output" will be null when the robot is disabled. This is
+// a tricky test to get to pass, it should pass at first but fail
+// as you add more code.
TEST_F(BasicControlLoopTest, Disabled) {
basic_simulation_.set_limit_sensor(true);