====== Walking Through the 2024 Codebase ======

Or, A Young Omnicat's Illustrated Primer

This page is the season-specific documentation of the code for the 2024 Crescendo game.   For a more general introduction to downloading tools, compatible programming environments, and an intro to WPILib (the main FRC code library) see the basic [[control:code:tutorial]] in this Wiki.

===== High-level overview of the 2024 code =====

The **RoboRio** is running a version of the Linux operating system. The 2024 code is written in Java, and runs on the RoboRio. The main repository for the 2024 code is [[https://github.com/Team1452/crescendo-2024]]


The first module launched when the code runs is main.java which creates an object called **robotInit()**, philosophically similar to setup() on an Arduino. This only runs once.

After that (again, somewhat imperfectly analogous to an Arduino), **RobotPeriodic** runs on a user- set frequency, like every 20 ms. If the activities in that cycle overrun, right now the thread where they started will continue and a new thread is launched. (Side note: this may or may not be being handled correctly by Java’s garbage collection, and should be monitored/researched in future.)

Some activities are interrupt-driven. For example, the shooter activities will be initiated when  appropriate conditions are met.

FIRST Robotics allows you to use several different modes of programming the robot. The one that we are using is called **LoggedRobot**, which uses the **Advantage Kit** to log robot behavior and report it to the driver. This toolkit in turn can be found at  [[https://github.com/Mechanical-Advantage/AdvantageKit]].

For most basic functions, we are using the WPILib library, with documentation at   [[https://docs.wpilib.org/en/stable/docs/software/basic-programming/java-gc.html]]

==== External Dependencies ====

=== Swerve Drive ===

The swerve drive uses the “Yet Another General Swerve Library” (YAGSL) library, largely built on top of the WPILib libary. It can be found, with examples, at

[[https://yagsl.gitbook.io/yagsl/fundamentals/swerve-drive]]

=== Robot Vision ===

Robot vision processing happens on the dedicated Limelight processor, a Raspberry Pi. The code that runs on the Limelight can be downloaded at [[https://limelightvision.io/pages/downloads]]. The Limelight has libraries that can do basic object recognition, including April tags. Information from the Limelight is transferred over an ethernet connection to the RoboRio.  **<<KAI: then what happens?? What libraries grab data? Is there a branch with tests of field-oriented control?>>**

=== Gyro (Pigeon) ===

**<<KAI add>>**

=== Motors and Encoders ===

**<<KAI add>>**

=== Other Dependencies ===

**<<KAI add>>**

=== 2024 File Structure ===

External dependencies like the ones noted above are contained in JSON files at   [[https://github.com/Team1452/crescendo-2024/tree/main/vendordeps]] 

**<<KAI: Please note what each of these libs in vendordeps controls/does>>** 

NavX controls...  

REVLib controls     

PathplannerLib controls    

Phoenix6Lib controls     

ReduxLib_2024 controls     

WPILibNewCommands .. (does what?)

The file structure of the 2024 code is as follows

{{:tree.png?400}}

=== Code Function ===

**<<ADD UML DIAGRAM (or at least narrative) AND MORE DETAIL HERE - TOPICS BELOW>>**

  - What is handled by WPILib and what is unique-to-us code
  - Swerve, separation of concerns (Indexer/LEDs/Shooter) and Auto
  - Walk through UML diagram from top. Explanation of (1) components/separation of concerns, (2) libraries/tools (YAGSL, REV/Phoenix/etc., custom path planner tool vs. better one), (3) Limelights. Mention everything that's bad and what we should've done instead/what we would have done with more time
  - - We are robot-centric control now - what might need to be added to be field-centric?

=== Testing ===
Unit tests should always be developed for code that can be repeated whenever significant functionality is added. Ones we used this year included:

1. Test to see whether the robot could move one meter straight ahead, and then turn a specified number of degrees.

2. Ask the robot to draw a square, usually 1 m on a side, and repeat clockwise and counterclockwise.

These tests will eliminate many simple errors that otherwise may be hard to debug.
**<<Kai add: other frequently-used tests?>>**