From cf2eb1974b73eecb2561b84c2a7c3cd22a264f90 Mon Sep 17 00:00:00 2001 From: Zach Harel Date: Fri, 21 Aug 2026 15:52:36 -0400 Subject: [PATCH 1/3] remove prettier plugin sentences-per-line --- .prettierrc | 2 +- package.json | 1 - pnpm-lock.yaml | 19 ------------------- 3 files changed, 1 insertion(+), 21 deletions(-) diff --git a/.prettierrc b/.prettierrc index 8556e263..b6cd4aa5 100644 --- a/.prettierrc +++ b/.prettierrc @@ -3,7 +3,7 @@ "singleQuote": true, "trailingComma": "all", "tabWidth": 4, - "plugins": ["prettier-plugin-astro", "prettier-plugin-sentences-per-line"], + "plugins": ["prettier-plugin-astro"], "overrides": [ { "files": "*.astro", diff --git a/package.json b/package.json index b561e642..5df77e26 100644 --- a/package.json +++ b/package.json @@ -56,7 +56,6 @@ "mdx2vast": "^0.3.1", "prettier": "^3.8.4", "prettier-plugin-astro": "^0.14.1", - "prettier-plugin-sentences-per-line": "^0.2.3", "remark-cli": "^12.0.1", "remark-frontmatter": "^5.0.0", "remark-lint-no-dead-urls": "^2.0.1", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 0bd58001..1cab038d 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -84,9 +84,6 @@ importers: prettier-plugin-astro: specifier: ^0.14.1 version: 0.14.1 - prettier-plugin-sentences-per-line: - specifier: ^0.2.3 - version: 0.2.3(prettier@3.8.4) remark-cli: specifier: ^12.0.1 version: 12.0.1 @@ -3015,11 +3012,6 @@ packages: resolution: {integrity: sha512-RiBETaaP9veVstE4vUwSIcdATj6dKmXljouXc/DDNwBSPTp8FRkLGDSGFClKsAFeeg+13SB0Z1JZvbD76bigJw==} engines: {node: ^14.15.0 || >=16.0.0} - prettier-plugin-sentences-per-line@0.2.3: - resolution: {integrity: sha512-zuzFfs97g9xo0wE4hX/RbAaTWrbW0NgqiPXcW7LR4mzQInCHLuTx8W/t6S1IqHSwegHoxHIgJSKBq02AH7IQJw==} - peerDependencies: - prettier: ^3 - prettier@3.8.4: resolution: {integrity: sha512-N2MylSdi48+5N/6S5j+maeHbUSIzzZ5uOcX5Hm4QpV8Dkb1HFjfAKTKX6yNPJQD9AhcT3ifHNB66tWTTJDi11Q==} engines: {node: '>=14'} @@ -3336,10 +3328,6 @@ packages: engines: {node: '>=10'} hasBin: true - sentences-per-line@0.5.2: - resolution: {integrity: sha512-Ch7cTyoP+nEo5+iZozSAeJ4c8R3jglpFwQMoQ98dn7wOa0QhXJjgO1wrjZgQJahSDB30BXfJ2PEBrlfhx8vK8A==} - engines: {node: '>=22.14.0'} - sharp@0.34.5: resolution: {integrity: sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} @@ -7681,11 +7669,6 @@ snapshots: prettier: 3.8.4 sass-formatter: 0.7.9 - prettier-plugin-sentences-per-line@0.2.3(prettier@3.8.4): - dependencies: - prettier: 3.8.4 - sentences-per-line: 0.5.2 - prettier@3.8.4: {} prismjs@1.30.0: {} @@ -8250,8 +8233,6 @@ snapshots: semver@7.7.4: {} - sentences-per-line@0.5.2: {} - sharp@0.34.5: dependencies: '@img/colour': 1.1.0 From ea7932b2ad0dcc129f5c1bdaae685026c9072346 Mon Sep 17 00:00:00 2001 From: Zach Harel Date: Fri, 21 Aug 2026 15:56:50 -0400 Subject: [PATCH 2/3] curse you glossary the platypus --- src/content/docs/resources/glossary.mdx | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/src/content/docs/resources/glossary.mdx b/src/content/docs/resources/glossary.mdx index b0be56dd..cdee8f65 100644 --- a/src/content/docs/resources/glossary.mdx +++ b/src/content/docs/resources/glossary.mdx @@ -14,13 +14,11 @@ Continuous Integration: A software development practice where developers frequen **GitHub** -GitHub is like Google Drive, but for code. -It hosts git repositories and allows for improved collaboration on projects through pull requests and issues +GitHub is like Google Drive, but for code. It hosts git repositories and allows for improved collaboration on projects through pull requests and issues **Limit Switch** -Type of sensor that triggers when physically or magnetically hit. -Can be used to trigger actions on a rising or falling edge, or check state of a mechanism +Type of sensor that triggers when physically or magnetically hit. Can be used to trigger actions on a rising or falling edge, or check state of a mechanism **Magnetic Encoder** @@ -40,8 +38,7 @@ Pulse Width Modulation: A communication spec used to communicate with motor cont **Repository** -A storage location for software packages, often used in version control systems like Git. -Repositories are just folders that contain files and subfolders, and they can be hosted on platforms like GitHub to facilitate collaboration and version tracking +A storage location for software packages, often used in version control systems like Git. Repositories are just folders that contain files and subfolders, and they can be hosted on platforms like GitHub to facilitate collaboration and version tracking **Spark MAX** From 2fbe983821cda895894a449e41521715d3c52c79 Mon Sep 17 00:00:00 2001 From: Zach Harel Date: Fri, 21 Aug 2026 16:08:12 -0400 Subject: [PATCH 3/3] also we are now limiting lines to 120 characters --- .prettierrc | 3 +- src/content/docs/best-practices/ci-checks.mdx | 30 +- .../docs/best-practices/code-formatter.mdx | 5 +- src/content/docs/best-practices/git-usage.mdx | 62 ++-- .../docs/best-practices/github-usage.mdx | 48 +-- src/content/docs/contribution/index.mdx | 15 +- .../contribution/methodsOfContributing.mdx | 30 +- src/content/docs/contribution/roadmap.mdx | 4 +- src/content/docs/contribution/styleguide.mdx | 102 +++--- .../educators-guide/introduction/index.mdx | 80 +++-- .../introduction/preparation.mdx | 31 +- .../introduction/the-stages.mdx | 13 +- .../getting-started/forking-and-cloning.mdx | 18 +- .../getting-started/required-tools.mdx | 48 +-- .../getting-started/vscode-overview.mdx | 45 +-- .../getting-started/website-feature-guide.mdx | 21 +- src/content/docs/learning-course/index.mdx | 68 ++-- .../stage0/classes-methods.mdx | 292 ++++++++---------- .../learning-course/stage0/conditionals.mdx | 150 ++++----- .../stage0/java-fundamentals.mdx | 112 +++---- .../docs/learning-course/stage0/operators.mdx | 127 ++++---- .../learning-course/stage0/stage-overview.mdx | 8 +- .../learning-course/stage1/stage-overview.mdx | 20 +- .../stage1/stage1a/drivetrain-sim.mdx | 103 +++--- .../stage1/stage1a/kitbot-drivetrain.mdx | 191 ++++++------ .../stage1/stage1a/stage-overview.mdx | 89 +++--- .../stage1b/command-based-kitbot-pt2.mdx | 66 ++-- .../stage1/stage1b/command-based-kitbot.mdx | 86 +++--- .../stage1/stage1b/command-based-overview.mdx | 58 ++-- .../stage1b/commands-and-mechanisms-pt2.mdx | 35 +-- .../stage1b/commands-and-mechanisms.mdx | 60 ++-- .../stage1/stage1b/spot-the-error-pt2.mdx | 3 +- .../stage1/stage1b/spot-the-error.mdx | 29 +- .../stage1/stage1b/stage-overview.mdx | 14 +- .../stage1b/suppliers-in-command-based.mdx | 50 ++- .../stage1/stage1b/the-command-body.mdx | 35 +-- .../stage1/stage1b/triggers.mdx | 48 ++- src/content/docs/resources/glossary.mdx | 22 +- src/content/docs/test-content-figure.mdx | 31 +- 39 files changed, 1036 insertions(+), 1216 deletions(-) diff --git a/.prettierrc b/.prettierrc index b6cd4aa5..7de17678 100644 --- a/.prettierrc +++ b/.prettierrc @@ -14,7 +14,8 @@ { "files": "*.mdx", "options": { - "proseWrap": "preserve" + "printWidth": 120, + "proseWrap": "always" } } ] diff --git a/src/content/docs/best-practices/ci-checks.mdx b/src/content/docs/best-practices/ci-checks.mdx index 863b6748..cb2c960c 100644 --- a/src/content/docs/best-practices/ci-checks.mdx +++ b/src/content/docs/best-practices/ci-checks.mdx @@ -8,10 +8,11 @@ codeRegionSources: format: best-practices/ci-checks/format.yml --- -Continuous Integration (CI) is a software development practice where developers frequently merge code changes into a shared repository, triggering automated builds and tests to ensures the codebase remains stable. -CI checks are automated tests that run when code is pushed or a pull request is opened. -They help ensure that your code builds, meets programming standards, and is formatted correctly before merging. -You can create CI checks using [GitHub Actions](https://docs.github.com/en/actions/get-started/continuous-integration). +Continuous Integration (CI) is a software development practice where developers frequently merge code changes into a +shared repository, triggering automated builds and tests to ensures the codebase remains stable. CI checks are automated +tests that run when code is pushed or a pull request is opened. They help ensure that your code builds, meets +programming standards, and is formatted correctly before merging. You can create CI checks using +[GitHub Actions](https://docs.github.com/en/actions/get-started/continuous-integration). -In GitHub on your fork of the repository, use the "sync" button to easily rebase your branch onto the primary frcsoftware.org repository to keep up to date with any changes that have been made since you started your branch +In GitHub on your fork of the repository, use the "sync" button to easily rebase your branch onto the primary +frcsoftware.org repository to keep up to date with any changes that have been made since you started your branch -5. Once you've completed your changes, check that you've committed everything, that your branch is up to date with main, and that everything has been pushed. - Then, create a pull request on GitHub, from your branch to the main branch of the frcsoftware.org repository. +5. Once you've completed your changes, check that you've committed everything, that your branch is up to date with main, + and that everything has been pushed. Then, create a pull request on GitHub, from your branch to the main branch of + the frcsoftware.org repository. -To recap the contribution steps, do the combination of creating and publishing a branch, making changes and commits, updating from main, pushing commits, and creating a pull request. +To recap the contribution steps, do the combination of creating and publishing a branch, making changes and commits, +updating from main, pushing commits, and creating a pull request. ### How to Get The Local Preview of the Website Running diff --git a/src/content/docs/contribution/roadmap.mdx b/src/content/docs/contribution/roadmap.mdx index 2ae51650..ed42fe2d 100644 --- a/src/content/docs/contribution/roadmap.mdx +++ b/src/content/docs/contribution/roadmap.mdx @@ -9,6 +9,4 @@ next: false The roadmap is a work in progress, and can be found on the GitHub project. - - Check out the GitHub project - +Check out the GitHub project diff --git a/src/content/docs/contribution/styleguide.mdx b/src/content/docs/contribution/styleguide.mdx index e30f3ecc..5a2ca9b3 100644 --- a/src/content/docs/contribution/styleguide.mdx +++ b/src/content/docs/contribution/styleguide.mdx @@ -10,30 +10,36 @@ import Aside from '../../../components/Aside.astro'; ## Futureproofing and Usefulness -To make the content you write useful for teams of all resource levels, while maintaining validity in the future, the goal isn't to go broad and shallow, but rather to go extra deep so you can equip students with the understanding of the underlying fundamentals behind concepts which they can then apply to their own unique situations. -Pros and cons are context dependent while fundamentals are universal. +To make the content you write useful for teams of all resource levels, while maintaining validity in the future, the +goal isn't to go broad and shallow, but rather to go extra deep so you can equip students with the understanding of the +underlying fundamentals behind concepts which they can then apply to their own unique situations. Pros and cons are +context dependent while fundamentals are universal. -At the same time, things that aren't easily accessible and/or commonly used by teams, like state-space control or MPC, shouldn't be included to prevent confusion. +At the same time, things that aren't easily accessible and/or commonly used by teams, like state-space control or MPC, +shouldn't be included to prevent confusion. ### Why is this important? -1. We don't need to figure out the pros and cons of everything for students to make a decision. - Software is a space that can change very quickly, and equipping them with the skills to make a decision is more important than using a specific technique. +1. We don't need to figure out the pros and cons of everything for students to make a decision. Software is a space that + can change very quickly, and equipping them with the skills to make a decision is more important than using a + specific technique. -2. This enables students to understand WHY a team would make a certain decision and figure out tradeoffs without us explicitly telling them. +2. This enables students to understand WHY a team would make a certain decision and figure out tradeoffs without us + explicitly telling them. -3. It makes it significantly less intensive to future proof and maintain. - If the meta shifts, having to redo sections to stay competitive is time consuming. - If the project dies and is no longer maintained, the information stays useful for way longer. +3. It makes it significantly less intensive to future proof and maintain. If the meta shifts, having to redo sections to + stay competitive is time consuming. If the project dies and is no longer maintained, the information stays useful for + way longer. -4. The small details are often the experience gap between the most reliable successful robots and not. - It's a lifesaver for teams without experience, and reduces the review workload on software mentors with experience. +4. The small details are often the experience gap between the most reliable successful robots and not. It's a lifesaver + for teams without experience, and reduces the review workload on software mentors with experience. ## Inspired by gm0's Style Guide @@ -43,25 +49,32 @@ Don't deal in absolutes. - Use pros/cons lists to compare options - Explain WHY something is good or bad - For example, we all know that splitting code into multiple files (but not too many) is better than one giant file. - But don't just say that it's better, say "Breaking up your code into separate files makes it easier to read and isolates independent sections of the robot code from one another, making it easier to maintain." - - Similarly, this course uses a command-based architecture because its authors believe that it's generally the best option for teams. - However, many teams are successful with different structures, such as ones based around non-command state machines, ROS setups, or even just smart usage of if statements and logic inside a periodic function. - Instead of saying "Use commands because they make it easier to program your robot," say that "The commands library is a good choice for programming your robot as it ensures that no two actions can conflict with each other by only allowing each mechanism to be used by one action/command at a time, while also providing a strong framework to build autonomous sequences and integrate automation." -- Still emphasize that teams are free to explore and innovate, but help set realistic expectations (see the following point) + But don't just say that it's better, say "Breaking up your code into separate files makes it easier to read and + isolates independent sections of the robot code from one another, making it easier to maintain." + - Similarly, this course uses a command-based architecture because its authors believe that it's generally the best + option for teams. However, many teams are successful with different structures, such as ones based around + non-command state machines, ROS setups, or even just smart usage of if statements and logic inside a periodic + function. Instead of saying "Use commands because they make it easier to program your robot," say that "The + commands library is a good choice for programming your robot as it ensures that no two actions can conflict with + each other by only allowing each mechanism to be used by one action/command at a time, while also providing a + strong framework to build autonomous sequences and integrate automation." +- Still emphasize that teams are free to explore and innovate, but help set realistic expectations (see the following + point) FRCSoftware.org is a guide **from a competitive standpoint**. -- Try to leave out stuff that doesn't work well or is too complex compared to the rest of this course. - For example, MPC or state space control can work very well, but requires a significant amount of controls and math knowledge that is far beyond what the rest of this course requires -- Try to leave opinions out as much as possible. - Do not speak authoritatively on stuff you do not have first-hand experience with whenever possible +- Try to leave out stuff that doesn't work well or is too complex compared to the rest of this course. For example, MPC + or state space control can work very well, but requires a significant amount of controls and math knowledge that is + far beyond what the rest of this course requires +- Try to leave opinions out as much as possible. Do not speak authoritatively on stuff you do not have first-hand + experience with whenever possible Keep in mind that FRC software trends are temporary and transient. -- Just because something is popular one season doesn't mean it's the end all be all. - There was a time when commands v1 was the most powerful framework available, but now we're on commands v3. - Currently, there are many teams using a RobotState.java file but there are also many not using it. - Think about why this could have such a split and how the changing and evolving frameworks, like commands v3, address this. +- Just because something is popular one season doesn't mean it's the end all be all. There was a time when commands v1 + was the most powerful framework available, but now we're on commands v3. Currently, there are many teams using a + RobotState.java file but there are also many not using it. Think about why this could have such a split and how the + changing and evolving frameworks, like commands v3, address this. ## Standards @@ -82,8 +95,7 @@ Adhere to brand standards when possible. - This also applies to team names: spell them how they are officially spelled - Check [The Blue Alliance](https://www.thebluealliance.com/) if you don't know how to spell a team's name -You can use "you" when writing, when it makes writing less awkward. -However, try avoiding excessively using it. +You can use "you" when writing, when it makes writing less awkward. However, try avoiding excessively using it. ### Links: @@ -96,9 +108,8 @@ All content must pass the project's linting and formatting checks before merging #### Sentence-per-line -Every sentence in `.mdx` and `.md` files must be on its own line. -This ensures cleaner diffs and easier review. -Enforced by `prettier-plugin-sentences-per-line`. +Every sentence in `.mdx` and `.md` files must be on its own line. This ensures cleaner diffs and easier review. Enforced +by `prettier-plugin-sentences-per-line`. #### Running the checks @@ -121,18 +132,17 @@ If `pnpm format:check` fails, run `pnpm prettier --write .` to auto-fix. #### RLI (region-based code fences) -Code fences must use the RLI system: ` ```language path/to/file#regionName ` with an empty body. -The referenced file lives under `examples/` and uses `// [regionName]` / `// [/regionName]` markers to delimit the snippet. -This keeps example code in real source files that are compiled and tested. +Code fences must use the RLI system: ` ```language path/to/file#regionName ` with an empty body. The referenced file +lives under `examples/` and uses `// [regionName]` / `// [/regionName]` markers to delimit the snippet. This keeps +example code in real source files that are compiled and tested. -If you need an inline code fence that doesn't reference an example file, suppress the rule by placing `{/* rli:ignore */}` on the line immediately before it. +If you need an inline code fence that doesn't reference an example file, suppress the rule by placing +`{/* rli:ignore */}` on the line immediately before it. #### Code Region Source Aliases -Alternatively, you can define the filepaths for code region source files in -the frontmatter of a page to reduce verbosity. -The default source will be used -for code regions with no specified source; otherwise, you can specify sources +Alternatively, you can define the filepaths for code region source files in the frontmatter of a page to reduce +verbosity. The default source will be used for code regions with no specified source; otherwise, you can specify sources with the `{sourceName}` syntax. {/* rli:ignore */} @@ -160,9 +170,9 @@ This pulls from `CommandBasedKitbotPt2.java`: #### Code Block Tabs -Use Starlight's `Tabs` and `TabItem` components to show alternate versions of a code block, such as CTRE vs. -REV variants of the same code. -Import them from `@astrojs/starlight/components`, then wrap each variant's code fence in its own `TabItem`: +Use Starlight's `Tabs` and `TabItem` components to show alternate versions of a code block, such as CTRE vs. REV +variants of the same code. Import them from `@astrojs/starlight/components`, then wrap each variant's code fence in its +own `TabItem`: {/* rli:ignore */} @@ -184,9 +194,9 @@ import { TabItem, Tabs } from '@astrojs/starlight/components'; ```` -If multiple `Tabs` on the same page (or across different pages) should stay in sync when the reader switches -between CTRE and REV, give the `Tabs` component a `syncKey`. -Rather than inlining a raw string, define a shared constant in `src/data/tabsSyncKeys.ts` and import it: +If multiple `Tabs` on the same page (or across different pages) should stay in sync when the reader switches between +CTRE and REV, give the `Tabs` component a `syncKey`. Rather than inlining a raw string, define a shared constant in +`src/data/tabsSyncKeys.ts` and import it: {/* rli:ignore */} @@ -216,5 +226,5 @@ import { TabItem, Tabs } from '@astrojs/starlight/components'; ```` -This way, once a reader picks CTRE or REV in one set of tabs, every other synced `Tabs` block on the site -defaults to the same choice, instead of having to reselect it on every page. +This way, once a reader picks CTRE or REV in one set of tabs, every other synced `Tabs` block on the site defaults to +the same choice, instead of having to reselect it on every page. diff --git a/src/content/docs/educators-guide/introduction/index.mdx b/src/content/docs/educators-guide/introduction/index.mdx index 4525a27c..fc1f3114 100644 --- a/src/content/docs/educators-guide/introduction/index.mdx +++ b/src/content/docs/educators-guide/introduction/index.mdx @@ -3,57 +3,69 @@ title: Educator's Guide Overview description: A guide for educators implementing the FRCSoftware.org Learning Course --- -The FRCSoftware.org Learning Course is a self-paced, comprehensive program that teaches FRC robot programming and Java skills. -This guide is intended to help educators effectively implement the course while supporting their students throughout the learning process. -Designed for accessibility, the course requires minimal prior knowledge of programming, physics, or math, making it suitable for students from various backgrounds. -The emphasis is on building knowledge through consistent practice and review. +The FRCSoftware.org Learning Course is a self-paced, comprehensive program that teaches FRC robot programming and Java +skills. This guide is intended to help educators effectively implement the course while supporting their students +throughout the learning process. Designed for accessibility, the course requires minimal prior knowledge of programming, +physics, or math, making it suitable for students from various backgrounds. The emphasis is on building knowledge +through consistent practice and review. ## Course Usage -The course is built for self-paced learning, where students can progress at their own speed. -It utilizes code and robot simulation, a tool standard throughout FRC programming, to enable students to see their work and results quickly and not require a specific robot, or any robot access. -It can either be used by students to self-teach or used to help teach new students in a more classroom-esque setting. +The course is built for self-paced learning, where students can progress at their own speed. It utilizes code and robot +simulation, a tool standard throughout FRC programming, to enable students to see their work and results quickly and not +require a specific robot, or any robot access. It can either be used by students to self-teach or used to help teach new +students in a more classroom-esque setting. -The ideal setup is for educators to offload most of the curriculum (concepts, exercises, projects) to the website, freeing them up to give more individualized help and review to each student. -This is what may be called a “self-paced blended learning” approach, where preferably meeting time or class time is given for students to do the work at their own pace and for educators to review and catch mistakes as students are working through exercises and projects. +The ideal setup is for educators to offload most of the curriculum (concepts, exercises, projects) to the website, +freeing them up to give more individualized help and review to each student. This is what may be called a “self-paced +blended learning” approach, where preferably meeting time or class time is given for students to do the work at their +own pace and for educators to review and catch mistakes as students are working through exercises and projects. -This approach helps increase motivation and engagement, reduces gaps in knowledge, builds confidence, and helps make sure every student gets the support they need to learn. +This approach helps increase motivation and engagement, reduces gaps in knowledge, builds confidence, and helps make +sure every student gets the support they need to learn. ## Course Content -While the initial Java content is taught via general exercises, the majority of the course is focused on teaching FRC programming skills through FRC-relevant exercises, where new skills and concepts are introduced in each project. -Each section has a bit of explanation on the concepts or skills being introduced in the exercise, with the exercises gradually decreasing in guidance to help students get more confident with writing software. +While the initial Java content is taught via general exercises, the majority of the course is focused on teaching FRC +programming skills through FRC-relevant exercises, where new skills and concepts are introduced in each project. Each +section has a bit of explanation on the concepts or skills being introduced in the exercise, with the exercises +gradually decreasing in guidance to help students get more confident with writing software. -The progression of the course moves from learning how to write Java to programming robots of increasing complexity, starting with individual mechanisms of robots and moving to full robots. -Students will then learn how to write a robot program from the ground-up, thinking about code structure and how to best write their code for a balance between speed and maintainability. +The progression of the course moves from learning how to write Java to programming robots of increasing complexity, +starting with individual mechanisms of robots and moving to full robots. Students will then learn how to write a robot +program from the ground-up, thinking about code structure and how to best write their code for a balance between speed +and maintainability. -Additionally, there are various reference sections that don't fall on the main Learning Course. -These cover topics that are relevant to FRC programming, such as swerve or vision, but aren't necessarily the core concepts that need to be taught to allow a student to meaningfully contribute in-season. -Generally, these topics are something only a core group of students on a programming subteam would need to know, while the Learning Course focuses on the concepts every student will want to know to effectively contribute. +Additionally, there are various reference sections that don't fall on the main Learning Course. These cover topics that +are relevant to FRC programming, such as swerve or vision, but aren't necessarily the core concepts that need to be +taught to allow a student to meaningfully contribute in-season. Generally, these topics are something only a core group +of students on a programming subteam would need to know, while the Learning Course focuses on the concepts every student +will want to know to effectively contribute. -The purpose of software in FRC is to maximize the robot's capabilities in matches, working hand in hand with the robot's design and the team's strategy. -As such, this course places a focus on giving students the tools to write code efficiently and to maximize the use of time once the robot is complete. -This includes heavy utilization of simulation to develop and validate code, structuring code to be both quick to write and easy to make changes and maintain in-season, and giving students the tools to evaluate when certain control strategies may be necessary or whether a simpler, but easier, strategy is appropriate. +The purpose of software in FRC is to maximize the robot's capabilities in matches, working hand in hand with the robot's +design and the team's strategy. As such, this course places a focus on giving students the tools to write code +efficiently and to maximize the use of time once the robot is complete. This includes heavy utilization of simulation to +develop and validate code, structuring code to be both quick to write and easy to make changes and maintain in-season, +and giving students the tools to evaluate when certain control strategies may be necessary or whether a simpler, but +easier, strategy is appropriate. -There exist infinitely many ways to structure a robot project or control a mechanism, but this course gives what its writers believe to be the best balance of simplicity, maintainability, and capability. -As such, how your team wrote code in the past isn't necessarily incorrect, it's just not how this course will be teaching. -The concepts taught in this course should be applicable to most teams' code structure. +There exist infinitely many ways to structure a robot project or control a mechanism, but this course gives what its +writers believe to be the best balance of simplicity, maintainability, and capability. As such, how your team wrote code +in the past isn't necessarily incorrect, it's just not how this course will be teaching. The concepts taught in this +course should be applicable to most teams' code structure. diff --git a/src/content/docs/educators-guide/introduction/preparation.mdx b/src/content/docs/educators-guide/introduction/preparation.mdx index 5832d72d..1bdc42de 100644 --- a/src/content/docs/educators-guide/introduction/preparation.mdx +++ b/src/content/docs/educators-guide/introduction/preparation.mdx @@ -3,25 +3,28 @@ title: Preparation description: A guide for educators to prepare themselves to deliver the Learning Course to students. --- -Before using the FRCSoftware.org Learning Course to teach your students, make sure you have an adequate understanding of the concepts covered. -The best way to do this is to go through the course yourself; however, the level of involvement with which you do so is dependent on your previous knowledge. -If you're new to FRC programming or Java, we recommend going pretty deep through the course as much as you can, at least so you're ahead of the students you're helping guide. -If you're pretty experienced with Java and FRC programming, you might just go through the Educator's Guide to get a complete overview of the course and caught up to date with practice. +Before using the FRCSoftware.org Learning Course to teach your students, make sure you have an adequate understanding of +the concepts covered. The best way to do this is to go through the course yourself; however, the level of involvement +with which you do so is dependent on your previous knowledge. If you're new to FRC programming or Java, we recommend +going pretty deep through the course as much as you can, at least so you're ahead of the students you're helping guide. +If you're pretty experienced with Java and FRC programming, you might just go through the Educator's Guide to get a +complete overview of the course and caught up to date with practice. -In particular, familiarizing yourself with the development environment, tools, and git is going to be particularly helpful to ensure that your students can focus on the code itself. -Additionally, having such software on your own computer will allow you to demonstrate things for students without impacting their own code. +In particular, familiarizing yourself with the development environment, tools, and git is going to be particularly +helpful to ensure that your students can focus on the code itself. Additionally, having such software on your own +computer will allow you to demonstrate things for students without impacting their own code. ## Final Advice 1. Remember that it is okay for students to be at wildly different sections of the course. -2. Even if a student just gets through Stage 1, they would have enough knowledge to be somewhat helpful and easy to guide during build season. - The more sections they complete, the more autonomous they should be as a developer, making them easier to lead to complete a task. -3. When helping students, make sure to not handhold them too much. - If you're in a situation where you can get the student to solve a problem by asking some guiding questions, do that. +2. Even if a student just gets through Stage 1, they would have enough knowledge to be somewhat helpful and easy to + guide during build season. The more sections they complete, the more autonomous they should be as a developer, making + them easier to lead to complete a task. +3. When helping students, make sure to not handhold them too much. If you're in a situation where you can get the + student to solve a problem by asking some guiding questions, do that. diff --git a/src/content/docs/educators-guide/introduction/the-stages.mdx b/src/content/docs/educators-guide/introduction/the-stages.mdx index c752a9e6..326729e9 100644 --- a/src/content/docs/educators-guide/introduction/the-stages.mdx +++ b/src/content/docs/educators-guide/introduction/the-stages.mdx @@ -3,8 +3,9 @@ title: The Stages description: An explanation FRCSoftware.org Learning Course stages for educators --- -The course progressively builds complexity while reinforcing core concepts of good software development practices, controls fundamentals, and code organization. -It starts with basic code to control a 2026 kitbot and progresses through more complex robots and mechanisms. +The course progressively builds complexity while reinforcing core concepts of good software development practices, +controls fundamentals, and code organization. It starts with basic code to control a 2026 kitbot and progresses through +more complex robots and mechanisms. ## Stage Section Overview @@ -15,7 +16,8 @@ It starts with basic code to control a 2026 kitbot and progresses through more c **Stage 1a: Basic FRC Programming** -- Introduces students to many of the development tools which will be used throughout the course and for general FRC development +- Introduces students to many of the development tools which will be used throughout the course and for general FRC + development - Provides an overview of FRC electronics - Introduces students to the 2026 Kitbot, which will be utilized throughout Stage 1 - Teaches the basics of FRC motor controller and gamepad interaction @@ -38,5 +40,6 @@ It starts with basic code to control a 2026 kitbot and progresses through more c - Discusses various code structure and organization choices that will have to be made in any given robot project - Covers one technique to prevent mechanisms from colliding with the rest of the robot -Additionally, all stages will naturally include a significant amount of debugging experience as students write their code. -Debugging is a critical skill that all students should know as, inevitably, some code won't work as expected on the first try. +Additionally, all stages will naturally include a significant amount of debugging experience as students write their +code. Debugging is a critical skill that all students should know as, inevitably, some code won't work as expected on +the first try. diff --git a/src/content/docs/learning-course/getting-started/forking-and-cloning.mdx b/src/content/docs/learning-course/getting-started/forking-and-cloning.mdx index 98c66270..a9395a7c 100644 --- a/src/content/docs/learning-course/getting-started/forking-and-cloning.mdx +++ b/src/content/docs/learning-course/getting-started/forking-and-cloning.mdx @@ -9,19 +9,19 @@ import ContentFigure from '@components/ContentFigure.astro'; ## Forking -Before beginning, it's necessary to create your own fork of the relevant repository. -Before doing so, you need to have followed the instructions in the "Required Tools" section. -To fork, go to the repository you intend to copy (for example, https://github.com/frcsoftware/Stage1-Template-REV) and click the "Fork" button in the top right corner. -This will create a copy of the repository under your own GitHub account, allowing you to make changes without affecting the original repository. +Before beginning, it's necessary to create your own fork of the relevant repository. Before doing so, you need to have +followed the instructions in the "Required Tools" section. To fork, go to the repository you intend to copy (for +example, https://github.com/frcsoftware/Stage1-Template-REV) and click the "Fork" button in the top right corner. This +will create a copy of the repository under your own GitHub account, allowing you to make changes without affecting the +original repository. ## Cloning -To clone the repository you just created, open VS Code. -Then, copy the URL of the repository you just forked. -In VS Code, open the version control sidebar (top left), and select "Clone Repository". -Paste the URL of your forked repository and select a local directory where you want it to be located. -This will create a local copy of the repository on your machine, allowing you to work on the code. +To clone the repository you just created, open VS Code. Then, copy the URL of the repository you just forked. In VS +Code, open the version control sidebar (top left), and select "Clone Repository". Paste the URL of your forked +repository and select a local directory where you want it to be located. This will create a local copy of the repository +on your machine, allowing you to work on the code. diff --git a/src/content/docs/learning-course/getting-started/required-tools.mdx b/src/content/docs/learning-course/getting-started/required-tools.mdx index 9197edd8..5f733830 100644 --- a/src/content/docs/learning-course/getting-started/required-tools.mdx +++ b/src/content/docs/learning-course/getting-started/required-tools.mdx @@ -9,43 +9,43 @@ To program an FRC Robot and follow along with this website, you need WPILib tool ## WPILib tools -The first tool that needs to be installed is the WPILib tool package. -WPILib’s tool package includes a version of VSCode that allows teams to write code and deploy it to their robot. +The first tool that needs to be installed is the WPILib tool package. WPILib’s tool package includes a version of VSCode +that allows teams to write code and deploy it to their robot. -This website requires using the alpha release of WPILib for the 2027 season. -You can find the download link [here](https://github.com/wpilibsuite/allwpilib/releases). +This website requires using the alpha release of WPILib for the 2027 season. You can find the download link +[here](https://github.com/wpilibsuite/allwpilib/releases). -Once you have downloaded the 2027 WPILib tools, you can follow the instructions on how to set up the WPILib tools here [here](https://docs.wpilib.org/en/stable/docs/zero-to-robot/step-2/wpilib-setup.html). +Once you have downloaded the 2027 WPILib tools, you can follow the instructions on how to set up the WPILib tools here +[here](https://docs.wpilib.org/en/stable/docs/zero-to-robot/step-2/wpilib-setup.html). -The WPILib tool package also includes different programs that are useful for data logging, simulation, dashboards, and more. -We will use some of these tools in later stages. +The WPILib tool package also includes different programs that are useful for data logging, simulation, dashboards, and +more. We will use some of these tools in later stages. ### Driver Station -If you intend to control a physical robot, you may also need to install the game tools. -This installs the Driver Station, a program that connects to the robot for controlling it. -Instructions can be found [here](https://docs.wpilib.org/en/stable/docs/zero-to-robot/step-2/frc-game-tools.html), but this is not necessary to complete the course. +If you intend to control a physical robot, you may also need to install the game tools. This installs the Driver +Station, a program that connects to the robot for controlling it. Instructions can be found +[here](https://docs.wpilib.org/en/stable/docs/zero-to-robot/step-2/frc-game-tools.html), but this is not necessary to +complete the course. ## git -The next tool is Git. -Git is a version control system that is used in FRC because it allows teams to keep track of changes made to the robot’s code throughout -the build and competition season. -It can also help teams manage their robot code through the various features that GitHub has such as Pull Requests, Issues, and Project boards. -Git can be installed using the instructions located [here](https://git-scm.com/install/). +The next tool is Git. Git is a version control system that is used in FRC because it allows teams to keep track of +changes made to the robot’s code throughout the build and competition season. It can also help teams manage their robot +code through the various features that GitHub has such as Pull Requests, Issues, and Project boards. Git can be +installed using the instructions located [here](https://git-scm.com/install/). ## Creating a GitHub account -GitHub is a website that hosts Git repositories and allows people to collaborate on code. -It’s commonly used in FRC because it's free and easily accessible, in addition to being an industry standard. +GitHub is a website that hosts Git repositories and allows people to collaborate on code. It’s commonly used in FRC +because it's free and easily accessible, in addition to being an industry standard. -For many of the lessons on this website, it will be necessary to have a GitHub account. -One can be can be created [here](https://github.com/signup). -It's also recommended to sign up for the [GitHub student developer pack](https://education.github.com/pack), this will give you access to a variety of resources. +For many of the lessons on this website, it will be necessary to have a GitHub account. One can be can be created +[here](https://github.com/signup). It's also recommended to sign up for the +[GitHub student developer pack](https://education.github.com/pack), this will give you access to a variety of resources. diff --git a/src/content/docs/learning-course/getting-started/vscode-overview.mdx b/src/content/docs/learning-course/getting-started/vscode-overview.mdx index cf1b3ef9..d88f58fd 100644 --- a/src/content/docs/learning-course/getting-started/vscode-overview.mdx +++ b/src/content/docs/learning-course/getting-started/vscode-overview.mdx @@ -7,10 +7,11 @@ next: learning-course/learning-course/getting-started/forking-and-cloning ## What Is VS Code -Visual Studio Code (VS Code) is a free and open source code editor created by Microsoft. -It's available on Windows, macOS, and Linux and can support virtually every programming language through available extensions on its Extension Marketplace. -Some main features include IntelliSense which is a code completion tool and it allows for you to quickly look at documentation for a specific command. -It also has integrated Git support which lets you stage, commit, push, pull, and view diffs from the Source Control panel without leaving the editor. +Visual Studio Code (VS Code) is a free and open source code editor created by Microsoft. It's available on Windows, +macOS, and Linux and can support virtually every programming language through available extensions on its Extension +Marketplace. Some main features include IntelliSense which is a code completion tool and it allows for you to quickly +look at documentation for a specific command. It also has integrated Git support which lets you stage, commit, push, +pull, and view diffs from the Source Control panel without leaving the editor. --- @@ -23,9 +24,9 @@ It also has integrated Git support which lets you stage, commit, push, pull, and src="/learning-course/getting-started/vscode-overview/IMG_0156.webp" /> -When you first open up VS Code, you are greeted with a welcome screen that has a few options. -It lets you quickly customize settings and also lets you watch some tutorial videos. -It also has options to create a file, open a file, open a project, and clone a Git repository. +When you first open up VS Code, you are greeted with a welcome screen that has a few options. It lets you quickly +customize settings and also lets you watch some tutorial videos. It also has options to create a file, open a file, open +a project, and clone a Git repository. --- @@ -33,13 +34,16 @@ It also has options to create a file, open a file, open a project, and clone a G VS Code's layout is categorized into a few key regions: -- The **Activity Bar** which is in the far left, consists of vertical icons which can be used to switch between the major views (Explorer, Search, Source Control, Run & Debug, Extensions). -- Next, the **Side Bar** which is next to the activity bar shows details for the selected view (for example: file tree in Explorer). -- After that, the **Editor** is the center area. - The editor is star of the show and it is where you can view and edit files. -- Next, the **Panel** is at the bottom of the screen. - It has four main views, which are the Terminal, Problems, Output, and Debug Console. -- Finally, the **Command Palette** is accesed through `Ctrl+Shift+P` / `Cmd+Shift+P` and it allows for you to search and run any command in VS Code. +- The **Activity Bar** which is in the far left, consists of vertical icons which can be used to switch between the + major views (Explorer, Search, Source Control, Run & Debug, Extensions). +- Next, the **Side Bar** which is next to the activity bar shows details for the selected view (for example: file tree + in Explorer). +- After that, the **Editor** is the center area. The editor is star of the show and it is where you can view and edit + files. +- Next, the **Panel** is at the bottom of the screen. It has four main views, which are the Terminal, Problems, Output, + and Debug Console. +- Finally, the **Command Palette** is accesed through `Ctrl+Shift+P` / `Cmd+Shift+P` and it allows for you to search and + run any command in VS Code. -To access the WPILib commands, which are shows in the large red box on the screenshot, you can either open the command palette using the keyboard shortcut `Ctrl+Shift+P` / `Cmd+Shift+P`, or by clicking the WPILib logo in the top right corner, where the arrow is pointing to on the screenshot. +To access the WPILib commands, which are shows in the large red box on the screenshot, you can either open the command +palette using the keyboard shortcut `Ctrl+Shift+P` / `Cmd+Shift+P`, or by clicking the WPILib logo in the top right +corner, where the arrow is pointing to on the screenshot. diff --git a/src/content/docs/learning-course/getting-started/website-feature-guide.mdx b/src/content/docs/learning-course/getting-started/website-feature-guide.mdx index 527180eb..28a5c4d1 100644 --- a/src/content/docs/learning-course/getting-started/website-feature-guide.mdx +++ b/src/content/docs/learning-course/getting-started/website-feature-guide.mdx @@ -5,19 +5,18 @@ prev: false next: learning-course/learning-course/getting-started/forking-and-cloning --- -Before you start learning, there are several features across the website that, if missed, will make it hard to go through the lessons effectively. -The following features are shown with examples to help you gain a quick understanding of them before you make your way through the website. +Before you start learning, there are several features across the website that, if missed, will make it hard to go +through the lessons effectively. The following features are shown with examples to help you gain a quick understanding +of them before you make your way through the website. ## Across the Website - [Links](/learning-course/) are shown with purple text -- Clicking on an image enlarges it and shows a caption, if applicable. - Press the `Esc` key to minimize it again. -- The website has a [glossary](/resources/glossary/) of terms related to the content. - Whenever a word in that glossary is mentioned in the website, it will be underlined. - You can hover over these underlined words to get a quick definition (e.g. PDH, Spark MAX). -- Some information is hidden in dropdowns. - Try to check most of them! +- Clicking on an image enlarges it and shows a caption, if applicable. Press the `Esc` key to minimize it again. +- The website has a [glossary](/resources/glossary/) of terms related to the content. Whenever a word in that glossary + is mentioned in the website, it will be underlined. You can hover over these underlined words to get a quick + definition (e.g. PDH, Spark MAX). +- Some information is hidden in dropdowns. Try to check most of them!
Hint @@ -57,8 +56,8 @@ Examples for different concepts are shown in an "Example" box like this one. ![Slide 1](/learning-course/getting-started/website-feature-guide/slide1.webp) Navigate the slideshows by pressing the arrows on the sides. -![Slide 2](/learning-course/getting-started/website-feature-guide/slide2.webp) The dots below the caption indicate the slide you're on. -They can also be clicked to navigate to slides. +![Slide 2](/learning-course/getting-started/website-feature-guide/slide2.webp) The dots below the caption indicate the +slide you're on. They can also be clicked to navigate to slides. diff --git a/src/content/docs/learning-course/index.mdx b/src/content/docs/learning-course/index.mdx index 0e98db18..e3e103b3 100644 --- a/src/content/docs/learning-course/index.mdx +++ b/src/content/docs/learning-course/index.mdx @@ -7,14 +7,13 @@ next: false import CourseSection from '@components/CourseSection.astro'; -Welcome to FRCSoftware's learning course! -The purpose of this course is to help students learn how to program an FRC robot no matter their skill level. -The progression of the course moves from learning how to write Java to programming robots of increasing complexity. -We start individual mechanisms of robots, using the FRC Kitbot, then move to more complex robots. +Welcome to FRCSoftware's learning course! The purpose of this course is to help students learn how to program an FRC +robot no matter their skill level. The progression of the course moves from learning how to write Java to programming +robots of increasing complexity. We start individual mechanisms of robots, using the FRC Kitbot, then move to more +complex robots. -Software in FRC is always changing! -If you want to give feedback or have comments, feel free to do so through our [GitHub](https://github.com/frcsoftware/frcsoftware.org) -or [Discord.](https://discord.com/invite/uUugPrPZFs) +Software in FRC is always changing! If you want to give feedback or have comments, feel free to do so through our +[GitHub](https://github.com/frcsoftware/frcsoftware.org) or [Discord.](https://discord.com/invite/uUugPrPZFs)

- Course Setup goes over downloading the tools needed to complete the - learning course, as well as how to navigate and use them. This is a - great place to start if you're new to FRC Programming. + Course Setup goes over downloading the tools needed to complete the learning course, as well as how to navigate + and use them. This is a great place to start if you're new to FRC Programming.

  • - [Required Tools:](/learning-course/getting-started/required-tools/) - Download the tools needed for this learning course. + [Required Tools:](/learning-course/getting-started/required-tools/) Download the tools needed for this + learning course.
  • - [VS Code - Overview:](/learning-course/getting-started/vscode-overview/) Learn - more about VS Code, the code editor used for this course. + [VS Code Overview:](/learning-course/getting-started/vscode-overview/) Learn more about VS Code, the code + editor used for this course.
  • - [Forking and - Cloning:](/learning-course/getting-started/forking-and-cloning/) - Learn how to use git to fork and clone. This is important for - accessing templates that are used throughout the course. + [Forking and Cloning:](/learning-course/getting-started/forking-and-cloning/) Learn how to use git to fork + and clone. This is important for accessing templates that are used throughout the course.
- +

- Stage 0 covers the basics of Java that is needed to program the Kitbot, - a simple FRC robot. This include: + Stage 0 covers the basics of Java that is needed to program the Kitbot, a simple FRC robot. This include:

    -
  • - {' '} - Learning about Java syntax, print statements, and variables{' '} -
    • +
  • Learning about Java syntax, print statements, and variables
  • Operators
  • Conditionals and loops
  • Objects and methods
    • @@ -66,25 +53,12 @@ or [Discord.](https://discord.com/invite/uUugPrPZFs)

    - +

    - Stage 1 is where students start to program Kitbot, a basic robot - commonly used to learn basic FRC skills. + Stage 1 is where students start to program Kitbot, a basic robot commonly used to learn basic FRC skills.

      -
    • - {' '} - Stage1A: Learn basic FRC programming skills by using the Robot - class to program Kitbot.{' '} -
      • -
    • - {' '} - Stage1B: Add Command-Based programming, a file structure for - programming FRC robots, to kitbot{' '} -
      • +
    • Stage1A: Learn basic FRC programming skills by using the Robot class to program Kitbot.
      • +
    • Stage1B: Add Command-Based programming, a file structure for programming FRC robots, to kitbot

    diff --git a/src/content/docs/learning-course/stage0/classes-methods.mdx b/src/content/docs/learning-course/stage0/classes-methods.mdx index 615fb2a6..54fb2da6 100644 --- a/src/content/docs/learning-course/stage0/classes-methods.mdx +++ b/src/content/docs/learning-course/stage0/classes-methods.mdx @@ -9,47 +9,41 @@ codeRegionSources: usage: stage0/snippets/src/classes-methods/Usage.java --- -In an [earlier lesson](/learning-course/stage0/java-fundamentals/), we discussed different data types in Java, -such as `int`, `double`, and `String`. -In this lesson, we're going to learn about classes, which are a way to create our own data types, -how to use them to create objects, and how to define a class's components: fields and methods. +In an [earlier lesson](/learning-course/stage0/java-fundamentals/), we discussed different data types in Java, such as +`int`, `double`, and `String`. In this lesson, we're going to learn about classes, which are a way to create our own +data types, how to use them to create objects, and how to define a class's components: fields and methods. ## Types of Types -The Java programming language has two types of types: **primitive types** and **reference types**. -**Primitive types** are the most basic types that are built into the language, -such as `int`, `double`, and `boolean`. -**Reference types** (also called object types) are more complex types that are defined by programmers. -Many reference types come built into the Java Development Kit (JDK), such as `String`, -and others come from external libraries, but you can also define your own object types. - -Classes are a way to define object types. -A **class** is a template for creating **object**s, -with **fields** and **methods** that define the object's state and behavior. -An **object** is an instance of a class; -for example, `"a"` and `"b"` are both objects of the `String` class. - -Before writing any code, it helps to have a mental picture of what an object actually is. -So far, all the code you've written has been from the perspective of a single actor: the computer running your program. -For instance, `System.out.println("hello");` reads like an instruction: "tell the computer to print hello." - -Classes let you write code from a different perspective, sometimes called **object-oriented programming**. -Instead of one actor doing everything, your program is made up of many objects, each with its own **state** and **behavior**, -similar to characters in a play. -A character has attributes, like a costume or a name, and capabilities, like singing, or speaking a line. -In code, an object's attributes are stored in its **fields**, and its capabilities are defined by its **methods**. - -Some of a character's attributes stay the same for the whole play, like their name, -while others change from scene to scene, like their costume or where they're standing on stage. -Fields work the same way: some are set once and never change, which we call **immutable**, -while others are expected to change over time, which we call **mutable**. -Whether a field should be mutable or immutable is a choice we make when we design a class, -and we'll see examples of both later in this lesson. - -In FRC code, objects are usually more abstract than characters in a play. -A `Point` represents a location, a `Motor` represents a physical motor, and so on. -Objects are also just a convenient way to group related data and behavior together, -so it doesn't always have to belong to a real-world thing. +The Java programming language has two types of types: **primitive types** and **reference types**. **Primitive types** +are the most basic types that are built into the language, such as `int`, `double`, and `boolean`. **Reference types** +(also called object types) are more complex types that are defined by programmers. Many reference types come built into +the Java Development Kit (JDK), such as `String`, and others come from external libraries, but you can also define your +own object types. + +Classes are a way to define object types. A **class** is a template for creating **object**s, with **fields** and +**methods** that define the object's state and behavior. An **object** is an instance of a class; for example, `"a"` and +`"b"` are both objects of the `String` class. + +Before writing any code, it helps to have a mental picture of what an object actually is. So far, all the code you've +written has been from the perspective of a single actor: the computer running your program. For instance, +`System.out.println("hello");` reads like an instruction: "tell the computer to print hello." + +Classes let you write code from a different perspective, sometimes called **object-oriented programming**. Instead of +one actor doing everything, your program is made up of many objects, each with its own **state** and **behavior**, +similar to characters in a play. A character has attributes, like a costume or a name, and capabilities, like singing, +or speaking a line. In code, an object's attributes are stored in its **fields**, and its capabilities are defined by +its **methods**. + +Some of a character's attributes stay the same for the whole play, like their name, while others change from scene to +scene, like their costume or where they're standing on stage. Fields work the same way: some are set once and never +change, which we call **immutable**, while others are expected to change over time, which we call **mutable**. Whether a +field should be mutable or immutable is a choice we make when we design a class, and we'll see examples of both later in +this lesson. + +In FRC code, objects are usually more abstract than characters in a play. A `Point` represents a location, a `Motor` +represents a physical motor, and so on. Objects are also just a convenient way to group related data and behavior +together, so it doesn't always have to belong to a real-world thing. -When programming, it can be useful to display information. -This can be helpful for making programs that display information to the user or trying to see what speed that a motor is running. -In Java, we can print information to a terminal using a print statement. -A print statement in Java looks like: +When programming, it can be useful to display information. This can be helpful for making programs that display +information to the user or trying to see what speed that a motor is running. In Java, we can print information to a +terminal using a print statement. A print statement in Java looks like: ```java #printLiteral ``` -What the print statement does is take information inside the parentheses, in the previous example, it’s “hello!”, and prints it out to the terminal screen. -When using a print statement, the text that we want to print out goes inside the parentheses and is in quotes. -However, if we are printing out the value of a variable, then we do not need quotes, as shown below. +What the print statement does is take information inside the parentheses, in the previous example, it’s “hello!”, and +prints it out to the terminal screen. When using a print statement, the text that we want to print out goes inside the +parentheses and is in quotes. However, if we are printing out the value of a variable, then we do not need quotes, as +shown below. ```java #printVariable @@ -115,15 +103,15 @@ However, if we are printing out the value of a variable, then we do not need quo ## Comments -When programming, we use comments to write notes that explain what the code does. -This helps make the code more readable for others because if they are unsure of what your code does, they can read your comments. -Comments are ignored by the compiler, which also means that you can use comments to prevent code from running. -In Java, there are two types of comments: single-line comments and multi-line comments. +When programming, we use comments to write notes that explain what the code does. This helps make the code more readable +for others because if they are unsure of what your code does, they can read your comments. Comments are ignored by the +compiler, which also means that you can use comments to prevent code from running. In Java, there are two types of +comments: single-line comments and multi-line comments. ### Single-line Comments -Single line comments begin with `//` and mark the rest of the line as being a comment. -For example, the code below leaves the note of "This prints out Hello World." preceding the print statement +Single line comments begin with `//` and mark the rest of the line as being a comment. For example, the code below +leaves the note of "This prints out Hello World." preceding the print statement ```java #singleLineComment @@ -135,14 +123,14 @@ You will also see comments placed at the end of a line like the following ``` -Both examples accomplish the same tasks and there is no difference. -Whether you put your comments preceding or alongside code is up to you and what makes the most sense for your code. +Both examples accomplish the same tasks and there is no difference. Whether you put your comments preceding or alongside +code is up to you and what makes the most sense for your code. ### Multi-line Comments -Multi-line Comments start with `/*` and end with `*/` The text or code that is in between the two will turn into comments. -Multi-line Comments are commonly used when you have many lines of text or need to turn a large amount of code into a comment. -For example, this is a comment with two lines of text. +Multi-line Comments start with `/*` and end with `*/` The text or code that is in between the two will turn into +comments. Multi-line Comments are commonly used when you have many lines of text or need to turn a large amount of code +into a comment. For example, this is a comment with two lines of text. ```java #multiLineComment diff --git a/src/content/docs/learning-course/stage0/operators.mdx b/src/content/docs/learning-course/stage0/operators.mdx index 0b27546d..89da5acb 100644 --- a/src/content/docs/learning-course/stage0/operators.mdx +++ b/src/content/docs/learning-course/stage0/operators.mdx @@ -7,21 +7,19 @@ codeRegionSources: default: stage0/snippets/src/Operators.java --- -In Java, operators are used to change or compare the values of variables. -There four different types of operators are: +In Java, operators are used to change or compare the values of variables. There four different types of operators are: - Arithmetic Operators - Assignment Operators - Comparison Operators - Logical Operators -Operators are commonly used to change the value of a variable in a loop or conditional. -These topics will be covered in the next sections! +Operators are commonly used to change the value of a variable in a loop or conditional. These topics will be covered in +the next sections! ## Arithmetic Operators -Arithmetic operators are used to perform basic math on variables. -These include: +Arithmetic operators are used to perform basic math on variables. These include: @@ -59,22 +57,18 @@ These include: - +
    `%` - Remainder: Returns the remainder of two numbers after division - Remainder: Returns the remainder of two numbers after division int, double `a % b`
    - + -Operators can be used when creating variables or when changing a variable's value after it was initialized. -In the example below, we have three variables whose values are set using different operators. -Without running the code, think about what value would each variable hold. +Operators can be used when creating variables or when changing a variable's value after it was initialized. In the +example below, we have three variables whose values are set using different operators. Without running the code, think +about what value would each variable hold. ```java #variables @@ -93,8 +87,9 @@ Without running the code, think about what value would each variable hold.
-In the example below, we have an integer variable named `magicNumber` that is set to 6. Using the multiplication operator, the value is adjusted inside the print statement. -Without running the code, what is the value of `magicNumber`? +In the example below, we have an integer variable named `magicNumber` that is set to 6. Using the multiplication +operator, the value is adjusted inside the print statement. Without running the code, what is the value of +`magicNumber`? ```java #multiplication @@ -104,24 +99,21 @@ Without running the code, what is the value of `magicNumber`? Answer

- `magicNumber`'s value remains 6. The value calculated inside - `println` only affects what gets printed, since it's never assigned - back to `magicNumber` using an equal sign. + `magicNumber`'s value remains 6. The value calculated inside `println` only affects what gets printed, since + it's never assigned back to `magicNumber` using an equal sign.

## Assignment Operators -Assignment operators are used when assigning or updating the values in a variable. -These include: +Assignment operators are used when assigning or updating the values in a variable. These include: @@ -140,56 +132,52 @@ These include:
`+=` - Addition: Takes the current value of the variable, adds the - stated amount then assigns the result to the variable. It's the - same as `x = x + y` + Addition: Takes the current value of the variable, adds the stated amount then assigns the result to the + variable. It's the same as `x = x + y` `a += 3`
`-=` - Subtraction: Takes the current value of the variable, subtracts - the stated amount then assigns the result to the variable. It's - the same as `x = x - y` + Subtraction: Takes the current value of the variable, subtracts the stated amount then assigns the + result to the variable. It's the same as `x = x - y` `a -= 4`
`*=` - Multiplication: Takes the current value of the variable, - multiplies the stated amount then assigns the result to the - variable. It's the same as `x = x * y` + Multiplication: Takes the current value of the variable, multiplies the stated amount then assigns the + result to the variable. It's the same as `x = x * y` `a *= 5`
`/=` - Division: Takes the current value of the variable, divides the - stated amount then assigns the result to the variable. It's the - same as `x = x / y` + Division: Takes the current value of the variable, divides the stated amount then assigns the result to + the variable. It's the same as `x = x / y` `a /= 6`
-Assignment operators are similar to arithmetic operators. -The main difference is that assignment operators are the shorthand version. -Using assignment operators can help make code easier to read. -It prevents having to write the variable name twice which can also be helpful in preventing code errors. +Assignment operators are similar to arithmetic operators. The main difference is that assignment operators are the +shorthand version. Using assignment operators can help make code easier to read. It prevents having to write the +variable name twice which can also be helpful in preventing code errors. -In the example below, we have variables `a` which is set to 10, and variable `b` which is set to 5. Since `+=` adds 2 to `a`, `a` will hold the value of 12. Similarly, `b` will now hold the value of 4 +In the example below, we have variables `a` which is set to 10, and variable `b` which is set to 5. Since `+=` adds 2 to +`a`, `a` will hold the value of 12. Similarly, `b` will now hold the value of 4 ```java #arithmetic ``` -Sometimes placed in the category of "unary operators", the `++` and `--` operators are also used to change the value of the a variable. -They help with incrementing and decrementing values and are used in conditionals (which are covered in a later stage). -For now, we can use the operators to change variables without using conditionals. +Sometimes placed in the category of "unary operators", the `++` and `--` operators are also used to change the value of +the a variable. They help with incrementing and decrementing values and are used in conditionals (which are covered in a +later stage). For now, we can use the operators to change variables without using conditionals. @@ -222,15 +210,14 @@ In the example below, we have two variables: `x` which is set to 6 and `y` which ``` -In the first print statement, we have `x++`. -This means it takes the value of x and increments it by 1 which gives us 7 because 6 + 1 is 7. -In the second print statement, we have `y--`. -This means that it takes the value of y, decrements it by 1 which gives us 6 since 7 - 1 is 6. +In the first print statement, we have `x++`. This means it takes the value of x and increments it by 1 which gives us 7 +because 6 + 1 is 7. In the second print statement, we have `y--`. This means that it takes the value of y, decrements it +by 1 which gives us 6 since 7 - 1 is 6. ## Comparison Operators -Comparison operators are symbols that tell the program how to compare values. -They can be used to help make decisions and are a main part of conditionals, which are discussed later in this stage. +Comparison operators are symbols that tell the program how to compare values. They can be used to help make decisions +and are a main part of conditionals, which are discussed later in this stage.
@@ -282,12 +269,11 @@ They can be used to help make decisions and are a main part of conditionals, whi
-Comparison operators help make decisions because they can return if the value of a comparison is true or false. -If you remember from the previous section, these are `booleans`! +Comparison operators help make decisions because they can return if the value of a comparison is true or false. If you +remember from the previous section, these are `booleans`! -Comparison operators are very similar to what you see in math problems. -In this example, we have two variables: `c` and `d`. -`c` is set to 2, and `d` is set to 4. The print statement compares the two variables using the greater than sign. +Comparison operators are very similar to what you see in math problems. In this example, we have two variables: `c` and +`d`. `c` is set to 2, and `d` is set to 4. The print statement compares the two variables using the greater than sign. In the example below, it returns false because 2 is not greater than 4. ```java #comparison @@ -296,12 +282,11 @@ In the example below, it returns false because 2 is not greater than 4. ## Logical Operators -Logical operators help a program make decisions by using true or false statements. -They are also used in conditionals. +Logical operators help a program make decisions by using true or false statements. They are also used in conditionals. @@ -331,9 +316,9 @@ They are also used in conditionals.
-In the example below we have 2 variables: `fiveIsGreaterThanThree` and `nineIsLessThanTwo`. -We know `fiveIsGreaterThanThree` is true since 5 is greater than 3. We also know that `nineIsLessThanTwo` is false since 9 is not less than 2. -Using that information and without running the code, what should the print statements print out? +In the example below we have 2 variables: `fiveIsGreaterThanThree` and `nineIsLessThanTwo`. We know +`fiveIsGreaterThanThree` is true since 5 is greater than 3. We also know that `nineIsLessThanTwo` is false since 9 is +not less than 2. Using that information and without running the code, what should the print statements print out? ```java #logical @@ -345,18 +330,16 @@ Using that information and without running the code, what should the print state

  • - false. && returns true if both statements are true - `nineIsLessThanTwo` is false, therefore the operator will - return false. + false. && returns true if both statements are true `nineIsLessThanTwo` is false, therefore the + operator will return false.
  • - true. || returns true if one of the statements are true - `fiveIsGreaterThanThree` is true, therefore the the operator - will return true. + true. || returns true if one of the statements are true `fiveIsGreaterThanThree` is true, therefore + the the operator will return true.
  • - false. ! reverses the outcome `fiveIsGreaterThanThree` is - true, adding ! will reverse it and return false. + false. ! reverses the outcome `fiveIsGreaterThanThree` is true, adding ! will reverse it and return + false.

diff --git a/src/content/docs/learning-course/stage0/stage-overview.mdx b/src/content/docs/learning-course/stage0/stage-overview.mdx index 5ecab2a6..9dc8993e 100644 --- a/src/content/docs/learning-course/stage0/stage-overview.mdx +++ b/src/content/docs/learning-course/stage0/stage-overview.mdx @@ -6,12 +6,12 @@ next: learning-course/stage0/intro-to-iava/java-fundamentals --- Learning the basics of Java is the most important step in learning FRC programming because it builds the foundation. -Using Java, we can write code that allows a robot to run a motor, adjust speed, and much more. -While there is a lot to learn when learning Java, FRCSoftware will only cover the basics needed to program a robot. +Using Java, we can write code that allows a robot to run a motor, adjust speed, and much more. While there is a lot to +learn when learning Java, FRCSoftware will only cover the basics needed to program a robot. Each section will have different activities and exercises to help build up a good understanding of the basics of Java. -If you’re new to programming, it is highly recommended to go through each step in order. -This will help ensure that you don’t miss any important information. +If you’re new to programming, it is highly recommended to go through each step in order. This will help ensure that you +don’t miss any important information. This stage will cover the following topics diff --git a/src/content/docs/learning-course/stage1/stage-overview.mdx b/src/content/docs/learning-course/stage1/stage-overview.mdx index 97e6200b..2e597108 100644 --- a/src/content/docs/learning-course/stage1/stage-overview.mdx +++ b/src/content/docs/learning-course/stage1/stage-overview.mdx @@ -5,19 +5,15 @@ prev: false next: stage-1a/stage-overview --- -Congratulations! -Whether you already know Java, have programmed an FRC robot before, -or are a complete beginner, you should have a good grasp of the basic syntax of the Java language by now. -In Stage 1, we'll be moving on to the exciting part: actually writing code for a robot! -It might seem daunting at first, but the best way to think through it is to focus on understanding -how each individual component of the code works, instead of trying to tackle it all at once. +Congratulations! Whether you already know Java, have programmed an FRC robot before, or are a complete beginner, you +should have a good grasp of the basic syntax of the Java language by now. In Stage 1, we'll be moving on to the exciting +part: actually writing code for a robot! It might seem daunting at first, but the best way to think through it is to +focus on understanding how each individual component of the code works, instead of trying to tackle it all at once. -This stage covers how to fully program a working kitbot for the 2026 FIRST Robotics Competition game, -REBUILT. -You'll start at stage 1A, which covers a simple way to code the kitbot. -Then, you'll move on to stage 1B, which uses a slightly more complex paradigm known as commands. -In addition, you'll also get to debug your robot in a simulation, to check if your code works! -Feel free to play around with the robot and control it in sim once you've finished! +This stage covers how to fully program a working kitbot for the 2026 FIRST Robotics Competition game, REBUILT. You'll +start at stage 1A, which covers a simple way to code the kitbot. Then, you'll move on to stage 1B, which uses a slightly +more complex paradigm known as commands. In addition, you'll also get to debug your robot in a simulation, to check if +your code works! Feel free to play around with the robot and control it in sim once you've finished! This stage is composed of the following sub-stages: diff --git a/src/content/docs/learning-course/stage1/stage1a/drivetrain-sim.mdx b/src/content/docs/learning-course/stage1/stage1a/drivetrain-sim.mdx index 725aaf60..18846fde 100644 --- a/src/content/docs/learning-course/stage1/stage1a/drivetrain-sim.mdx +++ b/src/content/docs/learning-course/stage1/stage1a/drivetrain-sim.mdx @@ -10,20 +10,23 @@ import { REV_CTRE_CHOOSER_KEY } from '@data/tabsSyncKeys.ts'; # Simulation -It's common to write code without having immediate access to a physical robot to test changes. -Luckily, your computer can also run robot code allowing it to be tested without a robot. -While there are some things that can be tested by simulating pure robot code, there are no physical motors to move and respond with new positions. -Instead we use simulation classes that use physics to take the desired input voltage to the motors and estimate how the physical mechanism would respond and update our motor controller instances to match. -For this stage custom classes have been provided that abstract away much of this logic. -You can find these files under the `simulation` folder if you would like to read the implementation. -You can also read the [WPILib docs on simulation](https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation/index.html) if you would like to learn more about simulation. +It's common to write code without having immediate access to a physical robot to test changes. Luckily, your computer +can also run robot code allowing it to be tested without a robot. While there are some things that can be tested by +simulating pure robot code, there are no physical motors to move and respond with new positions. Instead we use +simulation classes that use physics to take the desired input voltage to the motors and estimate how the physical +mechanism would respond and update our motor controller instances to match. For this stage custom classes have been +provided that abstract away much of this logic. You can find these files under the `simulation` folder if you would like +to read the implementation. You can also read the +[WPILib docs on simulation](https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation/index.html) if +you would like to learn more about simulation. # Drivetrain Sim -To simulate the drivetrain another class needs to instantiated in `Robot.java`. -Create an instance of the `DrivetrainSim` class under the `DifferentialDrive` instance using the left and right Leader motors as inputs. -This class will read the voltage commanded to the motors and, using its physics sim, update the motor controllers with new positions. -The class will then publish the new drivetrain position and additional motor data so it can be viewed in AdvantageScope. +To simulate the drivetrain another class needs to instantiated in `Robot.java`. Create an instance of the +`DrivetrainSim` class under the `DifferentialDrive` instance using the left and right Leader motors as inputs. This +class will read the voltage commanded to the motors and, using its physics sim, update the motor controllers with new +positions. The class will then publish the new drivetrain position and additional motor data so it can be viewed in +AdvantageScope. @@ -43,14 +46,15 @@ The class will then publish the new drivetrain position and additional motor dat # Periodic Methods -Robot code needs to be run in a loop so that it can continually make new commands to motor controllers based on new controller and sensor input. -To accomplish this Periodic Methods are provided in the `Robot` class and `OpMode` classes. +Robot code needs to be run in a loop so that it can continually make new commands to motor controllers based on new +controller and sensor input. To accomplish this Periodic Methods are provided in the `Robot` class and `OpMode` classes. Periodic methods get called every 20ms by default, causing any code placed inside of them to be run 50 times per second. -OpModeRobot has additional periodic methods that only run during specific robot states. -For example, the `teleopPeriodic()` function will only be called when teleop mode is selected on the driverstation. +OpModeRobot has additional periodic methods that only run during specific robot states. For example, the +`teleopPeriodic()` function will only be called when teleop mode is selected on the driverstation. -At the moment `DrivetrainSim` will not actually do anything because it is not being told to update periodically. -To fix this, `DrivetrainSim`'s `periodic()` function should be called inside of the `Robot` class' `simulationPeriodic()` function. +At the moment `DrivetrainSim` will not actually do anything because it is not being told to update periodically. To fix +this, `DrivetrainSim`'s `periodic()` function should be called inside of the `Robot` class' `simulationPeriodic()` +function. @@ -69,9 +73,8 @@ To fix this, `DrivetrainSim`'s `periodic()` function should be called inside of @@ -106,38 +109,28 @@ After adding the simulation code your `Robot.java` file should now look like thi When simulating code there are two main windows to control and visualize what the code is doing. -The first important window is the Sim GUI. -The Sim GUI is automatically opened when simulating code and acts as both a driverstation and shows information about simulated devices such as position and velocity. -More information about the Sim GUI can be found in [WPILIb's documentation](https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation/simulation-gui.html). - -The other important window is a program called AdvantageScope. -AdvantageScope is bundled with WPILib and is used to visualize data sent by the robot. -The main tabs used in AdvantageScope are **Line Graph**, used to graph numeric data such as a motors current position, and **2D Field** used to visualize positions on the field. -AdvantageScope can also be used to assist in debugging by visualizing logs generated by the robot during a match. -More information about using AdvantageScope can be found at [their docs](https://docs.advantagescope.org/). - -The first step in simulating code is opening AdvantageScope and loading the layout stored as `AdvantageScopeLayout.json` in the top level of the robot project. - - - -Next, use the WPILib icon in the upper right corner of VS Code to open the command palette and select `WPILib: Simulate Robot Code`. -This starts the simulation and opens the Sim GUI. - - - -Finally connect AdvantageScope to the simulation and select `MyTeleop` as the current `OpMode`. -Now when you enable the robot using the Sim GUI the robot should now be able to be controlled using WASD. - - +The first important window is the Sim GUI. The Sim GUI is automatically opened when simulating code and acts as both a +driverstation and shows information about simulated devices such as position and velocity. More information about the +Sim GUI can be found in +[WPILIb's documentation](https://docs.wpilib.org/en/stable/docs/software/wpilib-tools/robot-simulation/simulation-gui.html). + +The other important window is a program called AdvantageScope. AdvantageScope is bundled with WPILib and is used to +visualize data sent by the robot. The main tabs used in AdvantageScope are **Line Graph**, used to graph numeric data +such as a motors current position, and **2D Field** used to visualize positions on the field. AdvantageScope can also be +used to assist in debugging by visualizing logs generated by the robot during a match. More information about using +AdvantageScope can be found at [their docs](https://docs.advantagescope.org/). + +The first step in simulating code is opening AdvantageScope and loading the layout stored as `AdvantageScopeLayout.json` +in the top level of the robot project. + + + +Next, use the WPILib icon in the upper right corner of VS Code to open the command palette and select +`WPILib: Simulate Robot Code`. This starts the simulation and opens the Sim GUI. + + + +Finally connect AdvantageScope to the simulation and select `MyTeleop` as the current `OpMode`. Now when you enable the +robot using the Sim GUI the robot should now be able to be controlled using WASD. + + diff --git a/src/content/docs/learning-course/stage1/stage1a/kitbot-drivetrain.mdx b/src/content/docs/learning-course/stage1/stage1a/kitbot-drivetrain.mdx index 1d8f0530..b2f891be 100644 --- a/src/content/docs/learning-course/stage1/stage1a/kitbot-drivetrain.mdx +++ b/src/content/docs/learning-course/stage1/stage1a/kitbot-drivetrain.mdx @@ -11,30 +11,24 @@ import ContentImage from '@components/ContentImage.astro'; # Drivetrain - + The kitbot uses a four motor tank drive meaning the left and right sides are driven independently by two motors each. -This allows -the robot to move similar to a tank by driving the left and right sides at different speeds. -For this stage, the four drivetrain motors will be referred to as `leftLeader`, `leftFollower`, `rightLeader`, `rightFollower`. +This allows the robot to move similar to a tank by driving the left and right sides at different speeds. For this stage, +the four drivetrain motors will be referred to as `leftLeader`, `leftFollower`, `rightLeader`, `rightFollower`. # Motor Controllers -Motors can not be controlled directly. -Instead, Systemcore talks to a motor controller and the motor controller then drives the motors. -Vendors, such as REV or CTRE, provide classes that can be used to both control and get sensor data, such as position, velocity, and temperature, from their motor controllers. -While each individual type of motor controller has its own class, motor controllers from the same vendor are -mostly interacted with in the same way so this stage will only use the `SparkMax` for REV code and the `TalonFX` for CTRE code. +Motors can not be controlled directly. Instead, Systemcore talks to a motor controller and the motor controller then +drives the motors. Vendors, such as REV or CTRE, provide classes that can be used to both control and get sensor data, +such as position, velocity, and temperature, from their motor controllers. While each individual type of motor +controller has its own class, motor controllers from the same vendor are mostly interacted with in the same way so this +stage will only use the `SparkMax` for REV code and the `TalonFX` for CTRE code. -When creating a motor controller object, the physical motor controller's CAN ID and the CAN Bus ID are given. -CAN Bus refers to which of the 5 Systemcore CAN ports, or which CANivore, the device is plugged into. -CAN ID is an integer that each CAN device is configured to have. -All devices on a given CAN Bus must have a unique ID. -Using the combination of CAN Bus and CAN ID SystemCore can give commands to the correct motor controller. +When creating a motor controller object, the physical motor controller's CAN ID and the CAN Bus ID are given. CAN Bus +refers to which of the 5 Systemcore CAN ports, or which CANivore, the device is plugged into. CAN ID is an integer that +each CAN device is configured to have. All devices on a given CAN Bus must have a unique ID. Using the combination of +CAN Bus and CAN ID SystemCore can give commands to the correct motor controller. For this exercise the motor controllers will have the IDs: @@ -43,26 +37,29 @@ For this exercise the motor controllers will have the IDs: - `rightLeader`: CAN Bus 0, CAN ID 2 - `rightFollower`: CAN Bus 0, CAN ID 3 -The motor controller objects should be created inside the `Robot.java` at the top of the class. -This is how the motor controller objects for the left motors will look. +The motor controller objects should be created inside the `Robot.java` at the top of the class. This is how the motor +controller objects for the left motors will look. ```java stage1/stage1a/solutions/ctre/src/main/java/first/robot/Robot.java#DriveMotorsLeft ``` -For the CTRE code, the CAN ID of the leader motors are stored as a variable since they will be used later on to tell the follower which motor controller to follow. -This helps prevent errors from occurring by ensuring that there is a single source of truth for the correct CAN ID. -Additionally, CTRE uses a CANBus object to store the CANBus instead of just an integer. +For the CTRE code, the CAN ID of the leader motors are stored as a variable since they will be used later on to tell the +follower which motor controller to follow. This helps prevent errors from occurring by ensuring that there is a single +source of truth for the correct CAN ID. Additionally, CTRE uses a CANBus object to store the CANBus instead of just an +integer. ```java stage1/stage1a/solutions/rev/src/main/java/first/robot/Robot.java#DriveMotorsLeft ``` -Since the Spark Max can control both brushed and brushless motors it's necessary to specify the type as `MotorType.kBrushless` for motors like a NEO and `MotorType.kBrushed` for motors like a CIM. +Since the Spark Max can control both brushed and brushless motors it's necessary to specify the type as +`MotorType.kBrushless` for motors like a NEO and `MotorType.kBrushed` for motors like a CIM. -When writing code for a real robot, make sure your motor type is set correctly! Setting a NEO to `MotorType.kBrushed` will break the NEO. +When writing code for a real robot, make sure your motor type is set correctly! Setting a NEO to `MotorType.kBrushed` +will break the NEO. @@ -91,38 +88,30 @@ Now try creating the right motor controllers on your own. # Motor Controller Configuration -Motor Controllers have many settings that can be changed such as IDs, motor -types, and limits. -Vendors provide -software, such as REV's [REV Hardware Client 2](https://docs.revrobotics.com/rev-hardware-client-2) and CTRE's [Phoenix Tuner X](https://v6.docs.ctr-electronics.com/en/stable/docs/tuner/index.html), to run -and configure their devices from a computer. -However, it is recommended to -configure devices through code to ensure that all motor controllers are properly -configured. -This is especially useful because it can be easy to forget all of -the configurations that need to be added and their proper values. +Motor Controllers have many settings that can be changed such as IDs, motor types, and limits. Vendors provide software +such as REV's [REV Hardware Client 2](https://docs.revrobotics.com/rev-hardware-client-2) and CTRE's +[Phoenix Tuner X](https://v6.docs.ctr-electronics.com/en/stable/docs/tuner/index.html) to run and configure their +devices from a computer. However, it is recommended to configure devices through code to ensure that all motor +controllers are properly configured. This is especially useful because it can be easy to forget all of the +configurations that need to be added and their proper values. -For this section only the motor controller's invert setting will be configured. -This setting controls what direction a motor spins when the motor controller is given a command with a positive sign. -Since there are two motors on each side of the drivetrain, its important to ensure that the each of the motors on a side -move in sync with eachother. -This can be accomplished by telling one of the motor controllers to follow the other. -This is why one motor is named Leader and the other is Follower. -The code tells the Follower to listen to the commands given to the Leader. +For this section only the motor controller's invert setting will be configured. This setting controls what direction a +motor spins when the motor controller is given a command with a positive sign. Since there are two motors on each side +of the drivetrain, its important to ensure that the each of the motors on a side move in sync with eachother. This can +be accomplished by telling one of the motor controllers to follow the other. This is why one motor is named Leader and +the other is Follower. The code tells the Follower to listen to the commands given to the Leader. -The motor controller configuration will be done inside of the constructor for the robot class. -Motor Controllers are configured by first creating a motor controller configuration object. -This object stores the configuration so it can be changed and shared across different Motor Controllers. +The motor controller configuration will be done inside of the constructor for the robot class. Motor Controllers are +configured by first creating a motor controller configuration object. This object stores the configuration so it can be +changed and shared across different Motor Controllers. @@ -140,11 +129,13 @@ This object stores the configuration so it can be changed and shared across diff -Next, settings can be changed from their default by calling various functions on the configuration object with their new values. -For the left motors, the invert setting will be `true` for REV code and `Clockwise_Positive` for CTRE code. -This will cause the motors to spin in a direction that would drive the robot forward when a positive input is given. -Since the motors on the right side of the drivetrain are facing the opposite direction they would cause the wheels try and drive the robot backwards when given a positive input if they were configured the same way. -Instead they should be configured with an invert setting of `false` or `Counter_Clockwise_Positive` so they also drive the robot forward when given a positive input. +Next, settings can be changed from their default by calling various functions on the configuration object with their new +values. For the left motors, the invert setting will be `true` for REV code and `Clockwise_Positive` for CTRE code. This +will cause the motors to spin in a direction that would drive the robot forward when a positive input is given. Since +the motors on the right side of the drivetrain are facing the opposite direction they would cause the wheels try and +drive the robot backwards when given a positive input if they were configured the same way. Instead they should be +configured with an invert setting of `false` or `Counter_Clockwise_Positive` so they also drive the robot forward when +given a positive input. @@ -162,8 +153,8 @@ Instead they should be configured with an invert setting of `false` or `Counter_ -Finally, the configuration object gets given to the motor controller object. -It's important to remember that settings only get changed when the configuration gets given to the motor controller. +Finally, the configuration object gets given to the motor controller object. It's important to remember that settings +only get changed when the configuration gets given to the motor controller. @@ -187,8 +178,7 @@ It's important to remember that settings only get changed when the configuration -Now try configuring the right motor controllers on your own. -Remember that some of the configurations may be different. +Now try configuring the right motor controllers on your own. Remember that some of the configurations may be different.
Solution @@ -211,15 +201,12 @@ Remember that some of the configurations may be different. # Arcade Drive - + -While there are several ways to control a tank drive, this stage will be using arcade drive. -Arcade drive uses the y-axis of a joystick to control how fast the robot drives forward or backward while the x-axis controls how fast the robot rotates clockwise or counter clockwise. -WPIlib provides a class to convert joystick inputs into commands for the motors to follow called `DifferentialDrive`. +While there are several ways to control a tank drive, this stage will be using arcade drive. Arcade drive uses the +y-axis of a joystick to control how fast the robot drives forward or backward while the x-axis controls how fast the +robot rotates clockwise or counter clockwise. WPIlib provides a class to convert joystick inputs into commands for the +motors to follow called `DifferentialDrive`. An instance of `DifferentialDrive` should be created under where the motor controllers were declared. @@ -239,24 +226,26 @@ An instance of `DifferentialDrive` should be created under where the motor contr -Notice how the `DifferentialDrive` constructor takes the form `DifferentialDrive(DoubleConsumer leftMotor, DoubleConsumer rightMotor)`. -When created the `DifferentialDrive` is asking for a `DoubleConsumer` that it can use to drive the left and right motors. -A `Consumer` is simply a function that takes something as an input so a `DoubleConsumer` is a function that takes a double as an input when called. -The `motorController:setThrottle` syntax is used to proved the `DifferentialDrive` instance with the motor controllers `setThrottle()` function. -This function commands the motor to run a percentage of their maximum speed, also known as duty cycle, with an input from -1.0 to 1.0. -This allows the `DifferentialDrive` instance to call the provided motors controller's `setThrottle()` functions with the correct duty cycle when provided with input from the joysticks. +Notice how the `DifferentialDrive` constructor takes the form +`DifferentialDrive(DoubleConsumer leftMotor, DoubleConsumer rightMotor)`. When created the `DifferentialDrive` is asking +for a `DoubleConsumer` that it can use to drive the left and right motors. A `Consumer` is simply a function that takes +something as an input so a `DoubleConsumer` is a function that takes a double as an input when called. The +`motorController:setThrottle` syntax is used to proved the `DifferentialDrive` instance with the motor controllers +`setThrottle()` function. This function commands the motor to run a percentage of their maximum speed, also known as +duty cycle, with an input from -1.0 to 1.0. This allows the `DifferentialDrive` instance to call the provided motors +controller's `setThrottle()` functions with the correct duty cycle when provided with input from the joysticks. # IMU -An IMU, Inertial Measurement Unit, is a sensor that allows the robot to accurately track its 3d rotation (roll, pitch, and yaw) as it moves around the field. -While there are several vendors that sell very accurate IMUs, this stage will make use of Systemcore's built in IMU. -An instance of Systemcore's IMU should be created beneath the `differentialDrive`. +An IMU, Inertial Measurement Unit, is a sensor that allows the robot to accurately track its 3d rotation (roll, pitch, +and yaw) as it moves around the field. While there are several vendors that sell very accurate IMUs, this stage will +make use of Systemcore's built in IMU. An instance of Systemcore's IMU should be created beneath the +`differentialDrive`. @@ -275,10 +264,9 @@ An instance of Systemcore's IMU should be created beneath the `differentialDrive # Check Up @@ -310,24 +298,24 @@ By now your `Robot` class in `Robot.java` should look like this and VS code shou # OpModes -`OpMode`s are a class that registers itself with the driverstation providing a name and robot mode (autonomous, teleop, or utility). -This allows the robot to run different code based on what is selected on the driverstation. -This stage will use classes that extend `PeriodicOpMode.` -By extending `PeriodicOpMode` these classes gain a few useful functions that are only called when the OpMode is selected on the driverstation. +`OpMode`s are a class that registers itself with the driverstation providing a name and robot mode (autonomous, teleop, +or utility). This allows the robot to run different code based on what is selected on the driverstation. This stage will +use classes that extend `PeriodicOpMode.` By extending `PeriodicOpMode` these classes gain a few useful functions that +are only called when the OpMode is selected on the driverstation. - `start()` is called once when the robot transitions from disabled to enabled. - `periodic()` is called repeatedly when the robot is enabled. - `end()` is called once when the robot transitions from enabled to disabled. -- `disabledPeriodic()` is called repeatedly when the robot is disabled. - Further information about OpModes can be found in [this blog post](https://zharel.me/blog/opmodes/) if you would like to learn more. +- `disabledPeriodic()` is called repeatedly when the robot is disabled. Further information about OpModes can be found + in [this blog post](https://zharel.me/blog/opmodes/) if you would like to learn more. Two blank `PeriodicOpMode`s, `MyTeleop.java` and `MyAuto.java` are provided under the `opmode` folder. -To control the robot with joysticks a Teleop OpMode needs to be created that periodically gives the `DifferentialDrive` instance new values from the controller. -First a instance of `NiDsXboxController` needs to be created. -This class has functions that provide the state of different buttons on the controller. -Multiple controllers can be used at once so the driverstation gives each a slot. -The index provided in the constructor tells the `NiDsXboxController`which slot to listen too. +To control the robot with joysticks a Teleop OpMode needs to be created that periodically gives the `DifferentialDrive` +instance new values from the controller. First a instance of `NiDsXboxController` needs to be created. This class has +functions that provide the state of different buttons on the controller. Multiple controllers can be used at once so the +driverstation gives each a slot. The index provided in the constructor tells the `NiDsXboxController`which slot to +listen too. @@ -346,14 +334,13 @@ The index provided in the constructor tells the `NiDsXboxController`which slot t -Next, the `periodic()` method inside of `MyTeleop.java' will be used to continually update the `DifferentialDrive`index through the`arcadeDrive`function. -The`MyTeleop`class has the`Robot`class as a parameter in its constructor. -This allows the Opmode to access the methods and fields of the`Robot` class. +Next, the `periodic()` method inside of +`MyTeleop.java' will be used to continually update the `DifferentialDrive`index through the`arcadeDrive`function. The`MyTeleop`class has the`Robot`class as a parameter in its constructor. This allows the Opmode to access the methods and fields of the`Robot` +class. diff --git a/src/content/docs/learning-course/stage1/stage1a/stage-overview.mdx b/src/content/docs/learning-course/stage1/stage1a/stage-overview.mdx index 25404c37..4e410fd6 100644 --- a/src/content/docs/learning-course/stage1/stage1a/stage-overview.mdx +++ b/src/content/docs/learning-course/stage1/stage1a/stage-overview.mdx @@ -8,21 +8,21 @@ next: kitbot-drivetrain import { FileTree } from '@astrojs/starlight/components'; import YouTube from '@components/YouTube.astro'; -Welcome to Stage 1A! -Before we can start programming, we have to fork and clone the relevant repository: +Welcome to Stage 1A! Before we can start programming, we have to fork and clone the relevant repository: -- If your team primarily uses REV electronics (such as Spark MAX motor controllers), clone [the REV template](https://github.com/frcsoftware/Stage1-Template-REV). -- If your team primarily uses CTRE electronics (such as Kraken motors), clone [the CTRE template](https://github.com/frcsoftware/Stage1-Template-CTRE). +- If your team primarily uses REV electronics (such as Spark MAX motor controllers), clone + [the REV template](https://github.com/frcsoftware/Stage1-Template-REV). +- If your team primarily uses CTRE electronics (such as Kraken motors), clone + [the CTRE template](https://github.com/frcsoftware/Stage1-Template-CTRE). Now, before we get into the depths of the robot code, it's useful to look at a high-level overview of the contents of a -typical WPILib project. -As your code gets more advanced, you'll see more folders and files appear, but they're all controlled -by the same basic components. +typical WPILib project. As your code gets more advanced, you'll see more folders and files appear, but they're all +controlled by the same basic components. ### Stage 1A Template Structure @@ -43,91 +43,88 @@ by the same basic components. - Main.java -You'll notice that we're skipping a lot of files here, because you don't have to edit those. -What's great about using a framework like WPILib is that it automatically generates these files when you create a new project, so you can get started coding quicker. -The other folders, like `src/main/deploy/` for example, will come in handy as your robot code becomes more advanced. -Thus, the only files shown in the structure tree are the ones directly responsible for controlling what our kitbot will do. +You'll notice that we're skipping a lot of files here, because you don't have to edit those. What's great about using a +framework like WPILib is that it automatically generates these files when you create a new project, so you can get +started coding quicker. The other folders, like `src/main/deploy/` for example, will come in handy as your robot code +becomes more advanced. Thus, the only files shown in the structure tree are the ones directly responsible for +controlling what our kitbot will do. ### `Main.java` -The first file to take note of is the `Main.java` file; this is the entrypoint for any Java project in real life. -Its contents are pretty short and sweet (comments and package declaration removed for brevity): +The first file to take note of is the `Main.java` file; this is the entrypoint for any Java project in real life. Its +contents are pretty short and sweet (comments and package declaration removed for brevity): ```java stage1/snippets/Main.java#main ``` -You can see that all the `Main.java` file is doing is, quite literally, starting up the robot, -so there's really no reason to edit this file for now. +You can see that all the `Main.java` file is doing is, quite literally, starting up the robot, so there's really no +reason to edit this file for now. ### `Robot.java` But what is that one line in `Main.java` doing? + {/* rli:ignore */} ```java RobotBase.startRobot(first.robot.Robot::new); ``` -It seems to be "starting" an instance of the `first.robot.Robot` class, and if we go to that class file, we end up at `Robot.java`. -This is the core of your robot code, where: +It seems to be "starting" an instance of the `first.robot.Robot` class, and if we go to that class file, we end up at +`Robot.java`. This is the core of your robot code, where: - your subsystems are defined - shared behavior is defined - your debugging data is logged (telemetry). We'll go through this file, as well as all of the functionalities, more in detail later. ### `opmode/` -This folder contains all the OpModes that your robot will run. -An OpMode is a class that controls the behavior of your robot during a specific robot mode (autonomous, teleop, and utility). -You can have multiple OpModes per robot mode, and they are selected on the Driver Station to tell the robot which one to run. -This allows you to have different autonomous routines for different situations, -or multiple teleop routines for different drivers. -OpModes use the `Robot` class to access the robot's subsystems and other shared behavior. +This folder contains all the OpModes that your robot will run. An OpMode is a class that controls the behavior of your +robot during a specific robot mode (autonomous, teleop, and utility). You can have multiple OpModes per robot mode, and +they are selected on the Driver Station to tell the robot which one to run. This allows you to have different autonomous +routines for different situations, or multiple teleop routines for different drivers. OpModes use the `Robot` class to +access the robot's subsystems and other shared behavior. ### `simulation/` -These are the files that control simulation of the robot, allowing you to test code without actually having a physical robot in front of you. -We've set this up for you already; you'll just have to set up the simulation software yourself, which we'll cover at the end of Stage 1A. +These are the files that control simulation of the robot, allowing you to test code without actually having a physical +robot in front of you. We've set this up for you already; you'll just have to set up the simulation software yourself, +which we'll cover at the end of Stage 1A. ### The 2026 Kitbot -But what is all this code actually going to control? -Well, the answer is the 2026 FIRST Robotics Competition kitbot, the best starting point -for new FRC teams, as well as the simplest robot to get fully working. -You can watch the below video to learn more about what functionalities the kitbot has. -If you're a bit confused after watching that video, don't worry. -We'll explain the kitbot more in depth in the next section. +But what is all this code actually going to control? Well, the answer is the 2026 FIRST Robotics Competition kitbot, the +best starting point for new FRC teams, as well as the simplest robot to get fully working. You can watch the below video +to learn more about what functionalities the kitbot has. If you're a bit confused after watching that video, don't +worry. We'll explain the kitbot more in depth in the next section. -And that's all you need to know to get started! -The rest of Stage 1A will cover how to get from the template code to a working kitbot. +And that's all you need to know to get started! The rest of Stage 1A will cover how to get from the template code to a +working kitbot. This stage will cover the following topics: diff --git a/src/content/docs/learning-course/stage1/stage1b/command-based-kitbot-pt2.mdx b/src/content/docs/learning-course/stage1/stage1b/command-based-kitbot-pt2.mdx index 9ee6afc3..4f5a0b87 100644 --- a/src/content/docs/learning-course/stage1/stage1b/command-based-kitbot-pt2.mdx +++ b/src/content/docs/learning-course/stage1/stage1b/command-based-kitbot-pt2.mdx @@ -20,15 +20,16 @@ In this second part of the kitbot rewrite, you will: ### Task 1: The Drivetrain Mechanism -Create a new Java class named `Drivetrain.java` in the `mechanisms` package. -This class should implement `Mechanism`. +Create a new Java class named `Drivetrain.java` in the `mechanisms` package. This class should implement `Mechanism`. Then, do the following: -1. Initialize four motors as private class fields: `leftLeader`, `leftFollower`, `rightLeader`, and `rightFollower`, which are on CANBus 0 and CAN IDs 0-3 respectively. +1. Initialize four motors as private class fields: `leftLeader`, `leftFollower`, `rightLeader`, and `rightFollower`, + which are on CANBus 0 and CAN IDs 0-3 respectively. 2. Initialize a `DifferentialDrive` object named `differentialDrive` with the left and right leader motors. 3. Initialize an `OnboardIMU` object named `imu`. -4. Initialize a `DrivetrainSim` object named `drivetrainSim` and make a method named `periodic()` that runs the drivetrain sim `periodic()` method. +4. Initialize a `DrivetrainSim` object named `drivetrainSim` and make a method named `periodic()` that runs the + drivetrain sim `periodic()` method.
Hint @@ -42,8 +43,10 @@ Now that we have a `Drivetrain` class, we can create `Command`s that control the To do that, write the following: 1. The drivetrain motor configuration code, which can be found in `Robot.java` from stage 1A. -2. An `idle()` command that commands `0.0` speed and `0.0` rotation, and is set as the default command in the constructor. -3. An `arcadeDrive(DoubleSupplier forwardThrottle, DoubleSupplier rotationThrottle)` command that continuously updates the drive motor speeds using the values from the suppliers. +2. An `idle()` command that commands `0.0` speed and `0.0` rotation, and is set as the default command in the + constructor. +3. An `arcadeDrive(DoubleSupplier forwardThrottle, DoubleSupplier rotationThrottle)` command that continuously updates + the drive motor speeds using the values from the suppliers.
Item 1, Hint 1 @@ -68,12 +71,10 @@ To do that, write the following: ### Task 3: Using the Drivetrain -1. Create a `Drivetrain` instance in `Robot.java` named `drivetrain`. - It should be a public instead of private. +1. Create a `Drivetrain` instance in `Robot.java` named `drivetrain`. It should be a public instead of private. 2. Call `drivetrain.periodic();` in the `robotPeriodic` method. -3. Then, open `MyTeleop.java` (your teleop OpMode). - In the constructor, set the drivetrain's default command to `arcadeDrive`. - Pass lambda expressions that read from your controller's joystick axes. +3. Then, open `MyTeleop.java` (your teleop OpMode). In the constructor, set the drivetrain's default command to + `arcadeDrive`. Pass lambda expressions that read from your controller's joystick axes.
Hint 1 @@ -92,19 +93,17 @@ To do that, write the following:
### Task 4: Create Auto Mode Files -Create 2 java files in the `opmode` package, named `DriveStraightAutoMode.java` and `TurnInPlaceAutoMode.java`, -before deleting the `MyAuto.java` file. -Copy-paste the following code in each file, -while replacing `MyOpModeName` with the correct name for each opmode: +Create 2 java files in the `opmode` package, named `DriveStraightAutoMode.java` and `TurnInPlaceAutoMode.java`, before +deleting the `MyAuto.java` file. Copy-paste the following code in each file, while replacing `MyOpModeName` with the +correct name for each opmode: ```java #opModeSkeleton @@ -112,14 +111,12 @@ while replacing `MyOpModeName` with the correct name for each opmode: ### Task 5: Drive Straight Autonomous -In the `start()` method of `DriveStraightAutoMode.java`, schedule -an `arcadeDrive` command with a timeout of 4 seconds. +In the `start()` method of `DriveStraightAutoMode.java`, schedule an `arcadeDrive` command with a timeout of 4 seconds. Then, do the following: 1. Rename the class defined in `DriveStraightAutoMode.java` to `DriveStraightAutoMode`. -2. In the `start()` method, schedule an `arcadeDrive` command with a timeout of 4 seconds. - This `arcadeDrive` command should have a constant forward throttle of `0.5` - and a constant rotational throttle of `0`. +2. In the `start()` method, schedule an `arcadeDrive` command with a timeout of 4 seconds. This `arcadeDrive` command + should have a constant forward throttle of `0.5` and a constant rotational throttle of `0`.
Hint 1 @@ -143,14 +140,13 @@ Then, do the following: ### Task 6: Rotate in Place Command -Create a new `Command` in `Drivetrain.java`, called `rotateInPlace`, -with the parameters `double angleDegrees` and `DoubleSupplier rotationThrottle`. -It should execute these actions, in order: +Create a new `Command` in `Drivetrain.java`, called `rotateInPlace`, with the parameters `double angleDegrees` and +`DoubleSupplier rotationThrottle`. It should execute these actions, in order: 1. Define a local variable, named `targetAngle`, whose value is the sum of `angleDegrees` and the robot's current yaw. To get the robot's current yaw, call `imu.getRotation2d().getDegrees()`. -2. Call `differentialDrive.arcadeDrive()` in a while loop, - which should continue while the robot's current yaw is less than the `targetAngle`. +2. Call `differentialDrive.arcadeDrive()` in a while loop, which should continue while the robot's current yaw is less + than the `targetAngle`.
Hint @@ -162,17 +158,15 @@ It should execute these actions, in order: ### Task 7: Rotate in Place Autonomous -Finally, use the `rotateInPlace` command to implement a turn-in-place autonomous within `TurnInPlaceAutoMode.java`. -It should rotate the robot 90 degrees from its starting position, at a throttle of 0.2. +Finally, use the `rotateInPlace` command to implement a turn-in-place autonomous within `TurnInPlaceAutoMode.java`. It +should rotate the robot 90 degrees from its starting position, at a throttle of 0.2.
Hint - Use the `Scheduler` to schedule a new `rotateInPlace` command, just like how - task 3 accomplishes this. + Use the `Scheduler` to schedule a new `rotateInPlace` command, just like how task 3 accomplishes this.
# Solution -The solutions to this stage can be found below: -[CTRE](https://github.com/frcsoftware/Stage1B-Solution-CTRE) +The solutions to this stage can be found below: [CTRE](https://github.com/frcsoftware/Stage1B-Solution-CTRE) [REV](https://github.com/frcsoftware/Stage1B-Solution-REV) diff --git a/src/content/docs/learning-course/stage1/stage1b/command-based-kitbot.mdx b/src/content/docs/learning-course/stage1/stage1b/command-based-kitbot.mdx index c7a52718..95e49a0f 100644 --- a/src/content/docs/learning-course/stage1/stage1b/command-based-kitbot.mdx +++ b/src/content/docs/learning-course/stage1/stage1b/command-based-kitbot.mdx @@ -13,22 +13,18 @@ import { TabItem, Tabs } from '@astrojs/starlight/components'; ### What You'll Accomplish -You will rewrite the code for a kitbot's intake launcher and feeder -mechanisms. -In part 2 of this exercise, you'll rewrite the drivetrain code -in command-based, and add some basic auto modes. +You will rewrite the code for a kitbot's intake launcher and feeder mechanisms. In part 2 of this exercise, you'll +rewrite the drivetrain code in command-based, and add some basic auto modes. ### Task 1: Setup -Use git to clone stage 1 template code. -Because both stage 1A and stage 1B -use the same template, use the following terminal command to create a new project: +Use git to clone stage 1 template code. Because both stage 1A and stage 1B use the same template, use the following +terminal command to create a new project: @@ -48,9 +44,8 @@ use the same template, use the following terminal command to create a new projec -Then, navigate to the `Robot` class under `src/main/java/first/robot`. -For commands to function, you must call `Scheduler.getDefault().run()` in -the robot class' `robotPeriodic()` method. +Then, navigate to the `Robot` class under `src/main/java/first/robot`. For commands to function, you must call +`Scheduler.getDefault().run()` in the robot class' `robotPeriodic()` method. ```java #robotDef @@ -58,22 +53,18 @@ the robot class' `robotPeriodic()` method. ### Task 2: The Feeder Mechanism -Create a new package named `mechanisms` under the `robot` package. -Remember that -packages are folders that contain java files. -The `mechanisms` package -will contain the code for our feeder and intake launcher mechanisms. +Create a new package named `mechanisms` under the `robot` package. Remember that packages are folders that contain java +files. The `mechanisms` package will contain the code for our feeder and intake launcher mechanisms. -Then, create a new file in the `mechanisms` package named `Feeder.java`. -Define a class named `Feeder` that implements `Mechanism`, then add the following: +Then, create a new file in the `mechanisms` package named `Feeder.java`. Define a class named `Feeder` that implements +`Mechanism`, then add the following: -1. A private `TalonFX` or `SparkMax` motor controller object, named `motor`, with an ID of 5. - It is connected to a systemcore CANBus with ID 0. +1. A private `TalonFX` or `SparkMax` motor controller object, named `motor`, with an ID of 5. It is connected to a + systemcore CANBus with ID 0. 2. A `feed()` command that sets the throttle of the motor to 0.75 forever. 3. An `intake()` command that sets the throttle of the motor to -1 forever. 4. An `outtake()` command that sets the throttle of the motor to 1 forever. -5. An `idle()` command that sets the throttle of the motor to 0 forever. - Make this the default command. +5. An `idle()` command that sets the throttle of the motor to 0 forever. Make this the default command. The `feed()`, `intake()`, `outtake()` and `idle()` commands should be returned from methods. @@ -114,8 +105,7 @@ The `feed()`, `intake()`, `outtake()` and `idle()` commands should be returned f inside of the constructor.
-After completing all of that, copy-paste the following code into the `Feeder` class -to allow for simulation to work: +After completing all of that, copy-paste the following code into the `Feeder` class to allow for simulation to work: ```java #feederSim @@ -123,20 +113,17 @@ to allow for simulation to work: ### Task 3: The IntakeLauncher Mechanism -Create a file named `IntakeLauncher.java` in the `mechanisms` package. -Define a class named `IntakeLauncher` that implements `Mechanism`; then, add the following: +Create a file named `IntakeLauncher.java` in the `mechanisms` package. Define a class named `IntakeLauncher` that +implements `Mechanism`; then, add the following: -1. A private `TalonFX` or `SparkMax` motor controller object, named `motor`, with an ID of 4. - It is connected to a systemcore CANBus with ID 0. +1. A private `TalonFX` or `SparkMax` motor controller object, named `motor`, with an ID of 4. It is connected to a + systemcore CANBus with ID 0. 2. A `shoot()` command that waits 2 seconds, then sets the throttle of the motor to 0.9 forever. 3. A `intake()` command that sets throttle to 0.8 forever. 4. A `outtake()` command that sets throttle to -0.8 forever. -5. A `idle()` command that sets throttle to 0 forever. - Make this the default command. -6. The code needed for simulating the intake launcher. - You haven't officially learned - how to do this, but task 2's final section gives a hint. - Can you figure it out? +5. A `idle()` command that sets throttle to 0 forever. Make this the default command. +6. The code needed for simulating the intake launcher. You haven't officially learned how to do this, but task 2's final + section gives a hint. Can you figure it out?
Item 2 Hint @@ -154,14 +141,11 @@ Define a class named `IntakeLauncher` that implements `Mechanism`; then, add the ### Task 4: Finish the `Robot` class -Create new instances of the `IntakeLauncher` and `Feeder` classes. -They should be -public properties of the `Robot` class, so that they are accessible from opmodes. -Name them `intakeLauncher` and `feeder`, respectively. +Create new instances of the `IntakeLauncher` and `Feeder` classes. They should be public properties of the `Robot` +class, so that they are accessible from opmodes. Name them `intakeLauncher` and `feeder`, respectively. -You also need to call `intakeLauncher.periodic();` and `feeder.periodic();` -within a method of the `Robot` class. -Which method should it be? +You also need to call `intakeLauncher.periodic();` and `feeder.periodic();` within a method of the `Robot` class. Which +method should it be?
Hint @@ -170,17 +154,17 @@ Which method should it be? ### Task 5: Finish the teleop OpMode -In the constructor of the teleop opmode (it should be in `MyTeleop.java`), -create a private `CommandXboxController` instance named `xbox`. +In the constructor of the teleop opmode (it should be in `MyTeleop.java`), create a private `CommandXboxController` +instance named `xbox`. In your opmode constructor, define the following behavior: -1. While the `xbox.leftBumper()` trigger is active, - run the `robot.intakeLauncher.intake()` and `robot.feeder.intake()` commands. -2. While the `xbox.rightBumper()` trigger is active, - run the `robot.intakeLauncher.shoot()` and `robot.feeder.feed()` commands. -3. While the `xbox.a()` trigger is active, - run the `robot.intakeLauncher.outtake()` and `robot.feeder.outtake()` commands. +1. While the `xbox.leftBumper()` trigger is active, run the `robot.intakeLauncher.intake()` and `robot.feeder.intake()` + commands. +2. While the `xbox.rightBumper()` trigger is active, run the `robot.intakeLauncher.shoot()` and `robot.feeder.feed()` + commands. +3. While the `xbox.a()` trigger is active, run the `robot.intakeLauncher.outtake()` and `robot.feeder.outtake()` + commands.
Hint diff --git a/src/content/docs/learning-course/stage1/stage1b/command-based-overview.mdx b/src/content/docs/learning-course/stage1/stage1b/command-based-overview.mdx index 6c75ad3d..bc85fe76 100644 --- a/src/content/docs/learning-course/stage1/stage1b/command-based-overview.mdx +++ b/src/content/docs/learning-course/stage1/stage1b/command-based-overview.mdx @@ -10,19 +10,16 @@ import ContentImage from '@components/ContentImage.astro'; ### What is Command-Based Programming? -Up until now, most of the code you've written has been akin to a -set of instructions (execute this task, then this, and finally this). -However, robots (and humans!) don't just execute a set of tasks and shut down. +Up until now, most of the code you've written has been akin to a set of instructions (execute this task, then this, and +finally this). However, robots (and humans!) don't just execute a set of tasks and shut down. -Imagine your daily routine. -When your alarm clock rings, you turn it off, then tumble out of bed. -When your belly rumbles, you walk to the fridge, then get a snack. -When the clock strikes 8 AM, you open the front door to leave for school. +Imagine your daily routine. When your alarm clock rings, you turn it off, then tumble out of bed. When your belly +rumbles, you walk to the fridge, then get a snack. When the clock strikes 8 AM, you open the front door to leave for +school. -Notice how none of these actions had a predefined order; rather, they were a reaction to -certain kinds of stimuli. +Notice how none of these actions had a predefined order; rather, they were a reaction to certain kinds of stimuli. Command-based programming models robot behavior in a similar way. @@ -36,49 +33,38 @@ For instance, a command-based robot might have the following structure: Here, everything on the left is a `Trigger`, while everything on the right is a `Command`. ### Mechanisms and Priority However, the structure of using `Command`s to represent behaviors misses an important component. -Think back to the human example: you’re walking to the fridge, but the clock hits 8 AM before you get there. -You can't do both at once, since both actions require your arms and legs. -So, you stop, then leave for school. +Think back to the human example: you’re walking to the fridge, but the clock hits 8 AM before you get there. You can't +do both at once, since both actions require your arms and legs. So, you stop, then leave for school. -Next, the robot. -If the X and Y buttons are held, the shooter and intake motors should both run. -But if the X and A buttons are held, the robot code must choose between running the shooter -at a fast speed or a slow speed. +Next, the robot. If the X and Y buttons are held, the shooter and intake motors should both run. But if the X and A +buttons are held, the robot code must choose between running the shooter at a fast speed or a slow speed. Command-Based models this relationship with 2 concepts: Mechanisms and Priority. ##### Mechanisms -A Mechanism is a robot component whose state can be updated through commands. -`Command`s declare -the mechanisms they require - thus, mechanisms are also called "requirements". +A Mechanism is a robot component whose state can be updated through commands. `Command`s declare the mechanisms they +require - thus, mechanisms are also called "requirements". -An intake is a mechanism because your code controls its speed. -On the other hand, -an apriltag camera wouldn't be because your code only reads data from it, but doesn't update its state. +An intake is a mechanism because your code controls its speed. On the other hand, an apriltag camera wouldn't be because +your code only reads data from it, but doesn't update its state. - + ##### Priority -When 2 commands share one or more requirements, priority determines which command -should be canceled and which command should continue. +When 2 commands share one or more requirements, priority determines which command should be canceled and which command +should continue. -In the human example, the "leave for school" `Command` would have a higher priority -than the "get a snack" `Command`. +In the human example, the "leave for school" `Command` would have a higher priority than the "get a snack" `Command`. -Priority is represented as an `int`. -Commands default to a priority of 0, and a -larger number represents a higher priority. +Priority is represented as an `int`. Commands default to a priority of 0, and a larger number represents a higher +priority. diff --git a/src/content/docs/learning-course/stage1/stage1b/commands-and-mechanisms-pt2.mdx b/src/content/docs/learning-course/stage1/stage1b/commands-and-mechanisms-pt2.mdx index 9d88b62f..733b3d9b 100644 --- a/src/content/docs/learning-course/stage1/stage1b/commands-and-mechanisms-pt2.mdx +++ b/src/content/docs/learning-course/stage1/stage1b/commands-and-mechanisms-pt2.mdx @@ -11,19 +11,15 @@ import ContentImage from '@components/ContentImage.astro'; ### Default Commands -Most mechanisms define a "default command" that runs when -no other commands requiring it are active. -The default command -of an intake or a shooter, for instance, would be setting the throttle -of all motors to 0, forever. +Most mechanisms define a "default command" that runs when no other commands requiring it are active. The default command +of an intake or a shooter, for instance, would be setting the throttle of all motors to 0, forever. -To set a mechanism's default command, simply call `setDefaultCommand(Command)`, which is -an instance method of all mechanisms: +To set a mechanism's default command, simply call `setDefaultCommand(Command)`, which is an instance method of all +mechanisms: ```java #defaultCommand @@ -31,8 +27,7 @@ an instance method of all mechanisms: ### Adding Delays to Commands -Use `coroutine.wait()` to wait for a predefined amount of time within -the body of a command: +Use `coroutine.wait()` to wait for a predefined amount of time within the body of a command: ```java #delayCommand @@ -46,14 +41,13 @@ You can also give an existing command a timeout with the `withTimeout()` modifie ### More commands info -The following information isn't strictly needed for -the exercises in stage 1b; however, they will be very -useful for future exercises and coding a real robot. +The following information isn't strictly needed for the exercises in stage 1b; however, they will be very useful for +future exercises and coding a real robot. #### Commands without requirements -Sometimes, you need to create a command that doesn't require any mechanisms. -To do so, you can replace `run(...)` with `Command.noRequirements(...)`. +Sometimes, you need to create a command that doesn't require any mechanisms. To do so, you can replace `run(...)` with +`Command.noRequirements(...)`. ```java #noRequirementsCommand @@ -61,13 +55,12 @@ To do so, you can replace `run(...)` with `Command.noRequirements(...)`. #### Running Commands in parallel -`coroutine.awaitAll(a, b, c)` will run the commands a, b, and c in parallel, -waiting for all 3 to finish before proceeding. +`coroutine.awaitAll(a, b, c)` will run the commands a, b, and c in parallel, waiting for all 3 to finish before +proceeding. ```java #parallelCommands ``` -On the other hand, `coroutine.awaitAny(a, b, c)` runs a, b, and c in parallel -until any of a, b, or c finishes. -Then, it will cancel the remaining commands. +On the other hand, `coroutine.awaitAny(a, b, c)` runs a, b, and c in parallel until any of a, b, or c finishes. Then, it +will cancel the remaining commands. diff --git a/src/content/docs/learning-course/stage1/stage1b/commands-and-mechanisms.mdx b/src/content/docs/learning-course/stage1/stage1b/commands-and-mechanisms.mdx index c025a939..6c364531 100644 --- a/src/content/docs/learning-course/stage1/stage1b/commands-and-mechanisms.mdx +++ b/src/content/docs/learning-course/stage1/stage1b/commands-and-mechanisms.mdx @@ -17,25 +17,22 @@ Mechanisms are simply classes that have the `implements Mechanism` keyword: ``` -In general, you should create one instance of each mechanism, and that instance should be stored -in your robot class: +In general, you should create one instance of each mechanism, and that instance should be stored in your robot class: ```java #mechanismInRobotDef ``` ### Defining Commands -Most commands are defined inside of the file containing the class of a mechanism -(like Intake.java or Shooter.java). -The code below defines a new `Command`: +Most commands are defined inside of the file containing the class of a mechanism (like Intake.java or Shooter.java). The +code below defines a new `Command`: ```java #commandDef @@ -43,24 +40,20 @@ The code below defines a new `Command`: Notice that: -- Every line of code between `coroutine -> {` and `}` will be run - when the command runs, like a method body. -- This command will print "Full Speed Baby!" once before commanding - the motor to spin at max speed. -- The `named("Set to Full Throttle")` call is required to create a `Command`.[^1] - This allows coders to distinguish this command from others when debugging their code. +- Every line of code between `coroutine -> {` and `}` will be run when the command runs, like a method body. +- This command will print "Full Speed Baby!" once before commanding the motor to spin at max speed. +- The `named("Set to Full Throttle")` call is required to create a `Command`.[^1] This allows coders to distinguish this + command from others when debugging their code. -To change the priority of the command, simply add a `withPriority(int)` call before -you call `named()`: +To change the priority of the command, simply add a `withPriority(int)` call before you call `named()`: ```java #commandWithPriorityDef ``` ### Combining Commands and Mechanisms @@ -71,11 +64,11 @@ Here's an example of a command defined inside of a mechanism class: ``` -Commands created with `run()` will automatically require the mechanism that they are defined inside. -Here, the full throttle command requires the `Intake`. +Commands created with `run()` will automatically require the mechanism that they are defined inside. Here, the full +throttle command requires the `Intake`. -Also, notice that the `fullThrottle` method creates and returns a command. -All mechanism-specific commands should be defined this way, for 2 reasons: +Also, notice that the `fullThrottle` method creates and returns a command. All mechanism-specific commands should be +defined this way, for 2 reasons: 1. It allows for commands to define parameters, just like a method. 2. It gives the `Robot` class easy access to these commands. @@ -84,8 +77,7 @@ All mechanism-specific commands should be defined this way, for 2 reasons: ``` -However, this approach requires caution. -Observe the snippet below: +However, this approach requires caution. Observe the snippet below: {/* rli:ignore */} @@ -99,10 +91,8 @@ public Command printHiThenFullThrottle() { } ``` -Calling the `fullThrottle()` -method, as shown, doesn't spin the motor, but instead creates a `Command` object that must be run separately. -The java -compiler will catch this and throw a compile-time error. +Calling the `fullThrottle()` method, as shown, doesn't spin the motor, but instead creates a `Command` object that must +be run separately. The java compiler will catch this and throw a compile-time error. ### Command Sequences -If you want to run the `fullThrottle` command inside of another command, you must -call `coroutine.await(Command)`, like so: +If you want to run the `fullThrottle` command inside of another command, you must call `coroutine.await(Command)`, like +so: ```java #commandAwait @@ -136,4 +126,6 @@ That means you can run multiple commands in sequence: ``` -[^1]: WPILib JavaDocs for [`NeedsNameBuilderStage.named()`]() +[^1]: + WPILib JavaDocs for + [`NeedsNameBuilderStage.named()`]() diff --git a/src/content/docs/learning-course/stage1/stage1b/spot-the-error-pt2.mdx b/src/content/docs/learning-course/stage1/stage1b/spot-the-error-pt2.mdx index dcea6c47..c2e9986d 100644 --- a/src/content/docs/learning-course/stage1/stage1b/spot-the-error-pt2.mdx +++ b/src/content/docs/learning-course/stage1/stage1b/spot-the-error-pt2.mdx @@ -9,8 +9,7 @@ codeRegionSources: ### Exercise 1 -"Hello World!" doesn't show up in the console while the a button is pressed. -Can you spot the error? +"Hello World!" doesn't show up in the console while the a button is pressed. Can you spot the error? ```java #robotPeriodicBug diff --git a/src/content/docs/learning-course/stage1/stage1b/spot-the-error.mdx b/src/content/docs/learning-course/stage1/stage1b/spot-the-error.mdx index abc4eb6f..ce7dd1f2 100644 --- a/src/content/docs/learning-course/stage1/stage1b/spot-the-error.mdx +++ b/src/content/docs/learning-course/stage1/stage1b/spot-the-error.mdx @@ -11,21 +11,16 @@ import Aside from '@components/Aside.astro'; ### The Purpose of this Section -By looking through buggy code snippets that use command-based programming, -you can hopefully get a better intuition on how to spot common bugs and write better code. -If you are confident in your skills, you can skip ahead to the stage 1B exercise, but -the authors still highly recommend it. +By looking through buggy code snippets that use command-based programming, you can hopefully get a better intuition on +how to spot common bugs and write better code. If you are confident in your skills, you can skip ahead to the stage 1B +exercise, but the authors still highly recommend it. - + ### Exercise 1 -This code is supposed to spin the intake while the left bumper is held. -The intake should stop when the bumper is released. -It also compiles fine. +This code is supposed to spin the intake while the left bumper is held. The intake should stop when the bumper is +released. It also compiles fine. ```java #intakeOnTrueBug @@ -47,8 +42,7 @@ Can you spot the error? ### Exercise 2 -The `aButtonTrigger` is supposed to run a command while the A button is held. -The code compiles fine. +The `aButtonTrigger` is supposed to run a command while the A button is held. The code compiles fine. ```java #triggerCapturedValueBug @@ -107,16 +101,15 @@ Can you fix the compile-time error and the logic error? ### Exercise 4 -You've fixed the intake (reveal the answer to exercise 3 to see the full class), -and have the following code to run it while the left bumper is held: +You've fixed the intake (reveal the answer to exercise 3 to see the full class), and have the following code to run it +while the left bumper is held: ```java #intakeWhileTrue ``` -You hold down the left bumper, and the intake starts spinning; but releasing it doesn't -stop the intake. -Can you spot the error? +You hold down the left bumper, and the intake starts spinning; but releasing it doesn't stop the intake. Can you spot +the error?
Hint diff --git a/src/content/docs/learning-course/stage1/stage1b/stage-overview.mdx b/src/content/docs/learning-course/stage1/stage1b/stage-overview.mdx index 18b35719..cae42c2f 100644 --- a/src/content/docs/learning-course/stage1/stage1b/stage-overview.mdx +++ b/src/content/docs/learning-course/stage1/stage1b/stage-overview.mdx @@ -3,19 +3,21 @@ title: Stage 1B Overview description: An overview of Stage 1B --- -Stage 1A used a simple sequential approach to controlling the kitbot. -But real robots need to respond to many inputs at once, like button presses, sensor data, and vision. -Command-based programming solves this by modeling robot behavior as commands (actions) triggered by triggers (events). +Stage 1A used a simple sequential approach to controlling the kitbot. But real robots need to respond to many inputs at +once, like button presses, sensor data, and vision. Command-based programming solves this by modeling robot behavior as +commands (actions) triggered by triggers (events). ## Key Concepts Commands define individual robot actions (deploy the intake, index a game piece, drive based on joystick inputs). -Triggers define when commands should run (controller input, sensor data reaches a certain threshold, the start of autonomous or teleop). -Mechanisms represent the physical robot mechanisms that commands require and control (intake, indexer, drivetrain). +Triggers define when commands should run (controller input, sensor data reaches a certain threshold, the start of +autonomous or teleop). Mechanisms represent the physical robot mechanisms that commands require and control (intake, +indexer, drivetrain). ## Stage 1B Goals -By the end of Stage 1B, you'll rewrite your Stage 1A kitbot code into a command-based architecture, adding controller bindings, default commands, and simple autonomous routines. +By the end of Stage 1B, you'll rewrite your Stage 1A kitbot code into a command-based architecture, adding controller +bindings, default commands, and simple autonomous routines. This stage will cover the following topics: diff --git a/src/content/docs/learning-course/stage1/stage1b/suppliers-in-command-based.mdx b/src/content/docs/learning-course/stage1/stage1b/suppliers-in-command-based.mdx index 9f5c81a0..dfbcd62c 100644 --- a/src/content/docs/learning-course/stage1/stage1b/suppliers-in-command-based.mdx +++ b/src/content/docs/learning-course/stage1/stage1b/suppliers-in-command-based.mdx @@ -24,17 +24,15 @@ And the following code in Robot.java: ``` When you run the preceding code, what happens? 1. The intake does a little dance before rejoicing your coding skills. -2. The intake runs at a speed dependent on how far up or down the joystick - on the left is pushed. +2. The intake runs at a speed dependent on how far up or down the joystick on the left is pushed. 3. The intake does nothing.
@@ -44,27 +42,24 @@ When you run the preceding code, what happens? ### But Why? -Recall that the constructor of the `Robot` class is called when the -robot code is first loaded, not when the robot is enabled. -At this point, -your hands aren't even on the controller - so, the value of `controllerOutput` would be 0. +Recall that the constructor of the `Robot` class is called when the robot code is first loaded, not when the robot is +enabled. At this point, your hands aren't even on the controller - so, the value of `controllerOutput` would be 0. -When the robot is enabled, the value of `getLeftY()` will change; however, the value of the `throttle` -parameter passed into the `runAtThrottle` command cannot, because it's value has already been determined -before the command has even began. +When the robot is enabled, the value of `getLeftY()` will change; however, the value of the `throttle` parameter passed +into the `runAtThrottle` command cannot, because it's value has already been determined before the command has even +began. ### Fixing the problem -In java, we use a `DoubleSupplier` to represent a value of type `double` that is constantly changing. -We call `getAsDouble()` to fetch its current value. +In java, we use a `DoubleSupplier` to represent a value of type `double` that is constantly changing. We call +`getAsDouble()` to fetch its current value. ```java #runAtThrottleSupplier ``` -`DoubleSupplier` instances are created with the syntax of `() -> expression`, with the caveat that -the expression must return a `double`. -Calling `getAsDouble()` will evaluate that expression. +`DoubleSupplier` instances are created with the syntax of `() -> expression`, with the caveat that the expression must +return a `double`. Calling `getAsDouble()` will evaluate that expression. ```java #doubleSupplierExample @@ -82,27 +77,20 @@ Here is how we would define and use a `DoubleSupplier` in our previous example: ### `BooleanSupplier`s and the `until()` Command Modifier -You might recognize the `() ->` syntax used to define `DoubleSupplier`s. -As it turns out, -we define `Trigger`s with that syntax: +You might recognize the `() ->` syntax used to define `DoubleSupplier`s. As it turns out, we define `Trigger`s with that +syntax: ```java #triggerBooleanSupplier ``` -Notice, however, that the expression to the left of the `() ->` statement is -a `boolean` instead of a `double`. -As it turns out, the constructor for a `Trigger` -takes a `BooleanSupplier`. +Notice, however, that the expression to the left of the `() ->` statement is a `boolean` instead of a `double`. As it +turns out, the constructor for a `Trigger` takes a `BooleanSupplier`. - + -`BooleanSupplier`s are used in one other place: adding stop conditions to commands. -You can use the `until(BooleanSupplier)` method to add an arbitrary stop condition -to a command: +`BooleanSupplier`s are used in one other place: adding stop conditions to commands. You can use the +`until(BooleanSupplier)` method to add an arbitrary stop condition to a command: ```java #untilModifier diff --git a/src/content/docs/learning-course/stage1/stage1b/the-command-body.mdx b/src/content/docs/learning-course/stage1/stage1b/the-command-body.mdx index 389334d9..ca366769 100644 --- a/src/content/docs/learning-course/stage1/stage1b/the-command-body.mdx +++ b/src/content/docs/learning-course/stage1/stage1b/the-command-body.mdx @@ -11,9 +11,8 @@ import Aside from '@components/Aside.astro'; ### Something Looks Familiar Here... -If you've ever coded in Scratch, with blocks, or taken an intro to programming class, -you've probably written software as a sequence of statements. -Like so: +If you've ever coded in Scratch, with blocks, or taken an intro to programming class, you've probably written software +as a sequence of statements. Like so: ```java #triangleLoop @@ -21,9 +20,8 @@ Like so: (In case you were curious - this prints a triangle to the console.) -From the previous section, you might remember that command-based programming, -as a whole, cannot be represented with just a sequence of statements. -However, individual commands (or robot actions) can. +From the previous section, you might remember that command-based programming, as a whole, cannot be represented with +just a sequence of statements. However, individual commands (or robot actions) can. For instance, this command body runs a motor at full speed forever: @@ -37,27 +35,24 @@ And this command body would rotate your robot by roughly 90 degrees, then stop: ``` -Fundamentally, the commands (or robot actions) themselves can be represented with familiar -programming structures: while loops, variables, method calls, and more. +Fundamentally, the commands (or robot actions) themselves can be represented with familiar programming structures: while +loops, variables, method calls, and more. ### The Meaning of `coroutine.yield();` -`coroutine.yield()` is a special statement that must be called inside of while loops. -It allows for commands to run in parallel, while ensuring that background tasks -(like motor safety checks) are run. -An analogy would be the sips of water you take while you finish your homework. +`coroutine.yield()` is a special statement that must be called inside of while loops. It allows for commands to run in +parallel, while ensuring that background tasks (like motor safety checks) are run. An analogy would be the sips of water +you take while you finish your homework. -The `coroutine` object contains many other useful methods that can only be called -inside of commands. -Some of these will be mentioned in the following sections. +The `coroutine` object contains many other useful methods that can only be called inside of commands. Some of these will +be mentioned in the following sections. diff --git a/src/content/docs/learning-course/stage1/stage1b/triggers.mdx b/src/content/docs/learning-course/stage1/stage1b/triggers.mdx index 8afb9719..e179f60c 100644 --- a/src/content/docs/learning-course/stage1/stage1b/triggers.mdx +++ b/src/content/docs/learning-course/stage1/stage1b/triggers.mdx @@ -11,14 +11,13 @@ import Aside from '@components/Aside.astro'; ### A quick recap -Remember that `Trigger`s are the stimuli that trigger robot behavior, which we call `Command`s. -We say that `Trigger`s "schedule" `Command`s. +Remember that `Trigger`s are the stimuli that trigger robot behavior, which we call `Command`s. We say that `Trigger`s +"schedule" `Command`s. ### How triggers are defined -sources/Triggers, at their core, are methods that return a boolean - true for active, and false for inactive. -You can fetch -a trigger's active status with the `getAsBoolean()` method: +sources/Triggers, at their core, are methods that return a boolean - true for active, and false for inactive. You can +fetch a trigger's active status with the `getAsBoolean()` method: ```java #motorTooFastTrigger @@ -26,16 +25,16 @@ a trigger's active status with the `getAsBoolean()` method: Triggers can schedule commands in two ways: -1. `trigger.onTrue(Command)`: Schedules a command when a trigger switches from inactive to active. - In the following example, the `runAtThrottle` command will run once teleop mode is selected and enabled. +1. `trigger.onTrue(Command)`: Schedules a command when a trigger switches from inactive to active. In the following + example, the `runAtThrottle` command will run once teleop mode is selected and enabled. ```java #teleopEnabledRobot ``` -2. `trigger.whileTrue(Command)`: Identical to onTrue, but cancels the running command when the trigger becomes inactive again. - If `teleopEnabledTrigger.onTrue(...)` was changed to `teleopEnabledTrigger.whileTrue(...)`, disabling teleop mode - on the driver station will cancel the `runAtThrottle` command mid-run. +2. `trigger.whileTrue(Command)`: Identical to onTrue, but cancels the running command when the trigger becomes inactive + again. If `teleopEnabledTrigger.onTrue(...)` was changed to `teleopEnabledTrigger.whileTrue(...)`, disabling teleop + mode on the driver station will cancel the `runAtThrottle` command mid-run.