Frontend WebHID -laitesuodatin: HID-laitteiden valinnan selitys

WebHID API avaa verkkosovelluksille uusia mahdollisuuksia, mahdollistaen niiden suoran vuorovaikutuksen HID-laitteiden (Human Interface Devices) kuten peliohjainten, erikoistuneiden syöttölaitteiden ja muiden kanssa. Laitesuodattimien ymmärtäminen on kriittinen osa WebHID:n tehokasta käyttöä. Tämä kattava opas johdattaa sinut WebHID-laitesuodattimien saloihin, antaen sinulle valmiudet luoda tehokkaita ja mukaansatempaavia verkkokokemuksia.

Mikä on WebHID?

WebHID on verkko-API, joka mahdollistaa verkkosovellusten kommunikoinnin käyttäjän tietokoneeseen tai mobiililaitteeseen yhdistettyjen HID-laitteiden kanssa. Toisin kuin perinteiset verkko-API:t, jotka tukeutuvat tiettyihin laiteajureihin, WebHID tarjoaa yleisen rajapinnan vuorovaikutukseen monenlaisten laitteiden kanssa, kunhan käyttäjä myöntää siihen luvan. Tämä tekee siitä ihanteellisen laitteille, joilla ei ole natiivia selain-tukea tai jotka vaativat mukautettua syötteiden käsittelyä.

Miksi käyttää WebHID:tä?

• Suora pääsy laitteeseen: Kommunikoi suoraan HID-laitteiden kanssa ilman selainkohtaisia ajureita.
• Mukautettu syötteiden käsittely: Toteuta mukautettuja syötteiden yhdistämis- ja käsittelytoimintoja erikoistuneille laitteille.
• Laaja laitetuki: Tue laajempaa valikoimaa laitteita, mukaan lukien peliohjaimet, tieteelliset instrumentit ja teollisuuden ohjaimet.
• Parannettu käyttäjäkokemus: Luo immersiivisempiä ja interaktiivisempia verkkokokemuksia.

WebHID-laitesuodattimien ymmärtäminen

Laitesuodattimet ovat ratkaisevan tärkeitä, kun pyydetään pääsyä tiettyihin HID-laitteisiin. Kun verkkosovelluksesi kutsuu navigator.hid.requestDevice()-metodia, selain näyttää laitevalitsimen, jossa käyttäjä voi valita laitteen. Laitesuodattimien avulla voit rajata käyttäjälle esitettävien laitteiden luetteloa, mikä helpottaa oikean laitteen löytämistä.

Laitesuodatin on JavaScript-olio, joka määrittelee kriteerit HID-laitteiden vastaavuudelle. Voit määrittää useita suodattimia requestDevice()-kutsussa, ja selain näyttää vain laitteet, jotka vastaavat vähintään yhtä suodattimista.

Laitesuodattimen ominaisuudet

• vendorId (valinnainen): Laitteen USB-valmistajatunnus. Tämä on 16-bittinen luku, joka tunnistaa laitteen valmistajan.
• productId (valinnainen): Laitteen USB-tuotetunnus. Tämä on 16-bittinen luku, joka tunnistaa laitteen tietyn mallin.
• usagePage (valinnainen): Laitteen HID-käyttötarkoitussivu. Tämä tunnistaa laitteen kategorian (esim. yleiset työpöytäohjaimet, peliohjaimet).
• usage (valinnainen): Laitteen HID-käyttötarkoitus. Tämä tunnistaa laitteen tietyn toiminnon käyttötarkoitussivun sisällä (esim. joystick, peliohjain).

Voit käyttää näiden ominaisuuksien yhdistelmää luodaksesi erittäin tarkkoja suodattimia. Voit esimerkiksi suodattaa laitteita, joilla on tietty vendorId ja productId, kohdistaaksesi tietyn peliohjainmallin.

Käytännön esimerkkejä laitesuodattimista

Katsotaan muutamia käytännön esimerkkejä laitesuodattimien käytöstä verkkosovelluksissasi.

Esimerkki 1: Tietyn peliohjaimen suodattaminen

Oletetaan, että haluat kohdistaa tietyn peliohjaimen, jonka vendorId ja productId ovat tiedossa. Voit käyttää seuraavaa suodatinta:

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

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Käsittele valittu laite / valitut laitteet
  })
  .catch((error) => {
    // Käsittele virheet
  });

            

              
                Copy
              
            
          

Tässä esimerkissä suodatin vastaa vain laitteita, joiden vendorId on 0x045e (Microsoft) ja productId on 0x028e (Xbox 360 -ohjain). Korvaa nämä arvot kohdelaitteen asianmukaisella valmistajatunnuksella ja tuotetunnuksella.

Esimerkki 2: Minkä tahansa peliohjaimen suodattaminen

Jos haluat antaa käyttäjän valita minkä tahansa peliohjaimen, voit käyttää suodatinta, joka määrittää peliohjainten usagePage- ja usage-arvot:

            const filters = [
  {
    usagePage: 0x01, // Yleiset työpöytäohjaimet
    usage: 0x05, // Peliohjain
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Käsittele valittu laite / valitut laitteet
  })
  .catch((error) => {
    // Käsittele virheet
  });

            

              
                Copy
              
            
          

Tämä suodatin vastaa kaikkia HID-laitteita, jotka tunnistautuvat peliohjaimiksi standardien HID-käyttökoodeja käyttäen.

Esimerkki 3: Suodattimien yhdistäminen

Voit yhdistää useita suodattimia lisätäksesi joustavuutta. Voit esimerkiksi haluta antaa käyttäjän valita joko tietyn peliohjainmallin tai minkä tahansa peliohjaimen:

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Xbox 360 -ohjain
  },
  {
    usagePage: 0x01, // Yleiset työpöytäohjaimet
    usage: 0x05, // Peliohjain
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Käsittele valittu laite / valitut laitteet
  })
  .catch((error) => {
    // Käsittele virheet
  });

            

              
                Copy
              
            
          

Tässä tapauksessa laitevalitsin näyttää sekä tietyn Xbox 360 -ohjaimen (jos se on yhdistetty) että kaikki muut laitteet, jotka tunnistautuvat peliohjaimiksi.

Esimerkki 4: Tietyn näppäimistötyypin suodattaminen järjestelmässä

Jotkin erikoisnäppäimistöt vaativat tietyt HID-koodit oikein alustuakseen. Seuraava esimerkki olettaa, että tiedät näppäimistön valmistajatunnuksen, tuotetunnuksen, käyttötarkoitussivun ja käyttötarkoituksen. Nämä tiedot löytyvät yleensä valmistajan dokumentaatiosta tai useimmissa käyttöjärjestelmissä saatavilla olevilla laitelistaustyökaluilla.

            const filters = [
    {
        vendorId: 0x1234,  // Korvaa omalla valmistajatunnuksellasi
        productId: 0x5678, // Korvaa omalla tuotetunnuksellasi
        usagePage: 0x07,   // Korvaa omalla käyttötarkoitussivullasi (esim. näppäimistö/numeronäppäimistö)
        usage: 0x01      // Korvaa omalla käyttötarkoituksellasi (esim. näppäimistö)
    }
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Käsittele valittu laite / valitut laitteet
  })
  .catch((error) => {
    // Käsittele virheet
  });

            

              
                Copy
              
            
          

Laitetietojen hakeminen

Kun käyttäjä on valinnut laitteen, voit käyttää sen tietoja HIDDevice-olion kautta.

HIDDevice-olion ominaisuudet

• vendorId: Laitteen USB-valmistajatunnus.
• productId: Laitteen USB-tuotetunnus.
• productName: Laitteen nimi.
• collections: Taulukko HIDCollection-olioita, jotka edustavat laitteen HID-raporttien kuvaajia.

Voit käyttää näitä tietoja laitteen tunnistamiseen ja sovelluksesi konfigurointiin.

HID-raporttien käsittely

Kun olet saanut HIDDevice-olion, sinun täytyy avata se ja aloittaa HID-raporttien kuuntelu. HID-raportit ovat laitteen sovelluksellesi lähettämää raakadataa.

Laitteen avaaminen

            device.open()
  .then(() => {
    console.log('Laite avattu');

    // Aloita syöteraporttien kuuntelu
    device.addEventListener('inputreport', (event) => {
      const { data, reportId } = event;
      // Käsittele syöteraportti
      console.log(`Vastaanotettu syöteraportti ID:llä ${reportId}:`, data);
    });
  })
  .catch((error) => {
    console.error('Laitteen avaaminen epäonnistui:', error);
  });

            

              
                Copy
              
            
          

Syöteraporttien käsittely

Syöteraportit vastaanotetaan DataView-olioina. Datan rakenne riippuu laitteen HID-raportin kuvaajasta. Sinun tulee tutustua laitteen dokumentaatioon ymmärtääksesi, miten dataa tulkitaan.

Tässä on yksinkertaistettu esimerkki syöteraportin käsittelystä:

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

  // Olettaen, että raportin ensimmäinen tavu edustaa painikkeiden tilaa
  const buttonState = data.getUint8(0);

  // Käsittele painikkeiden tila
  if (buttonState & 0x01) {
    console.log('Painike 1 painettu');
  }
  if (buttonState & 0x02) {
    console.log('Painike 2 painettu');
  }
});

            

              
                Copy
              
            
          

Tämä on hyvin perusesimerkki. Todellisten HID-laitteiden raporttirakenteet ovat usein monimutkaisempia. HID-raportin käänteismallinnus voi olla monimutkainen prosessi; on kuitenkin olemassa työkaluja, jotka auttavat jäsentämisessä.

Virheidenkäsittely

On tärkeää käsitellä virheet asianmukaisesti WebHID:n kanssa työskennellessä. Tässä muutamia yleisiä virheitä, joihin saatat törmätä:

• SecurityError: Käyttäjä on kieltänyt luvan päästä HID-laitteisiin.
• NotFoundError: Yhtään vastaavaa laitetta ei löytynyt.
• InvalidStateError: Laite on jo avattu.
• Muut virheet: USB-virheet, odottamattomat laitteen yhteyden katkeamiset.

Kääri WebHID-koodisi aina try...catch-lohkoihin ja anna käyttäjälle informatiivisia virheilmoituksia.

WebHID-kehityksen parhaat käytännöt

• Käytä laitesuodattimia: Käytä aina laitesuodattimia rajataksesi käyttäjälle esitettävien laitteiden luetteloa.
• Anna selkeät ohjeet: Ohjeista käyttäjiä laitteen yhdistämisessä ja valtuuttamisessa. Jos laite ei ilmesty, selitä käyttäjälle, mistä löytää yleisten laitteiden valmistaja- ja tuotetunnukset.
• Käsittele virheet asianmukaisesti: Toteuta vankka virheidenkäsittely varmistaaksesi sujuvan käyttäjäkokemuksen.
• Tutustu laitteen dokumentaatioon: Viittaa laitteen dokumentaatioon ymmärtääksesi sen HID-raportin kuvaajan.
• Testaa useilla alustoilla: Testaa sovellustasi eri selaimilla ja käyttöjärjestelmillä yhteensopivuuden varmistamiseksi.
• Harkitse turvallisuutta: Ole tietoinen turvallisuusvaikutuksista, kun työskentelet käyttäjän syötteiden kanssa. Puhdista data ja vältä epäluotettavan koodin suorittamista.
• Tarjoa varavaihtoehtoja: Jos WebHID:tä ei tueta tai käyttäjä kieltää luvan, tarjoa vaihtoehtoisia syöttötapoja.

Edistyneet tekniikat

Ominaisuusraportit (Feature Reports)

Syöteraporttien lisäksi HID-laitteet voivat myös lähettää ja vastaanottaa ominaisuusraportteja. Ominaisuusraportteja käytetään laitteen konfigurointiin tai sen tilan hakemiseen.

Lähettääksesi ominaisuusraportin, käytä device.sendFeatureReport()-metodia.

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

device.sendFeatureReport(reportId, data)
  .then(() => {
    console.log('Ominaisuusraportti lähetetty onnistuneesti');
  })
  .catch((error) => {
    console.error('Ominaisuusraportin lähettäminen epäonnistui:', error);
  });

            

              
                Copy
              
            
          

Vastaanottaaksesi ominaisuusraportin, käytä device.getFeatureReport()-metodia.

            const reportId = 0x01;

device.getFeatureReport(reportId)
  .then((data) => {
    console.log('Vastaanotettu ominaisuusraportti:', data);
  })
  .catch((error) => {
    console.error('Ominaisuusraportin hakeminen epäonnistui:', error);
  });

            

              
                Copy
              
            
          

Tulostusraportit (Output Reports)

WebHID tukee myös tulostusraportteja, joiden avulla voit lähettää dataa laitteelle. Voit esimerkiksi käyttää tulostusraportteja ohjaamaan laitteen LED-valoja tai muita toimilaitteita.

Lähettääksesi tulostusraportin, käytä device.sendReport()-metodia.

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

device.sendReport(reportId, data)
  .then(() => {
    console.log('Tulostusraportti lähetetty onnistuneesti');
  })
  .catch((error) => {
    console.error('Tulostusraportin lähettäminen epäonnistui:', error);
  });

            

              
                Copy
              
            
          

Turvallisuusnäkökohdat

WebHID-pääsy vaatii käyttäjän luvan, mikä auttaa lieventämään joitakin turvallisuusriskejä. On kuitenkin tärkeää olla tietoinen mahdollisista haavoittuvuuksista.

• Datan puhdistaminen: Puhdista aina HID-laitteilta saatu data estääksesi koodin injektoinnin tai muut hyökkäykset.
• Alkuperärajoitukset: WebHID noudattaa saman alkuperän käytäntöä (same-origin policy), mikä estää pääsyn HID-laitteisiin eri alkuperästä.
• Käyttäjien tietoisuus: Valista käyttäjiä HID-laitteisiin pääsyn myöntämisen riskeistä ja kannusta heitä myöntämään lupa vain luotetuille verkkosivustoille.

Globaalit näkökulmat ja esimerkit

WebHID API:lla on globaaleja vaikutuksia, jotka mahdollistavat kehittäjille verkkosovellusten luomisen, jotka tukevat laajaa valikoimaa laitteita eri valmistajilta ja alueilta. Harkitse näitä esimerkkejä:

• Pelaaminen: Eri maiden eri valmistajien peliohjainten tukeminen (esim. Sony PlayStation -ohjaimet, Microsoft Xbox -ohjaimet, Nintendo Switch Pro Controller ja vähemmän tunnetut merkit Aasiasta ja Euroopasta).
• Saavutettavuus: Mukautettujen syöttölaitteiden luominen vammaisille käyttäjille, ottaen huomioon erilaiset alueelliset saavutettavuusstandardit ja mieltymykset. Esimerkiksi erikoistuneet näppäimistöt tai kytkinrajapinnat, jotka on suunniteltu erityistarpeisiin ja saatavilla eri asetteluilla.
• Teollisuusautomaatio: Liittyminen teollisuuden ohjaimiin ja antureihin, joita käytetään tuotantolaitoksissa ympäri maailmaa, tukien erilaisia viestintäprotokollia ja datamuotoja.
• Tieteellinen tutkimus: Yhdistäminen tieteellisiin instrumentteihin, joita käytetään tutkimuslaboratorioissa maailmanlaajuisesti, mahdollistaen tutkijoille datan keräämisen ja analysoinnin suoraan verkkosovelluksissa. Kuvittele laboratoriolaitteiden ohjaamista Tokion yliopistossa tutkijan kannettavalta Lontoossa.
• Koulutus: Koulutusrobottien ja interaktiivisten laitteiden tukeminen, joita käytetään luokkahuoneissa maailmanlaajuisesti, tarjoten opiskelijoille käytännön oppimiskokemuksia. Tähän voisi kuulua Kiinassa valmistettujen koodausrobottien käyttö luokkahuoneessa Brasiliassa.

WebHID vs. muut verkko-API:t

On syytä huomata, miten WebHID vertautuu muihin laitevuorovaikutukseen liittyviin verkko-API:hin:

• Gamepad API: Gamepad API tarjoaa korkeamman tason rajapinnan erityisesti peliohjaimille. WebHID tarjoaa enemmän joustavuutta ja hallintaa, mutta vaatii enemmän manuaalista laitedatan käsittelyä. Gamepad API sopii hyvin yleisille peliohjaimille, kun taas WebHID voi tukea eksoottisempia tai erikoistuneempia syöttölaitteita.
• WebUSB API: WebUSB mahdollistaa verkkosovellusten kommunikoinnin suoraan USB-laitteiden kanssa. WebHID on suunniteltu erityisesti HID-laitteille, kun taas WebUSB:tä voidaan käyttää laajemmalle valikoimalle USB-laitteita. WebUSB:tä voitaisiin käyttää erikoistuneelle tieteelliselle instrumentille, joka on kytketty USB:n kautta, kun taas WebHID:tä käytettäisiin mukautetulle näppäimistölle tai hiirelle.
• Web Serial API: Web Serial mahdollistaa kommunikoinnin sarjaporttien kautta. Tämä on hyödyllistä vuorovaikutuksessa sulautettujen järjestelmien ja muiden sarjayhteyksien kautta kommunikoivien laitteiden kanssa. Mikrokontrolleri, joka lähettää dataa sarjayhteyden kautta, voisi käyttää Web Serialia, kun taas itse rakennettu joystick käyttäisi WebHID:tä.

WebHID:n tulevaisuus

WebHID API kehittyy jatkuvasti, ja sen turvallisuutta, suorituskykyä ja helppokäyttöisyyttä pyritään jatkuvasti parantamaan. Kun yhä useammat laitteet ottavat käyttöön HID-standardin, WebHID:stä tulee yhä tärkeämpi työkalu verkkokehittäjille. Tulevaisuudessa on odotettavissa edistyneempiä ominaisuuksia ja parannettua selain-tukea.

Yhteenveto

WebHID on tehokas API, joka avaa laajan valikoiman mahdollisuuksia verkkosovelluksille. Ymmärtämällä laitesuodattimia ja miten käsitellä HID-raportteja, voit luoda mukaansatempaavia ja interaktiivisia verkkokokemuksia, jotka hyödyntävät HID-laitteiden täyden potentiaalin. Olitpa rakentamassa peliä, saavutettavuustyökalua tai teollisuuden ohjausjärjestelmää, WebHID voi auttaa sinua yhdistämään verkkosovelluksesi fyysiseen maailmaan. Muista asettaa etusijalle käyttäjäkokemus, turvallisuus ja alustojen välinen yhteensopivuus luodaksesi onnistuneita ja maailmanlaajuisesti saavutettavia WebHID-sovelluksia.