Tema 2 - GPS Tracker (2024)

• Publicare:
  • 15 Decembrie 2024

• Termen de predare:
  • 16 Ianuarie 2025 23:55 - deadline HARD

Dorim să realizăm firmware-ul pentru un dispozitiv IoT de monitorizare GPS (emulat printr-un script Python) folosind un Raspberry PI (de asemenea, emulat folosind qemu).

Pe scurt, va trebui să realizați o imagine incorporabilă cu Linux ce va implementa o aplicație de achiziție a datelor de la un senzor GPS conectat printr-o interfață UART (protocolul textual NMEA pentru GPS, detalii mai jos) și expune pe rețea un server HTTP cu o pagină web de vizualizare a datelor capturate.

Exemplu de frontend web (aspectul nu contează, dar puteți să faceți ceva drăguț dacă aveți timp/chef):

Pas inițial: realizarea unei imagini de bază de Linux (kernel + rootfs) ce va fi folosită ca punct de plecare / suport pentru programele & serviciile cerute de restul cerințelor:

• Imaginea trebuie construită din componente de la zero: kernel compilat + rootfs;
• Rootfs-ul să ocupe cât mai puțin posibil (vedeți mai jos punctajele); se poate folosi orice distribuție & abordare de generat rootfs (atât printre cele studiate la laborator, cât și celelalte populare în industrie):
  • Buildroot – recomandat, puteți obține cele mai reduse dimensiuni!
  • Debian, prin qemu + debootstrap – nerecomandat (se vor obține dimensiuni destul de mari, 500MB ~ 1GB) și vor fi depunctate (-20p);
  • Alpine Linux bootstrap-uit folosind apk.static – procedură similară cu debootstrap, însă se vor obține imagini mult mai mici (recomandat pentru avansați, puteți folosi scriptul alpine-chroot-install dat citiți-i codul înainte)!
  • Yocto Linux - worse learning curve than BuildRoot (pentru experți ;) )
  • NU se acceptă: rootfs gata construit / descărcabil (e.g., imaginea cu Debian / Raspberry OS);
• Kernel compilat de voi cu LOCALVERSION="-si-<prenume.nume>" (altfel se depunctează! vedeți mai jos);
• Sistemul (rootfs + kernel) să fie compilat pe AArch64 (i.e.: arm64) și să poată fi rulat în qemu folosind machine type raspi3b (recomandat) sau raspi4b; vedeți mai jos config-uri de kernel testate deja pentru compatibilitate + script de rulare recomandat;
• Imaginea trebuie împachetată într-un fișier disk SD (a cărui dimensiune trebuie să fie o putere a lui 2, cum găsiți precizat prin tutoriale) – alegeți, însă, o dimensiune cât mai mică posibil (e.g., dacă imaginea voastră ocupă 70MB, creați disk SD de 128MB).

Sistemul trebuie să conțină următoarele configurații de bază (ne ajută pe noi, în special, să automatizăm partea de testare):

• utilizator root cu parola tema2 (obligatoriu: să ne putem autentifica în consola emulată);
• hostname-ul tema2;
• să-și preia automat IP-ul folosind DHCP pe prima interfață disponibilă (recomandat: folosiți la rulare parametrul de kernel net.ifnames=0, astfel încât numele primei interfețe să fie eth0 pentru o configurație portabilă – parametru deja prezent în scriptul de rulare din schelet);
• să ruleze SSH pe portul 22 (și să fie activată autentificarea cu root + parolă, aka setarea PermitRootLogin!);
• să ruleze Avahi mDNS daemon și să răspundă la numele tema2.local (opțional, dar ne ajută la testare; setupul pe host se face mai dificil, însă pe mașina emulată, însă este suficient să fie compilat/instalat pachetul avahi-daemon - sau echivalentul în distribuția aleasă - și testa cu ping tema2.local).

Rezolvarea acestei cerințe este OBLIGATORIE pentru obținerea oricărui fel de punctaj (altfel nu avem ce testa ⇒ 0p)!

Recomandăm folosirea kernelului mainline, descărcabil de pe https://kernel.org/ (sau Github, torvalds/linux). NU LUAȚI MASTER-ul sau alte branch-uri experimentale! Folosiți un branch/tag de versiune (e.g., v6.12).

La configurarea kernelului, va trebui să setați parametrul LOCALVERSION la valoarea -si-<prenume.nume> (folosiți username-ul de pe Moodle în loc de placeholderl <prenume.nume>, e.g. -si-florin.stoian!). Vedeți aici variabilele implicate, TLDR: nu uitați să dezactivați LOCALVERSION_AUTO pentru a putea set versiunea voastră custom!

Au fost testate versiunile v6.12 și v6.6, compilate atât automat prin buildroot (însă se configurează mai special, vedeți mai jos), cât și manual. Așadar, aveți două opțiuni de compilare:

Pentru o testare rapidă a sistemului rădăcină, puteți folosi imaginea vmlinuz-test inclusă în scheletul de temă în scheletul de temă (atenție: nu a fost testată pe distribuții Debian cu systemd!).

Pur și simplu se descarcă codul sursă torvalds/linux de pe git (ori din GitHub release, arhivă .tar.gz mult mai mică) și să dă make ca în laborator (nu uitați să modificați LOCALVERSION!)!

Pentru a a nu avea probleme cu copierea/instalarea modulelor externe (e.g.: mmc, să nu vadă rootfs-ul, sau să nu se încarce automat driverul de rețea usb-net), recomandăm dezactivarea modulelor de kernel, adică MODULES=n din menuconfig – acest lucru va face integrarea tuturor driverelor în imaginea de kernel și va omite copierea lor pe sistemul rădăcină (în <rootfs>/lib/modules).

Pentru cei care folosesc buildroot, aveți opțiunea de a compila kernelul Linux (în menuconfig, aveți BR2_LINUX_KERNEL cu toate opțiunile de descărcare necesare).

Însă procesul de adaptare a configurației de kernel necesită pași + documentare suplimentară (still pretty much recommended!):

• va trebui să folosiți kernelul mainline (torvalds/linux); se recomandă utilizarea unei reguli de descărcare a arhivei tar.gz de pe GitHub (documentație aici cu ce să puneți la URL de descărcare) + exemplu la config-ul oficial Buildroot pentru raspberrypi;
• va trebui ori să patchuiți linux/linux.hash și să adăugați hash-urile arhivei descărcate de pe GitHub asociate versiunii voastre, sau dezactiva de tot verificarea de hash prin opțiunea BR2_DOWNLOAD_FORCE_CHECK_HASHES=n (însă este mai complicat și necesită modificarea variabilei BR_NO_CHECK_HASH_FOR direct din Makefile, aceasta nu e expusă în Kconfig!!);
• pentru a încărca automat modulele de kernel pe un rootfs de Buildroot, aveți nevoie de o soluție de gestiune a dispozitivelor Linux; puteți ori să folosiți systemd, ori va trebui configurat EUDEV (recomandat), exemplu de config ce trebuie efectual (depinde de ce defconfig ați ales dacă sunt prezente sau nu):

  # se poate alege și biblioteca ucLibC, însă am avut probleme cu python3-flask
  BR2_TOOLCHAIN_BUILDROOT_MUSL=y
  BR2_SHARED_STATIC_LIBS=y
  BR2_ROOTFS_DEVICE_CREATION_DYNAMIC_EUDEV=y

  • soluție alternativă ar fi să faceți ca la compilare manuală: să compilați tot kernelul ca monolit, fără module externe (MODULES=n)!
• pentru a customiza kernelul (va trebui să modificați, cel puțin: LOCALVERSION*), aveți target-ul buildroot make linux-menuconfig (atenție: nu uitați să faceți save / backup la config-ul de kernel după modificare, citiți în manual cum);

Deși e prezent în defconfig (în caz că vreți să optimizați), nu uitați să includeți driver-ul pentru dispozitivul serial ce emulează dispozitivul GPS, model FTDI FT232H.

În final, la rularea prin qemu, trebuie să folosiți device tree-ul care începe cu bcm2837-, deoarece rulați kernel-ul mainline. Vedeți explicația aici sau aici. DTB-ul îl puteți compila voi (din kernel: make dtbs, sau, la Buildroot, aveți setare în meniu) sau prelua din altă parte (cât timp funcționează).

Dorim ca sistemul să expună un server HTTP pe portul 80 o interfață web minimalistă care să prezinte, în timp real, datele de la GPS primite (lat/long + dată/timp) prin UART:

* Sistemul va trebui să ruleze un server http ce va asculta pe portul 80;

• Puteți folosi orice limbaj de programare / scripting / framework pentru a construi acest endpoint; exemple:
  • Python: http.server / flask / Django / etc.;
  • NodeJS: http / ExpressJS / other 1000s of libraries;
  • PHP (+ Apache / Nginx / Lighttpd etc.): cu sau fără framework;
  • Golang: net/http (bonus: dimensiuni mici ale aplicațiilor!);
  • Rust: http (built in libraries + dimensiuni ff. mici, la fel ca la GoLang!);
  • C/C++ (for hardcore developers): Facil / Oat++ / etc. – performanță++ && dimensiuni%–% ;)
• Atenție: Dacă alegeți să compilați rootfs prin Buildroot, veți avea de scris/făcut rost de scripturi de compilare + împachetare atât pentru codul vostru + toate dependințele necesare (e.g., la Python PIP / VirtualEnv, pachete npm pentru NodeJS etc.)! Se poate, desigur, face cross compiling, însă trebuie folosit compilatorul de la Buildroot (same thing for Yocto)!

Datele de la GPS le veți prelua de la un alt serviciu, descris în subsecțiune următoare. Dacă nu doriți să rezolvați acel task, puteți să prezentați pur și simplu câteva date de test (i.e. hardcodate) în interfața Web.

Pe lângă serviciul web, va trebui să dezvoltați un daemon de achiziție a datelor de pe un dispozitiv serial (emulat prin QEmu ca usb-serial model FTDI FT232H, vizibil în guest Linux ca /dev/ttyUSB0);

• Programul va rula într-o buclă de citire de la dispozitiv, parsare și trimitere date către .
• La fel ca la serviciul web, puteți folosi orice limbaj / biblioteci de conectare pe dispozitivul serial (chiar și bash :D ):
  • Python: pyserial;
  • NodeJS: serialport;
  • PHP: DirectIO;
  • Golang: goserial sau alte biblioteci similare (sunt multe cu același nume);
  • Rust: serialport;
  • C: POSIX + termios;
• Puteți face comunicarea între cele 2 procese (de la daemonul de achiziție date seriale la server HTTP) prin orice mecanism vă pune Linux / limbajul la dispoziție (unix pipes, sockeți, RPC framework al limbajului, chiar și sistem de fișiere pentru o implementare rudimentară);
• Acest program trebuie OBLIGATORIU să se numească gps-daemon și să pornească automat cu sistemul!

<hint> Fiind serială emulată, baud rate-ul configurat nu contează! (merge aproape orice e standard).

Instalați picocom în imagine pentru depanare facilă!</hint>

Dispozitivul serial emulat va trimite informații codificate în ASCII folosind standardul NMEA, câte o linie per tip citire, un mesaj fiind terminat prin secvența newline CRLF (i.e. \r\n).

Exemplu date:

$GPGGA,115357.00,4419.000,N,02636.013,E,1,12,0.92,15.2,M,32.5,M,,*69
$GPGSA,A,3,25,24,07,17,03,01,27,14,30,26,29,12,1.56,0.92,1.25*00
$GPGSV,4,1,15,08,04,320,58,29,00,328,47,06,67,141,51,11,66,056,66*7D
$GPGSV,4,2,15,01,48,001,68,07,85,075,16,30,69,342,59,17,40,340,16*71
$GPGSV,4,3,15,03,62,124,05,14,04,320,40,25,44,340,66,12,46,287,06*71
$GPGSV,4,4,15,26,35,180,68,24,46,202,49,27,90,060,36*4E
$GPGLL,4419.000,N,02636.013,E,115357.000,A,A*56
$GPRMC,115357.000,A,4419.000,N,02636.013,E,10.500,90.0,151224,,,A*6D
$GPHDT,90.0,T*0C
$GPVTG,90.0,T,,M,10.5,N,19.4,K*51
$GPZDA,115357.000,15,12,2024,0,0*51

Va trebui să filtrați aceste date (e.g., să extrageți coordonatele GPS și data/timpul și să le convertiți într-un format prezentabil în interfața web).

Vedeți aici un tutorial al formatului NMEA 0183. Este suficient să parsați/preluați doar tipurile GGA (latitudine/longitudine) și ZDA (dată + timp UTC), însă ar fi nice to have și informațiile despre viteză / vector de deplasare.

Ca și punct de pornire, puteți descărca un schelet inițial cu scripturi + structură recomandată (v0.1). Aceasta conține:

• Makefile util pentru construirea arhivelor; obligatoriu să-l studiați + editați, nu face ce trebuie nemodificat!
• script de testare launch-tema2.sh pe sistemul gazdă (va rula qemu cu fișierele kernel+imagine, vedeți mai jos, la conținutul arhivei, ce denumiri folosește);
• un script Python gps-emu.py ce emulează datele de la dispozitiv, integrat cu launch-tema2.sh (comunică printr-un FIFO în /tmp, vedeți cod sursă);
• o imagine de kernel vmlinuz-test compilată ca monolit (MODULES=n) cu strictul necesar de drivere (consolă serială, PL011, 8250, FT232, USBNET, DHCP etc.);

Deoarece Moodle nu acceptă dimensiuni foarte mari, soluția temei va fi împărțită și trimisă în două moduri (vă rugăm să respectați convențiile de denumire cu exactitate!):

• arhivă cu codul sursă + Readme + hash și alte metainformații (vedeți mai jos) → pe Moodle
• arhivă cu binarele / imaginea rulabilă → le urcați pe Sharepoint-ul contului Microsoft de student și dați share prin Link Public (pe care ni-l trimiteți doar nouă în fișierul url.txt);

Arhiva cu binarele (.tar.*z pls; se acceptă gz și xz) trebuie să conțină (obligatoriu: să folosiți strict aceste denumiri de fișiere):

• tema2.img: imaginea finală (format raw!); poate conține sau nu partiții (dar va trebui să adaptați scriptul de rulare).
• vmlinuz-tema2: imaginea kernel-ului compatibil cu QEMU;
• launch-tema2.sh: script de pornire QEMU (vedeți scheletul dat);
• includeți și scripturile suplimentare necesare pentru rulare (e.g., simulatorul de GPS în Python, dacă l-ați modificat);
• NU INCLUDEȚI: cache-ul de build al Buildroot / Yocto (poate avea 6-20 GB!), DOAR artefactele finale (copiați-le manual sau folosiți ceva similar ca în Makefile-ul din schelet)!
• Această arhivă nu ar trebui să depășească 500MB (folosiți tar.xz pentru rată de compresie bună).

Arhiva cu fișierele sursă (.zip pls) OBLIGATORIU să conțină:

• sursele aplicației (în orice limbaje ați ales), scripturi custom folosite pentru build și/sau overlay-ul copiat pe rootfs (orice ați inclus extra peste sistemul de bază – de preferat, organizat într-o structură Unix-like: ./etc/, ./usr/bin, ./opt/* etc.); NU COPIAȚI ROOTFS-UL GENERAT! (doar OVERLAY-ul, dacă ați folosit);
• fișierele de configurație (.config) ale kernel și/sau buildroot – obligatoriu dacă e cazul! folosiți numele kernel_config și buildroot_config în arhiva cu sursele (în niciun caz nu le lăsați hidden!);
• fișier README.txt cu explicații referitoare la modul de construire al imaginii, arhitectura soluției, configurații speciale de optimizare folosite etc.
• fișier url.txt cu URL către arhiva .tar.*z a binarelor de pe Sharepoint! (uploadată anterior);
• fișier checksum.txt care să conțină hash-ul SHA256 al arhivei cu binarele (obținut cu sha256sum); ATENȚIE: verificați și re-verificați (de încă 2 ori) conținutul fișierului la încărcare pe Moodle cu hash-ul real deoarece tema nu va fi punctată dacă diferă!
• NU INCLUDEȚI: fișiere sursă ale Buildroot / Yocto / biblioteci / frameworkuri / VirtualEnv descărcabile de pe Internet (menționați în Readme ce ați folosit);
• Hint: pentru a include un fișier la crearea automată a arhivei prin make source_archive, pur și simplu copiați-l pe rădăcină (sau într-un director care nu este ignorat – verificați Makefile-ul din schelet)!
• Această arhivă nu ar trebui să depășească 1MB (aveți restricție pe Moodle).

Din 100p total, aveți:

• (40p) Imaginea și funcționalitățile de bază (trebuie să ruleze în qemu!);
  • -20p depunctare pentru imagine/rootfs (contorizat fără kernel, ce poate avea max. 64M – deși nu e imposibil să-l faceți s depășească această dimensiune, încercați să nu) ce depășește 256MB (testat cu interpretorul Python în Buildroot, tot se încadrează în limită!);
  • -10p depunctare pentru kernel necompilat de voi (ori îl folosiți pe cel furnizat de noi în schelet, ori cel furnizat de voi nu conține LOCALVERSION="-si-<prenume.nume>");
  • Notă: chiar și cu depunctare, a avea un sistem funcțional în qemu este obligatoriu pentru a lua restul de puncte acordate pe task-urile următoare!
• (20p) Serverul web de prezentare a valorilor de la GPS;
• (30p) Daemonul care achiziționaează datele GPS pe UART;
• (10p) Readme scris clar și care descrie procesul urmat, arhitectura și implementarea funcționalităților cerute.

Bonus:

• (10p) Aspect / funcționalitate deosebită (e.g., grafice ale datelor / hartă pentru coordonatele GPS, implementări eficiente/elegante, utilizare Yocto :D etc.);
• (10p) Optimizări deosebite de spațiu ale imaginii finale (cele mai mici 10 imagini primite, însă doar dintre cele care implementează toate task-urile!);

• Tema are deadline HARD (nu mai sunt admise soluții după expirare), așadar se recomandă să vă apucați din timp de rezolvarea acesteia!
• ATENȚIE: orice formă de plagiat nu va fi permisă și va duce la depunctare totală / restanță!
• Pe Moodle găsiți și un forum ;) La fel pe Teams, avem un canal de discuții.

• Laboratorul 05. QEMU & Tools
• Laboratorul 06. The embedded boot process
• Laboratorul 07. Root filesystem și servicii de sistem
• Laboratorul 08. Kernel Build System
• Laboratorul 09. RootFS Bootstrapping
• Buildroot manual