مدیریت دستگاه USB وب فرانت‌اند: چرخه عمر دستگاه USB

API WebUSB دنیایی از امکانات را برای برنامه‌های وب باز می‌کند و ارتباط مستقیم با دستگاه‌های USB متصل به رایانه کاربر را ممکن می‌سازد. این به توسعه‌دهندگان اجازه می‌دهد تا تجربه‌های غنی و تعاملی ایجاد کنند که قبلاً فقط با برنامه‌های بومی امکان‌پذیر بود. با این حال، مدیریت مؤثر دستگاه‌های USB در یک برنامه وب نیازمند درک کامل از چرخه عمر دستگاه USB است. این راهنما یک نمای کلی جامع از این چرخه عمر و بهترین روش‌ها برای ساخت برنامه‌های WebUSB قوی و کاربرپسند برای مخاطبان جهانی ارائه می‌دهد.

درک چرخه عمر دستگاه USB

• کشف و اتصال دستگاه: تشخیص و اتصال به یک دستگاه USB.
• اخذ مجوز: درخواست مجوز کاربر برای دسترسی به دستگاه.
• شناسایی و پیکربندی دستگاه: شناسایی دستگاه و پیکربندی تنظیمات آن.
• انتقال داده: ارسال و دریافت داده بین برنامه وب و دستگاه.
• قطع اتصال دستگاه: قطع اتصال صحیح از دستگاه و آزادسازی منابع.
• رسیدگی به خطا: مدیریت خطاهایی که ممکن است در هر مرحله از چرخه عمر رخ دهد.

1. کشف و اتصال دستگاه

اولین قدم تشخیص و اتصال به دستگاه USB مورد نظر است. API WebUSB دو روش اصلی برای این کار ارائه می‌دهد:

• navigator.usb.requestDevice(): این روش از کاربر می‌خواهد که یک دستگاه USB را از لیست دستگاه‌های موجود انتخاب کند. این روش ترجیحی برای شروع اتصال است.
• navigator.usb.getDevices(): این روش لیستی از دستگاه‌های USB را برمی‌گرداند که برنامه وب قبلاً مجوز دسترسی به آنها را دارد. برای اتصال مجدد به دستگاه‌های مجاز قبلی بدون درخواست مجدد از کاربر مفید است.

مثال: درخواست یک دستگاه

این مثال نحوه استفاده از navigator.usb.requestDevice() برای درخواست یک دستگاه را نشان می‌دهد.

            async function requestUSBDevice() {
  try {
    const device = await navigator.usb.requestDevice({
      filters: [
        { vendorId: 0x1234, productId: 0x5678 }, // Example Vendor and Product IDs
        { vendorId: 0x9ABC } // Example Vendor ID only
      ]
    });

    console.log('Device connected:', device);
    // Store the device for later use

  } catch (error) {
    console.error('No device selected or error occurred:', error);
  }
}

            

              
                Copy
              
            
          

توضیح:

• آرایه filters به شما امکان می‌دهد معیارهایی را برای دستگاه‌هایی که می‌خواهید به کاربر نمایش دهید، مشخص کنید. می‌توانید بر اساس vendorId، productId یا هر دو فیلتر کنید.
• ارائه فیلترها به کاربر کمک می‌کند تا به سرعت دستگاه صحیح را پیدا کند، به ویژه در محیط‌هایی که دستگاه‌های USB متعددی وجود دارد.
• اگر کاربر گفتگوی انتخاب دستگاه را لغو کند یا خطایی رخ دهد، promise با یک خطا رد می‌شود.

مثال: دریافت دستگاه‌های مجاز قبلی

این مثال نحوه بازیابی دستگاه‌های مجاز قبلی با استفاده از navigator.usb.getDevices() را نشان می‌دهد.

            async function getAuthorizedDevices() {
  try {
    const devices = await navigator.usb.getDevices();

    if (devices.length === 0) {
      console.log('No previously authorized devices found.');
      return;
    }

    console.log('Authorized devices:');
    devices.forEach(device => {
      console.log(device);
      // Use the device
    });

  } catch (error) {
    console.error('Error getting authorized devices:', error);
  }
}

            

              
                Copy
              
            
          

توضیح:

• این روش یک آرایه از اشیاء USBDevice را برمی‌گرداند که نشان‌دهنده دستگاه‌هایی هستند که برنامه وب قبلاً مجوز دسترسی به آنها را دریافت کرده است.
• برای اتصال مجدد خودکار به دستگاه‌های شناخته شده بدون نیاز به تعامل کاربر مفید است.

2. اخذ مجوز

قبل از اینکه یک برنامه وب بتواند با یک دستگاه USB تعامل داشته باشد، باید از کاربر مجوز بگیرد. این یک اقدام امنیتی حیاتی برای جلوگیری از دسترسی وب‌سایت‌های مخرب به سخت‌افزار حساس بدون رضایت کاربر است.

روش navigator.usb.requestDevice() ذاتاً درخواست مجوز می‌کند. هنگامی که کاربر یک دستگاه را از گفتگو انتخاب می‌کند، به برنامه وب اجازه می‌دهد تا به آن دستگاه دسترسی داشته باشد.

ملاحظات مهم:

• ارتباط واضح: به وضوح به کاربر توضیح دهید که چرا برنامه شما نیاز به دسترسی به دستگاه USB دارد. زمینه و شفافیت را برای ایجاد اعتماد فراهم کنید.
• به حداقل رساندن مجوزها: فقط مجوزهای لازم برای عملکرد برنامه خود را درخواست کنید. از درخواست دسترسی گسترده که می‌تواند نگرانی‌های امنیتی را افزایش دهد، خودداری کنید.
• تجربه کاربری: جریان درخواست مجوز را طوری طراحی کنید که تا حد امکان یکپارچه و شهودی باشد. دستورالعمل‌های مفید ارائه دهید و از زبان گیج کننده یا نگران کننده خودداری کنید.

3. شناسایی و پیکربندی دستگاه

پس از برقراری اتصال، گام بعدی شناسایی دستگاه USB خاص و پیکربندی آن برای ارتباط است. این معمولاً شامل مراحل زیر است:

• باز کردن دستگاه: متد device.open() را برای ادعای دسترسی انحصاری به دستگاه فراخوانی کنید.
• انتخاب یک پیکربندی: یک پیکربندی مناسب برای دستگاه با استفاده از device.selectConfiguration() انتخاب کنید. یک دستگاه می‌تواند پیکربندی‌های متعددی داشته باشد که هر کدام عملکردهای مختلف و الزامات توان را ارائه می‌دهند.
• ادعای یک رابط: یک رابط برای ارتباط با استفاده از device.claimInterface() ادعا کنید. یک رابط نشان دهنده یک واحد عملکردی خاص در داخل دستگاه است.
• بازنشانی دستگاه: در صورت لزوم پیکربندی دستگاه را بازنشانی کنید.

مثال: پیکربندی دستگاه

            async function configureDevice(device) {
  try {
    await device.open();

    // Some devices may require a reset before configuring
    try {
        await device.reset();
    } catch (error) {
        console.warn("Device reset failed, continuing.", error);
    }

    if (device.configuration === null) {
      await device.selectConfiguration(1); // Select configuration #1 (or another appropriate value)
    }

    await device.claimInterface(0); // Claim interface #0 (or another appropriate value)

    console.log('Device configured successfully.');

  } catch (error) {
    console.error('Error configuring device:', error);
    try { await device.close(); } catch (e) { console.warn("Error closing device after configuration failure.")} 
  }
}

            

              
                Copy
              
            
          

توضیح:

• متد device.open() یک اتصال به دستگاه USB برقرار می‌کند. ضروری است که این متد را قبل از تلاش برای هر عملیات دیگری فراخوانی کنید.
• متد device.selectConfiguration() یک پیکربندی خاص را برای دستگاه انتخاب می‌کند. شماره پیکربندی به قابلیت‌های دستگاه بستگی دارد. برای مقدار صحیح به مستندات دستگاه مراجعه کنید.
• متد device.claimInterface() یک رابط را برای ارتباط ادعا می‌کند. شماره رابط نیز به قابلیت‌های دستگاه بستگی دارد.
• همیشه رسیدگی به خطا را برای رسیدگی مناسب به خرابی‌های احتمالی در طول فرآیند پیکربندی در نظر بگیرید.
• بستن دستگاه در رسیدگی به خطا تضمین می کند که منابع آزاد می شوند.

4. انتقال داده

پس از پیکربندی دستگاه، می‌توانید انتقال داده بین برنامه وب و دستگاه USB را شروع کنید. API WebUSB چندین روش برای انتقال داده ارائه می‌دهد که بسته به نوع نقطه پایانی که استفاده می‌کنید متفاوت است:

• device.transferIn(endpointNumber, length): داده‌ها را از دستگاه می‌خواند.
• device.transferOut(endpointNumber, data): داده‌ها را به دستگاه می‌نویسد.
• device.controlTransferIn(setup, length): یک انتقال کنترل برای خواندن داده از دستگاه انجام می‌دهد.
• device.controlTransferOut(setup, data): یک انتقال کنترل برای نوشتن داده به دستگاه انجام می‌دهد.

ملاحظات مهم:

• شماره نقاط پایانی: شماره نقاط پایانی نقاط پایانی خاصی را در دستگاه مشخص می‌کنند که برای انتقال داده استفاده می‌شوند. این اعداد در توصیف‌گرهای USB دستگاه تعریف شده‌اند.
• بافرهای داده: داده‌ها با استفاده از اشیاء ArrayBuffer منتقل می‌شوند. قبل از ارسال یا دریافت داده، باید داده‌های خود را به قالب ArrayBuffer تبدیل کنید.
• رسیدگی به خطا: انتقال داده می‌تواند به دلایل مختلفی مانند خطاهای دستگاه یا مشکلات ارتباطی با شکست مواجه شود. برای شناسایی و پاسخ به این شکست‌ها، رسیدگی به خطای قوی را پیاده‌سازی کنید.

مثال: ارسال داده

            async function sendData(device, endpointNumber, data) {
  try {
    const buffer = new Uint8Array(data).buffer; // Convert data to ArrayBuffer
    const result = await device.transferOut(endpointNumber, buffer);

    console.log('Data sent successfully:', result);

  } catch (error) {
    console.error('Error sending data:', error);
  }
}

            

              
                Copy
              
            
          

مثال: دریافت داده

            async function receiveData(device, endpointNumber, length) {
  try {
    const result = await device.transferIn(endpointNumber, length);

    if (result.status === 'ok') {
      const data = new Uint8Array(result.data);
      console.log('Data received:', data);
      return data;
    } else {
      console.error('Data transfer failed with status:', result.status);
      return null;
    }
  } catch (error) {
    console.error('Error receiving data:', error);
    return null;
  }
}

            

              
                Copy
              
            
          

5. قطع اتصال دستگاه

هنگامی که برنامه وب دیگر نیازی به برقراری ارتباط با دستگاه USB ندارد، قطع اتصال صحیح ضروری است. این شامل مراحل زیر است:

• آزاد کردن رابط: متد device.releaseInterface() را برای آزاد کردن رابط ادعا شده فراخوانی کنید.
• بستن دستگاه: متد device.close() را برای بستن اتصال به دستگاه فراخوانی کنید.

ملاحظات مهم:

• مدیریت منابع: قطع اتصال صحیح از دستگاه تضمین می‌کند که منابع آزاد می‌شوند و از تداخل احتمالی با برنامه‌های دیگر جلوگیری می‌کند.
• تجربه کاربری: نشانه‌ای واضح به کاربر ارائه دهید که چه زمانی دستگاه قطع شده است.
• قطع اتصال خودکار: در صورت بسته شدن صفحه وب یا خروج کاربر، قطع اتصال خودکار از دستگاه را در نظر بگیرید.

مثال: قطع اتصال دستگاه

            async function disconnectDevice(device, interfaceNumber) {
  try {
	  if(device.claimedInterface !== null) {
    	await device.releaseInterface(interfaceNumber); // Release the interface	
	  }
    await device.close(); // Close the device

    console.log('Device disconnected successfully.');

  } catch (error) {
    console.error('Error disconnecting device:', error);
  }
}

            

              
                Copy
              
            
          

6. رسیدگی به خطا

رسیدگی به خطا برای ساخت برنامه‌های WebUSB قوی و قابل اعتماد بسیار مهم است. خطاها می‌توانند در هر مرحله از چرخه عمر دستگاه USB به دلیل دلایل مختلفی مانند خطاهای دستگاه، مشکلات ارتباطی یا اقدامات کاربر رخ دهند.

استراتژی‌های رایج رسیدگی به خطا:

• بلوک‌های Try-Catch: از بلوک‌های try-catch برای رسیدگی به استثنائات احتمالی در طول عملیات ناهمزمان استفاده کنید.
• کدهای خطا: ویژگی status شیء USBTransferResult را برای تعیین موفقیت یا عدم موفقیت انتقال داده بررسی کنید.
• بازخورد کاربر: پیام‌های خطای آموزنده به کاربر ارائه دهید تا به آنها کمک کند مشکل را درک کرده و اقدامات اصلاحی انجام دهند.
• ثبت وقایع: خطاها را در کنسول یا در یک سرور برای اشکال زدایی و تجزیه و تحلیل ثبت کنید.
• بازنشانی دستگاه: در صورت بروز خطای مداوم، بازنشانی دستگاه را در نظر بگیرید.
• تخریب تدریجی: اگر یک خطای حیاتی رخ داد، به جای خراب شدن، عملکرد برنامه را به تدریج کاهش دهید.

بهترین روش‌ها برای مخاطبان جهانی

هنگام توسعه برنامه‌های WebUSB برای یک مخاطب جهانی، بهترین روش‌های زیر را در نظر بگیرید:

• بومی‌سازی: رابط کاربری برنامه و پیام‌های خطای خود را برای پشتیبانی از زبان‌های مختلف بومی‌سازی کنید.
• دسترسی: اطمینان حاصل کنید که برنامه شما برای کاربران دارای معلولیت قابل دسترسی است و از دستورالعمل‌های دسترسی مانند WCAG پیروی می‌کند.
• سازگاری بین مرورگرها: برنامه خود را در مرورگرهای مختلف آزمایش کنید تا از سازگاری اطمینان حاصل کنید. در حالی که WebUSB به طور گسترده پشتیبانی می‌شود، ممکن است تفاوت‌های ظریفی در رفتار بین مرورگرها وجود داشته باشد.
• امنیت: بهترین روش‌های امنیتی را برای محافظت از داده‌های کاربر و جلوگیری از حملات مخرب پیاده‌سازی کنید.
• پشتیبانی از دستگاه: آگاه باشید که همه دستگاه‌های USB توسط WebUSB پشتیبانی نمی‌شوند. برای اطمینان از سازگاری، مستندات دستگاه را بررسی کنید.
• دستورالعمل‌های واضح: دستورالعمل‌های واضح و مختصر به کاربر ارائه دهید که چگونه دستگاه USB را متصل و استفاده کند.
• ارائه بازگشت به حالت قبل: اگر دستگاه USB در دسترس نیست یا پشتیبانی نمی‌شود، یک مکانیسم بازگشت به حالت قبل برای دسترسی کاربران به عملکرد اصلی برنامه ارائه دهید.

ملاحظات امنیتی

WebUSB یک روش امن برای دسترسی به دستگاه‌های USB از برنامه‌های وب فراهم می‌کند، اما مهم است که از خطرات امنیتی احتمالی آگاه باشید:

• رضایت کاربر: WebUSB قبل از اینکه یک برنامه وب بتواند به یک دستگاه USB دسترسی داشته باشد، نیاز به رضایت صریح کاربر دارد. این از دسترسی بی‌صدا به سخت‌افزار حساس توسط وب‌سایت‌های مخرب جلوگیری می‌کند.
• محدودیت‌های منشأ: WebUSB محدودیت‌های منشأ را اعمال می‌کند، به این معنی که یک برنامه وب فقط می‌تواند از همان منشأ (پروتکل، دامنه و پورت) به دستگاه‌های USB دسترسی داشته باشد.
• الزام HTTPS: WebUSB برای جلوگیری از حملات مرد میانی نیاز به یک اتصال HTTPS امن دارد.

اقدامات امنیتی اضافی:

• اعتبارسنجی ورودی: تمام داده‌های دریافتی از دستگاه USB را برای جلوگیری از سرریز بافر و سایر آسیب‌پذیری‌های امنیتی اعتبارسنجی کنید.
• بازبینی کد: بازبینی‌های کد منظم را برای شناسایی و رفع مشکلات امنیتی احتمالی انجام دهید.
• ممیزی‌های امنیتی: ممیزی‌های امنیتی را برای ارزیابی وضعیت کلی امنیت برنامه خود انجام دهید.
• به روز باشید: در مورد آخرین تهدیدات و آسیب‌پذیری‌های امنیتی مطلع باشید و برنامه خود را بر این اساس به روز کنید.

نتیجه‌گیری

تسلط بر چرخه عمر دستگاه USB برای ساخت برنامه‌های WebUSB قوی، کاربرپسند و ایمن ضروری است. با درک هر مرحله از چرخه عمر، پیاده‌سازی رسیدگی به خطای مناسب و پیروی از بهترین روش‌ها، می‌توانید تجربه‌های وب جذابی ایجاد کنید که به طور یکپارچه با دستگاه‌های USB ادغام شوند. به یاد داشته باشید که تجربه کاربر، امنیت و دسترسی جهانی را در اولویت قرار دهید تا به مخاطبان گسترده‌تری دست یابید و یک محصول واقعاً استثنایی ارائه دهید.

این راهنما یک نقطه شروع برای سفر WebUSB شما ارائه می‌دهد. برای اطلاعات دقیق‌تر به مستندات API WebUSB و مستندات خاص دستگاه مراجعه کنید.

منابع بیشتر

• مشخصات API WebUSB
• مستندات MDN WebUSB