task_line.py

Purpose

This file implements the line-following controller. It reads the reflectance sensor array, estimates line position using a centroid-based method, filters and bounds the result, then generates left and right wheel velocity commands to keep the robot centered on the track.

Main Role

This file is the robot’s main path-tracking controller whenever line-follow mode is enabled. It turns raw reflectance readings into steering behavior.

Key Responsibilities

Read normalized reflectance sensor values
Compute line position using a weighted centroid
Apply confidence checks to avoid reacting to weak or noisy signals
Filter the position estimate and apply a deadband
Compute steering correction using proportional, integral, and derivative action
Clamp the steering effort to a maximum magnitude
Write left and right wheel velocity commands to Shares

Important Attributes / Shares / Variables

Name	Description
`sens`	Line sensor array object used to read reflectance values.
`v_base`	Base forward speed Share.
`vL_cmd`, `vR_cmd`	Left and right wheel velocity command Shares.
`lfEnable`	Share that enables or disables line-follow control.
`Kp`, `Ki`, `Kd`	Controller gains for steering correction.
`u_max`	Maximum steering correction magnitude.
`max_min`, `sum_min`	Confidence thresholds used to reject weak line signals.
`pos_alpha`	Low-pass filter coefficient for the line-position estimate.
`pos_deadband`	Small deadband around zero position error.
`_last_valid_pos`	Most recent valid line position, used when the signal weakens.

Important Methods / Behavior

Method / Logic	Description
`_reset_pid()`	Resets internal controller state when line-follow mode is disabled.
Centroid estimation	Computes an effective line position from the weighted sensor readings.
Weak-signal handling	Prevents the robot from immediately spinning when the line signal becomes unclear.
Wheel-command output	Uses the steering correction to adjust left and right speed commands around the base speed.

Click to view representative control behavior

if not self.lfEnable.get():
    self._reset_pid()
    yield self._state
    continue

Click to view engineering notes

One of the strongest parts of this file is its weak-line handling. Instead of assuming the sensor signal is always perfect, the controller includes thresholds, filtering, and hold-last-valid logic so the robot behaves more gracefully when the line momentarily becomes less clear.

Why This File Matters

This file is what allows the robot to follow the printed track smoothly rather than simply reacting to a threshold crossing. It is a large part of why the robot appears controlled instead of jerky.

Open raw task_line.py file