diff --git a/INSTRUCTIONS.md b/INSTRUCTIONS.md new file mode 100644 index 0000000..cc0b8d9 --- /dev/null +++ b/INSTRUCTIONS.md @@ -0,0 +1,20 @@ +Your job is to create documentation to aid new members of an FTC team in learning all the software + some electronics they need to know to succeed in FTC. The documentation should assume nothing except java knowledge. It should be organized in a way that is easy to follow and understand, with clear explanations and examples. + +First let's go over the structure of the documentation: +There are 2 folders that will eventually be removed and you should not concern yourself with them. They are the `java` and `markdown` folders. +This file is `INSTRUCTIONS.md` +There is a `PLANNING.md` file that has a very rough outline of what I want the documentation to look like. +The `README.md` file is going to be the main entry point for the documentation. It's audience is new members of the team, and it should explain how to use the documentation, and where to start. It is not up to date. You will need to update it. +There are 2 more folders: `codebase` and `intro`. These contain current documentation that has been written already. You should use this documentation as a reference for the style and format of the documentation you will be writing. The `codebase` folder contains documentation about the codebase, and the `intro` folder contains documentation about the basics of FTC and robotics in general. These folders are not necessarily complete. + +Your job will be completed in 2 steps: +The first is to make a more detailed outline of the documentation. I need you to expand on the contents of `PLANNING.md` and make a more detailed outline in `OUTLINE.md`. This is for you to use later, and I may edit parts of it if I see fit. It should organize everything into a logical structure that shows where each file goes, and what will be the different parts of each file. Please also include the already completed reference documentation in the outline as well. If you need to change any of the organization in `PLANNING.md` that's perfectly fine. + +The second step will be to actually write the documentation. You will use the outline you created in the first step to guide you in writing the documentation. You should write the documentation in a clear and concise manner, with examples and explanations that are easy to understand. You should also make sure to include any relevant information that you think would be helpful for new members of the team. + +Some more things to note: +The code style is to be consistent with previous years that our team has competed. Our team is Stuy Fission 310. I have put an old codebase from the power play season in the `power-play` folder. You should use this codebase as a reference for the code style and structure that we have used in the past. It will not be in the final documentation. We also have our own library of utils that we use called `FissionLib`. This is in the `FissionLib` folder. Please use this as a reference as well. +In case you need any information regarding FTC programming I have also included `gm0.org` documentation in the `gm0` folder. Feel free to use this as a reference too. gm0 is extremely useful for learning about FTC, and thus should be linked in this documentation as well. I will obviously not include the whole `gm0` documentation, but it's here for your reference. If there is any additional information that you are not sure about, please make a note either in the outline, or in the documentation, and tell me about it so I can provide you with the correct information. +One final thing is that previously we have used RoadRunner for our drivetrain. Some of the existing documentation references RoadRunner, and the `power-play` repo also does. However, we are switching to PedroPathing. Make sure the documentation you write is updated for pedro pathing and not roadrunner. Please also write patches for the existing documentation as well. I have included the pedro pathing documentation in the `pedro` folder. + +Please start step 1. Stop when you are done, I will review the outline and then we can move on to step 2. diff --git a/OUTLINE.md b/OUTLINE.md new file mode 100644 index 0000000..7e0363a --- /dev/null +++ b/OUTLINE.md @@ -0,0 +1,294 @@ +# Newbie Education Documentation Outline (Step 1) + +This outline expands `PLANNING.md` into a concrete, file-by-file documentation plan for new FTC software/electronics members. + +## Goals and Audience +- Audience: brand-new FTC members with basic Java knowledge. +- Goal: teach practical setup, codebase navigation, mechanism development, TeleOp, autonomous (PedroPathing), debugging, and team workflow. +- Style target: match current docs in `intro/` and `codebase/` (plain language, concrete examples, progressive complexity). + +## Existing Material Included as Reference + +### Already Written (Keep + integrate) +- `intro/00-setup.md` +- `intro/01-code-overview.md` +- `codebase/mechanisms/00-intro.md` +- `codebase/mechanisms/01-robot-scoring.md` + +### Existing Material Requiring Patches in Step 2 +- `intro/01-code-overview.md` + - Replace RoadRunner-focused section with PedroPathing-focused structure and terminology. + - Keep conceptual role of motion-planning libraries, but update folder/file examples to current PedroPathing usage. + +### Reference Sources (not part of final lesson set) +- `power-play/` (team historical style, opmode organization, dev opmodes, hardware/mechanism patterns) +- `FissionLib/` (team utility conventions + dependency setup) +- `gm0/` (external FTC learning reference to link where useful) +- `pedro/` (PedroPathing docs and setup flow) + +--- + +## Proposed Final Documentation Structure + +### 0) Main entry and usage guide + +#### `README.md` (rewrite in Step 2) +Purpose: onboarding index + learning path. + +Sections: +1. What this documentation is and who should use it +2. How to use this curriculum (self-study + with mentor + during season) +3. Recommended order (Intro → Codebase → TeleOp → Auton → Advanced) +4. Time estimates per section +5. Prerequisites and required tools +6. External references + - FTC SDK docs + - gm0 + - PedroPathing docs +7. Contributing/fixing docs + +--- + +### 1) Intro track (`intro/`) + +#### Existing: `intro/00-setup.md` (patch) +Keep most content; improve for clarity and current workflow. + +Planned section layout: +1. Why Android Studio + Git in FTC +2. Install checklist (Android Studio, Git, GitHub auth) +3. Clone FTC base + team code flow +4. Import project and first successful build +5. Common setup failures + - Gradle sync failures + - SDK/platform mismatch + - Git auth issues +6. Verification checklist before moving on + +#### Existing: `intro/01-code-overview.md` (major patch) +Planned section layout: +1. TeamCode vs teamcode clarity +2. Core folders (`hardware`, `opmode`, etc.) +3. How hardware classes and opmodes interact +4. Autonomous stack overview (PedroPathing, not RoadRunner) +5. Where to find tuning/test opmodes +6. Reading assignment: one TeleOp + one Auton walkthrough + +#### New: `intro/02-git-workflow.md` +1. Why Git matters during build season +2. Branch naming and PR expectations (team conventions) +3. Typical daily workflow + - pull/rebase + - branch + - commit small + - push + - PR +4. Resolving conflicts safely +5. Git mistakes to avoid +6. Mini exercise: add/change a mechanism constant and open PR + +#### New: `intro/03-android-studio-workflow.md` +1. Project/tool windows and navigation tips +2. Running opmodes and logcat basics +3. Build variants and sync/build cycle +4. Device connection basics (Control Hub / ADB overview) +5. Common compile errors and fast triage +6. Recovery checklist when “everything is broken” + +--- + +### 2) Codebase track (`codebase/`) + +#### Existing: `codebase/mechanisms/00-intro.md` (patch) +1. What counts as a mechanism +2. Mechanism class skeleton +3. `init` vs `loop` +4. HardwareMap mapping best practices +5. Servo/motor constants and naming +6. Basic button mapping pattern +7. Small updates for clarity and style consistency + +#### Existing: `codebase/mechanisms/01-robot-scoring.md` (patch) +1. Why `Scoring` exists (coordination layer) +2. State-based logic pattern +3. `Robot` as composition root +4. Button behavior in different states +5. Automation boundaries (manual vs automatic actions) +6. Add cautionary notes around blocking behavior and race conditions + +#### New: `codebase/mechanisms/02-mechanism-design.md` +1. How to decide if code belongs in a mechanism +2. Single responsibility in robot components +3. Interface design for mechanism APIs +4. Initialization order and dependencies +5. Safety defaults and fail-safe positions +6. Testing mechanism logic with dev opmodes + +#### New: `codebase/teleop/00-teleop-architecture.md` +1. TeleOp goals (driver speed + reliability) +2. Loop structure and update order +3. Controls abstraction (`Controls.java`-style patterns) +4. Click vs hold vs toggle inputs +5. State machine pattern for scoring flow +6. Telemetry priorities during matches + +#### New: `codebase/teleop/01-controls-and-input.md` +1. Mapping controls for driver + operator +2. Debouncing and edge detection +3. Shared buttons with state-dependent behavior +4. Avoiding input conflicts +5. Example control map template + +#### New: `codebase/commands/00-command-basics.md` +1. What a command is in team architecture +2. Why commands reduce TeleOp complexity +3. Command lifecycle (start/update/finish) +4. Basic command examples +5. When *not* to use commands + +#### New: `codebase/commands/01-command-sequences.md` +1. Sequencing actions safely +2. Interruptions and cancel behavior +3. Timeout/failure handling +4. Integrating with state machine logic +5. Debugging command flow + +#### New: `codebase/commands/02-common-bugs.md` +1. Known pitfalls (including autocommandmachine bug note from planning) +2. How to isolate command bugs +3. Logging and telemetry strategy for commands + +--- + +### 3) Autonomous + pathing track (`codebase/auton/`) + +#### New: `codebase/auton/00-auton-overview.md` +1. Match strategy constraints (30s, reliability over complexity) +2. Auton architecture overview +3. Required subsystem readiness before auton + +#### New: `codebase/auton/01-pedro-setup.md` +1. Why team is using PedroPathing +2. Installing/including PedroPathing in project +3. Required project/folder structure +4. Minimal first path opmode +5. Comparison note: RoadRunner concepts mapped to Pedro terms + +#### New: `codebase/auton/02-localization-and-constants.md` +1. Robot constants and geometry +2. Localization basics and sensor assumptions +3. How to gather/update constants +4. Versioning/timestamping tuned values + +#### New: `codebase/auton/03-tuning-workflow.md` +1. Pre-tuning checklist (mechanical + battery + field) +2. Tuning order and rationale +3. Verifying repeatability +4. What to retune and when + +#### New: `codebase/auton/04-path-building.md` +1. Constructing trajectories/paths in PedroPathing +2. Path segmentation and event markers/callback points +3. Reusable path snippets +4. Debugging bad paths (overshoot, drift, heading error) + +#### New: `codebase/auton/05-auton-control-flow.md` +1. Structuring complete autonomous routines +2. State machine vs command sequence in auton +3. Integrating scoring mechanism actions with pathing +4. Failsafes, time budgeting, and fallback parking + +#### New: `codebase/auton/06-ftcdashboard-with-auton.md` +1. Dashboard setup and access +2. Live constant editing (`@Config`) and safe usage +3. Telemetry panels for tuning +4. ADB/IP issues and troubleshooting + +#### New: `codebase/auton/07-real-world-failure-modes.md` +1. Battery voltage effects and mitigation +2. Slippage/collision recovery behaviors +3. “Auton went wrong” case studies and postmortem template + +--- + +### 4) FTC Dashboard track (`codebase/ftcdashboard/`) + +#### New: `codebase/ftcdashboard/00-intro.md` +1. What FTC Dashboard is +2. Team use cases (tuning, telemetry, quick iteration) +3. Security/practical precautions during practice and competition + +#### New: `codebase/ftcdashboard/01-connection-troubleshooting.md` +1. Network setup basics +2. Common IP/ADB pitfalls +3. Quick diagnostics checklist + +#### New: `codebase/ftcdashboard/02-telemetry-patterns.md` +1. High-value telemetry fields +2. Organizing telemetry by subsystem +3. Keeping telemetry useful without lag/noise + +--- + +### 5) Misc practical docs (`codebase/misc/`) + +#### New: `codebase/misc/00-dev-opmodes.md` +1. Purpose of dev opmodes +2. Naming and organization +3. Safety and cleanup rules +4. Promotion path from dev test to production code + +#### New: `codebase/misc/01-telemetry-best-practices.md` +1. Driver-station telemetry essentials +2. Logging for debugging vs match mode +3. Rate limiting and readability + +#### New: `codebase/misc/02-hardware-map-and-config.md` +1. Hardware naming conventions +2. Control Hub/Expansion Hub mapping hygiene +3. Configuration file management between robots + +#### New: `codebase/misc/03-ai-usage-guidelines.md` +1. When AI helps (boilerplate, refactor suggestions) +2. When AI hurts (blind-copying control logic) +3. Verification checklist for AI-generated code +4. Team expectations for attribution/review + +--- + +## Cross-Cutting Documentation Conventions (for Step 2) +- Every lesson includes: + - Objective + - Prerequisites + - Core concepts + - Worked example (small + realistic) + - Common mistakes + - Quick checklist / “Done when…” + - Optional challenge exercise +- Use consistent vocabulary across lessons (`mechanism`, `Robot`, `Scoring`, `TeleOp`, `Auton`). +- Keep examples aligned with team style from `power-play/` + `FissionLib` idioms, but modernized to PedroPathing. +- Prefer simple, maintainable patterns over clever abstractions for newbie readability. + +## Planned Patches to Existing Docs (Step 2 scope) +1. `README.md` — full rewrite as curriculum entry point. +2. `intro/00-setup.md` — update setup flow + troubleshooting details. +3. `intro/01-code-overview.md` — replace RoadRunner section with PedroPathing content. +4. `codebase/mechanisms/00-intro.md` — polish terminology and tighten examples. +5. `codebase/mechanisms/01-robot-scoring.md` — add stronger guidance on state logic and automation boundaries. + +## Open Questions / Info Needed from Team (before or during Step 2) +1. Current season repository name and exact expected folder structure in `teamcode`. +2. Whether command framework is currently active and which classes are canonical. +3. Preferred gamepad mapping standard (Xbox labels vs PS labels). +4. Exact PedroPathing integration method used by team this season. +5. Whether electronics lessons should be included now or in a separate track. +6. Any hard team conventions for branch naming, commit format, and PR checklist. + +## Suggested Build Order for Step 2 +1. Rewrite `README.md` (navigation first). +2. Patch intro files (`intro/00`, `intro/01`). +3. Patch mechanism docs (`codebase/mechanisms/*`). +4. Add TeleOp + commands docs. +5. Add auton/PedroPathing docs. +6. Add FTC Dashboard + misc docs. +7. Final pass for consistency and link integrity. diff --git a/PLANNING.md b/PLANNING.md index 28cee38..38719d6 100644 --- a/PLANNING.md +++ b/PLANNING.md @@ -1,4 +1,4 @@ -1. ftc intro - flint +1. ftc intro - [x] download stuff: git, android studio - [x] show the org/repo - [x] clone repo @@ -6,7 +6,7 @@ - [ ] basic mechanism - [ ] git tutorial (pretend to push some mechanism code) - [ ] basic teleop with controls (no commands yet) -1. android studio - daniel +1. android studio - [ ] how to set up a project - [ ] how to use git with android studio - [ ] how to use the FTC SDK @@ -33,8 +33,7 @@ - [ ] command sequences - [ ] (autocommandmachine has a bug?) 1. auton - - [ ] meep meep - - [ ] are we doing rr still? + - [ ] set up pedropathing - [ ] how to set up the bot and get constants and stuff - [ ] how to tune - [ ] how to write pathing @@ -52,9 +51,6 @@ - [ ] dev op modes - [ ] telemetry -and general lesson organization - order of stuff -install fissionlib and roadrunner stuff +not yet organized: +how to install fissionlib and pedropathing some instructions about using ai (when to not use and how to use copilot) -add homeworks - -read old stuff and check if anything can be reused diff --git a/README.md b/README.md index 5abf361..8e793e0 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,50 @@ -# newbie-education -This repo contains lessons and/or lesson plans for Stuy Fission Newbie Education. The lessons mainly pertain to Software Engineering, but team members in other departments may find the contained material helpful. It is suggested that the Head of Software Engineering be familiar with the lessons, and for every new software engineering or electronics member to go through the lessons. - -These lessons should __not__ replace hands-on learning. They should be supplements to the design and build process of a robot, and introduced throughout the season as appropriate. - -This project was started by Ryan Siu in February 2018 with the intent of preserving knowledge and learned experience for future generations of the team. - -## Contents -- git - - Overview of Git, usefulness, basic usage, GitHub, our organization and conventions -- java - - Introduction to Java, functional programming concepts, Java syntax, object oriented programming -- markdown - - Introduction to markdown, usefulness, formatting -- robot - - auton - - Autonomous programming, sensors, encoders, CV - - electronics - - Robot electronics, REV, MR, cables, robot configuration - - organization - - Code organization, documentation - - teleop - - Teleop programming, controllers -- websites - - fission310 - - Team website, updating content, posting, conventions - - jekyll - - Static site generator - -## Contributors +# Stuy Fission Newbie Education + +This repository is the onboarding curriculum for software and electronics members on FTC Team 310. + +The docs assume basic Java knowledge and teach FTC development from setup to TeleOp and autonomous. They are meant to be used alongside real robot work, not instead of it. + +## How to use this curriculum + +Follow the sections in this order: + +1. [intro/](intro/README.md) — environment setup + workflow basics +2. [codebase/](codebase/README.md) — how our robot code is organized +3. [teleop/](teleop/README.md) — driver-control architecture and input handling +4. [commands/](commands/README.md) — command patterns used in our code +5. [auton/](auton/README.md) — PedroPathing + autonomous structure +6. [ftcdashboard/](ftcdashboard/README.md) — tuning/debugging workflows +7. [misc/](misc/README.md) — dev opmodes, telemetry, hardware map, AI usage +8. [electronics/](electronics/README.md) — separate electrical fundamentals track + +**Start here:** [intro/README.md](intro/README.md) + +Suggested rhythm: +- Read one short doc +- Implement or test the concept on robot code +- Review with a mentor or returning developer + +## Important assumptions + +- Season names and repository names change each year. These docs intentionally avoid hard-coded season/repo values. +- Controller hardware can vary. SDK and many utility classes use Xbox-style button names in code, but comments may include PlayStation-equivalent labels when useful. +- Team code structure can evolve. Prefer consistency with previous years unless there is a clear reason to change. + +## External references + +- [FTC SDK docs](https://ftc-docs.firstinspires.org/) +- [Game Manual 0 (gm0)](https://gm0.org/) +- [PedroPathing docs](https://pedropathing.com/) +- [FTC Dashboard](https://acmerobotics.github.io/ftc-dashboard/) + +## Notes on this repo + +- `java/` and `markdown/` are legacy teaching folders and will be removed later. +- `power-play/`, `center-stage/`, `FissionLib/`, `gm0/`, and `pedro/` are reference material for writing/maintaining docs. +- The current teaching content lives in the top-level tracks listed above plus `intro/` and `codebase/`. + +## Contributing + +- Keep explanations beginner-friendly and practical. +- Prefer small examples that match our team code style. +- If a process changes year-to-year, document principles and add placeholders instead of hard-coding names. diff --git a/STYLE.md b/STYLE.md new file mode 100644 index 0000000..8c6a305 --- /dev/null +++ b/STYLE.md @@ -0,0 +1,12 @@ +you need to assume that people don't know anything except java. +they won't know what gradle is, they won't know what ftc terminologies are, stuff like localization, or telemetry. +i need you to explain every new term that you introduce, and you shouldn't make bullet pointed lists for everything. +make sure you always speak in full sentences and explain everything that someone wouldnt know before starting ftc. +don't use technical language off the bat, slowly introduce it with full sentence explainations. +i did a good job of this in my first couple docs, and you actually made them slightly worse, by shortening phrasing that would be useful for someone who is learning this for the first time. don't do that +use my original docs (00 and 01 of intro/ and codebase/mechanisms) as a reference +remember the audience: these people will want to read the docs in order and if they see stuff that they are confused by it won't help them learn +have a better intro than: "this document explains/is about". it should transition nicely from the previous docs, or just get straight to the point +don't put objective or prerequisites - people usually dont read that. just get to the point and assume people have mostly read the previous docs +don't include a summary +try to include examples for things diff --git a/auton/00-auton-overview.md b/auton/00-auton-overview.md new file mode 100644 index 0000000..e69de29 diff --git a/auton/01-pedro-setup.md b/auton/01-pedro-setup.md new file mode 100644 index 0000000..e69de29 diff --git a/auton/02-localization-and-constants.md b/auton/02-localization-and-constants.md new file mode 100644 index 0000000..e69de29 diff --git a/auton/03-tuning-workflow.md b/auton/03-tuning-workflow.md new file mode 100644 index 0000000..e69de29 diff --git a/auton/04-path-building.md b/auton/04-path-building.md new file mode 100644 index 0000000..e69de29 diff --git a/auton/05-auton-control-flow.md b/auton/05-auton-control-flow.md new file mode 100644 index 0000000..e69de29 diff --git a/auton/06-ftcdashboard-with-auton.md b/auton/06-ftcdashboard-with-auton.md new file mode 100644 index 0000000..e69de29 diff --git a/auton/07-real-world-failure-modes.md b/auton/07-real-world-failure-modes.md new file mode 100644 index 0000000..e69de29 diff --git a/auton/README.md b/auton/README.md new file mode 100644 index 0000000..55a5b63 --- /dev/null +++ b/auton/README.md @@ -0,0 +1,17 @@ +# Auton Track + +Read in this order: +1. [00-auton-overview.md](00-auton-overview.md) +2. [01-pedro-setup.md](01-pedro-setup.md) +3. [02-localization-and-constants.md](02-localization-and-constants.md) +4. [03-tuning-workflow.md](03-tuning-workflow.md) +5. [04-path-building.md](04-path-building.md) +6. [05-auton-control-flow.md](05-auton-control-flow.md) +7. [06-ftcdashboard-with-auton.md](06-ftcdashboard-with-auton.md) +8. [07-real-world-failure-modes.md](07-real-world-failure-modes.md) + +**Prerequisite:** [Commands Track](../commands/README.md) + +**External:** [PedroPathing Docs](https://pedropathing.com/) + +**After autonomy, proceed to:** [FTC Dashboard Track](../ftcdashboard/README.md) diff --git a/codebase/README.md b/codebase/README.md new file mode 100644 index 0000000..0511f78 --- /dev/null +++ b/codebase/README.md @@ -0,0 +1,29 @@ +# Codebase Overview + +This folder explains how robot code is structured and why that structure helps during build season. + +Use this folder as the conceptual map, then read deeper lessons in top-level tracks: +- `teleop/` +- `commands/` +- `auton/` +- `ftcdashboard/` +- `misc/` +- `electronics/` + +## What belongs here + +- Architecture principles +- Mechanism composition patterns +- Team style conventions that stay stable across seasons + +## Existing mechanism docs + +- [mechanisms/00-intro.md](mechanisms/00-intro.md) +- [mechanisms/01-robot-scoring.md](mechanisms/01-robot-scoring.md) +- [mechanisms/02-mechanism-design.md](mechanisms/02-mechanism-design.md) + +--- + +**Read first:** [Mechanisms Intro](mechanisms/00-intro.md) + +**After codebase fundamentals, proceed to:** [TeleOp Architecture](../teleop/README.md) diff --git a/codebase/mechanisms/02-mechanism-design.md b/codebase/mechanisms/02-mechanism-design.md new file mode 100644 index 0000000..3895994 --- /dev/null +++ b/codebase/mechanisms/02-mechanism-design.md @@ -0,0 +1,34 @@ +# Mechanism Design + +Once you understand what a mechanism class is, the next question is how to decide what should go inside it. A mechanism should own one part of the robot and the code that directly controls that part. If the robot has a claw, a slide, an intake, or a drivetrain, each of those can be treated as a mechanism if it has its own job and its own hardware. The main idea is to keep one class focused on one piece of the robot so the code stays easier to read, test, and change later. + +This is where the idea of single responsibility matters. Single responsibility means a class should have one main job instead of trying to do everything. A `Claw` class should care about the claw. A `Slides` class should care about the slides. A `Drivetrain` class should care about driving. If one class starts reaching into every part of the robot, the code becomes harder to understand and much harder to debug when something goes wrong. + +When you design a mechanism, start by asking what real hardware it controls. That usually means a motor, a servo, or a sensor. Then ask what simple actions the rest of the robot will need from that mechanism. A claw might need `open()` and `close()`. Slides might need `up()`, `down()`, and `stop()`. A drivetrain might need methods for driving forward, turning, and stopping. Those methods become the public way other parts of the program talk to the mechanism. + +Keeping the public API simple is important. An API is the set of methods another class is allowed to call. In this context, think of the API as the handle you give to the rest of the robot. You want that handle to be simple and safe. For example, instead of making other classes set raw servo positions directly, it is usually better to give them methods like `open()` and `close()`. That way the rest of the code does not need to know the exact numbers that the servo uses. + +Here is a simple way to think about the layers of responsibility. The mechanism knows how to move one part of the robot. The higher-level robot code decides when that part should move. The OpMode decides when the robot should start, stop, or react to drivers. Keeping those layers separate makes the whole program easier to reason about. + +```java +public class Claw extends Mechanism { + private Servo servo; + + public static double OPEN_POS = 0.7; + public static double CLOSE_POS = 0.5; + + public void open() { + servo.setPosition(OPEN_POS); + } + + public void close() { + servo.setPosition(CLOSE_POS); + } +} +``` + +This small example shows the kind of API a mechanism should expose. The class does not force the rest of the robot to know servo details. Instead, it gives clear methods that describe the action in plain language. That makes the code easier for a new team member to read because they can understand what the mechanism does without learning every hardware detail first. + +Having these simple methods is great, because we can reuse them whenever we want. Let's say we wanted to add a `toggle` method to the `Claw` class above. We would first add a variable to keep track if it's open or closed, and then inside out `toggle` method, we could just call `open` if it's closed, and `close` if it's open! We don't need extra code for setting the servo positions in the `toggle` function, because we already wrote the `open` and `close` methods. + +Testing is part of design too. The easiest way to test a new mechanism is usually with a [dev OpMode](../../misc/00-dev-opmodes.md), which is a small test program used only for development. In a dev OpMode you can move one mechanism at a time, watch its behavior, and change constants without worrying about the rest of the robot. That makes it much safer than trying to test a brand-new mechanism inside a full match program right away. diff --git a/commands/00-command-basics.md b/commands/00-command-basics.md new file mode 100644 index 0000000..e69de29 diff --git a/commands/01-command-sequences.md b/commands/01-command-sequences.md new file mode 100644 index 0000000..e69de29 diff --git a/commands/02-common-bugs.md b/commands/02-common-bugs.md new file mode 100644 index 0000000..e69de29 diff --git a/commands/README.md b/commands/README.md new file mode 100644 index 0000000..b125467 --- /dev/null +++ b/commands/README.md @@ -0,0 +1,10 @@ +# Commands Track + +Read in this order: +1. [00-command-basics.md](00-command-basics.md) +2. [01-command-sequences.md](01-command-sequences.md) +3. [02-common-bugs.md](02-common-bugs.md) + +**Prerequisite:** [TeleOp Architecture](../teleop/README.md) + +**After mastering commands, proceed to:** [Autonomous (Auton) Track](../auton/README.md) diff --git a/electronics/00-electronics-intro.md b/electronics/00-electronics-intro.md new file mode 100644 index 0000000..e69de29 diff --git a/electronics/01-control-hub-and-wiring-checks.md b/electronics/01-control-hub-and-wiring-checks.md new file mode 100644 index 0000000..e69de29 diff --git a/electronics/02-troubleshooting-playbook.md b/electronics/02-troubleshooting-playbook.md new file mode 100644 index 0000000..e69de29 diff --git a/electronics/README.md b/electronics/README.md new file mode 100644 index 0000000..b4829bf --- /dev/null +++ b/electronics/README.md @@ -0,0 +1,12 @@ +# Electronics Track + +Read in this order: +1. [00-electronics-intro.md](00-electronics-intro.md) - Electrical basics for software members +2. [01-control-hub-and-wiring-checks.md](01-control-hub-and-wiring-checks.md) - Hardware validation +3. [02-troubleshooting-playbook.md](02-troubleshooting-playbook.md) - Debugging electrical issues + +**Prerequisite:** [Misc Track](../misc/README.md) + +**External:** [Game Manual 0 - Electronics](https://gm0.org/en/latest/docs/common/electronics.html) + +**Completes the full curriculum** diff --git a/ftcdashboard/00-intro.md b/ftcdashboard/00-intro.md new file mode 100644 index 0000000..e69de29 diff --git a/ftcdashboard/01-connection-troubleshooting.md b/ftcdashboard/01-connection-troubleshooting.md new file mode 100644 index 0000000..e69de29 diff --git a/ftcdashboard/02-telemetry-patterns.md b/ftcdashboard/02-telemetry-patterns.md new file mode 100644 index 0000000..e69de29 diff --git a/ftcdashboard/README.md b/ftcdashboard/README.md new file mode 100644 index 0000000..a5c0a71 --- /dev/null +++ b/ftcdashboard/README.md @@ -0,0 +1,12 @@ +# FTC Dashboard Track + +Read in this order: +1. [00-intro.md](00-intro.md) - What is FTC Dashboard +2. [01-connection-troubleshooting.md](01-connection-troubleshooting.md) - Connecting and debugging +3. [02-telemetry-patterns.md](02-telemetry-patterns.md) - Organizing telemetry display + +**Prerequisite:** [Autonomous Track](../auton/README.md) (optional for teleop debugging) + +**External:** [FTC Dashboard GitHub](https://github.com/acmerobotics/ftc-dashboard) + +**After dashboard, proceed to:** [Misc Track](../misc/README.md) diff --git a/intro/02-git-workflow.md b/intro/02-git-workflow.md new file mode 100644 index 0000000..9b0ab58 --- /dev/null +++ b/intro/02-git-workflow.md @@ -0,0 +1,70 @@ +## Git Workflow + +Check out https://docs.github.com/en/get-started/using-git/about-git for a more detailed explanation of everything in this section. + +Now that you can open the project in Android Studio, the next step is learning how we save and share code as a team. Git is the tool that records versions of the code on your computer, and GitHub is the website where the team keeps the shared copy. If two people are working at the same time, Git helps each person keep their own changes until it is time to combine them safely. + +When we say repository, we mean the complete project history for the robot code. When we say branch, we mean a separate line of work inside that repository. The branch with the official team code is usually called `main`. When you are working on your own change, you usually make a branch so your work does not immediately change the shared code that everyone else is using. + +To start from the shared code, first make a local copy of the repository on your computer. Cloning means copying the repository from GitHub to your machine so you can edit it in Android Studio. + +```bash +git clone git@github.com:Fission310/.git +cd +``` + +The next step is to make sure your copy has the latest changes from the team before you begin. That way you are not editing an older version by accident. + +```bash +git fetch origin +git checkout main +git pull origin main +``` + +The `git fetch` command asks GitHub whether anyone has pushed new changes. The `git checkout main` command switches you to the main branch on your computer, and `git pull origin main` brings down the newest version of that branch. + +If you need your own line of work, create a branch named `feature`. + +```bash +git checkout -b feature +``` + +The `-b` option means create a new branch and switch to it right away. You do not need a long branch name for this class of work; just use `feature` when you are making a change and want to keep it separate from the shared branch. + +Once you make a change, commit it. A commit is a saved snapshot of your work. Use one commit message that explains what changed and why. + +```bash +git add path/to/changed/file +git commit -m "Short explanation of the change" +``` + +The `git add` command tells Git which file changes should be included in the commit. The `git commit` command creates the saved snapshot. The message should be short but clear enough that another student can understand what you changed later. + +After that, push your branch to GitHub so the team can see it. + +```bash +git push -u origin feature +``` + +If someone else has changed the shared code while you were working, you will usually combine their updates into your branch before you finish. For this class of workflow, we use merge. Merging means taking the changes from one branch and combining them with another branch. + +```bash +git fetch origin +git checkout feature +git merge origin/main +``` + +If Git can combine the changes cleanly, it will finish the merge for you. If it cannot, you will see a merge conflict. A merge conflict means Git found the same lines changed in both places and does not know which version to keep. When this happens, Git writes special markers into the file so you can see both versions. The file will contain lines that start with `<<<<<<<`, a separator line with `=======`, and a closing line with `>>>>>>>`. + +Open the conflicted file and read both versions carefully. Keep the code you want, delete the conflict marker lines, and make sure the file still makes sense as normal Java or text. After you fix the file, save it, add it again, and finish the merge. + +```bash +git add path/to/conflicted-file +git commit +``` + +Git will open the commit message for the merge. You can usually accept the default message, because the important part is that the branch now contains both sets of changes. + +If a conflict is hard to understand, ask another teammate to look at the file with you. Conflicts are normal, especially when two people edit the same mechanism or the same setup file, and the solution is usually to keep the intended lines from each version and remove the markers cleanly. + +The main habits to remember are simple. Keep changes small, save your work often, pull or fetch before you start if someone else may have changed the code, and ask for help when a conflict is unclear. When you are comfortable with that flow, the rest of the team workflow becomes much easier. diff --git a/intro/03-android-studio-workflow.md b/intro/03-android-studio-workflow.md new file mode 100644 index 0000000..dbf72f4 --- /dev/null +++ b/intro/03-android-studio-workflow.md @@ -0,0 +1,39 @@ +# Android Studio Overview + +Android Studio is where you open the code, make edits, and send the updated app to the robot. Android Studio is an integrated development environment, which is a fancy way of saying it is the program where you write code, organize files, build the app, and look for errors all in one place. + +The first thing you should get comfortable with is the Project pane on the left side of the window. That pane shows the folders and files in the project. You will use it to find the `teamcode` folder, which is the part of the project that contains our robot code. If the project tree looks crowded, remember that you do not need to understand every folder at once. At the beginning, you mainly need to know where `teamcode` is and how to open the files you are changing. You also shouldn't worry about most of the files outside of `teamcode`. + +Android Studio also lets you jump around the project quickly. If you know a file or class name, you can search for it instead of clicking through folders one by one. You can also jump to a class or method definition from code when you want to see where something comes from (ctrl/cmd click on it). These small navigation habits save a lot of time once the project gets larger. + +When you work on FTC code, you will hear the word Gradle. Gradle is the part of the build system that prepares the project for Android Studio, downloads libraries, and turns your Java code into an app that can run on the robot. Syncing means Android Studio should ask Gradle to read the project settings again so the editor knows what code and libraries are available. If the project is out of sync, red errors can appear even when the code itself is fine. To sync Gradle, click the elephant button that's on the top right of Android Studio. + +The normal rhythm is to edit code, wait for Android Studio to notice the change, and then build the project. Building means checking whether the code compiles correctly. If the code does not compile, Android Studio will show an error message and mark the problem in red. When you are new, the most helpful habit is to fix compile errors as soon as they appear instead of letting several pile up. + +At the top of Android Studio there is usually a toolbar with a few important buttons. The build button often looks like a hammer, and clicking it tells Android Studio to compile the project. You do not need to memorize the exact icon right away, but it is useful to know that the build button is the one you use when you want to check whether your code has any syntax or compile errors. + +There is also a button used to send the app to the robot. Sometimes it's a green play button, and sometimes it looks like a cycle or refresh-style arrow instead. Clicking that button tells Android Studio to run the selected configuration on the selected device. Before you press it, you should choose the correct device from the device dropdown near the top of the window. The device dropdown is where you need to select the Control Hub that Android Studio should send the code to. + +After the code builds, before you can send the code to the robot, you need to be connected. This is a 2 step process. First, connect to the Control Hub's WiFi. Then connect to the robot through adb. + +ADB (Android Debug Bridge) is the tool Android Studio uses to talk to Android devices such as the Control Hub. + +Here are a few common ADB actions. To connect to the robot, you usually use the robot's IP address. That is the number that tells your computer which device on the network is the Control Hub. + +```bash +adb connect 192.168.43.1 +``` + +If ADB gets stuck, you can try killing the ADB service. This basically just restarts everything fresh. + +```bash +adb kill-server +``` + +You should also disconnect from the robot when you are done working. + +```bash +adb disconnect +``` + +Once your computer is connected to the robot, you can send the code to the robot. We usually call this "pushing the code". The robot can only run the version of the code that is actually installed on the Control Hub, so a successful build on your computer does not automatically mean the robot has the new code yet, until you pushed it. After deployment, the Driver Station or RC app is what you use to choose and run an OpMode. diff --git a/intro/README.md b/intro/README.md new file mode 100644 index 0000000..390003f --- /dev/null +++ b/intro/README.md @@ -0,0 +1,10 @@ +# Introduction Track + +This track covers essential setup and workflow skills for new software members. + +**Read in this order:** +1. [00-setup.md](00-setup.md) +2. [02-git-workflow.md](02-git-workflow.md) +3. [03-android-studio-workflow.md](03-android-studio-workflow.md) + +**After completing this track**, proceed to [Codebase Overview](../codebase/README.md). diff --git a/misc/00-dev-opmodes.md b/misc/00-dev-opmodes.md new file mode 100644 index 0000000..e69de29 diff --git a/misc/01-telemetry-best-practices.md b/misc/01-telemetry-best-practices.md new file mode 100644 index 0000000..e69de29 diff --git a/misc/02-hardware-map-and-config.md b/misc/02-hardware-map-and-config.md new file mode 100644 index 0000000..e69de29 diff --git a/misc/03-ai-usage-guidelines.md b/misc/03-ai-usage-guidelines.md new file mode 100644 index 0000000..e69de29 diff --git a/misc/README.md b/misc/README.md new file mode 100644 index 0000000..1a56abd --- /dev/null +++ b/misc/README.md @@ -0,0 +1,16 @@ +# Misc Track + +Read in this order: +1. [00-dev-opmodes.md](00-dev-opmodes.md) - Development testing strategy +2. [01-telemetry-best-practices.md](01-telemetry-best-practices.md) - Telemetry organization +3. [02-hardware-map-and-config.md](02-hardware-map-and-config.md) - Hardware naming and layout +4. [03-ai-usage-guidelines.md](03-ai-usage-guidelines.md) - Responsible AI assistance + +**Prerequisite:** [Auton Track](../auton/README.md) + +**Cross-referenced from:** +- [Teleop Track](../teleop/README.md) - dev opmodes +- [Commands Track](../commands/README.md) - dev opmodes +- [FTC Dashboard Track](../ftcdashboard/README.md) - telemetry patterns + +**After misc, proceed to:** [Electronics Track](../electronics/README.md) diff --git a/teleop/00-teleop-architecture.md b/teleop/00-teleop-architecture.md new file mode 100644 index 0000000..e69de29 diff --git a/teleop/01-controls-and-input.md b/teleop/01-controls-and-input.md new file mode 100644 index 0000000..e69de29 diff --git a/teleop/README.md b/teleop/README.md new file mode 100644 index 0000000..3041d97 --- /dev/null +++ b/teleop/README.md @@ -0,0 +1,9 @@ +# TeleOp Track + +Read in this order: +1. [00-teleop-architecture.md](00-teleop-architecture.md) +2. [01-controls-and-input.md](01-controls-and-input.md) + +**Prerequisite:** [Codebase Overview](../codebase/README.md) + +**After TeleOp fundamentals, proceed to:** [Commands Track](../commands/README.md)