From 2d53d61ec3cb76e91989ae7fd445841ee450937d Mon Sep 17 00:00:00 2001 From: Flint Mueller Date: Sat, 23 May 2026 13:17:20 -0400 Subject: [PATCH 1/8] add instructions --- INSTRUCTIONS.md | 20 ++++++++++++++++++++ PLANNING.md | 14 +++++--------- 2 files changed, 25 insertions(+), 9 deletions(-) create mode 100644 INSTRUCTIONS.md 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/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 From c2867ca629c02eb038066e9e35ea3f1ac8b707a3 Mon Sep 17 00:00:00 2001 From: Flint Mueller Date: Sat, 23 May 2026 13:17:33 -0400 Subject: [PATCH 2/8] generate outline --- OUTLINE.md | 294 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 OUTLINE.md 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. From a5c461dac6cd2e064d2dfa4bad7aac60d1473530 Mon Sep 17 00:00:00 2001 From: Flint Mueller Date: Sat, 23 May 2026 13:18:29 -0400 Subject: [PATCH 3/8] initial round --- README.md | 80 ++++++++++++------- auton/00-auton-overview.md | 34 ++++++++ auton/01-pedro-setup.md | 61 ++++++++++++++ auton/02-localization-and-constants.md | 41 ++++++++++ auton/03-tuning-workflow.md | 40 ++++++++++ auton/04-path-building.md | 43 ++++++++++ auton/05-auton-control-flow.md | 45 +++++++++++ auton/06-ftcdashboard-with-auton.md | 38 +++++++++ auton/07-real-world-failure-modes.md | 43 ++++++++++ auton/README.md | 17 ++++ codebase/README.md | 29 +++++++ codebase/mechanisms/00-intro.md | 30 +++++-- codebase/mechanisms/01-robot-scoring.md | 27 ++++++- codebase/mechanisms/02-mechanism-design.md | 55 +++++++++++++ commands/00-command-basics.md | 44 ++++++++++ commands/01-command-sequences.md | 41 ++++++++++ commands/02-common-bugs.md | 38 +++++++++ commands/README.md | 10 +++ electronics/00-electronics-intro.md | 32 ++++++++ .../01-control-hub-and-wiring-checks.md | 34 ++++++++ electronics/02-troubleshooting-playbook.md | 40 ++++++++++ electronics/README.md | 12 +++ ftcdashboard/00-intro.md | 24 ++++++ ftcdashboard/01-connection-troubleshooting.md | 28 +++++++ ftcdashboard/02-telemetry-patterns.md | 35 ++++++++ ftcdashboard/README.md | 12 +++ intro/00-setup.md | 46 ++++++++--- intro/01-code-overview.md | 42 ++++++++-- intro/02-git-workflow.md | 66 +++++++++++++++ intro/03-android-studio-workflow.md | 53 ++++++++++++ intro/README.md | 10 +++ misc/00-dev-opmodes.md | 35 ++++++++ misc/01-telemetry-best-practices.md | 28 +++++++ misc/02-hardware-map-and-config.md | 29 +++++++ misc/03-ai-usage-guidelines.md | 30 +++++++ misc/README.md | 16 ++++ teleop/00-teleop-architecture.md | 45 +++++++++++ teleop/01-controls-and-input.md | 49 ++++++++++++ teleop/README.md | 9 +++ 39 files changed, 1336 insertions(+), 55 deletions(-) create mode 100644 auton/00-auton-overview.md create mode 100644 auton/01-pedro-setup.md create mode 100644 auton/02-localization-and-constants.md create mode 100644 auton/03-tuning-workflow.md create mode 100644 auton/04-path-building.md create mode 100644 auton/05-auton-control-flow.md create mode 100644 auton/06-ftcdashboard-with-auton.md create mode 100644 auton/07-real-world-failure-modes.md create mode 100644 auton/README.md create mode 100644 codebase/README.md create mode 100644 codebase/mechanisms/02-mechanism-design.md create mode 100644 commands/00-command-basics.md create mode 100644 commands/01-command-sequences.md create mode 100644 commands/02-common-bugs.md create mode 100644 commands/README.md create mode 100644 electronics/00-electronics-intro.md create mode 100644 electronics/01-control-hub-and-wiring-checks.md create mode 100644 electronics/02-troubleshooting-playbook.md create mode 100644 electronics/README.md create mode 100644 ftcdashboard/00-intro.md create mode 100644 ftcdashboard/01-connection-troubleshooting.md create mode 100644 ftcdashboard/02-telemetry-patterns.md create mode 100644 ftcdashboard/README.md create mode 100644 intro/02-git-workflow.md create mode 100644 intro/03-android-studio-workflow.md create mode 100644 intro/README.md create mode 100644 misc/00-dev-opmodes.md create mode 100644 misc/01-telemetry-best-practices.md create mode 100644 misc/02-hardware-map-and-config.md create mode 100644 misc/03-ai-usage-guidelines.md create mode 100644 misc/README.md create mode 100644 teleop/00-teleop-architecture.md create mode 100644 teleop/01-controls-and-input.md create mode 100644 teleop/README.md 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/auton/00-auton-overview.md b/auton/00-auton-overview.md new file mode 100644 index 0000000..e4868d4 --- /dev/null +++ b/auton/00-auton-overview.md @@ -0,0 +1,34 @@ +# Autonomous Overview + +## Objective + +Understand how to build autonomous routines that are reliable in real matches, not just in perfect testing. + +## Match constraints + +Autonomous is short and unforgiving. Reliability is usually worth more than theoretical max points. + +## Architecture checklist + +A complete auton usually combines: +- pathing follower (PedroPathing) +- mechanism actions (intake, claw, slides, etc.) +- progression logic (commands or state machine) +- telemetry/debug output for tuning + +## Readiness requirements before writing auton + +- drivetrain/localization stable +- mechanisms tested in dev opmodes +- key constants tuned +- fallback parking path available + +## Design principle + +Prefer simpler routines that finish consistently over complex routines that only work sometimes. + +**Learn more:** [Game Manual 0 - Autonomous Overview](https://gm0.org/en/latest/docs/software/lessons/autonomous.html) + +--- + +**Next:** [PedroPathing Setup](01-pedro-setup.md) diff --git a/auton/01-pedro-setup.md b/auton/01-pedro-setup.md new file mode 100644 index 0000000..a333400 --- /dev/null +++ b/auton/01-pedro-setup.md @@ -0,0 +1,61 @@ +# PedroPathing Setup (FTC Dashboard Path) + +## Why this method + +Pedro supports multiple dashboards. For this team curriculum, we use FTC Dashboard because it is widely used across FTC and integrates well with existing workflows. + +## Installation approach + +Use **manual integration into your existing FTC project** so your current team structure stays intact. + +### 1) Add Pedro Maven repository + +In `build.dependencies.gradle`, inside `repositories {}` add: + +```gradle +maven { url = "https://mymaven.bylazar.com/releases" } +``` + +### 2) Add Pedro dependency + +In `dependencies {}` add the Pedro dependency shown in the current official docs: + +```gradle +implementation '' +``` + +Use the exact artifact/version your team has tested. + +### 3) Add FTC Dashboard dependency (if not already present) + +```gradle +implementation 'com.acmerobotics.dashboard:dashboard:0.4.16' +``` + +### 4) Sync Gradle and confirm SDK versions + +Pedro 2.x docs target modern SDK/compile settings. Follow Android Studio prompts to sync and resolve version mismatches. + +### 5) Add Pedro package files + +Copy starter Pedro files (such as constants and tuning opmodes) from the Pedro quickstart into your `teamcode` package. + +Keep naming consistent with your team package structure; do not hard-code season names. + +## Minimal first opmode flow + +1. Create follower from constants +2. Set starting pose +3. Build one simple path (line) +4. Follow path in auton loop +5. Publish pose telemetry to dashboard + +## RoadRunner migration note + +Old team repos may still contain RoadRunner folders (`drive`, `trajectorysequence`, etc.). Keep those only as historical reference; new autonomous development should use PedroPathing. + +**External:** [PedroPathing Installation Docs](https://pedropathing.com/docs/pathing/installation) + +--- + +**Next:** [Localization and Constants](02-localization-and-constants.md) diff --git a/auton/02-localization-and-constants.md b/auton/02-localization-and-constants.md new file mode 100644 index 0000000..1277824 --- /dev/null +++ b/auton/02-localization-and-constants.md @@ -0,0 +1,41 @@ +# Localization and Constants + +## Objective + +Set up constants so PedroPathing follows paths predictably on your actual robot. + +## Constant categories + +Pedro constants typically include: +- follower/drive algorithm constants +- drivetrain hardware constants +- localizer constants (wheel/IMU/sensor settings) +- path completion constraints + +## Best practices + +- Keep constants in one dedicated class/package +- Document units (inches, radians, seconds) +- Add date + robot configuration notes when values change + +## Localization assumptions + +Localization quality depends on: +- wheel odometry quality and placement +- IMU consistency +- mechanical rigidity and wheel condition + +Bad localization makes all path tuning harder, so fix localization before aggressive path tuning. + +## Versioning tuned values + +When tuning updates constants: +- commit with message describing what changed and why +- include test context (battery state, field condition) +- avoid mixing unrelated mechanism changes in same commit + +**Learn more:** [PedroPathing - Constants](https://pedropathing.com/docs/pathing/constants) + +--- + +**Next:** [Pedro Tuning Workflow](03-tuning-workflow.md) diff --git a/auton/03-tuning-workflow.md b/auton/03-tuning-workflow.md new file mode 100644 index 0000000..b89c1ed --- /dev/null +++ b/auton/03-tuning-workflow.md @@ -0,0 +1,40 @@ +# Pedro Tuning Workflow + +## Pre-tuning checklist + +Before software tuning: +- verify motor directions +- verify hardware map names +- inspect drivetrain friction/mechanical issues +- use a reasonably charged battery + +## Recommended order + +1. Localization setup/tuning +2. Basic follower/path tests +3. Heading behavior tuning +4. Speed/deceleration constraints +5. Full-route repeatability tests + +## Repeatability test + +Run the same path multiple times from the same start pose. + +Track: +- average end error +- worst-case end error +- drift direction patterns + +## Retune triggers + +Retune when: +- drivetrain hardware changes +- localization hardware changes +- wheel wear changes behavior significantly +- behavior degrades after impacts/repairs + +**Learn more:** [PedroPathing - Tuning Guide](https://pedropathing.com/docs/pathing/tuning) + +--- + +**Next:** [Path Building with PedroPathing](04-path-building.md) diff --git a/auton/04-path-building.md b/auton/04-path-building.md new file mode 100644 index 0000000..994876d --- /dev/null +++ b/auton/04-path-building.md @@ -0,0 +1,43 @@ +# Path Building with PedroPathing + +## Objective + +Build readable and reusable paths that cooperate with mechanism actions. + +## Path primitives + +- **BezierLine**: straight segment between two poses/points +- **BezierCurve**: curved segment with control points +- **PathChain**: multiple segments grouped into one follow action + +## Practical pattern + +- Prebuild paths in `init()` +- Name paths by intent (`toSpike`, `toBackboard`, `toPark`) +- Keep one source of truth for key poses + +## Heading and constraints + +For each path, choose heading interpolation intentionally. +Do not rely on defaults unless you understand them. + +Apply constraints for sections where speed/precision tradeoffs differ. + +## Callbacks/events + +Use callbacks or command triggers for mechanism timing tied to path progress. +Prefer event-based timing over fixed sleeps when possible. + +## Debugging bad paths + +If pathing is unstable, check in this order: +1. localization quality +2. coordinate assumptions +3. heading interpolation choice +4. end conditions and constraints + +**Learn more:** [PedroPathing - Path Builder Reference](https://pedropathing.com/docs/pathing/reference/path-builder) + +--- + +**Next:** [Autonomous Control Flow](05-auton-control-flow.md) diff --git a/auton/05-auton-control-flow.md b/auton/05-auton-control-flow.md new file mode 100644 index 0000000..dcf945f --- /dev/null +++ b/auton/05-auton-control-flow.md @@ -0,0 +1,45 @@ +# Autonomous Control Flow + +## Two good patterns + +1. **Command composition** (recommended when available) +2. **Finite state machine** + +Both are valid. Choose one style per auton for readability. + +## Command-style auton + +Best when your team already uses command abstractions. + +Typical flow: +- follow path +- run scoring command sequence +- follow next path +- run intake/score command sequence + +This keeps progression logic concise. + +## State-machine auton + +Use explicit states when you need fine-grained transitions. + +Example state progression: +`START -> SCORE_PRELOAD -> PICKUP_1 -> SCORE_1 -> PARK` + +Transition on reliable conditions: +- `!follower.isBusy()` +- pose thresholds +- timeout fallback + +## Failsafes + +Always include: +- global timeout check +- fallback park state +- safe mechanism retract action before end + +**Related:** [Command Sequences](../commands/01-command-sequences.md) + +--- + +**Next:** [FTC Dashboard with Autonomous](06-ftcdashboard-with-auton.md) diff --git a/auton/06-ftcdashboard-with-auton.md b/auton/06-ftcdashboard-with-auton.md new file mode 100644 index 0000000..d217faa --- /dev/null +++ b/auton/06-ftcdashboard-with-auton.md @@ -0,0 +1,38 @@ +# FTC Dashboard with Autonomous + +## Why dashboard during auton work + +Dashboard gives fast visibility into pose, path progress, and mechanism states while tuning. + +## Basic setup + +1. Add FTC Dashboard dependency +2. Connect to robot network +3. Open dashboard in browser (`192.168.43.1:8080/dash` in common Control Hub setups) +4. Stream telemetry and field drawing data + +## What to display + +Minimum useful auton telemetry: +- current state/command +- robot pose (`x`, `y`, `heading`) +- path/segment identifier +- key mechanism targets and actual values + +## About live tuning + +Pedro docs note that FTC Dashboard does not provide full live configurability for all Pedro constants in the same way some other dashboards do. + +Use dashboard primarily for visualization and telemetry, then edit constants in code and redeploy. + +## Common connection issues + +- wrong IP/network +- stale app/deploy state +- missing telemetry updates in loop + +**Learn more:** [FTC Dashboard Track](../ftcdashboard/README.md) + +--- + +**Next:** [Real-World Auton Failure Modes](07-real-world-failure-modes.md) diff --git a/auton/07-real-world-failure-modes.md b/auton/07-real-world-failure-modes.md new file mode 100644 index 0000000..f78add7 --- /dev/null +++ b/auton/07-real-world-failure-modes.md @@ -0,0 +1,43 @@ +# Real-World Auton Failure Modes + +## Battery effects + +Low voltage changes acceleration/deceleration behavior and mechanism timing. + +Mitigations: +- tune with realistic battery ranges +- avoid overly tight timing windows +- use condition-based transitions where possible + +## Contact and slip + +Auton plans should assume occasional contact/slip. + +Mitigations: +- keep trajectories robust +- add conservative clearances near field elements +- include fallback states + +## Initialization mismatch + +Wrong start pose or mechanism start state can ruin the whole routine. + +Mitigations: +- explicit prestart checklist +- visible telemetry of selected side/path +- lock in start assumptions before pressing play + +## Postmortem template + +After a failed auton run, log: +1. start state (pose, mechanism state, battery) +2. first observed divergence +3. telemetry clues +4. root cause hypothesis +5. next single change to test + +**Related:** [Electronics Troubleshooting Playbook](../electronics/02-troubleshooting-playbook.md) + +--- + +**Next:** [FTC Dashboard Track](../ftcdashboard/README.md) 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/00-intro.md b/codebase/mechanisms/00-intro.md index e837bbe..d0756f0 100644 --- a/codebase/mechanisms/00-intro.md +++ b/codebase/mechanisms/00-intro.md @@ -1,12 +1,14 @@ # Mechanisms -Let's go over what a mechanism is, and then we can make our first one! +Let's go over what a mechanism is, and then make a simple one. ## What is a Mechanism? -A mechanism is some part of the robot that has a specific function. One of the simplest examples of a mechanism is a claw. You might have a claw on the robot to grab game pieces, and in the code, you would have a `Claw` class that contains code to make the claw move. +A mechanism is a part of the robot with a specific job. One of the simplest examples is a claw. If your robot has a claw to grab game pieces, the code should have a `Claw` class that controls it. -All mechanisms go in the `hardware/mechanisms` folder in `teamcode`. This helps us keep organized so we can find our mechanisms easily. Let's continue with the claw example. Create a new file called `Claw.java` in the `hardware/mechanisms` folder. If any of the folders don't exist, make them. And if `Claw.java` already exists, delete it and make a new one. In Android Studio you make a file by right-clicking on the folder you want to put it in, then going to `New > File`, or `New > Directory` if you want to make a new folder. +All mechanisms go in the `hardware/mechanisms` folder in `teamcode`. This keeps organization clear and consistent. + +Continue with the claw example. Create a new file called `Claw.java` in `hardware/mechanisms`. ## Claw Code @@ -85,7 +87,11 @@ This is where we start the actual code for our claw. We are making a class calle public static double CLOSE_POS = 0.5; ``` -Here are our variables that we will use in the claw class. The first one is a `Servo` that we call `servo` (`Servo` is the type, and `servo` is the name). `Servo` is a class from the base java library that all FTC teams use. We imported `Servo` at the top of the file. We use this variable to control the imaginary servo that moves our imaginary claw. If we had two servos controlling our claw, we would need two `Servo` variables. The next two variables are `OPEN_POS` and `CLOSE_POS`. These are the positions that the servo needs to be in to open and close the claw. For servos, the positions will always be `double`s between 0 and 1. The values of these variables will depend on how your claw is built, so you will need to change them to get your claw working. I picked 0.7 and 0.5 because I felt like it :) When you make your own mechanism, you should start with a guess, and then change the values until it works. These variables are `public` and `static` because we want to be able to change them from FTC Dashboard (again, we will get to that later). Just know that you should make all your position constants `public static`. +Here are the variables we use in the claw class. The first is a `Servo` variable named `servo`. We use this to control the servo that moves the claw. If the mechanism had two servos, we would declare two `Servo` variables. + +The next two variables are `OPEN_POS` and `CLOSE_POS`. These are servo target positions. Servo positions are `double`s from 0 to 1. + +These values depend on your real hardware, so you should tune them. Keep position constants `public static` so FTC Dashboard can adjust them quickly during testing. ```java public Claw(LinearOpMode opMode) { @@ -130,4 +136,18 @@ Now we get to the `open` (and `close`) functions. These are the functions that t } ``` -Lastly, we have the `loop` function. This is the second function that we get from the `Mechanism` class. The `loop` function runs continuously while the op mode is running. This is where you put code that needs to run over and over again. In the case of our claw, we want to be able to open and close it using buttons on the controller (it's called a gamepad in code). The code is pretty simple; we check if the `A` button (on an Xbox controller) is pressed, and if it is we call the `open` function. If `X` is pressed, we close the claw instead with `close()`. The `GamepadStatic.isButtonPressed` function just tells us if a certain button is pressed on the gamepad. The first parameter is the gamepad you want to check, and the second is the button. It will return `true` if the button is currently being held down on the controller. +Lastly, we have the `loop` function. This runs continuously while the op mode is active. + +In this example, `A` opens and `X` closes. In SDK/FissionLib code these button names follow Xbox-style labels. If your team is physically using PlayStation controllers, add comments so newer members can map labels correctly. + +`GamepadStatic.isButtonPressed(gamepad, Input.A)` returns `true` while that button is currently held. + +## Design note + +Mechanisms should focus on hardware behavior and local logic. Match strategy (when to score, when to transfer, etc.) should live in higher-level files like `Scoring` or TeleOp/auton classes. + +**Learn more:** [Game Manual 0 - Mechanisms & Subsystems](https://gm0.org/en/latest/docs/software/lessons/subsystems.html) + +--- + +**Next:** [Robot.java and Scoring.java](01-robot-scoring.md) diff --git a/codebase/mechanisms/01-robot-scoring.md b/codebase/mechanisms/01-robot-scoring.md index 7957608..c02dda1 100644 --- a/codebase/mechanisms/01-robot-scoring.md +++ b/codebase/mechanisms/01-robot-scoring.md @@ -1,6 +1,6 @@ # Robot.java and Scoring.java -In this section we will learn about the other two files in the `hardware` directory: `Robot.java` and `Scoring.java`. +In this section we will learn about two important files in the `hardware` directory: `Robot.java` and `Scoring.java`. ## Scoring.java @@ -68,7 +68,18 @@ public class Scoring extends Mechanism { } ``` -Note how similar this is to our `Claw.java` example. `Scoring` is also a `Mechanism` so that we can have the same `init` and `loop` methods. Our scoring sequence is made up of a claw and slides, so those will be variables in our class. The constructor is the same, and in the init method we just call the init methods for the claw and slides. The main difference is that we now have a state variable that keeps track of whether we are intaking a game element or scoring it. The state variable is an [enum](https://www.w3schools.com/java/java_enums.asp) that can be either `INTAKING` or `SCORING`. In `loop`, we check the state variable to see if we want to run the logic for intaking or scoring. This setup with `state` is a versatile way to have different logic for different parts of the game. This way you can also use a single button for different actions. +Note how similar this is to our `Claw.java` example. `Scoring` is also a `Mechanism`, so it has `init` and `loop` methods. + +The key difference is the `state` variable. The state tracks whether we are intaking or scoring. This makes button behavior context-dependent and safer. + +This setup is useful because one button can trigger different actions in different states. + +## State-machine safety tips + +- Keep states explicit and small. +- Keep transitions easy to read. +- Avoid transitions that depend only on long fixed delays. +- Prefer sensor/position checks for important transitions. ## Robot.java @@ -110,3 +121,15 @@ public class Robot extends Mechanism { ``` This `Robot` class is fairly simple. It just glues together the `Scoring` mechanism and the rest of the non-scoring mechanisms (in this case just the `Drivetrain`). In `init`, we call the init methods for both the drivetrain and scoring. In `loop`, we call the loop methods for both the drivetrain and scoring. + +## Automation boundary guideline + +- `Mechanism` classes: hardware-level behaviors (`open`, `close`, `setTarget`). +- `Scoring`: coordinated subsystem behavior and game-phase state. +- `Robot`: top-level composition of major subsystems. + +This boundary helps keep TeleOp and auton code easier to maintain. + +--- + +**Next:** [Mechanism Design Guide](02-mechanism-design.md) diff --git a/codebase/mechanisms/02-mechanism-design.md b/codebase/mechanisms/02-mechanism-design.md new file mode 100644 index 0000000..157ac0e --- /dev/null +++ b/codebase/mechanisms/02-mechanism-design.md @@ -0,0 +1,55 @@ +# Mechanism Design Guide + +## Objective + +Decide what should be a mechanism and design it so TeleOp and auton code stay clean. + +## What should be a mechanism + +Make a mechanism when hardware and behavior belong together. + +Examples: +- Intake motors + intake servos + intake sensors +- Slides motors + slide limit logic +- Claw servo(s) + open/close states + +Do **not** make a mechanism for random helper methods that do not own hardware. + +## API design rules + +Prefer methods that describe intent: +- `intake.start()` +- `intake.stop()` +- `slides.setTarget(height)` + +Avoid leaking raw hardware calls into TeleOp code. + +## Initialization and safety + +In `init(...)`: +- map all hardware once +- set safe startup positions +- reset mode/flags to known values + +Fail-safe defaults matter. If an opmode starts unexpectedly, the robot should still behave safely. + +## State and automation boundaries + +Keep local state inside the mechanism when possible, but keep game strategy state at higher layers (`Scoring`, TeleOp, auton controller). + +A good rule: +- mechanism = *how* one subsystem moves +- scoring/teleop/auton = *when* and *why* it moves + +## Testing pattern + +Use a dev opmode before integrating into main teleop: +1. test one mechanism in isolation +2. verify directions, limits, and default positions +3. then integrate with scoring/state logic + +**Related:** See [Dev OpModes](../../misc/00-dev-opmodes.md) for testing patterns. + +--- + +**Next:** [TeleOp Architecture](../../teleop/README.md) diff --git a/commands/00-command-basics.md b/commands/00-command-basics.md new file mode 100644 index 0000000..74cd56d --- /dev/null +++ b/commands/00-command-basics.md @@ -0,0 +1,44 @@ +# Command Basics + +## What is a command + +A command is a reusable action unit. It lets you move logic out of giant TeleOp/auton loops. + +Examples: +- close claw +- move slides to intake height +- run a timed intake pulse + +## Why use commands + +Commands make behavior composable and easier to test. + +Without commands, complex routines become long nested conditionals. With commands, routines are readable sequences. + +## Basic pattern (FissionLib style) + +```java +private Command closeClaw = () -> claw.close(); + +private CommandSequence grabSequence = new CommandSequence() + .addCommand(closeClaw) + .addWaitCommand(0.2) + .build(); +``` + +## Lifecycle idea + +For any command sequence, know: +- when it starts +- what conditions block/interrupt it +- when it is complete + +## When not to use commands + +If logic is a single immediate line and never reused, direct method calls can be clearer. + +**Related:** [TeleOp Architecture](../teleop/00-teleop-architecture.md) + +--- + +**Next:** [Command Sequences](01-command-sequences.md) diff --git a/commands/01-command-sequences.md b/commands/01-command-sequences.md new file mode 100644 index 0000000..f7e5abd --- /dev/null +++ b/commands/01-command-sequences.md @@ -0,0 +1,41 @@ +# Command Sequences + +## Objective + +Chain mechanism actions safely without scattering timing logic across TeleOp/auton. + +## Sequencing example + +A common scoring sequence: +1. stop intake +2. raise transfer platform +3. wait for mechanism settle +4. close claw +5. move slides/arm to scoring target + +This becomes one trigger instead of many manual button presses. + +## Interruption behavior + +Design for interruptions: +- What happens if driver cancels mid-sequence? +- Can robot safely return to intake state? +- Which mechanisms must stop immediately? + +## Timeouts and guards + +Never trust timing alone for important transitions. +Prefer sensor/position checks when possible, with timeout fallback. + +## Integration with state machines + +State machines decide *which* sequence to run. +Command sequences define *how* each transition executes. + +Use both together for clean architecture. + +**Related:** [TeleOp Architecture - State Machine Pattern](../teleop/00-teleop-architecture.md#state-machine-pattern) + +--- + +**Next:** [Common Command Bugs](02-common-bugs.md) diff --git a/commands/02-common-bugs.md b/commands/02-common-bugs.md new file mode 100644 index 0000000..16ae718 --- /dev/null +++ b/commands/02-common-bugs.md @@ -0,0 +1,38 @@ +# Common Command Bugs + +## Trigger spam + +Repeated trigger calls can restart a sequence every loop. + +Fix: gate triggers using click/edge detection or explicit `isBusy` checks. + +## Conflicting commands + +Two sequences controlling the same mechanism at once cause jitter or unsafe motion. + +Fix: enforce one owner per mechanism state transition. + +## Missing reset path + +A sequence reaches scoring posture but no reliable retract path exists. + +Fix: always pair each forward sequence with a tested reset/retract sequence. + +## Timing-only assumptions + +Delays that worked at full battery may fail at low voltage. + +Fix: combine delays with sensor/position checks. + +## Debug strategy + +When command behavior is wrong: +1. log sequence start and finish +2. log key state variable transitions +3. test sequence in a dev opmode before full TeleOp/auton + +**Related:** [Dev OpModes](../misc/00-dev-opmodes.md) + +--- + +**Next:** [Autonomous Track](../auton/README.md) 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..3b08ab9 --- /dev/null +++ b/electronics/00-electronics-intro.md @@ -0,0 +1,32 @@ +# Electronics Intro for Software Members + +## Goal + +Give software members enough electronics understanding to debug reliably and communicate with hardware teammates. + +## Core concepts + +- Control Hub and Expansion Hub roles +- motor and servo ports +- encoder feedback basics +- sensor wiring basics +- battery and power distribution + +## Why this matters for software + +Many "software bugs" are actually wiring, port, or configuration issues. + +If you understand the electrical basics, you debug faster and write safer assumptions in code. + +**Learn more:** [Game Manual 0 - Electronics Basics](https://gm0.org/en/latest/docs/common/electronics.html) + +--- + +**Next:** [Control Hub and Wiring Checks](01-control-hub-and-wiring-checks.md) + +## What to learn next + +1. Hardware map naming and port mapping +2. Motor direction/encoder checks +3. Sensor validation using telemetry +4. Power-related failure patterns 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..5531626 --- /dev/null +++ b/electronics/01-control-hub-and-wiring-checks.md @@ -0,0 +1,34 @@ +# Control Hub and Wiring Checks + +## Pre-code hardware sanity check + +Before debugging code, verify: +- battery is healthy and connected correctly +- hub is powered and visible +- expected motors/servos/sensors are plugged into correct ports +- cables are seated and not damaged + +## Fast motor/servo checks + +- test one actuator at a time in a dev opmode +- confirm direction matches code assumptions +- confirm no binding before raising power + +## Sensor checks + +For each sensor used in logic transitions: +- display raw values in telemetry +- validate value range in real robot conditions +- test failure behavior (sensor unplugged/noisy) + +## Common electrical causes of software symptoms + +- loose cable -> intermittent state transitions +- wrong port -> mechanism appears dead +- low battery -> unstable auton timing and movement + +**Learn more:** [Game Manual 0 - Control Hub](https://gm0.org/en/latest/docs/common/control-hub.html) + +--- + +**Next:** [Troubleshooting Playbook](02-troubleshooting-playbook.md) diff --git a/electronics/02-troubleshooting-playbook.md b/electronics/02-troubleshooting-playbook.md new file mode 100644 index 0000000..3b1c575 --- /dev/null +++ b/electronics/02-troubleshooting-playbook.md @@ -0,0 +1,40 @@ +# Electronics Troubleshooting Playbook + +## Priority order + +1. Safety first (disable power if behavior is unsafe) +2. Confirm mechanical freedom (no jams) +3. Confirm wiring and configuration +4. Then inspect software assumptions + +## Symptom-driven checks + +### Motor not moving +- hardware map name correct? +- correct port? +- mode/power set in code? +- motor direction reversed unexpectedly? + +### Servo jittering +- conflicting code paths setting position? +- unstable power or loose cable? +- invalid position spam in loop? + +### Sensor-triggered logic unreliable +- threshold too tight? +- noisy/unfiltered data? +- sensor physically misaligned? + +## Team handoff practice + +When escalating to another subteam member, provide: +- symptom and when it happens +- telemetry evidence +- what you already tested +- current hypothesis + +**Related:** [Auton - Real-World Failure Modes](../auton/07-real-world-failure-modes.md) + +--- + +**Next:** [Back to Curriculum Overview](../README.md) 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..5146d3d --- /dev/null +++ b/ftcdashboard/00-intro.md @@ -0,0 +1,24 @@ +# FTC Dashboard Intro + +## What it is + +FTC Dashboard is a browser-based tool for robot telemetry, graphs, and field visualization. + +## Common team use cases + +- tune mechanism constants (`@Config` classes) +- inspect sensor values in real time +- inspect autonomous pose/path behavior +- debug state machine transitions + +## Safety and competition notes + +- Do not rely on dashboard as your only debugging tool during matches. +- Keep telemetry lightweight enough for stable loop performance. +- Treat any runtime config edits carefully and document what changed. + +**Learn more:** [Game Manual 0 - Debugging](https://gm0.org/en/latest/docs/software/lessons/tuning-and-debugging.html) + +--- + +**Next:** [Connection Troubleshooting](01-connection-troubleshooting.md) diff --git a/ftcdashboard/01-connection-troubleshooting.md b/ftcdashboard/01-connection-troubleshooting.md new file mode 100644 index 0000000..073d935 --- /dev/null +++ b/ftcdashboard/01-connection-troubleshooting.md @@ -0,0 +1,28 @@ +# FTC Dashboard Connection Troubleshooting + +## Quick checklist + +1. Connect laptop to robot network +2. Confirm robot app is running +3. Open dashboard URL in browser +4. Verify opmode is actually sending telemetry each loop + +## Common issues + +- **Wrong IP/URL**: use the Control Hub address for your setup. +- **No telemetry data**: telemetry not updated in loop. +- **Connected but stale values**: opmode not running or app needs redeploy. +- **ADB confusion**: disconnect stale sessions and reconnect cleanly. + +## Fast diagnosis flow + +1. Test network reachability +2. Restart robot app/opmode +3. Rebuild and redeploy if needed +4. Check logcat for runtime exceptions + +**Related:** [Electronics - Control Hub Checks](../electronics/01-control-hub-checks.md) + +--- + +**Next:** [Telemetry Patterns](02-telemetry-patterns.md) diff --git a/ftcdashboard/02-telemetry-patterns.md b/ftcdashboard/02-telemetry-patterns.md new file mode 100644 index 0000000..1469c90 --- /dev/null +++ b/ftcdashboard/02-telemetry-patterns.md @@ -0,0 +1,35 @@ +# Telemetry Patterns + +## High-value telemetry fields + +For TeleOp: +- state machine state +- mechanism targets vs actual +- key sensor flags used in transitions + +For Auton: +- current path/segment +- pose (`x`, `y`, `heading`) +- follower busy/completion state + +## Organization pattern + +Group telemetry by subsystem. Example sections: +- `Drive` +- `Scoring` +- `Intake` +- `Auton` + +This makes debugging faster under time pressure. + +## Noise control + +- avoid printing every internal variable +- prefer stable, decision-relevant values +- remove temporary spam logs after fixing bugs + +**Related:** [Misc - Telemetry Best Practices](../misc/01-telemetry-best-practices.md) + +--- + +**Next:** [Misc Track](../misc/README.md) 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/00-setup.md b/intro/00-setup.md index ea6d985..d73b865 100644 --- a/intro/00-setup.md +++ b/intro/00-setup.md @@ -1,6 +1,6 @@ # Setting Up -Before we can begin learning how to program robots, we first need the tools to program with. The most important tool is our code editor or IDE (integrated development environment), because that's where we write all our code. When learning java you might've used Visual Studio Code or IntelliJ, but for FTC we will be using Android Studio. Why? Android Studio is designed to work with Android apps, which is perfect for our purposes; the control hub (the "computer" on the robot) runs on Android, so we need an IDE that can work with Android apps. +Before we can begin learning how to program robots, we first need the tools to program with. The most important tool is our code editor or IDE (integrated development environment), because that's where we write all our code. When learning java you might've used Visual Studio Code or IntelliJ, but for FTC we use Android Studio. Why? Android Studio is designed for Android apps, and the Control Hub runs Android. ## Android Studio Installation @@ -8,27 +8,53 @@ Download the latest version of [Android Studio](https://developer.android.com/st After installation, you should reach a home menu saying "Welcome to Android Studio". Don't select anything yet, and move on to the next part. You can keep Android Studio open though, we will be using it soon. +## Quick checklist + +Before continuing, make sure you have: +- Android Studio installed +- Git installed +- A GitHub account +- SSH auth set up for GitHub (recommended) + ## Git Installation and GitHub Account To get the code for our robot, we will be using Git, a version control system. Git allows us to keep track of changes to our code and collaborate with others. We will also be using GitHub, a platform for hosting Git repositories. -First create a [GitHub account](https://github.com) if you don't have one already. Then download and install [Git](https://git-scm.com/downloads). If you are having any trouble installing anything ask someone on the team :) +First create a [GitHub account](https://github.com) if you don't have one already. Then download and install [Git](https://git-scm.com/downloads). If you are having trouble installing anything, ask someone on the team. The last step is to link your computer to your GitHub account. This is so that you can save your code to GitHub and collaborate with other teammates. You can do this by following [these](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) instructions. ## Getting the Current FTC Code -Now it's time to get access to some code! First we have to get the FTC Robot Controller app from GitHub. This is the app that runs on the control hub and controls the robot. All teams use basically the same version of this code, and it's available on [GitHub](https://github.com/FIRST-Tech-Challenge/FtcRobotController). To get it, follow these steps: -1. Open up your terminal (if you don't know what is a terminal is, you should watch a basic tutorial). +Now it's time to get access to some code. First we get the FTC Robot Controller app from GitHub. This app runs on the Control Hub and is the base project every team starts from. It is available on [GitHub](https://github.com/FIRST-Tech-Challenge/FtcRobotController). To get it, follow these steps: +1. Open your terminal. 1. Navigate to the folder where you want to save the code. You can do this with the `cd` command. For example, if you want to save it in your documents, you can do `cd ~/Documents`. -1. Now clone (make a copy on your computer) the FTC Robot Controller app like this: `git clone git@github.com:FIRST-Tech-Challenge/FtcRobotController.git`. Don't close your terminal yet! +1. Clone the FTC Robot Controller app: `git clone git@github.com:FIRST-Tech-Challenge/FtcRobotController.git` -The other bit of the code that we want to get from GitHub is our current robot code. This is the part that actually controls *our* robot which shouldn't be confused with the FTC Robot Controller app. That's just a template. -1. Find the current year's GitHub repository from our [team's GitHub](https://github.com/Fission310/) -1. Click the green "Code" button, click on SSH, and copy the link. It should be something like `git@github.com:Fission310/.git` +The other code we need is the team's current robot code. This is the part that actually controls *our* robot and changes each season. +1. Find the current team's active repository from our [team GitHub organization](https://github.com/Fission310/) +1. Click the green "Code" button, click SSH, and copy the link. It will look like `git@github.com:Fission310/.git` 1. Go back to your terminal and navigate to where the robot code is stored. `cd FtcRobotController/TeamCode/src/main/java/org/firstinspires/ftc/` If you type `ls` you should see a folder called `teamcode`. This is where all the code for our robot will go. 1. Let's first delete the existing code in that folder. You can do this with `rm -rf teamcode/`. -1. Now it's time to clone our robot code into that folder. Do this with `git clone teamcode`. This will clone the code into the `teamcode` folder. +1. Clone the team robot code into that folder: `git clone teamcode` 1. The last step is to import the project into Android Studio. Go back to Android Studio and click on "Open". Navigate to the folder where you cloned the FTC Robot Controller app (probably called `FtcRobotController`), and select it. Click "Trust Project", and Android Studio should open! -Now everything is set up! +## First build check + +Before moving on: +1. In Android Studio, wait for indexing and Gradle sync to finish. +2. Run a build (`Build > Make Project`). +3. Confirm there are no setup-related errors. + +## Common setup issues + +- **Git authentication fails**: re-check SSH keys and GitHub account settings. +- **Gradle sync fails**: check internet connection, retry sync, and confirm Android SDK components are installed. +- **SDK version errors**: install missing Android SDK versions from the SDK Manager. +- **Project opens but classes are red**: let indexing finish, then try `File > Sync Project with Gradle Files`. + +Now everything is set up enough to start reading and running team code. + +--- + +**Next:** [Git Workflow](02-git-workflow.md) diff --git a/intro/01-code-overview.md b/intro/01-code-overview.md index 61b9e7f..95f8d65 100644 --- a/intro/01-code-overview.md +++ b/intro/01-code-overview.md @@ -1,25 +1,51 @@ # Code Overview -Now it's time to take a look at the code! +Now it's time to take a look at the code. ## How to Get to Teamcode On the left side of Android Studio you should see a bunch of folders. Navigate to `TeamCode > src > main > java > org > firstinspires > ftc > teamcode` (I know thats a lot of folders, but that's how all android projects are). This is where all the code for the robot goes. We call this folder `teamcode`. Like I said earlier, everything else is general code that gets everything running, but doesn't tell the robot what to do. That's what `teamcode` is for. -Inside `teamcode` you should see folders like `hardware`, and `opmode`. One important thing to note is the difference between `TeamCode` and `teamcode`. `TeamCode` is one of the base folders that came with the FTC Robot Controller, and `teamcode` is the name of the folder where all the robot code goes. If you see `lib` and `src`, but not `hardware` and `opmode`, then you are in `TeamCode` and not `teamcode`. Make sure you are in the right folder! +Inside `teamcode` you should see folders like `hardware` and `opmode`. One important thing to note is the difference between `TeamCode` and `teamcode`: +- `TeamCode` is the module from the FTC SDK template. +- `teamcode` is your Java package/folder where your robot classes live. + +If you see `lib` and `src`, but not your robot folders, you are likely looking at module-level `TeamCode` and not the package folder. ## Hardware -Since I've mentioned the `hardware` and `opmode` folders a few times, let's take a look at them. Open up the `hardware` folder. Inside you should see a bunch of java files. There is one file per mechanism on the robot. For example, all FTC robots have a drive train, so there is a `Drivetrain.java` file. If the robot has a claw, there will be a `Claw.java` file. Each of these files contains code that tells the robot how to use that mechanism. For example, the `Drivetrain.java` file contains code that tells the robot how to move forward, backward, turn, etc. +Since we've mentioned the `hardware` and `opmode` folders a few times, let's take a look at them. Open the `hardware` folder. Inside you should see one or more files per mechanism. For example: +- `Drivetrain.java` for movement +- `Claw.java` for grabbing game elements +- `Slides.java` for vertical motion + +Each mechanism class should expose simple methods (like `open()`, `close()`, `setTarget()`) and hide low-level motor/servo details. ## OpModes -Now open up the `opmode` folder. This is where we are going to use the `hardware` files! Inside you should see `auton` and `teleop` folders. An Op Mode is short for Operational Mode. In FTC, there are two types of Op Modes: Autonomous and TeleOp (Teleoperation). Autonomous (auton or auto for short) is when the robot moves by itself for the first 30 seconds of the match. TeleOp is everything after that, where the driver(s) control the robot. So, we put all out auton code in `auton`, and teleop code in `teleop`. Usually we will just have one teleop, but sometimes we will want different autons depending on where we choose to start the robot in a match. If there are a bunch of autons, it might be a good idea to put them in seperate folders inside `auton` based on what side of the field or what starting color they are for. +Now open the `opmode` folder. This is where we use the mechanism classes. Inside you should see `auton` and `teleop` folders. + +An OpMode is short for Operational Mode. In FTC: +- **Autonomous** (`auton`): robot runs pre-programmed logic for the first 30 seconds. +- **TeleOp** (`teleop`): drivers control the robot for the rest of the match. + +Usually teams keep one main teleop and multiple autons. As the season gets more complex, it helps to group autons by side/strategy. + +Inside these opmodes, you instantiate and use mechanism classes. Example: in teleop, if the driver presses a button, call `claw.close()`. + +## PedroPathing (Autonomous Pathing) + +Our team is moving to [PedroPathing](https://pedropathing.com/) for autonomous pathing. + +You will typically see Pedro code in a dedicated package (often named something like `pedroPathing`) with: +- a constants/config file for drivetrain/localizer/follower settings +- path-building code (Bezier lines/curves and path chains) +- autonomous opmodes that call follower update methods each loop -Inside each of the autons, we get to use the hardware classes. For example, in our main teleop, we might want the claw to close when the driver presses X. In that case we can use the `close` method from `Claw.java` to close the claw! +Most teams keep this separated from mechanism code, then connect both in auton opmodes. -## RoadRunner +### Important note about old repositories -The last few folders are used for [RoadRunner](https://learnroadrunner.com/introduction.html). We will get into more about RoadRunner later, but it's essentially a library (bunch of code that some smart people wrote to make our lives easier) that helps us move our drive train in a precise way. `util` contains a bunch of code that RoadRunner needs to work, and `trajectorysequence` contains the code that we will use to make the robot follow a path. +Older team repositories (including references in this learning repo) may still contain RoadRunner folders like `drive/`, `util/`, and `trajectorysequence/`. You should treat those as historical references for structure/style, not as the current pathing system. -We won't be changing the code in `util` and `trajectorysequence`, but we will change the code in the other folder that RoadRunner uses: `drive`. Inside `drive` there are a few files that we use to tell RoadRunner how our drive train works. Different robots have different sized drive trains, so we need to tell RoadRunner how our drive train is set up so it knows how to move it. Then there is also the `opmode` folder inside `drive`. As you might've guessed, `opmode` contains opmodes! These are mostly used to test our drive train, and some will be used to get the values we need to put in the other files in `drive`. We won't need to change these opmodes, but it's good to know where they are and what they do. +In this curriculum, autonomous docs and examples are PedroPathing-first. diff --git a/intro/02-git-workflow.md b/intro/02-git-workflow.md new file mode 100644 index 0000000..fda7a5e --- /dev/null +++ b/intro/02-git-workflow.md @@ -0,0 +1,66 @@ +# Git Workflow for FTC + +## Why Git matters + +Git protects the team from losing work and makes collaboration safer. Even if only one or two people are editing code, version history is still useful for rollback and debugging. + +## Recommended default workflow + +This team often works directly on `main` when the contributor count is low. That is acceptable for small changes, but you should still commit in small, meaningful chunks. + +If many people are working at once, use short-lived branches. + +## Daily routine + +1. Pull latest changes: `git pull` +2. Make one focused change (for example: one mechanism fix) +3. Run a local build +4. Commit with a clear message +5. Push: `git push` + +If using branches: +1. `git checkout -b ` +2. Work and commit +3. Push and open a PR +4. Merge after review + +## Commit message guidelines + +Good commit messages are short and specific. + +Examples: +- `fix intake servo direction` +- `add telemetry for slides target` +- `refactor scoring state transitions` + +Avoid: +- `stuff` +- `changes` +- `final` + +## Merge conflict basics + +If a pull or merge causes conflicts: +1. Read both versions carefully +2. Keep the correct behavior, not just whichever is newer +3. Rebuild and test before committing the resolution + +Never guess through conflicts in autonomous or safety-critical code. + +## Mistakes to avoid + +- Huge commits touching unrelated features +- Committing generated/build files +- Force-pushing shared history without team agreement +- Skipping build checks before pushing + +## Mini exercise + +1. Pick one mechanism constant (for example a servo position) +2. Change it in code +3. Commit with a clear message +4. Push and ask another member to review the change + +--- + +**Next:** [Android Studio Workflow](03-android-studio-workflow.md) diff --git a/intro/03-android-studio-workflow.md b/intro/03-android-studio-workflow.md new file mode 100644 index 0000000..066d81b --- /dev/null +++ b/intro/03-android-studio-workflow.md @@ -0,0 +1,53 @@ +# Android Studio Workflow + +## Goal + +Learn the Android Studio actions you will use every practice day. + +## Navigation essentials + +- Use the Project pane to find `TeamCode` and your `teamcode` package. +- Use `Shift` twice to search classes/files quickly. +- Use `Command + B` on a symbol to jump to definition. + +## Build and sync cycle + +You will repeat this loop constantly: +1. Edit code +2. Sync if prompted by Gradle changes +3. Build (`Build > Make Project`) +4. Fix compile errors immediately + +## Running OpModes + +Typical process: +1. Connect to robot network +2. Build and deploy from Android Studio +3. Open Driver Station / RC app +4. Select opmode and test + +## Logcat and debugging + +Use Logcat when telemetry is not enough. +- Filter by your package name +- Search for stack traces and `NullPointerException` +- Add temporary logs while debugging, then remove noisy ones + +## Common failure patterns + +- **Gradle sync issues**: retry sync, check internet and SDK manager +- **Device not detected**: check cable/network/ADB state +- **App won’t install**: uninstall old app versions and rebuild +- **Red code everywhere**: wait for indexing, then sync + rebuild + +## Recovery checklist when everything breaks + +1. Save work +2. `File > Sync Project with Gradle Files` +3. Rebuild +4. Invalidate caches only if problems persist +5. Ask a teammate before making large environment changes + +--- + +**Next:** [Codebase Overview](../codebase/README.md) 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..4970192 --- /dev/null +++ b/misc/00-dev-opmodes.md @@ -0,0 +1,35 @@ +# Dev OpModes + +## Purpose + +Dev opmodes are isolated test programs for one subsystem or behavior. + +They reduce risk by letting you test changes before touching main TeleOp or auton. + +## Naming and organization + +Use consistent names like: +- `IntakeDev` +- `SlidesDev` +- `DriveDev` + +Keep them in a dedicated dev folder/package. + +## Safety rules + +- start with low power/speed settings +- test one subsystem at a time +- include an obvious stop/reset path + +## Promotion to production + +A change should move from dev to main code only after: +1. repeated successful tests +2. no regressions in related subsystems +3. clear understanding of new constants/assumptions + +**Related:** [Commands Track](../commands/README.md) - Similar isolation principle for complex sequences + +--- + +**Next:** [Telemetry Best Practices](01-telemetry-best-practices.md) diff --git a/misc/01-telemetry-best-practices.md b/misc/01-telemetry-best-practices.md new file mode 100644 index 0000000..e050758 --- /dev/null +++ b/misc/01-telemetry-best-practices.md @@ -0,0 +1,28 @@ +# Telemetry Best Practices + +## Driver station telemetry + +During matches, telemetry should answer: +- what state are we in? +- why did (or didn't) we transition? +- are key mechanisms at target? + +## Debug mode vs match mode + +Keep two levels of verbosity: +- match mode: minimal, high-value lines +- debug mode: more detailed internals + +This prevents overload during driving while preserving deep debug capability. + +## Rate and readability + +- update regularly but avoid massive payloads +- use consistent labels +- include units when relevant (in, deg, ticks) + +**Related:** [FTC Dashboard Track](../ftcdashboard/02-telemetry-patterns.md) + +--- + +**Next:** [Hardware Map and Configuration](02-hardware-map-and-config.md) diff --git a/misc/02-hardware-map-and-config.md b/misc/02-hardware-map-and-config.md new file mode 100644 index 0000000..4bc8282 --- /dev/null +++ b/misc/02-hardware-map-and-config.md @@ -0,0 +1,29 @@ +# Hardware Map and Configuration + +## Objective + +Keep hardware naming predictable so code and wiring stay aligned. + +## Naming guidelines + +- use descriptive camelCase names +- include side/function (`leftSlide`, `clawServo`) +- avoid ambiguous names (`motor1`, `servo2`) + +## Configuration hygiene + +- keep one agreed robot configuration file per active robot +- document any port remaps immediately +- verify names after hardware swaps/repairs + +## Cross-robot consistency + +If multiple robots exist (practice/comp), either: +- keep matching hardware map names, or +- keep explicit configuration profiles and clearly document differences + +**Related:** [Electronics Track](../electronics/01-control-hub-checks.md) + +--- + +**Next:** [AI Usage Guidelines](03-ai-usage-guidelines.md) diff --git a/misc/03-ai-usage-guidelines.md b/misc/03-ai-usage-guidelines.md new file mode 100644 index 0000000..2af5af9 --- /dev/null +++ b/misc/03-ai-usage-guidelines.md @@ -0,0 +1,30 @@ +# AI Usage Guidelines + +## Where AI helps + +- drafting boilerplate classes +- suggesting refactors +- explaining compile/runtime errors +- generating test checklists + +## Where AI can hurt + +- copying code blindly without understanding it +- introducing unsafe mechanism behavior +- mismatching team architecture/conventions + +## Verification checklist + +Before merging AI-assisted code: +1. can you explain what each changed line does? +2. does it match team structure/style? +3. does it build and run safely on robot? +4. was it tested in a dev opmode first? + +## Team expectations + +AI is a helper, not an authority. Human review and robot testing decide what ships. + +--- + +**Next:** [Electronics Track](../electronics/README.md) 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..72089f1 --- /dev/null +++ b/teleop/00-teleop-architecture.md @@ -0,0 +1,45 @@ +# TeleOp Architecture + +## Goal + +Build a TeleOp that is fast for drivers, readable for developers, and stable under match pressure. + +## Recommended loop shape + +1. Read inputs +2. Update high-level state (scoring modes, toggles) +3. Update mechanisms +4. Publish telemetry + +Keeping this order consistent makes bugs easier to isolate. + +## State machine pattern + +Use explicit states when controls depend on context, for example: +- `INTAKE` +- `TRANSFER` +- `SCORING` + +A state machine helps one button do different actions safely in different phases. + +## Input handling model + +Treat button types differently: +- **hold**: action runs while held +- **click/tap**: action happens once on rising edge +- **toggle**: press alternates between modes + +## Telemetry priorities + +During matches, prefer high-value telemetry: +- current state +- mechanism targets vs current values +- sensor values used for critical transitions + +Avoid dumping large debug output every loop in competition TeleOp. + +**Learn more:** [Telemetry Best Practices](../misc/01-telemetry-best-practices.md) + +--- + +**Next:** [Controls and Input Mapping](01-controls-and-input.md) diff --git a/teleop/01-controls-and-input.md b/teleop/01-controls-and-input.md new file mode 100644 index 0000000..272f6d2 --- /dev/null +++ b/teleop/01-controls-and-input.md @@ -0,0 +1,49 @@ +# Controls and Input Mapping + +## Objective + +Create control mappings that are easy to learn and hard to misuse. + +## Controller naming convention + +FTC SDK and many helper classes use Xbox-style button names (`A`, `B`, `X`, `Y`). + +If your team uses PlayStation controllers, add comments for equivalents where helpful. Example: + +```java +if (GamepadStatic.isButtonPressed(gamepad, Input.A)) { // PS Cross + claw.open(); +} +``` + +Do not hard-code docs to one physical controller style. + +## Mapping strategy + +- Put critical actions on easy-to-reach buttons +- Separate driver and operator responsibilities +- Keep emergency/manual override accessible + +## Edge detection vs hold + +Use edge detection for one-time actions (toggle, sequence trigger). +Use hold logic for continuous actions (manual slide movement). + +## Conflict prevention + +Before each event: +- list actions that can run in parallel +- list actions that must be mutually exclusive +- enforce exclusivity with state checks + +## Simple control map template + +- Driver: drivetrain, heading reset, slow mode +- Operator: intake, transfer, scoring, reset +- Shared: emergency stop/manual recovery + +**Next step:** Use commands to simplify complex scoring transitions. + +--- + +**Next:** [Commands Track](../commands/README.md) 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) From a8852347826e83354dbaed6ae1b4706af7998a91 Mon Sep 17 00:00:00 2001 From: Flint Mueller Date: Sat, 23 May 2026 13:28:39 -0400 Subject: [PATCH 4/8] revert original docs --- codebase/mechanisms/00-intro.md | 30 +++------------- codebase/mechanisms/01-robot-scoring.md | 27 ++------------- intro/00-setup.md | 46 ++++++------------------- intro/01-code-overview.md | 42 +++++----------------- 4 files changed, 25 insertions(+), 120 deletions(-) diff --git a/codebase/mechanisms/00-intro.md b/codebase/mechanisms/00-intro.md index d0756f0..e837bbe 100644 --- a/codebase/mechanisms/00-intro.md +++ b/codebase/mechanisms/00-intro.md @@ -1,14 +1,12 @@ # Mechanisms -Let's go over what a mechanism is, and then make a simple one. +Let's go over what a mechanism is, and then we can make our first one! ## What is a Mechanism? -A mechanism is a part of the robot with a specific job. One of the simplest examples is a claw. If your robot has a claw to grab game pieces, the code should have a `Claw` class that controls it. +A mechanism is some part of the robot that has a specific function. One of the simplest examples of a mechanism is a claw. You might have a claw on the robot to grab game pieces, and in the code, you would have a `Claw` class that contains code to make the claw move. -All mechanisms go in the `hardware/mechanisms` folder in `teamcode`. This keeps organization clear and consistent. - -Continue with the claw example. Create a new file called `Claw.java` in `hardware/mechanisms`. +All mechanisms go in the `hardware/mechanisms` folder in `teamcode`. This helps us keep organized so we can find our mechanisms easily. Let's continue with the claw example. Create a new file called `Claw.java` in the `hardware/mechanisms` folder. If any of the folders don't exist, make them. And if `Claw.java` already exists, delete it and make a new one. In Android Studio you make a file by right-clicking on the folder you want to put it in, then going to `New > File`, or `New > Directory` if you want to make a new folder. ## Claw Code @@ -87,11 +85,7 @@ This is where we start the actual code for our claw. We are making a class calle public static double CLOSE_POS = 0.5; ``` -Here are the variables we use in the claw class. The first is a `Servo` variable named `servo`. We use this to control the servo that moves the claw. If the mechanism had two servos, we would declare two `Servo` variables. - -The next two variables are `OPEN_POS` and `CLOSE_POS`. These are servo target positions. Servo positions are `double`s from 0 to 1. - -These values depend on your real hardware, so you should tune them. Keep position constants `public static` so FTC Dashboard can adjust them quickly during testing. +Here are our variables that we will use in the claw class. The first one is a `Servo` that we call `servo` (`Servo` is the type, and `servo` is the name). `Servo` is a class from the base java library that all FTC teams use. We imported `Servo` at the top of the file. We use this variable to control the imaginary servo that moves our imaginary claw. If we had two servos controlling our claw, we would need two `Servo` variables. The next two variables are `OPEN_POS` and `CLOSE_POS`. These are the positions that the servo needs to be in to open and close the claw. For servos, the positions will always be `double`s between 0 and 1. The values of these variables will depend on how your claw is built, so you will need to change them to get your claw working. I picked 0.7 and 0.5 because I felt like it :) When you make your own mechanism, you should start with a guess, and then change the values until it works. These variables are `public` and `static` because we want to be able to change them from FTC Dashboard (again, we will get to that later). Just know that you should make all your position constants `public static`. ```java public Claw(LinearOpMode opMode) { @@ -136,18 +130,4 @@ Now we get to the `open` (and `close`) functions. These are the functions that t } ``` -Lastly, we have the `loop` function. This runs continuously while the op mode is active. - -In this example, `A` opens and `X` closes. In SDK/FissionLib code these button names follow Xbox-style labels. If your team is physically using PlayStation controllers, add comments so newer members can map labels correctly. - -`GamepadStatic.isButtonPressed(gamepad, Input.A)` returns `true` while that button is currently held. - -## Design note - -Mechanisms should focus on hardware behavior and local logic. Match strategy (when to score, when to transfer, etc.) should live in higher-level files like `Scoring` or TeleOp/auton classes. - -**Learn more:** [Game Manual 0 - Mechanisms & Subsystems](https://gm0.org/en/latest/docs/software/lessons/subsystems.html) - ---- - -**Next:** [Robot.java and Scoring.java](01-robot-scoring.md) +Lastly, we have the `loop` function. This is the second function that we get from the `Mechanism` class. The `loop` function runs continuously while the op mode is running. This is where you put code that needs to run over and over again. In the case of our claw, we want to be able to open and close it using buttons on the controller (it's called a gamepad in code). The code is pretty simple; we check if the `A` button (on an Xbox controller) is pressed, and if it is we call the `open` function. If `X` is pressed, we close the claw instead with `close()`. The `GamepadStatic.isButtonPressed` function just tells us if a certain button is pressed on the gamepad. The first parameter is the gamepad you want to check, and the second is the button. It will return `true` if the button is currently being held down on the controller. diff --git a/codebase/mechanisms/01-robot-scoring.md b/codebase/mechanisms/01-robot-scoring.md index c02dda1..7957608 100644 --- a/codebase/mechanisms/01-robot-scoring.md +++ b/codebase/mechanisms/01-robot-scoring.md @@ -1,6 +1,6 @@ # Robot.java and Scoring.java -In this section we will learn about two important files in the `hardware` directory: `Robot.java` and `Scoring.java`. +In this section we will learn about the other two files in the `hardware` directory: `Robot.java` and `Scoring.java`. ## Scoring.java @@ -68,18 +68,7 @@ public class Scoring extends Mechanism { } ``` -Note how similar this is to our `Claw.java` example. `Scoring` is also a `Mechanism`, so it has `init` and `loop` methods. - -The key difference is the `state` variable. The state tracks whether we are intaking or scoring. This makes button behavior context-dependent and safer. - -This setup is useful because one button can trigger different actions in different states. - -## State-machine safety tips - -- Keep states explicit and small. -- Keep transitions easy to read. -- Avoid transitions that depend only on long fixed delays. -- Prefer sensor/position checks for important transitions. +Note how similar this is to our `Claw.java` example. `Scoring` is also a `Mechanism` so that we can have the same `init` and `loop` methods. Our scoring sequence is made up of a claw and slides, so those will be variables in our class. The constructor is the same, and in the init method we just call the init methods for the claw and slides. The main difference is that we now have a state variable that keeps track of whether we are intaking a game element or scoring it. The state variable is an [enum](https://www.w3schools.com/java/java_enums.asp) that can be either `INTAKING` or `SCORING`. In `loop`, we check the state variable to see if we want to run the logic for intaking or scoring. This setup with `state` is a versatile way to have different logic for different parts of the game. This way you can also use a single button for different actions. ## Robot.java @@ -121,15 +110,3 @@ public class Robot extends Mechanism { ``` This `Robot` class is fairly simple. It just glues together the `Scoring` mechanism and the rest of the non-scoring mechanisms (in this case just the `Drivetrain`). In `init`, we call the init methods for both the drivetrain and scoring. In `loop`, we call the loop methods for both the drivetrain and scoring. - -## Automation boundary guideline - -- `Mechanism` classes: hardware-level behaviors (`open`, `close`, `setTarget`). -- `Scoring`: coordinated subsystem behavior and game-phase state. -- `Robot`: top-level composition of major subsystems. - -This boundary helps keep TeleOp and auton code easier to maintain. - ---- - -**Next:** [Mechanism Design Guide](02-mechanism-design.md) diff --git a/intro/00-setup.md b/intro/00-setup.md index d73b865..ea6d985 100644 --- a/intro/00-setup.md +++ b/intro/00-setup.md @@ -1,6 +1,6 @@ # Setting Up -Before we can begin learning how to program robots, we first need the tools to program with. The most important tool is our code editor or IDE (integrated development environment), because that's where we write all our code. When learning java you might've used Visual Studio Code or IntelliJ, but for FTC we use Android Studio. Why? Android Studio is designed for Android apps, and the Control Hub runs Android. +Before we can begin learning how to program robots, we first need the tools to program with. The most important tool is our code editor or IDE (integrated development environment), because that's where we write all our code. When learning java you might've used Visual Studio Code or IntelliJ, but for FTC we will be using Android Studio. Why? Android Studio is designed to work with Android apps, which is perfect for our purposes; the control hub (the "computer" on the robot) runs on Android, so we need an IDE that can work with Android apps. ## Android Studio Installation @@ -8,53 +8,27 @@ Download the latest version of [Android Studio](https://developer.android.com/st After installation, you should reach a home menu saying "Welcome to Android Studio". Don't select anything yet, and move on to the next part. You can keep Android Studio open though, we will be using it soon. -## Quick checklist - -Before continuing, make sure you have: -- Android Studio installed -- Git installed -- A GitHub account -- SSH auth set up for GitHub (recommended) - ## Git Installation and GitHub Account To get the code for our robot, we will be using Git, a version control system. Git allows us to keep track of changes to our code and collaborate with others. We will also be using GitHub, a platform for hosting Git repositories. -First create a [GitHub account](https://github.com) if you don't have one already. Then download and install [Git](https://git-scm.com/downloads). If you are having trouble installing anything, ask someone on the team. +First create a [GitHub account](https://github.com) if you don't have one already. Then download and install [Git](https://git-scm.com/downloads). If you are having any trouble installing anything ask someone on the team :) The last step is to link your computer to your GitHub account. This is so that you can save your code to GitHub and collaborate with other teammates. You can do this by following [these](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) instructions. ## Getting the Current FTC Code -Now it's time to get access to some code. First we get the FTC Robot Controller app from GitHub. This app runs on the Control Hub and is the base project every team starts from. It is available on [GitHub](https://github.com/FIRST-Tech-Challenge/FtcRobotController). To get it, follow these steps: -1. Open your terminal. +Now it's time to get access to some code! First we have to get the FTC Robot Controller app from GitHub. This is the app that runs on the control hub and controls the robot. All teams use basically the same version of this code, and it's available on [GitHub](https://github.com/FIRST-Tech-Challenge/FtcRobotController). To get it, follow these steps: +1. Open up your terminal (if you don't know what is a terminal is, you should watch a basic tutorial). 1. Navigate to the folder where you want to save the code. You can do this with the `cd` command. For example, if you want to save it in your documents, you can do `cd ~/Documents`. -1. Clone the FTC Robot Controller app: `git clone git@github.com:FIRST-Tech-Challenge/FtcRobotController.git` +1. Now clone (make a copy on your computer) the FTC Robot Controller app like this: `git clone git@github.com:FIRST-Tech-Challenge/FtcRobotController.git`. Don't close your terminal yet! -The other code we need is the team's current robot code. This is the part that actually controls *our* robot and changes each season. -1. Find the current team's active repository from our [team GitHub organization](https://github.com/Fission310/) -1. Click the green "Code" button, click SSH, and copy the link. It will look like `git@github.com:Fission310/.git` +The other bit of the code that we want to get from GitHub is our current robot code. This is the part that actually controls *our* robot which shouldn't be confused with the FTC Robot Controller app. That's just a template. +1. Find the current year's GitHub repository from our [team's GitHub](https://github.com/Fission310/) +1. Click the green "Code" button, click on SSH, and copy the link. It should be something like `git@github.com:Fission310/.git` 1. Go back to your terminal and navigate to where the robot code is stored. `cd FtcRobotController/TeamCode/src/main/java/org/firstinspires/ftc/` If you type `ls` you should see a folder called `teamcode`. This is where all the code for our robot will go. 1. Let's first delete the existing code in that folder. You can do this with `rm -rf teamcode/`. -1. Clone the team robot code into that folder: `git clone teamcode` +1. Now it's time to clone our robot code into that folder. Do this with `git clone teamcode`. This will clone the code into the `teamcode` folder. 1. The last step is to import the project into Android Studio. Go back to Android Studio and click on "Open". Navigate to the folder where you cloned the FTC Robot Controller app (probably called `FtcRobotController`), and select it. Click "Trust Project", and Android Studio should open! -## First build check - -Before moving on: -1. In Android Studio, wait for indexing and Gradle sync to finish. -2. Run a build (`Build > Make Project`). -3. Confirm there are no setup-related errors. - -## Common setup issues - -- **Git authentication fails**: re-check SSH keys and GitHub account settings. -- **Gradle sync fails**: check internet connection, retry sync, and confirm Android SDK components are installed. -- **SDK version errors**: install missing Android SDK versions from the SDK Manager. -- **Project opens but classes are red**: let indexing finish, then try `File > Sync Project with Gradle Files`. - -Now everything is set up enough to start reading and running team code. - ---- - -**Next:** [Git Workflow](02-git-workflow.md) +Now everything is set up! diff --git a/intro/01-code-overview.md b/intro/01-code-overview.md index 95f8d65..61b9e7f 100644 --- a/intro/01-code-overview.md +++ b/intro/01-code-overview.md @@ -1,51 +1,25 @@ # Code Overview -Now it's time to take a look at the code. +Now it's time to take a look at the code! ## How to Get to Teamcode On the left side of Android Studio you should see a bunch of folders. Navigate to `TeamCode > src > main > java > org > firstinspires > ftc > teamcode` (I know thats a lot of folders, but that's how all android projects are). This is where all the code for the robot goes. We call this folder `teamcode`. Like I said earlier, everything else is general code that gets everything running, but doesn't tell the robot what to do. That's what `teamcode` is for. -Inside `teamcode` you should see folders like `hardware` and `opmode`. One important thing to note is the difference between `TeamCode` and `teamcode`: -- `TeamCode` is the module from the FTC SDK template. -- `teamcode` is your Java package/folder where your robot classes live. - -If you see `lib` and `src`, but not your robot folders, you are likely looking at module-level `TeamCode` and not the package folder. +Inside `teamcode` you should see folders like `hardware`, and `opmode`. One important thing to note is the difference between `TeamCode` and `teamcode`. `TeamCode` is one of the base folders that came with the FTC Robot Controller, and `teamcode` is the name of the folder where all the robot code goes. If you see `lib` and `src`, but not `hardware` and `opmode`, then you are in `TeamCode` and not `teamcode`. Make sure you are in the right folder! ## Hardware -Since we've mentioned the `hardware` and `opmode` folders a few times, let's take a look at them. Open the `hardware` folder. Inside you should see one or more files per mechanism. For example: -- `Drivetrain.java` for movement -- `Claw.java` for grabbing game elements -- `Slides.java` for vertical motion - -Each mechanism class should expose simple methods (like `open()`, `close()`, `setTarget()`) and hide low-level motor/servo details. +Since I've mentioned the `hardware` and `opmode` folders a few times, let's take a look at them. Open up the `hardware` folder. Inside you should see a bunch of java files. There is one file per mechanism on the robot. For example, all FTC robots have a drive train, so there is a `Drivetrain.java` file. If the robot has a claw, there will be a `Claw.java` file. Each of these files contains code that tells the robot how to use that mechanism. For example, the `Drivetrain.java` file contains code that tells the robot how to move forward, backward, turn, etc. ## OpModes -Now open the `opmode` folder. This is where we use the mechanism classes. Inside you should see `auton` and `teleop` folders. - -An OpMode is short for Operational Mode. In FTC: -- **Autonomous** (`auton`): robot runs pre-programmed logic for the first 30 seconds. -- **TeleOp** (`teleop`): drivers control the robot for the rest of the match. - -Usually teams keep one main teleop and multiple autons. As the season gets more complex, it helps to group autons by side/strategy. - -Inside these opmodes, you instantiate and use mechanism classes. Example: in teleop, if the driver presses a button, call `claw.close()`. - -## PedroPathing (Autonomous Pathing) - -Our team is moving to [PedroPathing](https://pedropathing.com/) for autonomous pathing. - -You will typically see Pedro code in a dedicated package (often named something like `pedroPathing`) with: -- a constants/config file for drivetrain/localizer/follower settings -- path-building code (Bezier lines/curves and path chains) -- autonomous opmodes that call follower update methods each loop +Now open up the `opmode` folder. This is where we are going to use the `hardware` files! Inside you should see `auton` and `teleop` folders. An Op Mode is short for Operational Mode. In FTC, there are two types of Op Modes: Autonomous and TeleOp (Teleoperation). Autonomous (auton or auto for short) is when the robot moves by itself for the first 30 seconds of the match. TeleOp is everything after that, where the driver(s) control the robot. So, we put all out auton code in `auton`, and teleop code in `teleop`. Usually we will just have one teleop, but sometimes we will want different autons depending on where we choose to start the robot in a match. If there are a bunch of autons, it might be a good idea to put them in seperate folders inside `auton` based on what side of the field or what starting color they are for. -Most teams keep this separated from mechanism code, then connect both in auton opmodes. +Inside each of the autons, we get to use the hardware classes. For example, in our main teleop, we might want the claw to close when the driver presses X. In that case we can use the `close` method from `Claw.java` to close the claw! -### Important note about old repositories +## RoadRunner -Older team repositories (including references in this learning repo) may still contain RoadRunner folders like `drive/`, `util/`, and `trajectorysequence/`. You should treat those as historical references for structure/style, not as the current pathing system. +The last few folders are used for [RoadRunner](https://learnroadrunner.com/introduction.html). We will get into more about RoadRunner later, but it's essentially a library (bunch of code that some smart people wrote to make our lives easier) that helps us move our drive train in a precise way. `util` contains a bunch of code that RoadRunner needs to work, and `trajectorysequence` contains the code that we will use to make the robot follow a path. -In this curriculum, autonomous docs and examples are PedroPathing-first. +We won't be changing the code in `util` and `trajectorysequence`, but we will change the code in the other folder that RoadRunner uses: `drive`. Inside `drive` there are a few files that we use to tell RoadRunner how our drive train works. Different robots have different sized drive trains, so we need to tell RoadRunner how our drive train is set up so it knows how to move it. Then there is also the `opmode` folder inside `drive`. As you might've guessed, `opmode` contains opmodes! These are mostly used to test our drive train, and some will be used to get the values we need to put in the other files in `drive`. We won't need to change these opmodes, but it's good to know where they are and what they do. From 5a770dc1047f7c65ccf2d0293f41f6eaf81c3f1e Mon Sep 17 00:00:00 2001 From: Flint Mueller Date: Sat, 23 May 2026 13:49:21 -0400 Subject: [PATCH 5/8] lets do it slower --- STYLE.md | 8 +++ auton/00-auton-overview.md | 34 ---------- auton/01-pedro-setup.md | 61 ----------------- auton/02-localization-and-constants.md | 41 ------------ auton/03-tuning-workflow.md | 40 ----------- auton/04-path-building.md | 43 ------------ auton/05-auton-control-flow.md | 45 ------------- auton/06-ftcdashboard-with-auton.md | 38 ----------- auton/07-real-world-failure-modes.md | 43 ------------ codebase/mechanisms/02-mechanism-design.md | 55 ---------------- commands/00-command-basics.md | 44 ------------- commands/01-command-sequences.md | 41 ------------ commands/02-common-bugs.md | 38 ----------- electronics/00-electronics-intro.md | 32 --------- .../01-control-hub-and-wiring-checks.md | 34 ---------- electronics/02-troubleshooting-playbook.md | 40 ----------- ftcdashboard/00-intro.md | 24 ------- ftcdashboard/01-connection-troubleshooting.md | 28 -------- ftcdashboard/02-telemetry-patterns.md | 35 ---------- intro/02-git-workflow.md | 66 ------------------- intro/03-android-studio-workflow.md | 53 --------------- misc/00-dev-opmodes.md | 35 ---------- misc/01-telemetry-best-practices.md | 28 -------- misc/02-hardware-map-and-config.md | 29 -------- misc/03-ai-usage-guidelines.md | 30 --------- teleop/00-teleop-architecture.md | 45 ------------- teleop/01-controls-and-input.md | 49 -------------- 27 files changed, 8 insertions(+), 1051 deletions(-) create mode 100644 STYLE.md diff --git a/STYLE.md b/STYLE.md new file mode 100644 index 0000000..0f81261 --- /dev/null +++ b/STYLE.md @@ -0,0 +1,8 @@ +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 diff --git a/auton/00-auton-overview.md b/auton/00-auton-overview.md index e4868d4..e69de29 100644 --- a/auton/00-auton-overview.md +++ b/auton/00-auton-overview.md @@ -1,34 +0,0 @@ -# Autonomous Overview - -## Objective - -Understand how to build autonomous routines that are reliable in real matches, not just in perfect testing. - -## Match constraints - -Autonomous is short and unforgiving. Reliability is usually worth more than theoretical max points. - -## Architecture checklist - -A complete auton usually combines: -- pathing follower (PedroPathing) -- mechanism actions (intake, claw, slides, etc.) -- progression logic (commands or state machine) -- telemetry/debug output for tuning - -## Readiness requirements before writing auton - -- drivetrain/localization stable -- mechanisms tested in dev opmodes -- key constants tuned -- fallback parking path available - -## Design principle - -Prefer simpler routines that finish consistently over complex routines that only work sometimes. - -**Learn more:** [Game Manual 0 - Autonomous Overview](https://gm0.org/en/latest/docs/software/lessons/autonomous.html) - ---- - -**Next:** [PedroPathing Setup](01-pedro-setup.md) diff --git a/auton/01-pedro-setup.md b/auton/01-pedro-setup.md index a333400..e69de29 100644 --- a/auton/01-pedro-setup.md +++ b/auton/01-pedro-setup.md @@ -1,61 +0,0 @@ -# PedroPathing Setup (FTC Dashboard Path) - -## Why this method - -Pedro supports multiple dashboards. For this team curriculum, we use FTC Dashboard because it is widely used across FTC and integrates well with existing workflows. - -## Installation approach - -Use **manual integration into your existing FTC project** so your current team structure stays intact. - -### 1) Add Pedro Maven repository - -In `build.dependencies.gradle`, inside `repositories {}` add: - -```gradle -maven { url = "https://mymaven.bylazar.com/releases" } -``` - -### 2) Add Pedro dependency - -In `dependencies {}` add the Pedro dependency shown in the current official docs: - -```gradle -implementation '' -``` - -Use the exact artifact/version your team has tested. - -### 3) Add FTC Dashboard dependency (if not already present) - -```gradle -implementation 'com.acmerobotics.dashboard:dashboard:0.4.16' -``` - -### 4) Sync Gradle and confirm SDK versions - -Pedro 2.x docs target modern SDK/compile settings. Follow Android Studio prompts to sync and resolve version mismatches. - -### 5) Add Pedro package files - -Copy starter Pedro files (such as constants and tuning opmodes) from the Pedro quickstart into your `teamcode` package. - -Keep naming consistent with your team package structure; do not hard-code season names. - -## Minimal first opmode flow - -1. Create follower from constants -2. Set starting pose -3. Build one simple path (line) -4. Follow path in auton loop -5. Publish pose telemetry to dashboard - -## RoadRunner migration note - -Old team repos may still contain RoadRunner folders (`drive`, `trajectorysequence`, etc.). Keep those only as historical reference; new autonomous development should use PedroPathing. - -**External:** [PedroPathing Installation Docs](https://pedropathing.com/docs/pathing/installation) - ---- - -**Next:** [Localization and Constants](02-localization-and-constants.md) diff --git a/auton/02-localization-and-constants.md b/auton/02-localization-and-constants.md index 1277824..e69de29 100644 --- a/auton/02-localization-and-constants.md +++ b/auton/02-localization-and-constants.md @@ -1,41 +0,0 @@ -# Localization and Constants - -## Objective - -Set up constants so PedroPathing follows paths predictably on your actual robot. - -## Constant categories - -Pedro constants typically include: -- follower/drive algorithm constants -- drivetrain hardware constants -- localizer constants (wheel/IMU/sensor settings) -- path completion constraints - -## Best practices - -- Keep constants in one dedicated class/package -- Document units (inches, radians, seconds) -- Add date + robot configuration notes when values change - -## Localization assumptions - -Localization quality depends on: -- wheel odometry quality and placement -- IMU consistency -- mechanical rigidity and wheel condition - -Bad localization makes all path tuning harder, so fix localization before aggressive path tuning. - -## Versioning tuned values - -When tuning updates constants: -- commit with message describing what changed and why -- include test context (battery state, field condition) -- avoid mixing unrelated mechanism changes in same commit - -**Learn more:** [PedroPathing - Constants](https://pedropathing.com/docs/pathing/constants) - ---- - -**Next:** [Pedro Tuning Workflow](03-tuning-workflow.md) diff --git a/auton/03-tuning-workflow.md b/auton/03-tuning-workflow.md index b89c1ed..e69de29 100644 --- a/auton/03-tuning-workflow.md +++ b/auton/03-tuning-workflow.md @@ -1,40 +0,0 @@ -# Pedro Tuning Workflow - -## Pre-tuning checklist - -Before software tuning: -- verify motor directions -- verify hardware map names -- inspect drivetrain friction/mechanical issues -- use a reasonably charged battery - -## Recommended order - -1. Localization setup/tuning -2. Basic follower/path tests -3. Heading behavior tuning -4. Speed/deceleration constraints -5. Full-route repeatability tests - -## Repeatability test - -Run the same path multiple times from the same start pose. - -Track: -- average end error -- worst-case end error -- drift direction patterns - -## Retune triggers - -Retune when: -- drivetrain hardware changes -- localization hardware changes -- wheel wear changes behavior significantly -- behavior degrades after impacts/repairs - -**Learn more:** [PedroPathing - Tuning Guide](https://pedropathing.com/docs/pathing/tuning) - ---- - -**Next:** [Path Building with PedroPathing](04-path-building.md) diff --git a/auton/04-path-building.md b/auton/04-path-building.md index 994876d..e69de29 100644 --- a/auton/04-path-building.md +++ b/auton/04-path-building.md @@ -1,43 +0,0 @@ -# Path Building with PedroPathing - -## Objective - -Build readable and reusable paths that cooperate with mechanism actions. - -## Path primitives - -- **BezierLine**: straight segment between two poses/points -- **BezierCurve**: curved segment with control points -- **PathChain**: multiple segments grouped into one follow action - -## Practical pattern - -- Prebuild paths in `init()` -- Name paths by intent (`toSpike`, `toBackboard`, `toPark`) -- Keep one source of truth for key poses - -## Heading and constraints - -For each path, choose heading interpolation intentionally. -Do not rely on defaults unless you understand them. - -Apply constraints for sections where speed/precision tradeoffs differ. - -## Callbacks/events - -Use callbacks or command triggers for mechanism timing tied to path progress. -Prefer event-based timing over fixed sleeps when possible. - -## Debugging bad paths - -If pathing is unstable, check in this order: -1. localization quality -2. coordinate assumptions -3. heading interpolation choice -4. end conditions and constraints - -**Learn more:** [PedroPathing - Path Builder Reference](https://pedropathing.com/docs/pathing/reference/path-builder) - ---- - -**Next:** [Autonomous Control Flow](05-auton-control-flow.md) diff --git a/auton/05-auton-control-flow.md b/auton/05-auton-control-flow.md index dcf945f..e69de29 100644 --- a/auton/05-auton-control-flow.md +++ b/auton/05-auton-control-flow.md @@ -1,45 +0,0 @@ -# Autonomous Control Flow - -## Two good patterns - -1. **Command composition** (recommended when available) -2. **Finite state machine** - -Both are valid. Choose one style per auton for readability. - -## Command-style auton - -Best when your team already uses command abstractions. - -Typical flow: -- follow path -- run scoring command sequence -- follow next path -- run intake/score command sequence - -This keeps progression logic concise. - -## State-machine auton - -Use explicit states when you need fine-grained transitions. - -Example state progression: -`START -> SCORE_PRELOAD -> PICKUP_1 -> SCORE_1 -> PARK` - -Transition on reliable conditions: -- `!follower.isBusy()` -- pose thresholds -- timeout fallback - -## Failsafes - -Always include: -- global timeout check -- fallback park state -- safe mechanism retract action before end - -**Related:** [Command Sequences](../commands/01-command-sequences.md) - ---- - -**Next:** [FTC Dashboard with Autonomous](06-ftcdashboard-with-auton.md) diff --git a/auton/06-ftcdashboard-with-auton.md b/auton/06-ftcdashboard-with-auton.md index d217faa..e69de29 100644 --- a/auton/06-ftcdashboard-with-auton.md +++ b/auton/06-ftcdashboard-with-auton.md @@ -1,38 +0,0 @@ -# FTC Dashboard with Autonomous - -## Why dashboard during auton work - -Dashboard gives fast visibility into pose, path progress, and mechanism states while tuning. - -## Basic setup - -1. Add FTC Dashboard dependency -2. Connect to robot network -3. Open dashboard in browser (`192.168.43.1:8080/dash` in common Control Hub setups) -4. Stream telemetry and field drawing data - -## What to display - -Minimum useful auton telemetry: -- current state/command -- robot pose (`x`, `y`, `heading`) -- path/segment identifier -- key mechanism targets and actual values - -## About live tuning - -Pedro docs note that FTC Dashboard does not provide full live configurability for all Pedro constants in the same way some other dashboards do. - -Use dashboard primarily for visualization and telemetry, then edit constants in code and redeploy. - -## Common connection issues - -- wrong IP/network -- stale app/deploy state -- missing telemetry updates in loop - -**Learn more:** [FTC Dashboard Track](../ftcdashboard/README.md) - ---- - -**Next:** [Real-World Auton Failure Modes](07-real-world-failure-modes.md) diff --git a/auton/07-real-world-failure-modes.md b/auton/07-real-world-failure-modes.md index f78add7..e69de29 100644 --- a/auton/07-real-world-failure-modes.md +++ b/auton/07-real-world-failure-modes.md @@ -1,43 +0,0 @@ -# Real-World Auton Failure Modes - -## Battery effects - -Low voltage changes acceleration/deceleration behavior and mechanism timing. - -Mitigations: -- tune with realistic battery ranges -- avoid overly tight timing windows -- use condition-based transitions where possible - -## Contact and slip - -Auton plans should assume occasional contact/slip. - -Mitigations: -- keep trajectories robust -- add conservative clearances near field elements -- include fallback states - -## Initialization mismatch - -Wrong start pose or mechanism start state can ruin the whole routine. - -Mitigations: -- explicit prestart checklist -- visible telemetry of selected side/path -- lock in start assumptions before pressing play - -## Postmortem template - -After a failed auton run, log: -1. start state (pose, mechanism state, battery) -2. first observed divergence -3. telemetry clues -4. root cause hypothesis -5. next single change to test - -**Related:** [Electronics Troubleshooting Playbook](../electronics/02-troubleshooting-playbook.md) - ---- - -**Next:** [FTC Dashboard Track](../ftcdashboard/README.md) diff --git a/codebase/mechanisms/02-mechanism-design.md b/codebase/mechanisms/02-mechanism-design.md index 157ac0e..e69de29 100644 --- a/codebase/mechanisms/02-mechanism-design.md +++ b/codebase/mechanisms/02-mechanism-design.md @@ -1,55 +0,0 @@ -# Mechanism Design Guide - -## Objective - -Decide what should be a mechanism and design it so TeleOp and auton code stay clean. - -## What should be a mechanism - -Make a mechanism when hardware and behavior belong together. - -Examples: -- Intake motors + intake servos + intake sensors -- Slides motors + slide limit logic -- Claw servo(s) + open/close states - -Do **not** make a mechanism for random helper methods that do not own hardware. - -## API design rules - -Prefer methods that describe intent: -- `intake.start()` -- `intake.stop()` -- `slides.setTarget(height)` - -Avoid leaking raw hardware calls into TeleOp code. - -## Initialization and safety - -In `init(...)`: -- map all hardware once -- set safe startup positions -- reset mode/flags to known values - -Fail-safe defaults matter. If an opmode starts unexpectedly, the robot should still behave safely. - -## State and automation boundaries - -Keep local state inside the mechanism when possible, but keep game strategy state at higher layers (`Scoring`, TeleOp, auton controller). - -A good rule: -- mechanism = *how* one subsystem moves -- scoring/teleop/auton = *when* and *why* it moves - -## Testing pattern - -Use a dev opmode before integrating into main teleop: -1. test one mechanism in isolation -2. verify directions, limits, and default positions -3. then integrate with scoring/state logic - -**Related:** See [Dev OpModes](../../misc/00-dev-opmodes.md) for testing patterns. - ---- - -**Next:** [TeleOp Architecture](../../teleop/README.md) diff --git a/commands/00-command-basics.md b/commands/00-command-basics.md index 74cd56d..e69de29 100644 --- a/commands/00-command-basics.md +++ b/commands/00-command-basics.md @@ -1,44 +0,0 @@ -# Command Basics - -## What is a command - -A command is a reusable action unit. It lets you move logic out of giant TeleOp/auton loops. - -Examples: -- close claw -- move slides to intake height -- run a timed intake pulse - -## Why use commands - -Commands make behavior composable and easier to test. - -Without commands, complex routines become long nested conditionals. With commands, routines are readable sequences. - -## Basic pattern (FissionLib style) - -```java -private Command closeClaw = () -> claw.close(); - -private CommandSequence grabSequence = new CommandSequence() - .addCommand(closeClaw) - .addWaitCommand(0.2) - .build(); -``` - -## Lifecycle idea - -For any command sequence, know: -- when it starts -- what conditions block/interrupt it -- when it is complete - -## When not to use commands - -If logic is a single immediate line and never reused, direct method calls can be clearer. - -**Related:** [TeleOp Architecture](../teleop/00-teleop-architecture.md) - ---- - -**Next:** [Command Sequences](01-command-sequences.md) diff --git a/commands/01-command-sequences.md b/commands/01-command-sequences.md index f7e5abd..e69de29 100644 --- a/commands/01-command-sequences.md +++ b/commands/01-command-sequences.md @@ -1,41 +0,0 @@ -# Command Sequences - -## Objective - -Chain mechanism actions safely without scattering timing logic across TeleOp/auton. - -## Sequencing example - -A common scoring sequence: -1. stop intake -2. raise transfer platform -3. wait for mechanism settle -4. close claw -5. move slides/arm to scoring target - -This becomes one trigger instead of many manual button presses. - -## Interruption behavior - -Design for interruptions: -- What happens if driver cancels mid-sequence? -- Can robot safely return to intake state? -- Which mechanisms must stop immediately? - -## Timeouts and guards - -Never trust timing alone for important transitions. -Prefer sensor/position checks when possible, with timeout fallback. - -## Integration with state machines - -State machines decide *which* sequence to run. -Command sequences define *how* each transition executes. - -Use both together for clean architecture. - -**Related:** [TeleOp Architecture - State Machine Pattern](../teleop/00-teleop-architecture.md#state-machine-pattern) - ---- - -**Next:** [Common Command Bugs](02-common-bugs.md) diff --git a/commands/02-common-bugs.md b/commands/02-common-bugs.md index 16ae718..e69de29 100644 --- a/commands/02-common-bugs.md +++ b/commands/02-common-bugs.md @@ -1,38 +0,0 @@ -# Common Command Bugs - -## Trigger spam - -Repeated trigger calls can restart a sequence every loop. - -Fix: gate triggers using click/edge detection or explicit `isBusy` checks. - -## Conflicting commands - -Two sequences controlling the same mechanism at once cause jitter or unsafe motion. - -Fix: enforce one owner per mechanism state transition. - -## Missing reset path - -A sequence reaches scoring posture but no reliable retract path exists. - -Fix: always pair each forward sequence with a tested reset/retract sequence. - -## Timing-only assumptions - -Delays that worked at full battery may fail at low voltage. - -Fix: combine delays with sensor/position checks. - -## Debug strategy - -When command behavior is wrong: -1. log sequence start and finish -2. log key state variable transitions -3. test sequence in a dev opmode before full TeleOp/auton - -**Related:** [Dev OpModes](../misc/00-dev-opmodes.md) - ---- - -**Next:** [Autonomous Track](../auton/README.md) diff --git a/electronics/00-electronics-intro.md b/electronics/00-electronics-intro.md index 3b08ab9..e69de29 100644 --- a/electronics/00-electronics-intro.md +++ b/electronics/00-electronics-intro.md @@ -1,32 +0,0 @@ -# Electronics Intro for Software Members - -## Goal - -Give software members enough electronics understanding to debug reliably and communicate with hardware teammates. - -## Core concepts - -- Control Hub and Expansion Hub roles -- motor and servo ports -- encoder feedback basics -- sensor wiring basics -- battery and power distribution - -## Why this matters for software - -Many "software bugs" are actually wiring, port, or configuration issues. - -If you understand the electrical basics, you debug faster and write safer assumptions in code. - -**Learn more:** [Game Manual 0 - Electronics Basics](https://gm0.org/en/latest/docs/common/electronics.html) - ---- - -**Next:** [Control Hub and Wiring Checks](01-control-hub-and-wiring-checks.md) - -## What to learn next - -1. Hardware map naming and port mapping -2. Motor direction/encoder checks -3. Sensor validation using telemetry -4. Power-related failure patterns diff --git a/electronics/01-control-hub-and-wiring-checks.md b/electronics/01-control-hub-and-wiring-checks.md index 5531626..e69de29 100644 --- a/electronics/01-control-hub-and-wiring-checks.md +++ b/electronics/01-control-hub-and-wiring-checks.md @@ -1,34 +0,0 @@ -# Control Hub and Wiring Checks - -## Pre-code hardware sanity check - -Before debugging code, verify: -- battery is healthy and connected correctly -- hub is powered and visible -- expected motors/servos/sensors are plugged into correct ports -- cables are seated and not damaged - -## Fast motor/servo checks - -- test one actuator at a time in a dev opmode -- confirm direction matches code assumptions -- confirm no binding before raising power - -## Sensor checks - -For each sensor used in logic transitions: -- display raw values in telemetry -- validate value range in real robot conditions -- test failure behavior (sensor unplugged/noisy) - -## Common electrical causes of software symptoms - -- loose cable -> intermittent state transitions -- wrong port -> mechanism appears dead -- low battery -> unstable auton timing and movement - -**Learn more:** [Game Manual 0 - Control Hub](https://gm0.org/en/latest/docs/common/control-hub.html) - ---- - -**Next:** [Troubleshooting Playbook](02-troubleshooting-playbook.md) diff --git a/electronics/02-troubleshooting-playbook.md b/electronics/02-troubleshooting-playbook.md index 3b1c575..e69de29 100644 --- a/electronics/02-troubleshooting-playbook.md +++ b/electronics/02-troubleshooting-playbook.md @@ -1,40 +0,0 @@ -# Electronics Troubleshooting Playbook - -## Priority order - -1. Safety first (disable power if behavior is unsafe) -2. Confirm mechanical freedom (no jams) -3. Confirm wiring and configuration -4. Then inspect software assumptions - -## Symptom-driven checks - -### Motor not moving -- hardware map name correct? -- correct port? -- mode/power set in code? -- motor direction reversed unexpectedly? - -### Servo jittering -- conflicting code paths setting position? -- unstable power or loose cable? -- invalid position spam in loop? - -### Sensor-triggered logic unreliable -- threshold too tight? -- noisy/unfiltered data? -- sensor physically misaligned? - -## Team handoff practice - -When escalating to another subteam member, provide: -- symptom and when it happens -- telemetry evidence -- what you already tested -- current hypothesis - -**Related:** [Auton - Real-World Failure Modes](../auton/07-real-world-failure-modes.md) - ---- - -**Next:** [Back to Curriculum Overview](../README.md) diff --git a/ftcdashboard/00-intro.md b/ftcdashboard/00-intro.md index 5146d3d..e69de29 100644 --- a/ftcdashboard/00-intro.md +++ b/ftcdashboard/00-intro.md @@ -1,24 +0,0 @@ -# FTC Dashboard Intro - -## What it is - -FTC Dashboard is a browser-based tool for robot telemetry, graphs, and field visualization. - -## Common team use cases - -- tune mechanism constants (`@Config` classes) -- inspect sensor values in real time -- inspect autonomous pose/path behavior -- debug state machine transitions - -## Safety and competition notes - -- Do not rely on dashboard as your only debugging tool during matches. -- Keep telemetry lightweight enough for stable loop performance. -- Treat any runtime config edits carefully and document what changed. - -**Learn more:** [Game Manual 0 - Debugging](https://gm0.org/en/latest/docs/software/lessons/tuning-and-debugging.html) - ---- - -**Next:** [Connection Troubleshooting](01-connection-troubleshooting.md) diff --git a/ftcdashboard/01-connection-troubleshooting.md b/ftcdashboard/01-connection-troubleshooting.md index 073d935..e69de29 100644 --- a/ftcdashboard/01-connection-troubleshooting.md +++ b/ftcdashboard/01-connection-troubleshooting.md @@ -1,28 +0,0 @@ -# FTC Dashboard Connection Troubleshooting - -## Quick checklist - -1. Connect laptop to robot network -2. Confirm robot app is running -3. Open dashboard URL in browser -4. Verify opmode is actually sending telemetry each loop - -## Common issues - -- **Wrong IP/URL**: use the Control Hub address for your setup. -- **No telemetry data**: telemetry not updated in loop. -- **Connected but stale values**: opmode not running or app needs redeploy. -- **ADB confusion**: disconnect stale sessions and reconnect cleanly. - -## Fast diagnosis flow - -1. Test network reachability -2. Restart robot app/opmode -3. Rebuild and redeploy if needed -4. Check logcat for runtime exceptions - -**Related:** [Electronics - Control Hub Checks](../electronics/01-control-hub-checks.md) - ---- - -**Next:** [Telemetry Patterns](02-telemetry-patterns.md) diff --git a/ftcdashboard/02-telemetry-patterns.md b/ftcdashboard/02-telemetry-patterns.md index 1469c90..e69de29 100644 --- a/ftcdashboard/02-telemetry-patterns.md +++ b/ftcdashboard/02-telemetry-patterns.md @@ -1,35 +0,0 @@ -# Telemetry Patterns - -## High-value telemetry fields - -For TeleOp: -- state machine state -- mechanism targets vs actual -- key sensor flags used in transitions - -For Auton: -- current path/segment -- pose (`x`, `y`, `heading`) -- follower busy/completion state - -## Organization pattern - -Group telemetry by subsystem. Example sections: -- `Drive` -- `Scoring` -- `Intake` -- `Auton` - -This makes debugging faster under time pressure. - -## Noise control - -- avoid printing every internal variable -- prefer stable, decision-relevant values -- remove temporary spam logs after fixing bugs - -**Related:** [Misc - Telemetry Best Practices](../misc/01-telemetry-best-practices.md) - ---- - -**Next:** [Misc Track](../misc/README.md) diff --git a/intro/02-git-workflow.md b/intro/02-git-workflow.md index fda7a5e..e69de29 100644 --- a/intro/02-git-workflow.md +++ b/intro/02-git-workflow.md @@ -1,66 +0,0 @@ -# Git Workflow for FTC - -## Why Git matters - -Git protects the team from losing work and makes collaboration safer. Even if only one or two people are editing code, version history is still useful for rollback and debugging. - -## Recommended default workflow - -This team often works directly on `main` when the contributor count is low. That is acceptable for small changes, but you should still commit in small, meaningful chunks. - -If many people are working at once, use short-lived branches. - -## Daily routine - -1. Pull latest changes: `git pull` -2. Make one focused change (for example: one mechanism fix) -3. Run a local build -4. Commit with a clear message -5. Push: `git push` - -If using branches: -1. `git checkout -b ` -2. Work and commit -3. Push and open a PR -4. Merge after review - -## Commit message guidelines - -Good commit messages are short and specific. - -Examples: -- `fix intake servo direction` -- `add telemetry for slides target` -- `refactor scoring state transitions` - -Avoid: -- `stuff` -- `changes` -- `final` - -## Merge conflict basics - -If a pull or merge causes conflicts: -1. Read both versions carefully -2. Keep the correct behavior, not just whichever is newer -3. Rebuild and test before committing the resolution - -Never guess through conflicts in autonomous or safety-critical code. - -## Mistakes to avoid - -- Huge commits touching unrelated features -- Committing generated/build files -- Force-pushing shared history without team agreement -- Skipping build checks before pushing - -## Mini exercise - -1. Pick one mechanism constant (for example a servo position) -2. Change it in code -3. Commit with a clear message -4. Push and ask another member to review the change - ---- - -**Next:** [Android Studio Workflow](03-android-studio-workflow.md) diff --git a/intro/03-android-studio-workflow.md b/intro/03-android-studio-workflow.md index 066d81b..e69de29 100644 --- a/intro/03-android-studio-workflow.md +++ b/intro/03-android-studio-workflow.md @@ -1,53 +0,0 @@ -# Android Studio Workflow - -## Goal - -Learn the Android Studio actions you will use every practice day. - -## Navigation essentials - -- Use the Project pane to find `TeamCode` and your `teamcode` package. -- Use `Shift` twice to search classes/files quickly. -- Use `Command + B` on a symbol to jump to definition. - -## Build and sync cycle - -You will repeat this loop constantly: -1. Edit code -2. Sync if prompted by Gradle changes -3. Build (`Build > Make Project`) -4. Fix compile errors immediately - -## Running OpModes - -Typical process: -1. Connect to robot network -2. Build and deploy from Android Studio -3. Open Driver Station / RC app -4. Select opmode and test - -## Logcat and debugging - -Use Logcat when telemetry is not enough. -- Filter by your package name -- Search for stack traces and `NullPointerException` -- Add temporary logs while debugging, then remove noisy ones - -## Common failure patterns - -- **Gradle sync issues**: retry sync, check internet and SDK manager -- **Device not detected**: check cable/network/ADB state -- **App won’t install**: uninstall old app versions and rebuild -- **Red code everywhere**: wait for indexing, then sync + rebuild - -## Recovery checklist when everything breaks - -1. Save work -2. `File > Sync Project with Gradle Files` -3. Rebuild -4. Invalidate caches only if problems persist -5. Ask a teammate before making large environment changes - ---- - -**Next:** [Codebase Overview](../codebase/README.md) diff --git a/misc/00-dev-opmodes.md b/misc/00-dev-opmodes.md index 4970192..e69de29 100644 --- a/misc/00-dev-opmodes.md +++ b/misc/00-dev-opmodes.md @@ -1,35 +0,0 @@ -# Dev OpModes - -## Purpose - -Dev opmodes are isolated test programs for one subsystem or behavior. - -They reduce risk by letting you test changes before touching main TeleOp or auton. - -## Naming and organization - -Use consistent names like: -- `IntakeDev` -- `SlidesDev` -- `DriveDev` - -Keep them in a dedicated dev folder/package. - -## Safety rules - -- start with low power/speed settings -- test one subsystem at a time -- include an obvious stop/reset path - -## Promotion to production - -A change should move from dev to main code only after: -1. repeated successful tests -2. no regressions in related subsystems -3. clear understanding of new constants/assumptions - -**Related:** [Commands Track](../commands/README.md) - Similar isolation principle for complex sequences - ---- - -**Next:** [Telemetry Best Practices](01-telemetry-best-practices.md) diff --git a/misc/01-telemetry-best-practices.md b/misc/01-telemetry-best-practices.md index e050758..e69de29 100644 --- a/misc/01-telemetry-best-practices.md +++ b/misc/01-telemetry-best-practices.md @@ -1,28 +0,0 @@ -# Telemetry Best Practices - -## Driver station telemetry - -During matches, telemetry should answer: -- what state are we in? -- why did (or didn't) we transition? -- are key mechanisms at target? - -## Debug mode vs match mode - -Keep two levels of verbosity: -- match mode: minimal, high-value lines -- debug mode: more detailed internals - -This prevents overload during driving while preserving deep debug capability. - -## Rate and readability - -- update regularly but avoid massive payloads -- use consistent labels -- include units when relevant (in, deg, ticks) - -**Related:** [FTC Dashboard Track](../ftcdashboard/02-telemetry-patterns.md) - ---- - -**Next:** [Hardware Map and Configuration](02-hardware-map-and-config.md) diff --git a/misc/02-hardware-map-and-config.md b/misc/02-hardware-map-and-config.md index 4bc8282..e69de29 100644 --- a/misc/02-hardware-map-and-config.md +++ b/misc/02-hardware-map-and-config.md @@ -1,29 +0,0 @@ -# Hardware Map and Configuration - -## Objective - -Keep hardware naming predictable so code and wiring stay aligned. - -## Naming guidelines - -- use descriptive camelCase names -- include side/function (`leftSlide`, `clawServo`) -- avoid ambiguous names (`motor1`, `servo2`) - -## Configuration hygiene - -- keep one agreed robot configuration file per active robot -- document any port remaps immediately -- verify names after hardware swaps/repairs - -## Cross-robot consistency - -If multiple robots exist (practice/comp), either: -- keep matching hardware map names, or -- keep explicit configuration profiles and clearly document differences - -**Related:** [Electronics Track](../electronics/01-control-hub-checks.md) - ---- - -**Next:** [AI Usage Guidelines](03-ai-usage-guidelines.md) diff --git a/misc/03-ai-usage-guidelines.md b/misc/03-ai-usage-guidelines.md index 2af5af9..e69de29 100644 --- a/misc/03-ai-usage-guidelines.md +++ b/misc/03-ai-usage-guidelines.md @@ -1,30 +0,0 @@ -# AI Usage Guidelines - -## Where AI helps - -- drafting boilerplate classes -- suggesting refactors -- explaining compile/runtime errors -- generating test checklists - -## Where AI can hurt - -- copying code blindly without understanding it -- introducing unsafe mechanism behavior -- mismatching team architecture/conventions - -## Verification checklist - -Before merging AI-assisted code: -1. can you explain what each changed line does? -2. does it match team structure/style? -3. does it build and run safely on robot? -4. was it tested in a dev opmode first? - -## Team expectations - -AI is a helper, not an authority. Human review and robot testing decide what ships. - ---- - -**Next:** [Electronics Track](../electronics/README.md) diff --git a/teleop/00-teleop-architecture.md b/teleop/00-teleop-architecture.md index 72089f1..e69de29 100644 --- a/teleop/00-teleop-architecture.md +++ b/teleop/00-teleop-architecture.md @@ -1,45 +0,0 @@ -# TeleOp Architecture - -## Goal - -Build a TeleOp that is fast for drivers, readable for developers, and stable under match pressure. - -## Recommended loop shape - -1. Read inputs -2. Update high-level state (scoring modes, toggles) -3. Update mechanisms -4. Publish telemetry - -Keeping this order consistent makes bugs easier to isolate. - -## State machine pattern - -Use explicit states when controls depend on context, for example: -- `INTAKE` -- `TRANSFER` -- `SCORING` - -A state machine helps one button do different actions safely in different phases. - -## Input handling model - -Treat button types differently: -- **hold**: action runs while held -- **click/tap**: action happens once on rising edge -- **toggle**: press alternates between modes - -## Telemetry priorities - -During matches, prefer high-value telemetry: -- current state -- mechanism targets vs current values -- sensor values used for critical transitions - -Avoid dumping large debug output every loop in competition TeleOp. - -**Learn more:** [Telemetry Best Practices](../misc/01-telemetry-best-practices.md) - ---- - -**Next:** [Controls and Input Mapping](01-controls-and-input.md) diff --git a/teleop/01-controls-and-input.md b/teleop/01-controls-and-input.md index 272f6d2..e69de29 100644 --- a/teleop/01-controls-and-input.md +++ b/teleop/01-controls-and-input.md @@ -1,49 +0,0 @@ -# Controls and Input Mapping - -## Objective - -Create control mappings that are easy to learn and hard to misuse. - -## Controller naming convention - -FTC SDK and many helper classes use Xbox-style button names (`A`, `B`, `X`, `Y`). - -If your team uses PlayStation controllers, add comments for equivalents where helpful. Example: - -```java -if (GamepadStatic.isButtonPressed(gamepad, Input.A)) { // PS Cross - claw.open(); -} -``` - -Do not hard-code docs to one physical controller style. - -## Mapping strategy - -- Put critical actions on easy-to-reach buttons -- Separate driver and operator responsibilities -- Keep emergency/manual override accessible - -## Edge detection vs hold - -Use edge detection for one-time actions (toggle, sequence trigger). -Use hold logic for continuous actions (manual slide movement). - -## Conflict prevention - -Before each event: -- list actions that can run in parallel -- list actions that must be mutually exclusive -- enforce exclusivity with state checks - -## Simple control map template - -- Driver: drivetrain, heading reset, slow mode -- Operator: intake, transfer, scoring, reset -- Shared: emergency stop/manual recovery - -**Next step:** Use commands to simplify complex scoring transitions. - ---- - -**Next:** [Commands Track](../commands/README.md) From 7194ed60655b26d80545c195b7136592fa5d7451 Mon Sep 17 00:00:00 2001 From: Flint Mueller Date: Sat, 23 May 2026 14:14:48 -0400 Subject: [PATCH 6/8] git-overview --- STYLE.md | 3 ++ intro/02-git-workflow.md | 70 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 73 insertions(+) diff --git a/STYLE.md b/STYLE.md index 0f81261..263e3b5 100644 --- a/STYLE.md +++ b/STYLE.md @@ -6,3 +6,6 @@ don't use technical language off the bat, slowly introduce it with full sentence 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 diff --git a/intro/02-git-workflow.md b/intro/02-git-workflow.md index e69de29..9b0ab58 100644 --- a/intro/02-git-workflow.md +++ 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. From 282c261b3068e36f391831bd5119adb010a6dcbf Mon Sep 17 00:00:00 2001 From: Flint Mueller Date: Sat, 23 May 2026 14:42:09 -0400 Subject: [PATCH 7/8] android studio --- intro/03-android-studio-workflow.md | 39 +++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/intro/03-android-studio-workflow.md b/intro/03-android-studio-workflow.md index e69de29..dbf72f4 100644 --- a/intro/03-android-studio-workflow.md +++ 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. From 321397bdb9c792058d7bf08c24877c907a0e7fbc Mon Sep 17 00:00:00 2001 From: Flint Mueller Date: Sat, 23 May 2026 14:54:05 -0400 Subject: [PATCH 8/8] mech design --- STYLE.md | 1 + codebase/mechanisms/02-mechanism-design.md | 34 ++++++++++++++++++++++ 2 files changed, 35 insertions(+) diff --git a/STYLE.md b/STYLE.md index 263e3b5..8c6a305 100644 --- a/STYLE.md +++ b/STYLE.md @@ -9,3 +9,4 @@ remember the audience: these people will want to read the docs in order and if t 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/codebase/mechanisms/02-mechanism-design.md b/codebase/mechanisms/02-mechanism-design.md index e69de29..3895994 100644 --- a/codebase/mechanisms/02-mechanism-design.md +++ 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.