Laborator: NXP Cup Car

La finalul laboratorului veți putea:

• să explicați pe scurt ce este NXP Cup și care sunt componentele principale ale mașinii;
• să descrieți fluxul de date dintre senzori, algoritmul de control și actuatoare;
• să reglați un controller PID pentru urmărirea liniei;
• să implementați și să testați local două module software utile pentru o mașină autonomă de tip line follower.

NXP Cup este un concurs de robotică în care echipele construiesc și programează o mașină autonomă la scară mică. Obiectivul tipic este parcurgerea unui traseu marcat pe sol, cât mai rapid și cât mai stabil, fără intervenție umană.

Într-o rundă de concurs, mașina trebuie să:

• citească traseul folosind senzori;
• estimeze poziția față de linie;
• decidă direcția și viteza potrivite;
• comande servo-ul de direcție și motoarele;
• rămână stabilă la curbe, intersecții și schimbări de contrast.

O mașină NXP Cup conține, în general, următoarele blocuri:

În fiecare iterație a buclei de control, mașina execută aproximativ pașii de mai jos:

1. Citește vectorii raportați de PixyCam2.
2. Calculează eroarea de direcție din vectorul detectat de PixyCam2.
3. Calculează eroarea: error = 0 - pixy_error.
4. Aplică un controller PID pe eroare.
5. Transformă ieșirea PID într-o comandă pentru servo.
6. Alege viteza motorului în funcție de stabilitate și de curbură.
7. Trimite comenzile către actuatoare.
8. Repetă la următorul pas de timp.

Ideea importantă este că mașina nu „știe” traseul dinainte. Ea reacționează continuu la măsurători. Dacă linia este la stânga, trebuie să vireze stânga; dacă linia este la dreapta, trebuie să vireze dreapta; dacă linia este aproape de centru, trebuie să meargă drept.

Un controller PID folosește trei termeni:

Formula discretă folosită în laborator este:

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

După calcul, ieșirea se limitează la intervalul acceptat de servo:

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

O implementare simplă pentru urmărirea liniei poate folosi următoarea arhitectură:

pixy.c           -> citire vectori PixyCam2
pixy_vector.c    -> estimarea erorii din vectorul PixyCam2
pid.c            -> controller PID
steering.c       -> conversie PID output -> comandă servo
speed.c          -> control viteză
main.c           -> bucla principală de control

Pentru laborator nu aveți nevoie să modificați tot codul mașinii. Veți lucra pe exerciții izolate, cu teste automate, iar la final veți încărca pe mașină doar binarul pentru exercițiul de PID.

Veți primi:

• binarul de bază pentru mașină;
• un fișier de configurare pentru parametrii PID;
• un script de încărcare pe placă;
• arhiva nxp_car_lab_skeleton.zip cu schelete de cod pentru exercițiile locale;
• teste automate pentru verificarea exercițiilor locale, incluse în arhivă.

Nu veți primi codul complet al mașinii. Scopul este să lucrați pe interfețe clare, asemănător cu situațiile în care integrați un modul într-un sistem existent. În proiectul folosit la laborator, informația despre traseu vine de la PixyCam2, nu de la o bară de senzori reflectivi.

Reglați parametrii kp, ki și kd astfel încât mașina să urmărească linia cât mai stabil.

• un binar precompilat pentru mașină;
• un fișier pid_config.txt cu parametrii editabili;
• un script de încărcare, de exemplu flash_car.sh;
• acces la mașină pentru testarea finală.

Exemplu de fișier de configurare:

kp=0.35
ki=0.00
kd=0.08
speed=0.40

1. Porniți de la ki = 0.
2. Creșteți kp până când mașina începe să urmărească linia, dar fără oscilații mari.
3. Creșteți kd pentru a reduce oscilațiile.
4. Folosiți ki doar dacă mașina are o abatere persistentă într-o parte.
5. Reduceți viteza dacă mașina devine instabilă în curbe.
6. Notați combinația de parametri care a funcționat cel mai bine.

./flash_car.sh pid_config.txt

După încărcare, testați mașina pe traseu și completați tabelul:

• Ce se întâmplă când kp este prea mic?
• Ce se întâmplă când kp este prea mare?
• Cum se schimbă comportamentul când măriți kd?
• A fost necesar un termen integral? De ce?

Implementați o funcție care primește un vector detectat de PixyCam2 și returnează eroarea de direcție normalizată față de centrul imaginii.

Acest exercițiu se face pe laptop și nu necesită mașina.

Implementați funcția:

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

PixyCam2 raportează vectori în coordonate de imagine. În acest exercițiu folosim doar vectorul principal al traseului. Coordonata x crește de la stânga la dreapta, iar coordonata y crește de sus în jos. Pentru a decide direcția, folosiți capătul de jos al vectorului, adică punctul cu y mai mare. Dacă y0 == y1, folosiți media dintre x0 și x1.

Funcția trebuie să întoarcă o eroare normalizată în intervalul [-1.0, 1.0]:

• -1.0 înseamnă că vectorul este la marginea stângă a imaginii;
• 0.0 înseamnă că vectorul este în centrul imaginii;
• 1.0 înseamnă că vectorul este la marginea dreaptă a imaginii.

Dacă frame_width ⇐ 1, funcția trebuie să returneze 0.0. Înainte de normalizare, limitați coordonata x la intervalul [0, frame_width - 1].

Formula recomandată este:

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

Un posibil testbench este inclus în arhiva de laborator în exercise2_pixy_vector/test_pixy_vector.c.

Compilare și rulare din arhiva de laborator:

cd nxp_car_lab_skeleton
make test-pixy

Dacă programul se termină fără eroare, testele au trecut.

Implementați conversia dintre ieșirea controllerului PID și comanda trimisă către servo.

Acest exercițiu se face pe laptop și nu necesită mașina.

Controllerul PID produce o valoare abstractă, de exemplu în intervalul [-1.0, 1.0]:

• -1.0 înseamnă viraj maxim stânga;
• 0.0 înseamnă roți drepte;
• 1.0 înseamnă viraj maxim dreapta.

Servo-ul primește un impuls PWM în microsecunde. În acest exercițiu folosim convenția:

Implementați funcția:

int pid_output_to_servo_us(float pid_output);

Funcția trebuie să:

1. limiteze pid_output la intervalul [-1.0, 1.0];
2. convertească liniar valoarea limitată la intervalul [1000, 2000];
3. returneze rezultatul ca întreg.

Formula recomandată:

servo_us = 1500 + pid_output * 500

Un posibil testbench:

#include <assert.h>
 
int pid_output_to_servo_us(float pid_output);
 
int main(void) {
    assert(pid_output_to_servo_us(-1.0f) == 1000);
    assert(pid_output_to_servo_us(-0.5f) == 1250);
    assert(pid_output_to_servo_us(0.0f) == 1500);
    assert(pid_output_to_servo_us(0.5f) == 1750);
    assert(pid_output_to_servo_us(1.0f) == 2000);
    assert(pid_output_to_servo_us(2.0f) == 2000);
    assert(pid_output_to_servo_us(-2.0f) == 1000);
 
    return 0;
}

Compilare și rulare din arhiva de laborator:

cd nxp_car_lab_skeleton
make test-steering

Dacă programul se termină fără eroare, testele au trecut.

La finalul laboratorului încărcați:

• fișierul pid_config.txt cu cea mai bună combinație găsită;
• răspunsurile la întrebările de la exercițiul 1;
• implementarea pentru estimate_pixy_vector_error;
• implementarea pentru pid_output_to_servo_us;
• capturi sau output text care arată că testele locale trec.

• Schimbați un singur parametru PID la un moment dat.
• Nu începeți cu viteză mare.
• Dacă mașina oscilează stânga-dreapta, reduceți kp sau creșteți ușor kd.
• Dacă mașina reacționează prea lent, creșteți kp.
• Dacă pierde linia în curbe, reduceți viteza sau creșteți reacția controllerului.
• Pentru exercițiile locale, testați și cazuri extreme, nu doar exemplele din enunț.