Differences
This shows you the differences between two versions of the page.
|
rasb:lab:03 [2026/06/26 13:39] rares.sarmasag |
rasb:lab:03 [2026/06/30 14:48] (current) rares.sarmasag [Lab 3: NXP Cup Autonomous Car] |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== Lab 3: NXP Cup Autonomous Car ====== | ====== Lab 3: NXP Cup Autonomous Car ====== | ||
| + | {{:rasb:lab:nxpcar-lab.zip|Lab 3 skel}} | ||
| ===== Duration ===== | ===== Duration ===== | ||
| Line 75: | Line 75: | ||
| ===== Project Layout ===== | ===== Project Layout ===== | ||
| - | The laboratory package contains the following files: | + | The workspace is organized into three functional directories: |
| - | * ''pid_tuning/pid_config.txt'' - configuration file containing runtime PID parameters (Kp, Ki, Kd, speed); | + | |
| - | * ''pid_tuning/flash_car.sh'' - script for uploading the parameters to the vehicle; | + | |
| - | * ''exercise2_pixy_vector/pixy_vector.c'' - source file for the PixyCam2 coordinate error estimator (student TODO); | + | |
| - | * ''exercise2_pixy_vector/pixy_vector.h'' - header file defining the PixyVector structure and function signature; | + | |
| - | * ''exercise2_pixy_vector/test_pixy_vector.c'' - testbench for validating the error estimation; | + | |
| - | * ''exercise3_steering/steering.c'' - source file for the servo command converter (student TODO); | + | |
| - | * ''exercise3_steering/steering.h'' - header file defining the servo mapping function signature; | + | |
| - | * ''exercise3_steering/test_steering.c'' - testbench for validating the servo conversion; | + | |
| - | * ''Makefile'' - build system to compile and execute the test suites. | + | |
| - | 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. | + | * **''pid_tuning/''** — PlatformIO project for configuring and flashing the physical vehicle. |
| + | * ''platformio.ini'': PlatformIO configuration file. | ||
| + | * ''src/configpid.cpp'': Source file where you edit your vehicle's PID gains ($K_p$, $K_i$, $K_d$). | ||
| + | * ''lib/libnxpcar.a'': Precompiled static library containing the vehicle's core autonomous driving logic. | ||
| + | * **''exercise2_pixy_vector/''** — Coordinate mapping and error estimation. | ||
| + | * ''pixy_vector.c'' / ''.h'': Student implementation file and interface. | ||
| + | * ''test_pixy_vector.o'': Precompiled local unit test suite object. | ||
| + | * **''exercise3_steering/''** — Steering actuator command conversion. | ||
| + | * ''steering.c'' / ''.h'': Student implementation file and interface. | ||
| + | * ''test_steering.o'': Precompiled local unit test suite object. | ||
| + | * **''test_runner''** — Precompiled interactive test runner TUI dashboard executable. | ||
| + | * **''Makefile''** — Compiles and links student implementations with precompiled test objects (via ''make test''). | ||
| + | |||
| + | Students do not need to modify the full vehicle firmware. You will implement and validate the core modules locally, write your PID gains in the configuration file, and flash the precompiled vehicle firmware. | ||
| --- | --- | ||
| - | ===== Exercise 1: Experimental PID Tuning ===== | + | ===== Exercise 1: Steering PID Controller Flashing & Tuning ===== |
| ==== Objective ==== | ==== Objective ==== | ||
| - | Tune the ''kp'', ''ki'', and ''kd'' gains of the vehicle controller to achieve stable and fast line-following behavior on the physical track. | + | Tune the steering PID gains ($K_p$, $K_i$, $K_d$) of the physical vehicle by editing the configuration file, compiling, and flashing the firmware onto the Teensy 4.1 using PlatformIO. |
| ==== Materials ==== | ==== Materials ==== | ||
| - | * Pre-compiled vehicle binary running on the platform; | + | * The student skeleton PlatformIO project inside ''pid_tuning/''; |
| - | * The editable ''pid_tuning/pid_config.txt'' parameter file; | + | * A Teensy 4.1 microcontroller on the NXP Cup Car; |
| - | * The flashing script ''pid_tuning/flash_car.sh''. | + | * A USB-micro cable to connect the Teensy to your laptop. |
| - | + | ||
| - | Example configuration file: | + | |
| - | <code text> | + | |
| - | kp=0.35 | + | |
| - | ki=0.00 | + | |
| - | kd=0.08 | + | |
| - | speed=0.40 | + | |
| - | </code> | + | |
| ==== Procedure ==== | ==== Procedure ==== | ||
| - | - Start with the integral term disabled (''ki = 0.00''). | + | 1. Open the ''pid_tuning/'' directory in VS Code (make sure the **PlatformIO IDE** extension is installed). |
| - | - Increase the proportional gain ''kp'' progressively until the car follows the line, but starts to oscillate left-and-right around the center. | + | 2. Open ''src/configpid.cpp'' and set your desired PID gains (do not modify the `extern` keyword as it is required to link with the precompiled library): |
| - | - Increase the derivative gain ''kd'' to dampen the oscillations and smooth the vehicle's trajectory. | + | <code c> |
| - | - Introduce a tiny integral gain ''ki'' only if the vehicle exhibits a persistent offset to one side (due to mechanical misalignment). | + | extern const float STEER_KP = 1.8f; |
| - | - Reduce the ''speed'' parameter if the vehicle spins out or loses the line in sharp curves. | + | extern const float STEER_KI = 0.00f; |
| - | - Record your experimental runs in the table below. | + | extern const float STEER_KD = 0.20f; |
| + | </code> | ||
| + | 3. Connect the Teensy 4.1 on your vehicle to your computer via USB. | ||
| + | 4. Build and flash the project: | ||
| + | - In VS Code, click the **PlatformIO: Upload** button (arrow icon at the bottom status bar), or | ||
| + | - Open a terminal inside the ''pid_tuning/'' folder and run: | ||
| + | <code bash> | ||
| + | pio run -t upload | ||
| + | </code> | ||
| + | - PlatformIO will automatically compile your ''configpid.cpp'', link it against the precompiled static library ''lib/libnxpcar.a'', and upload the complete firmware to the vehicle! | ||
| + | 5. Disconnect the USB cable, place the vehicle on the track, and turn on the power switch to observe its behavior. | ||
| + | 6. To adjust the gains, turn off the vehicle, reconnect the Teensy to your laptop via USB, edit the values in ''src/configpid.cpp'', and re-flash. | ||
| + | 7. Start with the integral term disabled (''ki = 0.00''). | ||
| + | 8. Increase the proportional gain ''kp'' progressively (e.g., in steps of 0.2) until the car follows the line, but starts to oscillate left-and-right around the center. | ||
| + | 9. Increase the derivative gain ''kd'' to dampen the oscillations and smooth the vehicle's trajectory. | ||
| + | 10. Record your experimental runs in the table below. | ||
| ==== Tuning Recommendations ==== | ==== Tuning Recommendations ==== | ||
| * **One Parameter at a Time**: Alter only a single PID gain parameter between experimental runs to isolate the physical effect of each gain. | * **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 at low speeds (e.g., ''speed=0.40'') before attempting high-speed runs to prevent physical damage to the vehicle. | + | * **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 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 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, reduce ''speed'' or increase the steering controller gain. | + | * **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. |
| - | ==== Uploading to the Vehicle ==== | + | ==== Telemetry & Diagnostics over USB Serial ==== |
| - | Deploy the modified configuration using the flashing script: | + | The Teensy car code automatically streams real-time CSV telemetry data over the USB Serial interface (at 115200 baud). If you plug the USB cable while the car is on a stand and open the PlatformIO Serial Monitor, you can observe the real-time CSV output: |
| - | <code bash> | + | <code text> |
| - | ./flash_car.sh pid_config.txt | + | CSV format: time,state,vecs,side,lat,heading,curv,conf,steer,motor,dt |
| </code> | </code> | ||
| + | This is useful for verifying that the camera sees the track and the steering controller reacts correctly. | ||
| Test the vehicle on the track and document your findings: | Test the vehicle on the track and document your findings: | ||
| - | ^ Run ^ kp ^ ki ^ kd ^ speed ^ Observations ^ | + | ^ Run ^ Kp ^ Ki ^ Kd ^ Observations ^ |
| - | | 1 | | | | | | | + | | 1 | | | | | |
| - | | 2 | | | | | | | + | | 2 | | | | | |
| - | | 3 | | | | | | | + | | 3 | | | | | |
| - | | 4 | | | | | | | + | | 4 | | | | | |
| ==== Questions & Observations ==== | ==== Questions & Observations ==== | ||
| Line 165: | Line 177: | ||
| Clamp the selected $x$ coordinate to the valid image boundaries $[0, \text{frame\_width} - 1]$ before normalization. | Clamp the selected $x$ coordinate to the valid image boundaries $[0, \text{frame\_width} - 1]$ before normalization. | ||
| - | Recommended normalization formula: | + | Students should derive a linear scaling formula to map the clamped $x$ coordinate from the pixel space $[0, \text{frame\_width} - 1]$ to the normalized target space $[-1.0, 1.0]$. |
| - | <code text> | + | |
| - | center = (frame_width - 1) / 2.0 | + | |
| - | error = (x - center) / center | + | |
| - | </code> | + | |
| ==== Examples for frame_width = 79 ==== | ==== Examples for frame_width = 79 ==== | ||
| Line 212: | Line 221: | ||
| 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). | 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: | + | Students should derive a linear conversion formula that maps the clamped PID steering command from $[-1.0, 1.0]$ to the physical servo PWM pulse width range $[1000, 2000]$ microseconds. |
| - | <code text> | + | |
| - | servo_us = 1500 + pid_output * 500 | + | |
| - | </code> | + | |
| ==== Examples ==== | ==== Examples ==== | ||
| Line 246: | Line 253: | ||
| Upon completion of the laboratory, submit the following: | Upon completion of the laboratory, submit the following: | ||
| - | * The tuned ''pid_config.txt'' configuration file; | + | * Your final tuned PID parameters (Kp, Ki, Kd) documented in your report; |
| * Written answers to the theoretical questions in Exercise 1; | * Written answers to the theoretical questions in Exercise 1; | ||
| * Your C implementations for ''exercise2_pixy_vector/pixy_vector.c'' and ''exercise3_steering/steering.c''; | * 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. | ||
| ===== Grading Criteria ===== | ===== Grading Criteria ===== | ||
