Frontend WebHID filtar uređaja: Objašnjen odabir uređaja s ljudskim sučeljem (HID)

WebHID API otvara svijet mogućnosti za web aplikacije, omogućujući im izravnu interakciju s uređajima s ljudskim sučeljem (HID) poput gamepada, specijaliziranih ulaznih uređaja i više. Ključan dio učinkovitog korištenja WebHID-a je razumijevanje filtara uređaja. Ovaj sveobuhvatni vodič provest će vas kroz sve detalje WebHID filtara uređaja, osnažujući vas da stvorite moćna i zanimljiva web iskustva.

Što je WebHID?

WebHID je web API koji omogućuje web aplikacijama komunikaciju s HID uređajima spojenim na korisnikovo računalo ili mobilni uređaj. Za razliku od tradicionalnih web API-ja koji se oslanjaju na specifične upravljačke programe (drivere), WebHID pruža generičko sučelje za interakciju sa širokim rasponom uređaja, pod uvjetom da korisnik da dopuštenje. To ga čini idealnim za uređaje koji nemaju izvornu podršku preglednika ili zahtijevaju prilagođeno rukovanje unosom.

Zašto koristiti WebHID?

• Izravan pristup uređaju: Komunicirajte izravno s HID uređajima bez oslanjanja na upravljačke programe specifične za preglednik.
• Prilagođeno rukovanje unosom: Implementirajte prilagođeno mapiranje i obradu unosa za specijalizirane uređaje.
• Široka podrška za uređaje: Podržite širi raspon uređaja, uključujući gamepade, znanstvene instrumente i industrijske kontrolere.
• Poboljšano korisničko iskustvo: Stvorite upečatljivija i interaktivnija web iskustva.

Razumijevanje WebHID filtara uređaja

Filtri uređaja ključni su za traženje pristupa određenim HID uređajima. Kada vaša web aplikacija pozove navigator.hid.requestDevice(), preglednik prikazuje birač uređaja, omogućujući korisniku odabir uređaja. Filtri uređaja omogućuju vam da suzite popis uređaja predstavljenih korisniku, olakšavajući im pronalaženje onog ispravnog.

Filtar uređaja je JavaScript objekt koji specificira kriterije za podudaranje s HID uređajima. Možete specificirati više filtara u pozivu requestDevice(), a preglednik će prikazati samo uređaje koji odgovaraju barem jednom od filtara.

Svojstva filtra uređaja

• vendorId (opcionalno): USB ID dobavljača (Vendor ID) uređaja. To je 16-bitni broj koji identificira proizvođača uređaja.
• productId (opcionalno): USB ID proizvoda (Product ID) uređaja. To je 16-bitni broj koji identificira specifičan model uređaja.
• usagePage (opcionalno): HID stranica upotrebe (Usage Page) uređaja. Ona identificira kategoriju uređaja (npr. Općenite kontrole radne površine, Kontrole za igre).
• usage (opcionalno): HID upotreba (Usage) uređaja. Ona identificira specifičnu funkciju uređaja unutar stranice upotrebe (npr. Joystick, Gamepad).

Možete koristiti kombinaciju ovih svojstava za stvaranje vrlo specifičnih filtara. Na primjer, mogli biste filtrirati uređaje s određenim vendorId i productId kako biste ciljali određeni model gamepada.

Praktični primjeri filtara uređaja

Pogledajmo neke praktične primjere kako koristiti filtre uređaja u vašim web aplikacijama.

Primjer 1: Filtriranje za određeni gamepad

Pretpostavimo da želite ciljati određeni gamepad s poznatim vendorId i productId. Možete koristiti sljedeći filtar:

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Xbox 360 Controller
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Handle the selected device(s)
  })
  .catch((error) => {
    // Handle errors
  });

            

              
                Copy
              
            
          

U ovom primjeru, filtar će odgovarati samo uređajima s vendorId od 0x045e (Microsoft) i productId od 0x028e (Xbox 360 kontroler). Zamijenite ih odgovarajućim ID-om dobavljača i ID-om proizvoda uređaja kojeg ciljate.

Primjer 2: Filtriranje za bilo koji gamepad

Ako želite korisniku omogućiti odabir bilo kojeg gamepada, možete koristiti filtar koji specificira usagePage i usage za gamepade:

            const filters = [
  {
    usagePage: 0x01, // Generic Desktop Controls
    usage: 0x05, // Gamepad
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Handle the selected device(s)
  })
  .catch((error) => {
    // Handle errors
  });

            

              
                Copy
              
            
          

Ovaj filtar će odgovarati svakom HID uređaju koji se identificira kao gamepad koristeći standardne HID kodove upotrebe.

Primjer 3: Kombiniranje filtara

Možete kombinirati više filtara kako biste pružili veću fleksibilnost. Na primjer, možda želite korisniku omogućiti odabir ili određenog modela gamepada ili bilo kojeg gamepada:

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Xbox 360 Controller
  },
  {
    usagePage: 0x01, // Generic Desktop Controls
    usage: 0x05, // Gamepad
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Handle the selected device(s)
  })
  .catch((error) => {
    // Handle errors
  });

            

              
                Copy
              
            
          

U ovom slučaju, birač uređaja će prikazati i specifični Xbox 360 kontroler (ako je spojen) i bilo koji drugi uređaj koji se identificira kao gamepad.

Primjer 4: Filtriranje za specifičnu vrstu tipkovnice na sustavu

Neke specijalizirane tipkovnice zahtijevaju specifične HID kodove za pravilnu inicijalizaciju. Sljedeći primjer pretpostavlja da znate ID dobavljača, ID proizvoda, stranicu upotrebe i upotrebu za tipkovnicu. Ove informacije obično možete pronaći u dokumentaciji proizvođača ili korištenjem alata za popisivanje uređaja dostupnih na većini operativnih sustava.

            const filters = [
    {
        vendorId: 0x1234,  // Replace with your vendor ID
        productId: 0x5678, // Replace with your product ID
        usagePage: 0x07,   // Replace with your usage page (e.g., Keyboard/Keypad)
        usage: 0x01      // Replace with your usage (e.g., Keyboard)
    }
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Handle the selected device(s)
  })
  .catch((error) => {
    // Handle errors
  });

            

              
                Copy
              
            
          

Dobivanje informacija o uređaju

Jednom kada korisnik odabere uređaj, možete pristupiti njegovim informacijama koristeći HIDDevice objekt.

Svojstva HIDDevice-a

• vendorId: USB ID dobavljača (Vendor ID) uređaja.
• productId: USB ID proizvoda (Product ID) uređaja.
• productName: Naziv uređaja.
• collections: Niz HIDCollection objekata koji predstavljaju deskriptore HID izvješća uređaja.

Možete koristiti ove informacije za identifikaciju uređaja i konfiguraciju vaše aplikacije u skladu s tim.

Rukovanje HID izvješćima

Nakon što ste dobili HIDDevice, trebate ga otvoriti i početi osluškivati HID izvješća. HID izvješća su sirovi podaci koje uređaj šalje vašoj aplikaciji.

Otvaranje uređaja

            device.open()
  .then(() => {
    console.log('Device opened');

    // Start listening for input reports
    device.addEventListener('inputreport', (event) => {
      const { data, reportId } = event;
      // Process the input report
      console.log(`Received input report with ID ${reportId}:`, data);
    });
  })
  .catch((error) => {
    console.error('Failed to open device:', error);
  });

            

              
                Copy
              
            
          

Obrada ulaznih izvješća

Ulazna izvješća primaju se kao DataView objekti. Struktura podataka ovisi o deskriptoru HID izvješća uređaja. Morat ćete konzultirati dokumentaciju uređaja kako biste razumjeli kako interpretirati podatke.

Evo pojednostavljenog primjera kako obraditi ulazno izvješće:

            device.addEventListener('inputreport', (event) => {
  const { data, reportId } = event;

  // Assuming the first byte of the report represents the button state
  const buttonState = data.getUint8(0);

  // Process the button state
  if (buttonState & 0x01) {
    console.log('Button 1 pressed');
  }
  if (buttonState & 0x02) {
    console.log('Button 2 pressed');
  }
});

            

              
                Copy
              
            
          

Ovo je vrlo osnovni primjer. HID uređaji u stvarnom svijetu često imaju složenije strukture izvješća. Reverzni inženjering HID izvješća može biti složen proces; međutim, dostupni su alati koji pomažu u procesu parsiranja.

Rukovanje greškama

Važno je elegantno rukovati greškama pri radu s WebHID-om. Evo nekih uobičajenih grešaka s kojima se možete susresti:

• SecurityError: Korisnik je odbio dopuštenje za pristup HID uređajima.
• NotFoundError: Nisu pronađeni odgovarajući uređaji.
• InvalidStateError: Uređaj je već otvoren.
• Ostale greške: USB greške, neočekivana isključenja uređaja.

Uvijek omotajte svoj WebHID kod u try...catch blokove i pružite informativne poruke o greškama korisniku.

Najbolje prakse za WebHID razvoj

• Koristite filtre uređaja: Uvijek koristite filtre uređaja kako biste suzili popis uređaja predstavljenih korisniku.
• Pružite jasne upute: Uputite korisnike kako spojiti i autorizirati uređaj, a ako se uređaj ne pojavi, objasnite im gdje mogu pronaći ID dobavljača i ID proizvoda za uobičajene uređaje.
• Elegantno rukujte greškama: Implementirajte robusno rukovanje greškama kako biste osigurali glatko korisničko iskustvo.
• Konzultirajte dokumentaciju uređaja: Pogledajte dokumentaciju uređaja kako biste razumjeli njegov deskriptor HID izvješća.
• Testirajte na više platformi: Testirajte svoju aplikaciju na različitim preglednicima i operativnim sustavima kako biste osigurali kompatibilnost.
• Razmotrite sigurnost: Budite svjesni sigurnosnih implikacija pri radu s korisničkim unosom. Sanitizirajte podatke i izbjegavajte izvršavanje nepouzdanog koda.
• Pružite alternativne opcije: Ako WebHID nije podržan ili korisnik odbije dopuštenje, pružite alternativne metode unosa.

Napredne tehnike

Izvješća o značajkama (Feature Reports)

Osim ulaznih izvješća, HID uređaji također mogu slati i primati izvješća o značajkama. Izvješća o značajkama koriste se za konfiguraciju uređaja ili dohvaćanje njegovog statusa.

Za slanje izvješća o značajkama, koristite metodu device.sendFeatureReport().

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Example data

device.sendFeatureReport(reportId, data)
  .then(() => {
    console.log('Feature report sent successfully');
  })
  .catch((error) => {
    console.error('Failed to send feature report:', error);
  });

            

              
                Copy
              
            
          

Za primanje izvješća o značajkama, koristite metodu device.getFeatureReport().

            const reportId = 0x01;

device.getFeatureReport(reportId)
  .then((data) => {
    console.log('Received feature report:', data);
  })
  .catch((error) => {
    console.error('Failed to get feature report:', error);
  });

            

              
                Copy
              
            
          

Izlazna izvješća (Output Reports)

WebHID također podržava izlazna izvješća, koja vam omogućuju slanje podataka *na* uređaj. Na primjer, mogli biste koristiti izlazna izvješća za kontrolu LED dioda ili drugih aktuatora na uređaju.

Za slanje izlaznog izvješća, koristite metodu device.sendReport().

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Example data

device.sendReport(reportId, data)
  .then(() => {
    console.log('Output report sent successfully');
  })
  .catch((error) => {
    console.error('Failed to send output report:', error);
  });

            

              
                Copy
              
            
          

Sigurnosna razmatranja

Pristup WebHID-u zahtijeva dopuštenje korisnika, što pomaže u ublažavanju nekih sigurnosnih rizika. Međutim, i dalje je važno biti svjestan potencijalnih ranjivosti.

• Sanitizacija podataka: Uvijek sanitizirajte podatke primljene s HID uređaja kako biste spriječili ubacivanje koda (code injection) ili druge napade.
• Ograničenja podrijetla: WebHID podliježe politici istog podrijetla (same-origin policy), što sprječava pristup HID uređajima s različitih podrijetla.
• Svijest korisnika: Educirajte korisnike o rizicima davanja pristupa HID uređajima i potičite ih da dopuštenje daju samo pouzdanim web stranicama.

Globalne perspektive i primjeri

WebHID API ima globalne implikacije, omogućujući programerima stvaranje web aplikacija koje podržavaju širok raspon uređaja različitih proizvođača i regija. Razmotrite ove primjere:

• Igranje: Podrška za gamepade različitih proizvođača iz različitih zemalja (npr. Sony PlayStation kontroleri, Microsoft Xbox kontroleri, Nintendo Switch Pro kontroler i manje poznate marke iz Azije i Europe).
• Pristupačnost: Stvaranje prilagođenih ulaznih uređaja za korisnike s invaliditetom, uzimajući u obzir različite regionalne standarde pristupačnosti i preferencije. Na primjer, specijalizirane tipkovnice ili sučelja s prekidačima dizajnirana za specifične potrebe i dostupna u različitim rasporedima.
• Industrijska automatizacija: Povezivanje s industrijskim kontrolerima i senzorima koji se koriste u proizvodnim pogonima diljem svijeta, podržavajući različite komunikacijske protokole i formate podataka.
• Znanstveno istraživanje: Povezivanje sa znanstvenim instrumentima koji se koriste u istraživačkim laboratorijima globalno, omogućujući istraživačima prikupljanje i analizu podataka izravno u web aplikacijama. Zamislite kontroliranje laboratorijske opreme na sveučilištu u Tokiju s laptopa istraživača u Londonu.
• Obrazovanje: Podrška za obrazovne robote i interaktivne uređaje koji se koriste u učionicama diljem svijeta, pružajući učenicima praktična iskustva učenja. To bi moglo uključivati robote za kodiranje proizvedene u Kini koji se koriste u učionici u Brazilu.

WebHID u usporedbi s drugim web API-jima

Vrijedno je napomenuti kako se WebHID uspoređuje s drugim web API-jima vezanim za interakciju s uređajima:

• Gamepad API: Gamepad API pruža sučelje više razine specifično za gamepade. WebHID nudi veću fleksibilnost i kontrolu, ali zahtijeva više ručnog rukovanja podacima uređaja. Gamepad API je prikladan za uobičajene gamepade, dok WebHID može podržati egzotičnije ili specijalizirane ulazne uređaje.
• WebUSB API: WebUSB omogućuje web aplikacijama izravnu komunikaciju s USB uređajima. WebHID je specifično dizajniran za uređaje s ljudskim sučeljem, dok se WebUSB može koristiti za širi raspon USB uređaja. WebUSB bi se mogao koristiti za specijalizirani znanstveni instrument spojen putem USB-a, dok bi se WebHID koristio za prilagođenu tipkovnicu ili miš.
• Web Serial API: Web Serial omogućuje komunikaciju preko serijskih portova. To je korisno za interakciju s ugrađenim sustavima i drugim uređajima koji komuniciraju preko serijskih veza. Mikrokontroler koji šalje podatke preko serijske veze mogao bi koristiti Web Serial, dok bi prilagođeni joystick koristio WebHID.

Budućnost WebHID-a

WebHID API se neprestano razvija, uz stalne napore da se poboljša njegova sigurnost, performanse i jednostavnost korištenja. Kako sve više uređaja usvaja HID standard, WebHID će postati sve važniji alat za web programere. Očekujte vidjeti naprednije značajke i poboljšanu podršku preglednika u budućnosti.

Zaključak

WebHID je moćan API koji otvara širok raspon mogućnosti za web aplikacije. Razumijevanjem filtara uređaja i načina rukovanja HID izvješćima, možete stvoriti zanimljiva i interaktivna web iskustva koja iskorištavaju puni potencijal uređaja s ljudskim sučeljem. Bilo da gradite igru, alat za pristupačnost ili industrijski kontrolni sustav, WebHID vam može pomoći povezati vašu web aplikaciju s fizičkim svijetom. Ne zaboravite dati prioritet korisničkom iskustvu, sigurnosti i kompatibilnosti na više platformi kako biste stvorili uspješne i globalno dostupne WebHID aplikacije.