Differences
This shows you the differences between two versions of the page.
|
rasb:lab:03 [2026/06/26 15:01] 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: Real-Time PID Tuning via Bluetooth ===== | + | ===== 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 using a live Bluetooth connection. | + | 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/''; |
| - | * A smartphone with a Bluetooth Serial app (e.g. "PID Controll" or generic Bluetooth SPP terminal); | + | * A Teensy 4.1 microcontroller on the NXP Cup Car; |
| - | * An external Bluetooth serial module (e.g. HC-05, HC-06, HM-10) wired to Teensy's UART port ''Serial1''. | + | * A USB-micro cable to connect the Teensy to your laptop. |
| - | + | ||
| - | Example serial commands sent from the mobile app: | + | |
| - | <code text> | + | |
| - | P1.80 (Sets steering Kp to 1.80) | + | |
| - | I0.01 (Sets steering Ki to 0.01) | + | |
| - | D0.20 (Sets steering Kd to 0.20) | + | |
| - | </code> | + | |
| ==== Procedure ==== | ==== Procedure ==== | ||
| - | - Connect your smartphone's Bluetooth app to the vehicle's Bluetooth module. | + | 1. Open the ''pid_tuning/'' directory in VS Code (make sure the **PlatformIO IDE** extension is installed). |
| - | - Start with the integral term disabled (''ki = 0.00''). | + | 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 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. | + | <code c> |
| - | - Increase the derivative gain ''kd'' to dampen the oscillations and smooth the vehicle's trajectory. | + | extern const float STEER_KP = 1.8f; |
| - | - 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_KI = 0.00f; |
| - | - 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. | + | extern const float STEER_KD = 0.20f; |
| - | - Record your experimental runs in the table below. | + | </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 ==== | ||
| Line 125: | Line 134: | ||
| * **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. | * **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. | ||
| - | ==== Real-Time Communication ==== | + | ==== Telemetry & Diagnostics over USB Serial ==== |
| - | 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. | + | 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 text> | ||
| + | CSV format: time,state,vecs,side,lat,heading,curv,conf,steer,motor,dt | ||
| + | </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: | ||
| Line 164: | 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 211: | 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 256: | ||
| * 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 ===== | ||
