task_motor.py

Purpose

This file implements the motor-control task for a single wheel. It combines encoder updates, PI velocity control, optional logging, and publication of observer-related signals such as motor voltage and wheel displacement in meters.

Main Role

The task provides low-level closed-loop actuation for one wheel. Two instances of this task are created in main.py, one for the left motor and one for the right motor. This is what makes commanded wheel speeds repeatable and robust to disturbances such as battery variation or friction changes.

Key Responsibilities

Update encoder position and velocity
Regulate wheel speed with PI control
Send effort commands to the motor driver
Publish motor voltage to the observer
Publish wheel displacement in meters to the observer
Log velocity, time, and effort when requested
Auto-detect encoder sign so forward motion is positive

Important Attributes / Shares / Variables

Name	Description
`_mot`	Motor-driver object used to apply PWM effort to the wheel.
`_enc`	Encoder object used to measure wheel position and velocity.
`_goFlag`	Share that enables or disables active motor control.
`_vRef`	Share containing the desired wheel velocity.
`_Kp`, `_Ki`	PI controller gain Shares.
`_dataValues`, `_timeValues`, `_effortValues`	Queues used for logging speed, timestamp, and control effort.
`_u_share`	Share used to publish motor voltage for the observer.
`_s_share`	Share used to publish wheel displacement in meters.
`_Vbatt`	Battery voltage scale factor used to convert effort percentage to volts.
`_R`	Wheel radius in meters.
`_CPR`	Counts per revolution used for displacement conversion.
`_m_per_count`	Distance-per-count conversion factor.
`_sign`	Direction sign chosen so forward motion is treated as positive.
`_v_filt`	Filtered velocity state used in control.
`_e_int`	Integral-of-error accumulator for PI control.

Important Methods

Method	Description
`_sat()`	Saturates the control effort to a bounded range.
`_clear_queue()`	Clears queue contents before new logging sessions.
`_update_encoder_and_publish_s()`	Always updates encoder position and publishes wheel displacement, even when the motor-go flag is false. This is important for observer behavior when the robot is moved by hand.
`run()`	Main generator task implementing initialization, wait, and run behavior.

Click to view representative PI-control concept

error = vRef - velocity
effort = Kp * error + Ki * integral_error

Click to view engineering notes

A subtle but very good design choice in this file is that encoder updates continue even when the motor is disabled. That means displacement Shares still reflect the physical motion of the robot, which is valuable for state estimation and debugging.

Why This File Matters

This file closes the loop around each wheel. Without it, the robot would behave much more like an open-loop platform and would be less stable and repeatable during line following, turns, and obstacle-course maneuvers.

Open raw task_motor.py file