Metrici LPR – LuxRiot Export Script

Ghid de Integrare pentru LuxRiot VCA

Prezentare generală Acest document explică modul de utilizare a luxriot_lpr.php, un script ajutător care primește o cerere HTTP POST de tip License‑Plate‑Recognition (LPR) de la un motor Metrici LPR, o validează, construiește un payload JSON și îl transmite către un server LuxRiot VCA folosind autentificare Digest.

1. Prezentare Generală

Acceptă un set de câmpuri POST care descriu un eveniment de detectare a unui vehicul.
Validează câmpurile obligatorii și autentifică cererea folosind un authkey per cameră stocat în tabelul MySQL general_cameras.
Creează un payload JSON de metadate pentru VCA (Vehicle‑Count‑Analytics).
Efectuează o autentificare Digest în doi pași către serverul LuxRiot și transmite payload-ul.

2. Câmpuri POST (trimise în corpul cererii)

Câmp	Descriere	Obligatoriu?
`id`	Identificatorul camerei (număr întreg)	Da
`number`	Numărul de înmatriculare detectat	Da
`country_code`	Codul de țară al plăcuței	Da
`first_seen`	Marcajul temporal când plăcuța a fost văzută prima dată	Da
`last_seen`	Marcajul temporal când plăcuța a fost văzută ultima dată	Da
`probability`	Încredere (0‑1)	Da
`direction`	Direcția vehiculului (ex. „in", „out")	Da
`plate_image`	URL sau imagine base64 a plăcuței (opțional)	Nu
`car_image`	URL sau imagine base64 a vehiculului (opțional)	Nu
`transactionkey`	Identificator de tranzacție pentru eveniment	Da
`gps_latitude`	Latitudine (opțional)	Nu
`gps_longitude`	Longitudine (opțional)	Nu
`have_companion`	Indicator care semnalează o plăcuță companion (opțional)	Nu
`companion_image`	Imaginea plăcuței companion (opțional)	Nu
`weight`	Greutatea vehiculului (opțional)	Nu
`speed`	Viteza vehiculului (opțional)	Nu
`triggerkey`	Cheie care identifică sursa declanșatorului (opțional)	Nu
`vehicle_class`	Clasa vehiculului ca text (ex. „car")	Nu
`vehicle_color`	Culoarea vehiculului ca text	Nu
`vehicle_maker`	Producătorul vehiculului ca text	Nu
`plate_bbox`	Coordonatele casetei de delimitare în formatul `x;y;width;height` (ex. „0.3;0.4;0.2;0.1"). Utilizat pentru a poziționa suprapunerea metadatelor. Implicit: centru (0.5;0.5;0.2;0.1) dacă nu este furnizat.	Nu
`auth`	Hash MD5 calculat dintr-o concatenare a mai multor câmpuri (opțional — dacă este omis, scriptul îl calculează)	Nu

Notă: Scriptul va calcula hash-ul auth automat dacă nu este furnizat. Dacă plate_bbox este furnizat, scriptul parsează coordonatele și le folosește pentru a poziționa suprapunerea metadatelor numărului de înmatriculare în sistemul LuxRiot VCA. Coordonatele ar trebui să fie relative la dimensiunile imaginii vehiculului.

3. Procesul de Autentificare

Se preia authkey-ul specific camerei din tabelul MySQL general_cameras folosind id-ul furnizat.
Se construiește un șir concatenat folosind câmpurile enumerate în codul sursă (vezi authString în script) și authkey-ul preluat.
Se calculează md5($authString). Câmpul auth furnizat trebuie să corespundă acestui hash; în caz contrar, cererea este respinsă cu Wrong authentication.

După validarea POST, scriptul efectuează o autentificare HTTP Digest cu serverul LuxRiot. Pașii sunt:

Se trimite o cerere inițială POST către /clientApi/VCA/{targetid}/pushMetaData pentru a obține un răspuns 401 care conține un header WWW-Authenticate.
Se parsează valorile realm și nonce din acel header.
Se calculează response-ul Digest folosind funcția ajutătoare compute_digest_response() (bazată pe MD5, așa cum este implementată în script).
Se emite cererea finală POST cu payload-ul JSON și header-ul construit Authorization: Digest ….

4. Parametri GET (obligatorii în query string)

Parametru	Descriere
`server`	URL-ul de bază sau IP-ul serverului LuxRiot (ex. `http://10.0.0.5`)
`port`	Portul pe care ascultă serverul (ex. `80` sau `443`)
`user`	Numele de utilizator pentru autentificarea Digest
`pass`	Parola pentru autentificarea Digest
`targetid`	Identificatorul țintă VCA utilizat în URL-ul endpoint-ului
`displaytimelive`	Opțional — durata de afișare (ms) pentru vizualizarea live (folosit în metadatele plăcuței)
`displaytimearchive`	Opțional — durata de afișare (ms) pentru vizualizarea arhivei (folosit în metadatele plăcuței)

Notă: Dacă oricare dintre parametrii obligatorii (server, port, user, pass) lipsește, scriptul returnează HTTP 400.

5. Exemplu de Configurare

Mai jos este un exemplu de configurare care arată cum se setează motorul Metrici LPR pentru a trimite evenimente către acest script. Pentru aceasta, navigați la folderul /home/metrici/metrici și deschideți fișierul .ini corespunzător. Apoi puteți modifica valoarea cheii reporting_url, sau, mai bine, adăugați adresa acestui script la cheia reporting_duplicate_url.

6. Exemplu de Utilizare (cURL)

Următorul exemplu arată cum se apelează scriptul din linia de comandă. Înlocuiți valorile substituente cu date reale.

curl -X POST \
  -d "id=12" \
  -d "number=ABC1234" \
  -d "country_code=US" \
  -d "first_seen=2024-09-19T10:15:00Z" \
  -d "last_seen=2024-09-19T10:15:05Z" \
  -d "probability=0.96" \
  -d "direction=in" \
  -d "transactionkey=tx12345" \
  -d "plate_bbox=0.3;0.4;0.2;0.1" \
  "http://yourhost/luxriot_lpr.php?server=10.0.0.5&port=80&user=admin&pass=secret&targetid=7"

Scriptul va răspunde cu unul dintre următoarele coduri de stare HTTP:

200 — Metadatele au fost trimise cu succes.
400 — Lipsesc parametri POST sau GET obligatorii.
401 — Autentificarea a eșuat (hash auth greșit sau date de autentificare Digest incorecte).
500 — Eroare de server sau răspuns neașteptat de la endpoint-ul LuxRiot.

7. Formatul Răspunsului

În caz de succes, scriptul afișează un mesaj în text simplu:

Metadata sent successfully

În caz de eroare, afișează un mesaj ușor de citit și setează codul de stare HTTP corespunzător (vezi lista de mai sus).