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 77: | Line 77: | ||
| The workspace is organized into three functional directories: | The workspace is organized into three functional directories: | ||
| - | * **''pid_tuning/''** — Parameters and deployment scripts for the physical vehicle. | + | * **''pid_tuning/''** — PlatformIO project for configuring and flashing the physical vehicle. |
| - | * ''pid_config.txt'': Contains the runtime PID gains ($K_p$, $K_i$, $K_d$) and speed profile. | + | * ''platformio.ini'': PlatformIO configuration file. |
| - | * ''flash_car.sh'': The script to upload configurations to the car. | + | * ''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. | * **''exercise2_pixy_vector/''** — Coordinate mapping and error estimation. | ||
| * ''pixy_vector.c'' / ''.h'': Student implementation file and interface. | * ''pixy_vector.c'' / ''.h'': Student implementation file and interface. | ||
| - | * ''test_pixy_vector.c'': The local unit test suite. | + | * ''test_pixy_vector.o'': Precompiled local unit test suite object. |
| * **''exercise3_steering/''** — Steering actuator command conversion. | * **''exercise3_steering/''** — Steering actuator command conversion. | ||
| * ''steering.c'' / ''.h'': Student implementation file and interface. | * ''steering.c'' / ''.h'': Student implementation file and interface. | ||
| - | * ''test_steering.c'': The local unit test suite. | + | * ''test_steering.o'': Precompiled local unit test suite object. |
| - | * **''Makefile''** — Compiles and executes both test suites (via ''make test''). | + | * **''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, and then tune the PID parameters on the physical car. | + | 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 167: | 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 214: | 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 248: | 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 ===== | ||
