Skip to content

Commit d7aa645

Browse files
jasondamingjasondaming
committed
Add Commands v3 documentation outline (Phase 2)
Create skeleton structure for Commands v3 documentation with section headers and TODO notes describing what content should go in each section. This phase establishes the documentation organization for review before content is written. Files created: - index.rst: Landing page with overview and quick examples - what-is-commands-v3.rst: Conceptual foundation and core concepts - getting-started.rst: Hands-on tutorial for first v3 program - mechanisms.rst: Deep dive into Mechanisms (v3's Subsystems) - commands-and-coroutines.rst: Core command creation and coroutine API - async-await-patterns.rst: Async/await helpers for orchestration - command-compositions.rst: Traditional composition groups - binding-commands-to-triggers.rst: Button bindings and triggers - priorities-and-interrupts.rst: Priority system and interruption - structuring-v3-project.rst: Code organization best practices - testing-and-simulation.rst: Testing commands with simulation - telemetry-and-debugging.rst: Enhanced telemetry and debugging - migration-from-v2.rst: Migration guide from v2 to v3 - advanced-topics.rst: Advanced patterns and edge cases Each file contains: - Section headers outlining the article structure - TODO directives describing what content should be written - Guidance for future content writers on what to include No actual tutorial content or code examples are included - this is purely structural planning for review. Related to #3095 Related to #3165
1 parent 99e9d0f commit d7aa645

14 files changed

+1213
-0
lines changed

‎source/docs/software/commandbased/commands-v3/advanced-topics.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Advanced Topics
2+
3+
.. todo::
4+
This article covers advanced patterns, optimizations, and edge cases in Commands v3. This content is for experienced teams who have mastered the basics and want to push v3 to its limits or handle unusual requirements.
5+
6+
## Custom Command Base Classes
7+
8+
.. todo::
9+
Explain how and when to create custom base classes for commands. Cover:
10+
- When custom base classes are useful vs. unnecessary abstraction
11+
- Creating abstract command base classes with common functionality
12+
- Decorator pattern for command functionality
13+
- Wrapping commands to add cross-cutting concerns
14+
- Best practices for base class design
15+
- Examples of useful base class patterns (describe scenarios, not full implementations)
16+
17+
## Dynamic Command Generation
18+
19+
.. todo::
20+
Explain patterns for generating commands dynamically at runtime. Cover:
21+
- When dynamic command generation is needed
22+
- Creating commands from parameters/configuration
23+
- Path planning and generated trajectories as commands
24+
- Loading command sequences from files or network
25+
- Command builders and fluent APIs
26+
- Performance considerations for dynamic generation
27+
- Memory management for dynamically created commands
28+
- Examples of dynamic generation scenarios
29+
30+
## Performance Optimization
31+
32+
.. todo::
33+
Provide guidance on optimizing v3 command performance. Cover:
34+
- Understanding scheduler overhead
35+
- Minimizing allocations in command execution
36+
- Efficient trigger condition evaluation
37+
- Optimizing periodic operations
38+
- Profiling v3 command code
39+
- Trade-offs between readability and performance
40+
- When optimization matters vs. premature optimization
41+
- Benchmarking techniques
42+
43+
## Advanced Async Patterns
44+
45+
.. todo::
46+
Showcase advanced patterns using async/await and coroutines. Cover:
47+
- Command pipelines and streaming patterns
48+
- State machines implemented with async/await
49+
- Error handling and recovery with async commands
50+
- Cancellation and timeout patterns
51+
- Resource pooling and management
52+
- Coordinating multiple mechanisms with complex dependencies
53+
- Real-time responsive commands with background processing
54+
- Describe complex scenarios and how to implement them with v3 features
55+
56+
## Edge Cases and Gotchas
57+
58+
.. todo::
59+
Document edge cases, limitations, and common pitfalls. Cover:
60+
- Commands that never yield (infinite loops without yield)
61+
- Forked commands and lifecycle management
62+
- Nested trigger scopes and cleanup
63+
- Priority conflicts and circular dependencies
64+
- Requirements conflicts with complex command compositions
65+
- Thread safety considerations (if any)
66+
- Limitations of the coroutine model
67+
- Breaking scheduler assumptions
68+
- Memory leaks and resource exhaustion
69+
- Common mistakes and how to avoid them
70+
- What NOT to do in v3 commands

‎source/docs/software/commandbased/commands-v3/async-await-patterns.rst‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Async/Await Patterns
2+
3+
.. todo::
4+
This article explains the async/await helper functions that enable advanced command orchestration in v3. These functions allow commands to launch other commands and wait for them to complete, enabling powerful composition patterns. Teams should understand basic command creation before reading this article.
5+
6+
## Introduction to Async/Await
7+
8+
.. todo::
9+
Provide an overview of async/await in Commands v3. Cover:
10+
- What async/await means in the context of v3 (not OS-level async)
11+
- Why async/await is useful for command orchestration
12+
- How async/await differs from composition groups
13+
- When to use async/await vs. other patterns
14+
- High-level mental model for how it works with the scheduler
15+
- Relationship to coroutines and yield()
16+
17+
## await()
18+
19+
.. todo::
20+
Explain the await() function in detail. Cover:
21+
- What await(command) does: schedule a command and wait for it to complete
22+
- How await() blocks the calling command until the child completes
23+
- Requirements and priority handling with awaited commands
24+
- What happens if the awaited command is interrupted
25+
- What happens if the parent command is interrupted
26+
- Return values and status from awaited commands
27+
- Examples of await() patterns (describe what examples should show)
28+
29+
## awaitAll()
30+
31+
.. todo::
32+
Explain the awaitAll() function in detail. Cover:
33+
- What awaitAll(commands) does: wait for multiple commands in parallel
34+
- How awaitAll() differs from await() in a loop
35+
- When all commands must complete vs. early termination scenarios
36+
- Requirements management across multiple parallel commands
37+
- Error and interruption handling
38+
- Performance implications of parallel execution
39+
- Examples of awaitAll() patterns (describe what examples should show)
40+
41+
## awaitAny()
42+
43+
.. todo::
44+
Explain the awaitAny() function in detail. Cover:
45+
- What awaitAny(commands) does: wait until any command completes
46+
- Race condition semantics: which command "wins"
47+
- What happens to other commands when one completes
48+
- Use cases for awaitAny() (timeouts, alternative paths, etc.)
49+
- How interruption is handled
50+
- Differences from race groups in composition
51+
- Examples of awaitAny() patterns (describe what examples should show)
52+
53+
## fork()
54+
55+
.. todo::
56+
Explain the fork() function in detail. Cover:
57+
- What fork(command) does: launch a command without waiting for it
58+
- "Fire and forget" semantics
59+
- When to use fork() vs. await()
60+
- Lifecycle of forked commands relative to parent
61+
- Requirements and priority considerations
62+
- Common use cases (background operations, side effects, etc.)
63+
- Potential pitfalls and how to avoid them
64+
- Examples of fork() patterns (describe what examples should show)
65+
66+
## Practical Patterns
67+
68+
.. todo::
69+
Showcase common practical patterns combining async/await functions. Cover:
70+
- Timeout patterns using awaitAny() with wait()
71+
- Sequential operations with conditional logic
72+
- Parallel operations with synchronization points
73+
- Launching background tasks with fork()
74+
- Complex state machines using async/await
75+
- Error recovery and fallback patterns
76+
- Describe several real-world scenarios and which async/await functions to combine

‎source/docs/software/commandbased/commands-v3/binding-commands-to-triggers.rst‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Binding Commands to Triggers
2+
3+
.. todo::
4+
This article explains how to connect commands to button inputs and other events using the trigger system. Triggers are how robot code responds to driver input and sensor events. This is essential knowledge for any team using Commands v3.
5+
6+
## Triggers Overview
7+
8+
.. todo::
9+
Provide an overview of the trigger system in v3. Cover:
10+
- What triggers are and their role in the command framework
11+
- How triggers differ from directly calling command.schedule()
12+
- When trigger bindings are evaluated by the scheduler
13+
- Available trigger sources (buttons, joysticks, sensors, custom)
14+
- High-level syntax for creating and binding triggers
15+
- How v3 triggers compare to v2 triggers
16+
17+
## Button Bindings
18+
19+
.. todo::
20+
Explain how to bind commands to physical buttons. Cover:
21+
- Accessing button triggers from controllers/joysticks
22+
- Available binding methods: onTrue(), onFalse(), whileTrue(), whileFalse(), toggleOnTrue(), etc.
23+
- When each binding type activates and deactivates commands
24+
- Multiple bindings on the same button
25+
- Button composition (modifier keys, button combinations)
26+
- Best practices for organizing button bindings in RobotContainer
27+
- Examples of common button binding patterns (describe what examples should show)
28+
29+
## Creating Custom Triggers
30+
31+
.. todo::
32+
Explain how to create custom triggers beyond simple buttons. Cover:
33+
- Creating triggers from boolean supplier functions
34+
- Sensor-based triggers (limit switches, photoelectric sensors, etc.)
35+
- State-based triggers (robot state, game piece detection, etc.)
36+
- Time-based triggers
37+
- Network table triggers
38+
- Performance considerations for trigger condition functions
39+
- Best practices for custom trigger implementation
40+
- Examples of custom trigger patterns (describe what examples should show)
41+
42+
## Trigger Composition
43+
44+
.. todo::
45+
Explain how to compose triggers using logical operations. Cover:
46+
- Available composition operations: and(), or(), negate()
47+
- Creating complex trigger conditions from simple ones
48+
- Debouncing triggers
49+
- Edge detection (rising/falling edges)
50+
- Trigger filtering and transformation
51+
- When composition is evaluated
52+
- Examples of trigger composition patterns (describe what examples should show)
53+
54+
## Inner Trigger Scopes
55+
56+
.. todo::
57+
Explain inner trigger scopes for command-local bindings. Cover:
58+
- What inner trigger scopes are and when to use them
59+
- How to create an inner scope within a command
60+
- Lifecycle of inner scope bindings (when they're active)
61+
- Use cases: responding to events during command execution
62+
- How inner scopes interact with command interruption
63+
- Cleanup of inner scope bindings
64+
- Differences from global trigger bindings
65+
- Examples of inner scope patterns (describe what examples should show)
66+
67+
## Practical Patterns
68+
69+
.. todo::
70+
Showcase common practical patterns for trigger usage. Cover:
71+
- Organizing bindings in RobotContainer
72+
- Driver control schemes (tank drive, arcade drive, split stick, etc.)
73+
- Operator control panels and button boxes
74+
- Mode switching and control profiles
75+
- Cancellation buttons and emergency stops
76+
- Trigger-based autonomous selection
77+
- Testing and debugging trigger bindings
78+
- Describe several real-world scenarios and recommended trigger patterns

‎source/docs/software/commandbased/commands-v3/command-compositions.rst‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Command Compositions
2+
3+
.. todo::
4+
This article covers the traditional command composition groups that allow combining multiple commands into more complex behaviors. While v3 emphasizes async/await patterns, composition groups are still important and useful in many scenarios. This article should help teams understand when to use compositions vs. async/await.
5+
6+
## Composition Overview
7+
8+
.. todo::
9+
Provide an overview of command composition in v3. Cover:
10+
- What command compositions are and why they exist
11+
- How compositions differ from async/await patterns
12+
- When to use compositions vs. async/await
13+
- Available composition types in v3
14+
- How v3 compositions compare to v2 command groups
15+
- General syntax and usage patterns
16+
17+
## Sequence Groups
18+
19+
.. todo::
20+
Explain sequence command groups in detail. Cover:
21+
- What sequence groups do: run commands one after another
22+
- How to create a sequence group
23+
- When commands transition in the sequence
24+
- What happens if a command in the sequence is interrupted
25+
- Requirements aggregation across sequence members
26+
- Common use cases for sequences
27+
- Comparison to using await() in a coroutine
28+
- Examples of sequence group patterns (describe what examples should show)
29+
30+
## Parallel Groups
31+
32+
.. todo::
33+
Explain parallel command groups in detail. Cover:
34+
- What parallel groups do: run multiple commands simultaneously
35+
- How to create a parallel group
36+
- When the parallel group completes (all commands finish)
37+
- Requirements handling with overlapping requirements
38+
- What happens if one command is interrupted
39+
- Common use cases for parallel groups
40+
- Comparison to using awaitAll() in a coroutine
41+
- Examples of parallel group patterns (describe what examples should show)
42+
43+
## Race Groups
44+
45+
.. todo::
46+
Explain race command groups in detail. Cover:
47+
- What race groups do: run commands in parallel until one finishes
48+
- How to create a race group
49+
- When the race group completes (first command finishes)
50+
- What happens to other commands when one finishes
51+
- Common use cases for race groups (timeouts, alternatives)
52+
- Comparison to using awaitAny() in a coroutine
53+
- Examples of race group patterns (describe what examples should show)
54+
55+
## Deadline Groups
56+
57+
.. todo::
58+
Explain deadline command groups in detail. Cover:
59+
- What deadline groups do: run commands with one as a "deadline"
60+
- How to create a deadline group and specify the deadline command
61+
- When the deadline group completes
62+
- Differences between deadline command and other commands
63+
- Common use cases for deadline groups
64+
- How to achieve similar behavior with async/await
65+
- Examples of deadline group patterns (describe what examples should show)
66+
67+
## Repeating and Looping
68+
69+
.. todo::
70+
Explain repeating and looping command patterns. Cover:
71+
- Available repeat/loop composition functions
72+
- Infinite repeats vs. counted repeats
73+
- When the loop terminates
74+
- How interruption affects repeated commands
75+
- Performance implications of repeated compositions
76+
- Common use cases for repeating commands
77+
- Comparison to using yield() loops in coroutines
78+
- Examples of repeat patterns (describe what examples should show)
79+
80+
## Conditional Groups
81+
82+
.. todo::
83+
Explain conditional command execution patterns. Cover:
84+
- Available conditional composition functions (if/else-style branching)
85+
- How conditions are evaluated
86+
- When condition evaluation happens (command creation vs. execution)
87+
- Proxy commands and deferred command selection
88+
- Common use cases for conditional groups
89+
- Comparison to using if/else in coroutines
90+
- Examples of conditional patterns (describe what examples should show)

0 commit comments

Comments
 (0)