task_course.py

Purpose

This file implements the high-level finite state machine for the full obstacle course. It contains the ordered sequence of line-following segments, straight drives, turning maneuvers, wall contact, backup behavior, cup interaction, and the final end-of-course actions. In the full software stack, this is the file that decides what the robot should be doing right now.

Main Role

While lower-level files handle actuation, sensing, and estimation, task_course.py coordinates the robot’s overall behavior. It enables or disables line following, changes controller gains and base speeds for different phases, commands direct wheel velocities for special maneuvers, and uses measured wheel travel to determine when a segment has been completed.

State Machine Overview

The file defines a large number of named states, beginning with initialization and idle modes and continuing through the entire obstacle-course routine. These include fast and slow line-following sections, right and left turns, straight segments, wall interaction, cup interaction, and final approach states.

Click to view key FSM groups

Startup and idle: S0_INIT, S1_IDLE
Early line-follow and turning: S2_FAST_LINE, S3_SLOW_LINE, S4_SMALL_RIGHT, S5_STRAIGHT, S6_TURN_RIGHT
Wall interaction: S8_DRIVE_TO_WALL, S9_BACK_UP, S10_TURN_LEFT, S11_FORWARD_AFTER_TURN, S12_RESUME_LINE
Final approach and cup path: S17_FAST_FINAL_LINE_1 through S31_END_STRAIGHT
Mid-course correction states: S111_MID_LEFT through S114_MID_RIGHT

Key Responsibilities

Define the ordered autonomous sequence of the obstacle course
Apply different gains and base speeds for different sections of the course
Enable and disable line-follow mode at the correct times
Command direct left and right wheel velocities during turns, backups, and straight segments
Store wheel-travel references at the start of each segment and compare them against current measured travel
React safely when the course-enable flag is turned off or when a bump event occurs

Important Attributes / Shares / Variables

Name	Description
`_state`	Current finite-state-machine state.
`_courseEnable`	Master enable Share for the autonomous routine. If false, the task forces the robot back to a stopped or idle condition.
`_bumpEvent`	Share indicating collision contact from the bump task. This is cleared when restarting certain behaviors.
`_leftMotorGo`, `_rightMotorGo`	Shares used to enable the left and right motor tasks.
`_lfEnable`	Share that enables or disables line-follow mode.
`_velL`, `_velR`	Direct wheel velocity command Shares used during non-line-follow segments.
`_vBase`	Base speed Share used by the line-follow controller.
`_sL_meas`, `_sR_meas`	Measured left and right wheel displacement Shares.
`_Kp`, `_Ki`	Motor PI gain Shares that are updated for different sections of the course.
`_seg_sL0`, `_seg_sR0`	Wheel displacement references recorded at the start of a segment, used to compute segment travel.

Important Internal Helper Methods

Method	Description
`_clear_bump_event()`	Attempts to reset the bump-event Share so old contact events do not carry into a new course run.
`_stop()`	Disables line-follow mode, disables both motors, zeros wheel commands, and disables the course.
`_apply_fast_settings()`	Loads the fast line-follow PI gains and base speed into the shared variables.
`_apply_slow_settings()`	Loads the slow line-follow PI gains and base speed into the shared variables.
`_mark_segment_start()`	Captures the current left and right wheel displacement values as the reference for a new segment.
`_avg_forward_travel()`	Returns average forward wheel travel relative to the marked segment start.
`_avg_backward_travel()`	Returns average backward travel relative to the marked segment start.
`_avg_abs_wheel_travel()`	Returns average absolute wheel travel, useful for turning segments where one wheel may move differently from the other.
`_start_fast_line()`, `_start_slow_line()`	Configure and begin line-following segments.
`_start_small_right()`, `_start_turn_right()`, `_start_turn_left()`	Configure direct wheel-speed commands for turning maneuvers.
`_start_drive_to_wall()`, `_start_back_up()`, `_start_forward_after_turn()`	Configure straight or reverse motion segments outside of line-follow mode.

Click to view representative transition logic

elif self._state == S2_FAST_LINE:
    if not self._courseEnable.get():
        self._stop()
        self._clear_bump_event()
        self._state = S1_IDLE
        yield self._state
        continue
    if self._avg_forward_travel() >= FAST_LINE_TRAVEL:
        self._start_slow_line()
        self._state = S3_SLOW_LINE

Click to view engineering notes

The constants at the top of the file define both controller settings and travel thresholds. This means the file serves as both the behavior definition and the tuning hub for the course. The measured wheel displacements are used instead of open-loop time delays wherever possible, which improves repeatability.

Why This File Matters

This file is the behavioral core of the robot. It is where the full autonomous routine is encoded. The line-follow controller, motor controllers, and observer can all work independently, but without this file the robot would not know when to transition from line following into turning, wall approach, cup interaction, or the final exit behavior.

Open raw task_motor.py file