Clear, robust subsystem behavior comes from well-structured state machines. Use this guide to design, implement, and debug yours effectively.

Overview

A state machine is a way to organize the different tasks your subsystem needs to complete. For an oven, example states might be "Off", "Warming", "Baking", or "Convection". The state machine tells the robot what it should be doing now and what it should do next.

What is a state?

A state bundles the actions your robot should take for a specific mode of operation.

• Example: Oven "Bake" state
  • Turn on convection fans
  • Enable heating elements
  • Regulate to target temperature

Programming a state machine

1. Define your states
   • Create an enum of all states inside a companion object.
   • Keep names descriptive and concise.
2. Write the periodic loop
   • Implement fun periodic() to run your state machine.
   • Track currentState and compute nextState each cycle.
   • Log the active state for debugging with Logger.recordOutput("Subsystem/State", currentState).
3. Implement behavior per state
   • Use a when (currentState) block.
   • For each case, run outputs and compute transitions.

From request to state

This is a function that will go inside of your companion object along with your enum of states. It will take a “Request” which is created by your superstructure and set your current state to that request. See example code below for how to write this.

What kinds of states should I add?

Start with a minimal, reliable set and expand as needed.

• Uninitialized
  • Short, do-nothing state to avoid executing outputs while the robot boots.
• Zeroed or Homed
  • Zeroed: Set zero at the current sensor position. Good when absolute reference is not required, e.g., a flywheel.
  • Homed: Move to a known reference. Good when an absolute position matters, e.g., an elevator at its hard stop.