Web HID API: põhjalik juhend inimliidese seadmetele juurdepääsuks

Web HID API on võimas veebi API, mis võimaldab veebirakendustel otse suhelda inimliidese seadmetega (HID). HID-seadmed hõlmavad laia valikut välisseadmeid, sealhulgas klaviatuure, hiiri, mängukontrollereid, spetsialiseeritud sisendseadmeid nagu vöötkoodiskannereid ja isegi tööstuslikke juhtimissüsteeme. See võimekus avab põnevaid võimalusi veebipõhistele rakendustele suhelda füüsilise maailmaga uutel ja uuenduslikel viisidel.

Mis on Web HID API?

Web HID API pakub standardiseeritud liidest veebibrauseritele juurdepääsuks ja suhtlemiseks HID-seadmetega. Enne Web HID API-d olid veebirakendused suures osas piiratud standardsete brauserisündmustega (nt hiireklõpsud, klaviatuurisisend) suhtlemisega. Spetsiifilisemale riistvarale juurdepääs nõudis brauserilaiendusi või natiivseid rakendusi, mis tõid kaasa keerukusi arenduses, kasutuselevõtus ja turvalisuses.

Web HID API lahendab need piirangud, pakkudes turvalist ja standardiseeritud viisi veebirakendustele, et:

• Loetleda HID-seadmeid: Avastada kasutaja süsteemiga ühendatud HID-seadmeid.
• Taotleda juurdepääsu: Saada kasutajalt luba konkreetsetele HID-seadmetele juurdepääsemiseks.
• Saata ja vastu võtta andmeid: Vahetada andmeid HID-seadmetega aruannete abil.

Web HID API eelised

Web HID API pakub arendajatele ja kasutajatele mitmeid kaalukaid eeliseid:

• Otsene riistvara interaktsioon: Võimaldab veebirakendustel otse juhtida ja vastu võtta andmeid laialt valikult HID-seadmetelt, laiendades veebipõhiste rakenduste võimalusi.
• Parem kasutajakogemus: Võimaldab kaasahaaravamaid ja interaktiivsemaid kogemusi, kasutades ära spetsialiseeritud riistvara võimekust. Kujutage ette veebipõhist muusikaproduktsiooni rakendust, mis suhtleb otse MIDI-klaviatuuriga, või veebipõhist mängu, mis kasutab täiustatud mängupuldi funktsioone.
• Platvormideülene ühilduvus: Loodud olema platvormist sõltumatu, võimaldades veebirakendustel töötada järjepidevalt erinevates operatsioonisüsteemides ja brauserites, mis API-d toetavad.
• Täiustatud turvalisus: Rakendab tugevaid turvameetmeid, sealhulgas kasutaja loaküsimisi ja päritolupõhiseid piiranguid, et kaitsta kasutaja privaatsust ja vältida pahatahtlikku juurdepääsu HID-seadmetele.
• Lihtsustatud arendus: Pakub suhteliselt lihtsat JavaScript API-d HID-seadmetega suhtlemiseks, vähendades riistvaraga liidestuvate veebirakenduste arendamise keerukust.

Turvakaalutlused

Web HID API sisaldab mitmeid turvamehhanisme, et kaitsta kasutajaid pahatahtlike veebirakenduste eest:

• Kasutaja luba: Enne kui veebirakendus saab HID-seadmele juurdepääsu, peab kasutaja selgesõnaliselt loa andma. Brauser kuvab viiba, milles palutakse kasutajal anda luba konkreetsele seadmele juurdepääsuks.
• Päritolupõhised piirangud: Juurdepääs HID-seadmetele on piiratud veebirakenduse päritoluga (domeeniga). See takistab pahatahtlikul veebisaidil juurdepääsu teiste veebisaitide kasutatavatele HID-seadmetele.
• HTTPS-i nõue: Web HID API on saadaval ainult veebirakendustele, mida serveeritakse HTTPS-i kaudu, tagades, et side brauseri ja serveri vahel on krüpteeritud ja pealtkuulamise eest kaitstud.
• Piiratud seadme juurdepääs: API piirab, millist tüüpi HID-seadmetele veebirakendused juurde pääsevad. Tundliku funktsionaalsusega seadmed (nt turvatõkendid) on tavaliselt välistatud.

Arendajatel on ülioluline järgida Web HID API kasutamisel turvalisuse parimaid tavasid, et veelgi leevendada võimalikke riske. See hõlmab HID-seadmetelt saadud andmete hoolikat valideerimist ja tundliku teabe salvestamise vältimist.

Kuidas Web HID API-d kasutada

Siin on samm-sammuline juhend Web HID API kasutamiseks oma veebirakenduses:

1. samm: kontrollige API tuge

Esmalt veenduge, et brauser toetab Web HID API-d:

            if ("hid" in navigator) {
  console.log("Web HID API on toetatud!");
} else {
  console.log("Web HID API ei ole selles brauseris toetatud.");
}
            

              
                Copy
              
            
          

2. samm: taotlege seadmele juurdepääsu

Kasutage meetodit navigator.hid.requestDevice(), et paluda kasutajal valida HID-seade. Saate määrata filtreid, et kitsendada seadmete loendit tootja ID (vendorId) ja toote ID (productId) alusel. Need ID-d saate seadme dokumentatsioonist või süsteemi utiliitide abil.

            async function requestHIDDevice() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        { vendorId: 0x1234, productId: 0x5678 }, // Näidis tootja ja toote ID
        { usagePage: 0x0001, usage: 0x0006 } // Valikuline usagePage ja usage
      ],
    });

    if (devices.length > 0) {
      const device = devices[0];
      console.log("Valitud seade:", device);
      await connectToDevice(device);
    } else {
      console.log("Seadet ei valitud.");
    }
  } catch (error) {
    console.error("Viga seadme taotlemisel:", error);
  }
}

            

              
                Copy
              
            
          

Tähtis: vendorId ja productId on konkreetsete seadmete sihtimiseks üliolulised. Peate leidma need väärtused HID-seadme jaoks, mida kavatsete kasutada. Tööriistad nagu `lsusb` Linuxis või Seadmehaldur Windowsis aitavad teil neid leida.

Parameetreid `usagePage` ja `usage` kasutatakse seadme valiku täpsustamiseks. Need väärtused vastavad HID kasutus Tabelitele, mis määratlevad seadme kavandatud kasutuse. Näiteks `usagePage: 0x0001` ja `usage: 0x0006` tähistavad sageli geneerilist klaviatuuri.

3. samm: ühendage seadmega

Kui kasutaja on seadme valinud, peate sellega ühenduse avama:

            async function connectToDevice(device) {
  try {
    await device.open();
    console.log("Seade on ühendatud.");

    device.addEventListener("inputreport", handleInputReport);

    device.addEventListener("disconnect", () => {
        console.log('Seade on lahti ühendatud.');
    });
  } catch (error) {
    console.error("Viga seadmega ühendumisel:", error);
  }
}

            

              
                Copy
              
            
          

Meetod `device.open()` loob ühenduse HID-seadmega. On ülioluline käsitleda selle protsessi käigus tekkida võivaid vigu.

Kood seadistab ka sündmusekuulaja sündmusele inputreport. See sündmus käivitatakse, kui HID-seade saadab andmeid veebirakendusele. Lisatakse ka teine sündmusekuulaja sündmusele "disconnect", et käsitleda seadme lahtiühendamist.

4. samm: käsitlege sisendiaruandeid

Sündmus inputreport annab juurdepääsu HID-seadme saadetud andmetele. Andmed on tavaliselt struktureeritud baidimassiivina.

            function handleInputReport(event) {
  const { data, device, reportId } = event;
  const uint8Array = new Uint8Array(data.buffer);

  console.log("Vastuvõetud sisendiaruanne:", uint8Array);
  console.log("Aruande ID:", reportId);

  // Töötle andmeid seadme ja aruande ID põhjal
  processData(uint8Array, reportId, device);
}

            

              
                Copy
              
            
          

Sündmuse atribuut data sisaldab ArrayBuffer'it, mis esindab seadmelt saadud toorandmeid. Saate selle lihtsamaks käsitlemiseks teisendada Uint8Array'ks.

reportId on valikuline identifikaator, mida saab kasutada sama seadme saadetud eri tüüpi aruannete eristamiseks. Kui seade kasutab aruande ID-sid, peate neid oma andmetöötlusloogikas asjakohaselt käsitlema.

5. samm: saatke väljundiaruandeid (valikuline)

Mõned HID-seadmed võimaldavad teil andmeid seadmesse tagasi saata (väljundiaruanded). Seda saab kasutada seadme käitumise juhtimiseks (nt LED-ide seadistamine, mootorite juhtimine).

            async function sendOutputReport(device, reportId, data) {
  try {
    const uint8Array = new Uint8Array(data);
    await device.sendReport(reportId, uint8Array);
    console.log("Väljundiaruanne saadetud.");
  } catch (error) {
    console.error("Viga väljundiaruande saatmisel:", error);
  }
}

            

              
                Copy
              
            
          

Meetod device.sendReport() saadab seadmele väljundiaruande. reportId identifitseerib konkreetse aruande ja data on baidimassiiv, mis sisaldab saadetavaid andmeid.

6. samm: sulgege ühendus

Kui olete seadmega suhtlemise lõpetanud, on oluline ühendus sulgeda:

            async function disconnectDevice(device) {
  try {
    await device.close();
    console.log("Seade on lahti ühendatud.");
  } catch (error) {
    console.error("Viga seadme lahtiühendamisel:", error);
  }
}

            

              
                Copy
              
            
          

Meetod device.close() sulgeb ühenduse HID-seadmega.

Web HID API praktilised rakendused

Web HID API-l on lai valik potentsiaalseid rakendusi, sealhulgas:

• Mängimine: Veebipõhiste mängude arendamine, mis toetavad täiustatud mängukontrollereid, juhtkange ja muid mänguseadmeid. Kujutage ette, et mängite oma brauseris võidusõidumängu täieliku jõutagasiside toega oma roolilt.
• Muusikaproduktsioon: Veebipõhiste muusikaproduktsiooni rakenduste loomine, mis suhtlevad MIDI-klaviatuuride, trummimasinate ja muude muusikariistadega. Muusik Argentiinas saab teha koostööd teisega Jaapanis sama MIDI-seadet kasutades, mida juhitakse veebirakenduse kaudu.
• Tööstuslik juhtimine: Veebipõhiste armatuurlaudade ja juhtpaneelide ehitamine tööstusseadmetele, mis võimaldavad operaatoritel masinaid eemalt jälgida ja juhtida. Näiteks saab Austraalia sisemaal asuvat päikesepaneelide farmi jälgida ja reguleerida veebiliidese kaudu, mis on ühendatud juhtimisriistvaraga.
• Juurdepääsetavus: Abitehnoloogiate arendamine, mis kasutavad spetsialiseeritud sisendseadmeid, et aidata puuetega inimestel veebiga suhelda. Veebisaidil navigeerimiseks ja teksti sisestamiseks saab kasutada kohandatud lülitiliidest.
• Teadusuuringud: Teadusinstrumentide ja andmekogumisseadmetega liidestamine otse veebipõhistest uurimisvahenditest. Šveitsis asuv teadlane saab veebibrauserist eemalt juhtida mikroskoopi, hankides pilte ja andmeid.
• Müügikoha (POS) süsteemid: Vöötkoodiskannerite, krediitkaardilugejate ja muude POS-seadmete integreerimine veebipõhistesse müügikohasüsteemidesse. Ghanas asuv väikeettevõte saab müügi haldamiseks kasutada veebirakendust, kasutades otse arvutiga ühendatud USB-vöötkoodiskannerit.
• Kohandatud sisendseadmed: Kohandatud või nišš-sisendseadmete toetamine, mida veebibrauserid algselt ei toeta. See hõlmab spetsiaalseid kontrollereid simulatsioonideks, andmesisestusterminale ja muud unikaalset riistvara.

Koodinäide: klaviatuurisisendi lugemine

See näide demonstreerib, kuidas lugeda klaviatuurisisendit geneeriliselt HID-klaviatuurilt, kasutades Web HID API-d.

            // Taotle HID-seadet
async function requestKeyboard() {
    try {
        const devices = await navigator.hid.requestDevice({
            filters: [{
                usagePage: 0x0001,
                usage: 0x0006
            }]
        });

        if (devices.length > 0) {
            const keyboard = devices[0];
            console.log("Klaviatuur valitud:", keyboard);
            await connectKeyboard(keyboard);
        } else {
            console.log("Klaviatuuri ei valitud.");
        }
    } catch (error) {
        console.error("Viga klaviatuuri taotlemisel:", error);
    }
}

// Ühendu klaviatuuriga
async function connectKeyboard(keyboard) {
    try {
        await keyboard.open();
        console.log("Klaviatuur ühendatud.");

        keyboard.addEventListener("inputreport", handleKeyboardInput);

        keyboard.addEventListener("disconnect", () => {
            console.log('Klaviatuur lahti ühendatud.');
        });

    } catch (error) {
        console.error("Viga klaviatuuriga ühendumisel:", error);
    }
}

// Käsitle klaviatuurisisendit
function handleKeyboardInput(event) {
    const { data, reportId } = event;
    const uint8Array = new Uint8Array(data.buffer);

    // Näide: prindi toorandmed
    console.log("Klaviatuurisisend:", uint8Array);

    // TODO: Rakenda klahvikoodi parsimise loogika
    // See on lihtsustatud näide; tegelik klaviatuuri dekodeerimine on keerulisem

    // Lihtne näide lihtsate klahvivajutuste tõlgendamiseks toorandmete põhjal
    if(uint8Array[2] !== 0) {
      console.log("Klahvi vajutati");
      // Edasine parsimine tegeliku klahvi tuvastamiseks saab teha siin.
    }
}

// Nupp seadme taotluse käivitamiseks
const requestButton = document.createElement('button');
requestButton.textContent = 'Taotle klaviatuuri';
requestButton.addEventListener('click', requestKeyboard);
document.body.appendChild(requestButton);

            

              
                Copy
              
            
          

Selgitus:

• Kood taotleb esmalt juurdepääsu HID-seadmetele, mis vastavad klaviatuuri kasutusprofiilile (`usagePage: 0x0001, usage: 0x0006`).
• Seejärel ühendub see valitud klaviatuuriga ja kuulab sündmusi inputreport.
• Funktsioon handleKeyboardInput võtab vastu klaviatuurilt saadud toorandmed.
• Näide pakub kohatäitjat klahvikoodi parsimise loogikale. Klaviatuurisisendi dekodeerimine võib olla keeruline, kuna see sõltub klaviatuuripaigutusest ja konkreetsest HID-aruande vormingust. Korrektse dekodeerimise rakendamiseks peate tutvuma klaviatuuri dokumentatsiooni või HID spetsifikatsioonidega.

Väljakutsed ja piirangud

Kuigi Web HID API pakub märkimisväärseid eeliseid, on sellel ka mõningaid väljakutseid ja piiranguid:

• Brauseri tugi: Web HID API-d ei toeta veel kõik suuremad brauserid. Enne API kasutamist oma rakenduses peate kontrollima brauseri ühilduvust. 2024. aasta lõpu seisuga on parim tugi Chrome'il ja Edge'il. Firefoxi tugi on arendamisel.
• Seadmedraiveri nõuded: Mõnel juhul võivad HID-seadmed nõuda kasutaja süsteemi spetsiifiliste draiverite installimist. See võib lisada keerukust kasutuselevõtu protsessile.
• Andmete parsimise keerukus: HID-seadmetelt saadud andmete parsimine võib olla keeruline, kuna andmevorming on sageli seadmespetsiifiline ja võib nõuda üksikasjalikke teadmisi HID-protokollist. Peate mõistma aruande kirjeldajat ja HID kasutus tabeleid.
• Turvaprobleemid: Kuigi Web HID API sisaldab turvameetmeid, on siiski oluline olla teadlik potentsiaalsetest turvariskidest. Arendajad peavad hoolikalt valideerima HID-seadmetelt saadud andmeid ja vältima tundliku teabe salvestamist.
• Asünkroonne olemus: Web HID API on asünkroonne, mis tähendab, et asünkroonsete operatsioonide käsitlemiseks peate kasutama lubadusi või async/await. See võib lisada koodile keerukust, eriti arendajatele, kes ei ole asünkroonse programmeerimisega tuttavad.

Web HID API kasutamise parimad tavad

Sujuva ja turvalise kogemuse tagamiseks Web HID API kasutamisel arvestage järgmiste parimate tavadega:

• Kontrollige alati API tuge: Enne Web HID API kasutamist veenduge, et brauser seda toetab.
• Taotlege seadmele juurdepääsu ainult siis, kui see on vajalik: Vältige juurdepääsu taotlemist HID-seadmetele, kui see pole absoluutselt vajalik.
• Andke kasutajatele selgeid selgitusi: Seadmele juurdepääsu taotlemisel andke kasutajatele selgeid ja lühikesi selgitusi selle kohta, miks teie rakendus vajab seadmele juurdepääsu.
• Valideerige HID-seadmetelt saadud andmeid: Valideerige hoolikalt kõiki HID-seadmetelt saadud andmeid, et vältida turvaauke.
• Käsitlege vigu sujuvalt: Rakendage robustne veakäsitlus, et sujuvalt käsitleda võimalikke vigu seadme ühendamisel, andmeedastusel ja lahtiühendamisel.
• Sulgege seadme ühendus, kui olete lõpetanud: Sulgege alati ühendus HID-seadmega, kui olete selle kasutamise lõpetanud.
• Järgige turvalisuse parimaid tavasid: Järgige turvalisuse parimaid tavasid, et kaitsta kasutaja privaatsust ja vältida pahatahtlikku juurdepääsu HID-seadmetele.
• Kasutage funktsioonide tuvastamist: Kontrollige, kas `navigator.hid` on olemas, enne kui proovite API-d kasutada. Pakkuge varumehhanisme või informatiivseid teateid brauseritele, mis seda ei toeta.
• Sujuv tagasiminek: Kujundage oma rakendus nii, et see toimiks ka siis, kui mõned HID-funktsioonid pole saadaval. Näiteks pakkuge klaviatuuri ja hiire alternatiive, kui konkreetset mängupulti ei toetata.

Web HID API tulevik

Web HID API on veel suhteliselt uus, kuid sellel on potentsiaal revolutsiooniliselt muuta viisi, kuidas veebirakendused riistvaraga suhtlevad. Kuna brauserite tugi paraneb ja üha rohkem arendajaid võtab API omaks, võime oodata laiemat valikut uuenduslikke veebipõhiseid rakendusi, mis kasutavad HID-seadmete võimsust. Samuti on oodata edasist standardimist ja seadmete ühilduvuse parandusi, mis lihtsustavad arendust ja parandavad kasutajakogemust.

Kokkuvõte

Web HID API annab veebiarendajatele võimaluse luua rikkalikumaid ja interaktiivsemaid kogemusi, ületades lõhe veebi ja füüsilise maailma vahel. Mõistes API võimekust, turvakaalutlusi ja parimaid tavasid, saavad arendajad avada veebipõhiste rakenduste jaoks hulgaliselt võimalusi. Alates mängimisest ja muusikaproduktsioonist kuni tööstusliku juhtimise ja juurdepääsetavuseni on Web HID API valmis edendama innovatsiooni erinevates tööstusharudes.

Alustage Web HID API avastamist juba täna ja leidke põnev potentsiaal, mida see teie järgmise veebiprojekti jaoks pakub!