2 hours:

• 0h30 theoretical introduction to NXP Cup, vehicle dynamics, and PID control;
• 1h30 practical tuning and modular firmware development.

After this laboratory, students should be able to:

• Explain the data flow in an autonomous line-follower (sensors, control, actuators);
• Describe the role of Proportional, Integral, and Derivative terms in a PID controller;
• Tune a PID controller experimentally on physical or emulated hardware;
• Implement and validate coordinate mapping algorithms for line tracking camera sensors;
• Map abstract controller commands to physical servo PWM pulse widths.

The lab focuses on programming and tuning an autonomous line-following vehicle. The system utilizes a PixyCam2 camera for line detection, a PID controller for trajectory correction, and a steering servomotor.

``` [PixyCam2 Camera] → vector path → [Error Estimator (Ex 2)] → error → [PID Controller] → output → [Servo Command (Ex 3)] → PWM → [Steering Servo] ```

In each control loop iteration, the vehicle executes the following sequence:

1. Read the path vectors reported by PixyCam2.
2. Estimate the lateral steering error from the detected vector.
3. Compute the tracking error: error = 0.0f - estimated_error.
4. Apply the PID control algorithm to the tracking error.
5. Map the PID controller output to a physical servo command.
6. Adjust the motor speed profile based on path curvature and stability.
7. Write commands to the actuators (servo and ESC).
8. Wait for the next control cycle.

The vehicle does not know the track geometry in advance; it reacts dynamically to real-time measurements. If the line shifts left, it steers left; if it shifts right, it steers right; if the line is centered, the wheels remain straight.

An NXP Cup autonomous vehicle consists of the following primary components:

The PID controller computes the steering adjustment using three distinct terms:

The discrete implementation used in the vehicle firmware is:

integral = integral + error * dt;
derivative = (error - previous_error) / dt;
output = kp * error + ki * integral + kd * derivative;
previous_error = error;

After computing the output, it is saturated to the safety limits of the steering servo:

if (output > max_output) output = max_output;
if (output < min_output) output = min_output;

The workspace is organized into three functional directories:

• pid_tuning/ — Parameters and deployment scripts for the physical vehicle.
  • pid_config.txt: Contains the runtime PID gains ($K_p$, $K_i$, $K_d$) and speed profile.
  • flash_car.sh: The script to upload configurations to the car.
• exercise2_pixy_vector/ — Coordinate mapping and error estimation.
  • pixy_vector.c / .h: Student implementation file and interface.
  • test_pixy_vector.c: The local unit test suite.
• exercise3_steering/ — Steering actuator command conversion.
  • steering.c / .h: Student implementation file and interface.
  • test_steering.c: The local unit test suite.
• Makefile — Compiles and executes both test suites (via make test).

Students do not need to modify the full vehicle firmware. You will implement and validate the core modules locally, and then tune the PID parameters on the physical car.

—

Tune the kp, ki, and kd gains of the vehicle controller to achieve stable and fast line-following behavior on the physical track using a live Bluetooth connection.

• Pre-compiled vehicle binary running on the platform;
• A smartphone with a Bluetooth Serial app (e.g. “PID Controll” or generic Bluetooth SPP terminal);
• An external Bluetooth serial module (e.g. HC-05, HC-06, HM-10) wired to Teensy's UART port Serial1.

Example serial commands sent from the mobile app:

P1.80    (Sets steering Kp to 1.80)
I0.01    (Sets steering Ki to 0.01)
D0.20    (Sets steering Kd to 0.20)

1. Connect your smartphone's Bluetooth app to the vehicle's Bluetooth module.
2. Start with the integral term disabled (ki = 0.00).
3. Increase the proportional gain kp progressively using the app sliders or terminal inputs until the car follows the line, but starts to oscillate left-and-right around the center.
4. Increase the derivative gain kd to dampen the oscillations and smooth the vehicle's trajectory.
5. Introduce a tiny integral gain ki only if the vehicle exhibits a persistent offset to one side (due to mechanical misalignment).
6. Note that speed control is standard-implemented in the vehicle firmware and adapts dynamically based on steering effort, so no speed tuning is required in this exercise.
7. Record your experimental runs in the table below.

• One Parameter at a Time: Alter only a single PID gain parameter between experimental runs to isolate the physical effect of each gain.
• Safety First: Start testing with the vehicle on a stand or at low speeds before attempting high-speed runs to prevent physical damage to the vehicle.
• Handling Oscillations: If the vehicle exhibits high-frequency oscillations (wiggling), decrease kp or slightly increase kd.
• Handling Sluggishness: If the vehicle reacts too slowly to curves and drifts wide, increase kp.
• Handling Curve Instability: If the vehicle flies off the track in sharp turns, check if the steering controller gains need further tuning or if the track requires lower speed limits.

The Teensy car code automatically listens for incoming serial tuning commands on both USB Serial and the Bluetooth Serial port (Serial1 at 9600 baud). Adjustments are applied instantly to the running controllers, allowing you to tune parameters on the fly without re-flashing.

Test the vehicle on the track and document your findings:

• What physical behavior is observed when kp is too low?
• What physical behavior is observed when kp is too high?
• How does the vehicle's trajectory change as you increase kd?
• Was an integral term ki necessary for stable tracking? Explain why.

—

Implement a C function that parses a raw tracking vector from PixyCam2 and returns a normalized steering error relative to the image frame center.

The PixyCam2 reports line tracking vectors in image coordinates. The $x$ coordinate increases from left to right, and the $y$ coordinate increases from top to bottom. To determine the immediate direction of the path, you must track the endpoint of the vector that is closest to the front of the car (the bottom of the image frame, which corresponds to the larger $y$ coordinate).

• If $y_0 > y_1$, use $x_0$.
• If $y_1 > y_0$, use $x_1$.
• If the vector is horizontal ($y_0 == y_1$), use the average of $x_0$ and $x_1$.

The function must return a normalized error in the range [-1.0, 1.0]:

• -1.0 represents the far-left edge of the frame;
• 0.0 represents the exact center of the frame;
• 1.0 represents the far-right edge of the frame.

If the input frame_width ⇐ 1, return 0.0f. Clamp the selected $x$ coordinate to the valid image boundaries $[0, \text{frame\_width} - 1]$ before normalization.

Recommended normalization formula:

center = (frame_width - 1) / 2.0
error = (x - center) / center

Implement the function in exercise2_pixy_vector/pixy_vector.c:

typedef struct {
    int x0;
    int y0;
    int x1;
    int y1;
} PixyVector;
 
float estimate_pixy_vector_error(PixyVector vector, int frame_width);

Compile and run the local unit tests from the workspace:

cd nxp_car_lab_skeleton
make test-pixy

—

Implement a C function to map the abstract floating-point PID controller output to a physical PWM pulse width in microseconds for the steering servomotor.

The PID controller produces an abstract output intended to represent steering direction. The function must:

1. Clamp the input `pid_output` to the safe operating range of ''[-1.0, 1.0]'', where ''-1.0'' represents maximum left steer and ''1.0'' represents maximum right steer.
2. Map this clamped value linearly to a standard servo PWM pulse width in the range ''[1000, 2000]'' microseconds, where ''1500'' microseconds represents the center position (wheels straight).

Recommended conversion formula:

servo_us = 1500 + pid_output * 500

Implement the function in exercise3_steering/steering.c:

int pid_output_to_servo_us(float pid_output);

Compile and run the local unit tests:

cd nxp_car_lab_skeleton
make test-steering

—

Upon completion of the laboratory, submit the following:

• Your final tuned PID parameters (Kp, Ki, Kd) documented in your report;
• Written answers to the theoretical questions in Exercise 1;
• Your C implementations for exercise2_pixy_vector/pixy_vector.c and exercise3_steering/steering.c;
• Terminal output logs or screenshots showing that both local test suites pass successfully.

• Local Validation: Always verify your code implementations using the local test suites (make test) before deploying or tuning.
• Code Quality: Write clean, self-documenting code, handle all safety clamping, and consider extreme edge cases (such as negative or zero frame width).