Proiectarea unui protocol simplu de control robot prin HTTP

Dezvoltatorii au adesea nevoie de un protocol ușor, deschis, care să permită oricărei aplicații să comande un robot fără SDK-uri proprietare.

Răspunsul este să expui un set mic de endpoint-uri HTTP pentru mișcare și un flux MJPEG pentru vizualizare, un model deja utilizat în robotul Baby Carpathron ESP32‑CAM de la Qubitpage.

De ce să alegi HTTP și MJPEG pentru controlul robotului

Ubiquitatea și compatibilitatea cu firewall-urile ale HTTP

HTTP este fundamentul webului modern, ceea ce înseamnă că fiecare sistem de operare, router și serviciu cloud știe deja cum să îl gestioneze. Un robot care expune API-ul său de control prin HTTP simplu poate fi accesat de pe un laptop, un telefon sau o funcție cloud fără a instala drivere personalizate sau a deschide porturi non‑standard. Deoarece traficul HTTP folosește portul 80 (sau 443 pentru TLS), majoritatea firewall-urilor corporative și a dispozitivelor NAT îl permit în mod implicit, reducând nevoia de configurări de rețea complexe.

În proiectul Carpathron Robotics, mașina robot Baby Carpathron ESP32‑CAM utilizează aceeași abordare. Firmware-ul său rulează un server web ușor care ascultă pe http://192.168.1.42. Comenzile precum /move sau /led sunt trimise cu simple cereri GET sau POST, iar robotul răspunde cu payload-uri JSON. Această arhitectură permite dezvoltatorilor să testeze robotul din orice browser, din aplicația Carpathron Remote (software/carpathron-remote), sau din agentul desktop AI‑asistat Carpathon Robotics & Coding disponibil pe Microsoft Store.

Simplitatea MJPEG pentru video live

Fluxurile MJPEG constau dintr-o secvență de imagini JPEG livrate printr-un răspuns HTTP multipart. Spre deosebire de WebRTC sau RTSP, MJPEG nu necesită negociere, nu are un canal de semnalizare separat și nu necesită biblioteci client specializate. Un tag standard <img src="http://…/stream"> sau orice browser modern poate reda video în timp real, ceea ce este ideal pentru prototipare rapidă și depanare.

Mașina robot Baby Carpathron implementează feedul camerei sale cu protocolul open Carpathron Robot Protocol. ESP32‑CAM oferă un endpoint MJPEG la /mjpeg, iar aplicația Carpathron Avatar pe Meta Quest 3/3S consumă aceeași adresă URL pentru a afișa o vedere urmărire a capului robotului. Deoarece video-ul este livrat prin HTTP, aceleași reguli firewall care permit traficul de comenzi permit și fluxul video, menținând amprenta de rețea minimă.

Beneficii în lumea reală pentru dezvoltatori

Alegerea HTTP și MJPEG elimină necesitatea SDK-urilor personalizate. Un dezvoltator poate trimite o comandă cu curl, deschide un tab de browser pentru video și integra endpoint-urile în cadrele web existente cu câteva linii de cod. Acest lucru reduce pragul de intrare pentru pasionați și accelerează adopția în mediile educaționale, unde platforma Carpathron Robotics este deja folosită pentru a învăța programarea Arduino și ESP32.

Mai mult, natura stateless a HTTP simplifică scalarea. Mai multe roboți pot împărți un singur proxy invers, iar load balancer-ele pot distribui traficul fără a rescrie protocolul. Lipsa latenței de compresie a MJPEG garantează că feedback-ul vizual rămâne receptiv, ceea ce este crucial când se conduce robotul prin mișcarea capului în interfața Meta Quest.

În ansamblu, combinația HTTP pentru comenzi și control și MJPEG pentru video live oferă o bază simplă, compatibilă cu firewall-urile și pregătită pentru browser, pe care ecosistemul Carpathron Robotics îl valorifică pentru a oferi o experiență consistentă pe robotul Baby Carpathron, agentul AI Windows și viitoarele platforme umanoid modulare.

Designul API-ului principal – endpointuri și payloaduri

Set de comenzi RESTful

Protocolo Robot Carpathon definește un set minim de endpointuri HTTP care acoperă majoritatea acțiunilor roboților de nivel amator. Fiecare endpoint acceptă un corp JSON și returnează un obiect de stare JSON. URL-ul de bază este adresa IP a robotului, de exemplu http://192.168.4.10/api. Endpointurile esențiale sunt:

• /move – instrucțiune pentru ca robotul să meargă înainte, înapoi sau să vireze. Payloadul conține direction (una dintre valorile forward, backward, left, right) și speed (0‑255).
• /stop – oprește imediat toate mișcările. Nu se necesită payload; se acceptă un obiect JSON gol ({}).
• /status – returnează citirile curente ale senzorilor, nivelul bateriei și timestamp-ul ultimei comenzi. Răspunsul este un obiect JSON; corpul cererii este ignorat.
• /camera/start și /camera/stop – controlează fluxul MJPEG pe ESP32‑CAM. Endpointul de start poate include un câmp opțional resolution (de ex. 640x480).
• /ping – verificare de sănătate ușoară folosită de Avatarul Carpathron pentru a verifica conectivitatea.

Toate endpointurile sunt accesate cu metoda HTTP POST exceptând /status și /ping, care acceptă GET. Robotul nu necesită niciodată o licență pentru conexiunile în intrare; aceasta respectă politica Carpathron Remote care permite accesul nelimitat în rețeaua locală.

Structura payloadului JSON

Fiecare comandă urmează un schemă consistentă, făcându‑o ușor de generat pentru bibliotecile client. Hârtia generică a cererii arată astfel:

Pentru /move, obiectul payload conține:

Hârtia răspunsului reflectă cererea, adăugând un câmp status și un câmp opțional data pentru valorile senzorilor:

Dacă apare o eroare, câmpul status este setat la error și se furnizează un șir error_message. Acest model uniform simplifică înregistrarea și retratarea automată.

Versionare și extensibilitate

Protocolul rezervă un prefix /v1/ în URL (de ex. /v1/move) pentru a permite extensii viitoare fără a afecta clienții existenți. Comenzi noi, cum ar fi /arm sau /lights, pot fi adăugate sub aceeași versiune. Deoarece robotul rulează un server HTTP ușor, supraîncărcarea versionării este neglijabilă.

Sfat: Când integrezi cu Avatarul Carpathron, folosește endpointul Carpathron Remote /ping la fiecare 5 secunde pentru a menține sesiunea WebSocket activă și a evita reconectările inutile.

Configurarea fluxului video MJPEG

Flash firmware-ul ESP32‑CAM

Descarcă scheletul CarpathronCam.ino de pe depozitul Carpathron robotics de pe GitHub. Deschide proiectul în Arduino IDE, selectează AI‑Thinker ESP32‑CAM ca placă și configurează credențialele Wi‑Fi în secțiunea setup():

const char* ssid = "YOUR_SSID";
const char* password = "YOUR_PASSWORD";

Compilează și încarcă schița folosind un adaptor USB‑to‑TTL. Firmware-ul pornește un server web pe portul 80 și începe să transmită cadre MJPEG de la camera integrată.

Verifică punctul final HTTP

După ce ESP32‑CAM se repornește, afișează adresa IP pe monitorul serial, de exemplu 192.168.1.42. Fluxul MJPEG este disponibil la:

http://192.168.1.42:80/mjpeg

Deschide această adresă în browser; ar trebui să vezi un video actualizat continuu. Serverul trimite următoarele antete, necesare pentru compatibilitatea MJPEG:

• Content-Type: multipart/x-mixed-replace; boundary=frame
• Cache-Control: no-cache
• Pragma: no-cache

Integrează fluxul cu Carpathron Remote

Lansează aplicația Carpathron Robotics & Coding din Microsoft Store (Carpathron Robotics). În fila Video, adaugă o nouă sursă și lipește URL-ul MJPEG. Aplicația adaugă automat antetele necesare, astfel încât video-ul să apară în tabloul de bord al controlului, alături de panoul de control al robotului.

Reglează rezoluția și rata de cadre

Configurarea implicită transmite la 640×480 px, 15 fps. Pentru a reduce lățimea de bandă, editează constantele schiței înainte de flash:

#define FRAMESIZE FRAMESIZE_QVGA   // 320×240
#define FRAME_RATE 10               // fps

Încarcă din nou firmware-ul; noile setări intră în vigoare imediat. Verifică modificarea prin examinarea antetului Content-Length în instrumentele de dezvoltare ale browserului – ar trebui să scadă proporțional.

Depanează problemele comune

Dacă fluxul returnează 404 Not Found, confirmă că ESP32‑CAM rulează cea mai recentă versiune a firmware-ului Carpathron și că calea URL este exact /mjpeg. Un răspuns 403 Forbidden indică de obicei că dispozitivul încă se conectează la Wi‑Fi; așteaptă până când monitorul serial afișează WiFi connected. Pentru blocări intermitente, reduce parametru de calitate JPEG în schiță:

#define JPEG_QUALITY 12   // valoare mai mică = compresie mai mare

În cele din urmă, asigură-te că robotul și stația de control împărtășesc aceeași subrețea; altfel cererea HTTP nu va ajunge niciodată la ESP32‑CAM.

Pas cu pas: Implementarea protocolului pe un robot Linux

Mai jos găsiți un ghid concis pentru transformarea unei plăci Linux generic—cum ar fi un Raspberry Pi sau ESP32‑CAM care rulează Linux—într-un robot care comunică protocolul Carpathron Robot Protocol prin HTTP. Procedura presupune o instalare nouă a sistemului de operare cu privilegii sudo.

1. Instalați un server web ușor. Rulați sudo apt-get update && sudo apt-get install -y nginx. Configurația implicită ascultă pe portul 80 și servește fișierele din /var/www/html.
2. Creați directorul API. Executați sudo mkdir -p /var/www/html/api/v1 și setați proprietatea la utilizatorul www-data: sudo chown -R www-data:www-data /var/www/html/api. Acest lucru izolează punctele finale de control de la resursele statice.
3. Scrieți scriptul de control. Salvați următorul fragment Python Flask ca /var/www/html/api/v1/control.py:

   from flask import Flask, request, jsonify
   app = Flask(__name__)
   
   @app.route('/api/v1/move', methods=['POST'])
   def move():
       cmd = request.json.get('action')
       # Exemplu: forward, left, stop
       # Inserare cod specific hardware aici
       return jsonify(status='ok', executed=cmd)
   
   if __name__ == '__main__':
       app.run(host='0.0.0.0', port=8080)
   

   Apoi instalați Flask cu sudo pip3 install flask.
4. Expuneți serviciul Flask prin Nginx. Adăugați un bloc de locație în /etc/nginx/sites-available/default:

   location /api/v1/ {
       proxy_pass http://127.0.0.1:8080/;
       proxy_set_header Host $host;
   }
   

   Reîncărcați Nginx: sudo systemctl reload nginx. Robotul acceptă acum POST-uri JSON la http://<ip>/api/v1/move.
5. Configurați fluxul MJPEG. Instalați mjpg-streamer (sudo apt-get install -y mjpg-streamer) și porniți-l către dispozitivul camera: mjpg_streamer -i "input_uvc.so -d /dev/video0 -r 640x480 -f 30" -o "output_http.so -p 8090 -w /usr/local/share/mjpg-streamer/www". Fluxul este accesibil la http://<ip>:8090/?action=stream.
6. Încadrați fluxul în răspunsul API. Modificați control.py pentru a include URL-ul video:

   @app.route('/api/v1/status', methods=['GET'])
   def status():
       return jsonify(
           video='http://'+request.host.split(':')[0]+':8090/?action=stream',
           ready=True
       )
   

   Acest punct final permite clientului Carpathron remote să obțină feedul live fără configurări suplimentare.
7. Activați pornirea automată la boot. Creați un fișier de serviciu systemd /etc/systemd/system/carpathron-api.service cu:

   [Unit]
   Description=Carpathron Robot API
   After=network.target
   
   [Service]
   User=www-data
   WorkingDirectory=/var/www/html/api/v1
   ExecStart=/usr/bin/python3 control.py
   Restart=on-failure
   
   [Install]
   WantedBy=multi-user.target
   

   Activați-l: sudo systemctl enable --now carpathron-api. Robotul pornește acum cu control HTTP și streaming MJPEG pregătite.
8. Verificați conectivitatea. Dintr-o stație de lucru, rulați: curl -X POST -H "Content-Type: application/json" -d '{"action":"forward"}' http://<robot_ip>/api/v1/move și deschideți http://<robot_ip>:8090 într-un browser. Răspunsurile de succes confirmă că protocolul este funcțional.

Sfat: Păstrați procesul Flask pe un port non‑standard (de ex., 8080) și proxiați prin Nginx. Această separare vă permite să adăugați terminarea TLS sau limitarea ratelor în Nginx fără a modifica codul robotului.

Cu punctele finale HTTP și feedul MJPEG în funcțiune, robotul respectă protocolul Carpathron Robot Protocol și poate fi controlat din aplicația Carpathron remote sau orice client personalizat.

Check‑list de securitate pentru API-urile robotului deschise

Când expui punctele finale de control al robotului pe internetul public, prima linie de apărare este autentificarea. Un API complet deschis invită la injectarea de comenzi neautorizate, manipularea firmware-ului și scurgeri de date. Chiar și un simplu sistem de token adaugă o barieră care oprește scanerele casual și forțează ca o cerere deliberată să includă o valoare secretă.

Pentru implementările care se bazează deja pe tehnicianul AI Carpathron Remote, poate fi introdus un pas suplimentar de aprobare. Tehnicianul AI validează cererea împotriva motorului de politici și poate solicita o confirmare umană prin canalul de control WhatsApp. Această abordare este utilă pentru roboți de mare valoare sau pentru mediile în care operatorii la distanță au nevoie de auditabilitate.

Implementează verificarea token-ului pe partea firmware a robotului utilizând o verificare HMAC ușoară. Stochează secretul într-o secțiune read‑only a flash-ului ESP32‑CAM și rotește-l printr-o actualizare OTA sigură. Pentru aprobarea tehnicianului AI, robotul ar trebui să expună un punct final /request‑approval care redirecționează comanda primită către serviciul Carpathron Remote; serviciul returnează un token de aprobare semnat pe care robotul îl validează înainte de execuție.

Întărirea la nivel de rețea completează autentificarea. Plasează robotul în spatele unui firewall care permite doar traficul de intrare pe porturile 80/443 și activează terminarea TLS fie pe robot (dacă resursele permit), fie pe un proxy invers. Folosește fail2ban sau un instrument similar pentru a bloca încercările repetate de token eșuat și înregistrează fiecare cerere cu IP-ul sursă, timestamp-ul și payload-ul comenzii pentru analiză forensică.

În final, documentează postura de securitate în specificația API-ului public al robotului și furnizează o referință rapidă pentru integratori. Legătura către documentația Carpathron Remote (Carpathron Remote) și pagina de produse (Carpathron Robotics & Coding) asigură ca dezvoltatorii să poată obține cele mai recente ghiduri de gestionare a token-urilor și pașii de integrare ai tehnicianului AI.

Instrumente de testare și depanare

Verificare prin linie de comandă cu curl

Pentru verificări rapide ale punctelor finale, curl oferă vizibilitate brută a HTTP-ului. Solicită starea robotului cu:

curl -X GET http://robot.local/api/v1/status

Răspunsul include un obiect JSON cu câmpurile uptime, battery și mode. Pentru a iniția un mișcare, trimite un POST cu un payload JSON:

curl -X POST http://robot.local/api/v1/move \
     -H "Content-Type: application/json" \
     -d '{"direction":"forward","speed":0.5}'

Inspectează codul de stare HTTP și corpul; un 200 indică succes, în timp ce 400 sau 500 arată payload-uri malformate sau erori de server. Adăugarea -v afișează anteturile solicitării/răspunsului, utilă pentru a detecta tokenuri de autentificare lipsă.

Testare interactivă cu Postman

GUI-ul Postman simplifică scenariile multi‑pas. Creează o colecție numită „Carpathron Robot”. Adaugă o solicitare „Get Video Stream” care să indice http://robot.local/api/v1/video și setează metoda la GET. Activează opțiunea „Save Response” pentru a captura fluxul MJPEG pentru analize ulterioare.

Folosește editorul de teste integrat pentru a verifica că antetul Content-Type este egal cu multipart/x-mixed-replace;boundary=frame. Exemplu de script:

pm.test("MJPEG header present", function () {
    pm.response.to.have.header("Content-Type", /multipart\/x-mixed-replace/);
});

Întreabă solicitările cu fila „Tests” pentru a verifica că un apel /move de succes schimbă mode de la idle la active. Exportă colecția și partajeaz-o cu colegii pentru testare de regresie consistentă.

Depanare live prin Carpathron Remote

Agentul Carpathron Remote include un chat și o interfață vocală care redirecționează comenzile direct la API-ul HTTP al robotului. Deschide consola de la distanță, tastează „move forward 0.3” și urmărește robotul să răspundă în timp real. Intrarea vocală funcționează la fel, permițând verificarea fără mâini a latenței și a interpretării comenzilor.

Remote afișează, de asemenea, URL-ul brut al solicitării și payload-ul înainte de transmitere, ceea ce ajută la identificarea denumirilor de parametri nepotrivite. Pentru o inspectare mai profundă, activează comutatorul „Log HTTP traffic”; jurnalul poate fi descărcat ca fișier .json și deschis în orice vizualizator JSON.

Învață mai multe despre funcția de asistență la distanță pe pagina de produs Carpathron Remote.

Instrumente de analiză a fluxului video

În timp ce curl poate prelua fluxul MJPEG, inspecția vizuală beneficiază de instrumente care decodează datele multipart. FFmpeg poate converti fluxul într-un fișier video local:

ffmpeg -i http://robot.local/api/v1/video -c copy robot_feed.mp4

După înregistrare, redă fișierul cu VLC pentru a verifica continuitatea cadrelor și latența. Dacă cadrele lipsesc, compară timestamp-urile din metadatele JSON returnate de /video/info cu durata fișierului înregistrat.

Verificări automate de sănătate

Combină curl cu un script shell simplu pentru a interoga robotul la fiecare 30 de secunde:

#!/bin/bash
while true; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://robot.local/api/v1/status)
  if [ "$STATUS" -ne 200 ]; then
    echo "$(date) – API down (HTTP $STATUS)" >> /var/log/robot_health.log
  fi
  sleep 30
done

Fișierul jurnal oferă un înregistrare cronologică a perioadelor de indisponibilitate, utilă atunci când corelezi evenimentele de rețea cu comportamentul robotului. Integrează scriptul cu systemd pentru a asigura rularea la pornire.

Sumar al toolkit-ului recomandat

• curl – rapid, scriptabil, arată traficul brut HTTP.
• Postman – constructor vizual de solicitări, teste automate, partajare colecții.
• Carpathron Remote – depanare live prin chat/voice, logare solicitări, feedback direct de la robot.
• FFmpeg – decodează și înregistrează fluxuri MJPEG pentru analiză vizuală.
• Scripturi shell – monitorizare continuă a sănătății și alertare.

Întrebări frecvente

Cum pot autentifica comenzile fără să construiesc propriul server de autentificare?

Protocolul Carpathron Robot suportă autentificarea bazată pe token generat de agentul Windows Muse Carpathron. După prima conexiune reușită, agentul returnează un JWT cu durată scurtă pe care clientul trebuie să îl includă în antetul Authorization al fiecărei cereri HTTP. Deoarece tokenul este semnat cu o cheie încorporată în binarul Windows, nu este necesar un serviciu extern de autentificare, iar tokenul expiră după cinci minute, forțând clientul să solicite unul nou.

Poate protocolul funcționa pe roboți Windows și Linux?

Da. Protocolul este pur HTTP cu payload opțional MJPEG, astfel încât orice platformă care poate rula un server web ușor poate să îl implementeze. Pe Linux poți folosi python -m http.server împreună cu ffmpeg pentru a servi fluxul MJPEG, în timp ce pe Windows agentul Muse Carpathron oferă un serviciu gata făcut care ascultă pe portul 8080. Ambele implementări expun aceleași puncte finale REST, făcând controlul cross‑platform fără probleme.

Ce lățime de bandă este necesară pentru un flux MJPEG lin?

Un flux MJPEG de 640×480 la 15 fps consumă de obicei 1,2 Mbps când calitatea de compresie este setată la 70 %. Pentru majoritatea rețelelor Wi‑Fi, acest lucru este bine în limita capacității unui canal de 2,4 GHz. Dacă ai nevoie de rezoluție sau rate de cadre mai mari, crește estimarea lățimii de bandă proporțional; un flux de 1280×720 la 30 fps poate ajunge la 5 Mbps.

Este posibil să adaugi un tehnician AI pentru acțiuni doar pentru admin?

Agentul Windows Muse Carpathron include un modul opțional de tehnician AI care poate fi activat prin parametrul de interogare adminMode=true. Când este activ, AI-ul poate interpreta comenzi în limbaj natural, cum ar fi „actualizează firmware” sau „resetează setările de rețea”, și le traduce în apeluri HTTP corespunzătoare. Deoarece modulul rulează local, nu trimite niciodată credențialele de admin către un serviciu extern, păstrând securitatea în timp ce oferă asistență fără mâini.

Cum gestionează protocolul întreruperile de rețea?

Fiecare cerere de comandă include un contor de retrageri în payload-ul JSON; robotul va încerca operația până la trei ori înainte de a returna o eroare. Pentru fluxurile MJPEG, clientul ar trebui să implementeze o logică de reconectare cu back‑off exponențial, deoarece serverul repornește automat fluxul atunci când primește un nou GET HTTP. În plus, autentificarea bazată pe token expiră rapid, forțând reautentificarea care servește și ca verificare de sănătate după o întrerupere.

Combinarea tuturor elementelor

Începe prin a instala aplicația Carpathron Robotics & Coding din Microsoft Store și conectează robotul ESP32‑CAM la aceeași rețea Wi‑Fi ca PC-ul tău. Deschide fila Settings, activează serverul HTTP și notează URL-ul de endpoint generat (de exemplu http://192.168.1.42:8080). Folosește ruta încorporată /cmd pentru a trimite comenzi JSON precum {"action":"move","direction":"forward","speed":50}. Robotul confirmă fiecare cerere cu un payload de stare, permițând verificarea execuției reușite.

Pentru feedback video, solicită fluxul MJPEG de la /video și încorporează URL-ul într-un browser sau într-un simplu tag <img>. Combină comenzile de mișcare cu verificări periodice ale imaginilor pentru a implementa evitarea obstacolelor sau logică de urmat linie. Toate interacțiunile sunt înregistrate în consola aplicației, care poate fi exportată pentru depanare.

Urmând acești pași, creezi un ciclu de control ușor, bazat pe HTTP, care funcționează cu orice hardware compatibil Carpathron. Când ești gata să explorezi scenarii mai avansate, vizitează pagina cea mai relevantă de pe Qubitpage pentru resurse suplimentare și exemple din comunitate.