Add arm and shooting bot projects with associated docs

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 SciBorgs Programming
+Copyright (c) 2024 SciBorgs Programming
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -0,0 +1,25 @@
+# SciGuides
+
+Welcome to SciGuides, a repository made by FRC Team 1155 and 2265 to gather all of our experience and knowledge for public and internal use.
+
+## Usage
+
+SciGuides is project-based, containing guides and reference sheets aimed at guiding readers towards a high level of competency around FRC code.
+
+It can be used as teaching material, robot code practice, or for referencing information and generational knowledge.
+
+This repository additionally functions as the curriculum of our school's central robotics program.
+
+## Contributing & Updating
+
+There are a few values we emphasize when writing SciGuides:
+
+- Don't reinvent the wheel.
+  - Maintaining more than necessary, or redundant information, would be a waste of time, so we heavily reference existing documentation from vendors, libraries, and WPILib.
+  - Minimize what must be changed from year-to-year! There is no need to restate information with existing documentation past a simple sentence or past the purposes of introduction.
+
+- Experiencing is the heart of learning.
+  - It is our firm belief that people learn best when actually **writing** and **seeing** code (not just text) on the screen. Code examples, code examples, code examples (and the occasional image and gif, too!)
+
+- These guidelines are not immutable.
+  - Use your own discretion (or that of your fellow team members) to determine what is best for this repository to achieve its goals.

reference-sheets/Command-based.md

@@ -0,0 +1,96 @@
+# [The Command-based Paradigm](https://docs.wpilib.org/en/stable/docs/software/commandbased/what-is-command-based.html)
+
+For its wide capabilities and ease of use, we use WPILib's command-based paradigm to compartmentalize and control the different parts of our robot.
+
+Subsystems represent independent parts of the robot and their hardware, which work together to achieve a desired action.
+
+Commands safely direct those subsystems to perform actions in a wide suite of ways. They can be chained together in parallel or made sequential to one another, among other handy functions.
+
+These are general definitions; there's actually a fair bit of nuance to both.
+
+## [Subsystems](https://docs.wpilib.org/en/stable/docs/software/commandbased/subsystems.html)
+
+For our purposes, all subsystems extend WPILib's `SubsystemBase`. It provides command safety functionality, its [inherited periodic methods](https://docs.wpilib.org/en/stable/docs/software/commandbased/subsystems.html#periodic), and [default commands](https://docs.wpilib.org/en/stable/docs/software/commandbased/subsystems.html#default-commands). See in greater detail on [the official WPILib docs](https://docs.wpilib.org/en/stable/docs/software/commandbased/subsystems.html).
+
+Advanced readers may want to know [more about specifics that define subsystems](#a-word-on-what-makes-a-subsystem-a-subsystem).
+
+## [Commands](https://docs.wpilib.org/en/stable/docs/software/commandbased/commands.html)
+
+Commands represent robot actions with the hardware. They should be used for actions that may interfere with how the robot is run (i.e actual robot movement or changing PID constants.)
+
+Every individual command has a defined structure, with methods that are called when it begins, throughout its runtime, and when it ends (as a result of a set end condition OR by interruption). Check the [official docs](https://docs.wpilib.org/en/stable/docs/software/commandbased/commands.html) for specfics.
+
+A nice list of these individual commands can be found under the subclasses of WPILib's [Command class](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html).
+
+_Note: we avoid using specific control commands like `PIDCommand` or `SwerveControllerCommand` as they limit our precision and capabilities compared to using their components individually._
+
+### Command Compositions
+
+Commands can also be chained together to create much larger commands for complex routines. You'll likely be using these a lot:
+
+- [Parallel Commands](https://docs.wpilib.org/en/stable/docs/software/commandbased/command-compositions.html#parallel) - run multiple commands / runnables at once
+  - Deadline and Race Commands (different end conditions)
+- [Sequential Commands](https://docs.wpilib.org/en/stable/docs/software/commandbased/command-compositions.html#sequence) - run commands / runnables after the previous one ends
+
+For more examples, see a good list [here](https://docs.wpilib.org/en/stable/docs/software/commandbased/command-compositions.html#composition-types).
+
+### Decorators
+
+WPILib provides command methods that can chain onto other commands to dynamically create compositions like the one below.
+
+These include methods like `andThen()` and `alongWith()`, representing the creation of a sequential and parallel command respectively.
+
+When properly composed, complex commands can often be read through like plain english, like below:
+
+```java
+    operator
+        .leftTrigger()
+        .whileTrue(
+            shooting.shootWithPivot(PivotConstants.FEED_ANGLE, ShooterConstants.DEFAULT_VELOCITY));
+    // while the operator controller's left trigger button is held, shoot
+```
+
+Individual commands and command groups each have their own singular / group of decorators. The majority can be found [here](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html).
+
+Commands can also be accessed through [WPILib's `Commands`](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html) class.
+
+## Triggers
+
+A big part of the command-based ecosystem are triggers. Users can bind commands and `Runnable` actions to triggers, which are run in specified ways when the trigger is activated. 
+
+Common operations with trigger commands include, but are not limited to:
+
+- `onTrue()`, run once on trigger activation
+- `whileTrue()`, run periodically while trigger is active
+
+For instance, the `teleop()` trigger in `Robot.java` (and its sisters) run binded commands when teleop mode is activated on the robot (by DriverStation or FMS).
+
+See [here for examples and specific usage in WPILib](https://docs.wpilib.org/en/stable/docs/software/commandbased/binding-commands-to-triggers.html).
+
+## Specifics & Common Issues
+
+### Singular Command Instances
+
+Each instance of a command can only be scheduled once, otherwise risking unpredictable behavior. To remedy this, we create command factories that return new instances of a command each time it is called, like below:
+
+```java
+    public Command updateSetpoint(double velocity) {
+        return run(() -> hardware.setVelocity(velocity));
+    }
+```
+
+### Command Composition Requirements & Proxying
+
+When created, command compositions take on the subsystem requirements of all of its parts, sometimes creating undesirable behavior as no other commands can be run on a subsystem even if the composition has sequenced past that point.
+
+The current best solution to this (as of 24-25) is command proxying. See [the docs](https://docs.wpilib.org/en/stable/docs/software/commandbased/command-compositions.html#scheduling-other-commands) for a more in-depth discussion.
+
+### A word on what makes a subsystem a subsystem
+
+More specifically, subsystems can be defined as collections of hardware that are not dependent on others to function well. As a result, multiple different mechanisms can be part of a single subsystem.
+
+For instance, imagine a double-jointed arm. When the joint connected to the main pivot moves, the position of the arm stemming from the joint will change, making their movement and position dependent on one another.
+
+As a result, it is good practice to contain both mechanisms in the same subsystem so that they have easy access to each other's information, which makes accounting for relative position easier. This limits code duplication and makes working with the whole simpler.
+
+**This is not set in stone, and from year to year, the requirements for robot operation may change. Use your own discretion to see what sense of organization works best for your robot!**

reference-sheets/README.md

@@ -0,0 +1,3 @@
+# Document Reference Sheets
+
+This folder contains guides that introduce and summarize key topics (and practices) with links to official WPILib / vendor documentation for further, in-depth exploration.

reference-sheets/Sensors.md

@@ -0,0 +1,35 @@
+# [Fundamentals of Sensors](https://docs.wpilib.org/en/stable/docs/software/hardware-apis/sensors/sensor-overview-software.html#sensor-overview-software)
+
+This aims to be an brief reference to the different sensors that you will most commonly see and use on the robot. For further details, see the linked materials or consult your favorite search engine.
+
+## [Encoders](https://docs.wpilib.org/en/stable/docs/software/hardware-apis/sensors/encoders-software.html#encoders-software)
+
+They measure rotation. Many brushless motors have encoders integrated inside of them, while others can be found outside of the robot. Most measure what is effectively rotational displacement, as encoders read negative values from relative backwards movement.
+
+All encoders have some sort of default unit. Various vendors will have different methods of changing the units returned; read their docs!
+
+### [Relative Encoders](https://docs.wpilib.org/en/stable/docs/software/hardware-apis/sensors/sensor-overview-software.html#sensor-overview-software)
+
+When powered on, its distance measurement will read 0. The zero-point will change on code boot, making its measurements "relative" to whenever it started.
+
+### [Absolute Encoders](https://docs.wpilib.org/en/stable/docs/software/hardware-apis/sensors/encoders-software.html#encoders-software)
+
+Has a set zero point. Will always know where it is, even between code deploys.
+
+## [Gyroscope](https://docs.wpilib.org/en/stable/docs/software/hardware-apis/sensors/gyros-software.html)
+
+It measures the rate of rotation of whatever plane it is on (and sometimes its relative axes). Usually found on the base of the drivetrain.
+
+## [Beambreaks]()
+
+Detect if something has passed through them. Two key components: a part that shoots a ray of light, and a receiver. When the receiver no longer detects light, a signal is returned.
+
+For our program, beambreak sensors return true when unblocked, and false when blocked. **THIS IS SUBJECT TO CHANGE.**
+
+## [Cameras](https://docs.photonvision.org/en/latest/docs/integration/aprilTagStrategies.html)
+
+Using the known position of a camera and the known position of targets in its view, the target-relative and field-relative position of a robot can be calculated. These can be used to auto-correct odometry, auto-aim towards a target, or [automate movement entirely](https://www.youtube.com/watch?v=2zB0w69P4mc&t=73s).
+
+## [Interactions with Software](https://docs.wpilib.org/en/stable/docs/software/hardware-apis/sensors/digital-inputs-software.html#digital-inputs-software)
+
+From a code perspective, nearly all will be integrated into hardware (that can be interacted with their apis) or plugged into the RoboRIO (that can be interacted with using built-in WPILib classes, like `RelativeEncoder` or `DigitalInput`).

reference-sheets/Simulation.md

@@ -0,0 +1,34 @@
+# Robot Simulation
+
+Simulation in WPILib allows for code and logic to be tested onboard your computer, rather than physical hardware. It's exceptionally useful for when construction and electronics have not finished the robot, but you have code to run!
+
+There are a few different facets of simulation to take note of before you can start, including:
+
+- [The Simulation GUI](https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation)
+- [WPILib's simulation classes](#simulation-classes)
+  - [Physics simulators](https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation/physics-sim.html)
+  - [Mechanism2d](https://docs.wpilib.org/en/stable/docs/software/dashboards/glass/mech2d-widget.html)
+  - [Field2d](https://docs.wpilib.org/en/stable/docs/software/dashboards/glass/field2d-widget.html)
+- [Logging & Dashboards](#logging--dashboards)
+
+## Logging & Dashboards
+
+In testing, it is common to want to directly observe robot measurements and values in order to tune your systems or debug. This is also incredibly important when working with simulation, as you otherwise have no reference to what is going on without a physical robot.
+
+For more details, visit [our doc](/reference-sheets/Telemetry.md).
+
+## Simulation Classes
+
+This section will heavily reference the WPILib docs [here](https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation/introduction.html).
+
+Before doing anything with simulation, make sure desktop support is turned on. Follow [these instructions](https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation/introduction.html). Use [the next doc](https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation) as reference for the GUI when working with it (same as above).
+
+WPILib contains generic simulation classes for different mechanisms (like `ElevatorSim`) based on physical details and constraints about your system. You can see a full list of them and examples on using them [here](https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation/physics-sim.html).
+
+### Widgets
+
+There's also the widget classes `Field2d` and `Mechanism2d`, which respectively allow for pixel representations of the field and parts of mechanisms.
+
+Physical objects, like game pieces, wheels, the drivetrain, etc., can be added to a Field2d object, allowing for digital representations of a real-life field. [Here's more](https://docs.wpilib.org/en/stable/docs/software/dashboards/glass/field2d-widget.html) on how you can use it.
+
+Mechanism2ds allow for block representations of mechanisms. This is most commonly used for simulating arms and elevators. See [the docs](https://docs.wpilib.org/en/stable/docs/software/dashboards/glass/mech2d-widget.html) for usage details and further clarifications.

reference-sheets/Telemetry.md

@@ -0,0 +1,34 @@
+# Telemetry
+
+### The art of logging and log-viewing
+
+In testing (real or simulated), it is common to want to directly observe robot measurements and values in order to tune your systems and debug. Rather than looping print statements, WPILib provides interfaces allowing certain information to be logged while the robot runs.
+
+Loggers send data to [NetworkTables](https://docs.wpilib.org/en/stable/docs/software/networktables/networktables-intro.html), which can be read [while running](#dashboards) or stored for later viewing in [log files](#log-viewers).
+
+Only classes that implement `Sendable` can be sent over NetworkTables; see [here](https://docs.wpilib.org/en/stable/docs/software/telemetry/robot-telemetry-with-sendable.html#what-is-sendable) for more details.
+
+For more in-depth information on the inner workings, visit [the docs](https://docs.wpilib.org/en/stable/docs/software/telemetry/telemetry.html).
+
+## Logging libraries
+
+Logging libraries, third-party or WPILib-made, are not monolithic. Some are annotation-based (using Java `@Annotations`), while others are framework-based. All are unique; a nice list of them can be found [here](https://docs.wpilib.org/en/stable/docs/software/telemetry/3rd-party-libraries.html).
+
+- [Monologue](https://github.com/shueja/Monologue/wiki) (we use this!)
+- [Epilogue](https://docs.wpilib.org/pt/latest/docs/software/telemetry/robot-telemetry-with-annotations.html) (official WPILib)
+- [AdvantageKit](https://github.com/Mechanical-Advantage/AdvantageKit/blob/main/docs/WHAT-IS-ADVANTAGEKIT.md)
+- [URCL](https://github.com/Mechanical-Advantage/URCL)
+
+## Dashboards
+
+There are two types of dashboards: driving and programming. We'll be talking about the ones related to debugging.
+
+These programs allow you to view data over NetworkTables in real time, allowing you to see logged data while working on a real or simulated robot. These **will be your main tools for debugging**.
+
+Here's a [nice list](https://docs.wpilib.org/en/stable/docs/software/dashboards/dashboard-intro.html) of them.
+
+## Log Viewers
+
+Log viewers will pull measurements from log files and most commonly allow you to graph data or visualize them in some way. These are especially useful for direct post-match debugging, given you have the ability to process and debug with the data formats.
+
+See [this doc](https://docs.wpilib.org/en/stable/docs/software/telemetry/datalog-download.html#downloading-processing-data-logs) for more information.