دستگاه های USB

این سند نحوه استفاده از USB API برای برقراری ارتباط با دستگاه های USB را توضیح می دهد. برخی از دستگاه‌ها از طریق USB API قابل دسترسی نیستند (برای جزئیات به بخش هشدارها در زیر مراجعه کنید). Chrome Apps همچنین می‌تواند به دستگاه‌های سریال و بلوتوث متصل شود.

برای اطلاعات پس زمینه در مورد USB، به مشخصات رسمی USB مراجعه کنید. USB in a NutShell یک دوره آموزشی خرابی معقول است که ممکن است برای شما مفید باشد.

نیاز آشکار

USB API به مجوز "usb" در فایل مانیفست نیاز دارد:

"permissions": [
  "usb"
]

علاوه بر این، برای جلوگیری از انگشت نگاری ، باید تمام انواع دستگاه هایی که می خواهید به آنها دسترسی داشته باشید را در فایل مانیفست اعلام کنید. هر نوع دستگاه USB مربوط به یک جفت شناسه فروشنده/شناسه محصول (VID/PID) است. می توانید از usb.getDevices برای شمارش دستگاه ها بر اساس جفت VID/PID آنها استفاده کنید.

همانطور که در مثال زیر نشان داده شده است، باید جفت‌های VID/PID را برای هر نوع دستگاهی که می‌خواهید تحت مجوز usbDevices در فایل مانیفست برنامه خود استفاده کنید، اعلام کنید:

"permissions": [
  {
    "usbDevices": [
      {
        "vendorId": 123,
        "productId": 456
      }
    ]
  }
]

از Chrome 57 ، برای برنامه‌هایی که به‌عنوان برنامه‌های کیوسک ChromeOS اجرا می‌شوند، الزام برای اعلام همه انواع دستگاه در مانیفست برنامه کاهش یافته است. برای برنامه‌های کیوسک، می‌توانید از ویژگی مجوز interfaceClass برای درخواست اجازه دسترسی به دستگاه‌های USB استفاده کنید که:

• یک رابط USB از یک کلاس رابط خاص را پیاده سازی کنید
• یک کلاس دستگاه USB خاص داشته باشید

برای مثال، مجوز usbDevices زیر به یک برنامه اجازه دسترسی به همه دستگاه‌های USB را می‌دهد که رابط چاپگر را اجرا می‌کنند (کد کلاس رابط ۷)، و به دستگاه‌های هاب USB (کد کلاس دستگاه ۹):

"permissions": [
  {
    "usbDevices": [
      {"interfaceClass": 7},
      {"interfaceClass": 9}
    ]
  }
]

برای لیست مقادیر قابل قبول interfaceClass ، کدهای کلاس USB را ببینید.

ویژگی interfaceClass را می توان با ویژگی vendorId ترکیب کرد تا فقط از یک فروشنده خاص به دستگاه های USB دسترسی داشته باشد، همانطور که در مثال زیر نشان داده شده است:

"permissions": [
  {
    "usbDevices": [
      {
        "vendorId": 123,
        "interfaceClass": 7
      }
    ]
  }
]

پیدا کردن یک دستگاه

برای تعیین اینکه آیا یک یا چند دستگاه خاص به سیستم کاربر متصل هستند، از روش usb.getDevices استفاده کنید:

chrome.usb.getDevices(enumerateDevicesOptions, callback);

مثال:

function onDeviceFound(devices) {
  this.devices=devices;
  if (devices) {
    if (devices.length > 0) {
      console.log("Device(s) found: "+devices.length);
    } else {
      console.log("Device could not be found");
    }
  } else {
    console.log("Permission denied.");
  }
}

chrome.usb.getDevices({"vendorId": vendorId, "productId": productId}, onDeviceFound);

باز کردن یک دستگاه

هنگامی که اشیاء Device برگردانده می شوند، می توانید یک دستگاه را با استفاده از usb.openDevice باز کنید تا یک دسته اتصال به دست آورید. فقط با استفاده از دستگیره های اتصال می توانید با دستگاه های USB ارتباط برقرار کنید.

مثال:

var usbConnection = null;
var onOpenCallback = function(connection) {
  if (connection) {
    usbConnection = connection;
    console.log("Device opened.");
  } else {
    console.log("Device failed to open.");
  }
};

chrome.usb.openDevice(device, onOpenCallback);

برای ساده‌سازی فرآیند باز کردن، می‌توانید از روش usb.findDevices استفاده کنید که دستگاه‌ها را در یک تماس شمارش می‌کند، درخواست دسترسی می‌کند و باز می‌کند:

chrome.usb.findDevices({"vendorId": vendorId, "productId": productId, "interfaceId": interfaceId}, callback);

که معادل است با:

chrome.usb.getDevices({"vendorId": vendorId, "productId": productId}, function (devices) {
  if (!devices) {
    console.log("Error enumerating devices.");
    callback();
    return;
  }
  var connections = [], pendingAccessRequests = devices.length;
  devices.forEach(function (device) {
    chrome.usb.requestAccess(interfaceId, function () {
      // No need to check for errors at this point.
      // Nothing can be done if an error occurs anyway. You should always try
      // to open the device.
      chrome.usb.openDevices(device, function (connection) {
        if (connection) connections.push(connection);
        pendingAccessRequests--;
        if (pendingAccessRequests == 0) {
          callback(connections);
        }
      });
    });
  })
});

USB داده ها را از یک دستگاه انتقال می دهد و دریافت می کند

پروتکل USB چهار نوع انتقال را تعریف می کند: کنترل ، حجیم ، هم زمان و وقفه . این نقل و انتقالات در زیر توضیح داده شده است.

انتقال می تواند در هر دو جهت انجام شود: دستگاه به میزبان (ورودی) و میزبان به دستگاه (خروجی). به دلیل ماهیت پروتکل USB، پیام‌های ورودی و خروجی باید توسط میزبان (رایانه‌ای که برنامه Chrome را اجرا می‌کند) آغاز شود. برای پیام‌های ورودی (دستگاه به میزبان)، میزبان (که توسط کد جاوا اسکریپت شما آغاز شده است) پیامی را که به‌عنوان «inbound» پرچم‌گذاری شده است به دستگاه ارسال می‌کند. جزئیات پیام به دستگاه بستگی دارد، اما معمولاً مشخصه ای از آنچه شما از آن درخواست می کنید دارد. سپس دستگاه با داده های درخواستی پاسخ می دهد. پاسخ دستگاه توسط کروم مدیریت می شود و به صورت ناهمزمان به پاسخی که در روش انتقال مشخص کرده اید تحویل داده می شود. پیام خروجی (میزبان به دستگاه) مشابه است، اما پاسخ حاوی داده‌های برگردانده شده از دستگاه نیست.

برای هر پیام از دستگاه، پاسخ تماس مشخص شده یک شی رویداد با ویژگی های زیر دریافت می کند:

مثال:

var onTransferCallback = function(event) {
   if (event && event.resultCode === 0 && event.data) {
     console.log("got " + event.data.byteLength + " bytes");
   }
};

chrome.usb.bulkTransfer(connectionHandle, transferInfo, onTransferCallback);

کنترل نقل و انتقالات

انتقال کنترل معمولاً برای ارسال یا دریافت تنظیمات یا پارامترهای فرمان به یک دستگاه USB استفاده می شود. متد controlTransfer همیشه از نقطه پایانی 0 به/خوانده می شود و هیچ نیازی به applicationInterface نیست. این روش ساده است و سه پارامتر را دریافت می کند:

chrome.usb.controlTransfer(connectionHandle, transferInfo, transferCallback)

مقادیر برای شی transferInfo :

مثال:

var transferInfo = {
  "requestType": "vendor",
   "recipient": "device",
  "direction": "out",
  "request":  0x31,
  "value": 120,
  "index": 0,
  // Note that the ArrayBuffer, not the TypedArray itself is used.
  "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer
};
chrome.usb.controlTransfer(connectionHandle, transferInfo, optionalCallback);

نقل و انتقالات ایزوکرون

انتقال هم زمان پیچیده ترین نوع انتقال USB است. آنها معمولا برای جریان داده ها، مانند ویدئو و صدا استفاده می شوند. برای شروع یک انتقال هم زمان (اعم از ورودی یا خروجی)، باید از روش usb.isochronousTransfer استفاده کنید:

chrome.usb.isochronousTransfer(connectionHandle, isochronousTransferInfo, transferCallback)

مقادیر برای شی isochronousTransferInfo :

مثال:

var transferInfo = {
  "direction": "in",
  "endpoint": 1,
  "length": 2560
};

var isoTransferInfo = {
  "transferInfo": transferInfo,
  "packets": 20,
  "packetLength": 128
};

chrome.usb.isochronousTransfer(connectionHandle, isoTransferInfo, optionalCallback);

نقل و انتقالات انبوه

انتقال انبوه معمولاً برای انتقال حجم زیادی از داده های غیر حساس به زمان به روشی قابل اعتماد استفاده می شود. usb.bulkTransfer دارای سه پارامتر است:

chrome.usb.bulkTransfer(connectionHandle, transferInfo, transferCallback);

مقادیر برای شی transferInfo :

مثال:

var transferInfo = {
  "direction": "out",
  "endpoint": 1,
  "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer
};

نقل و انتقالات را قطع کنید

انتقال وقفه به مقدار کمی از داده های حساس به زمان استفاده می شود. از آنجایی که تمام ارتباطات USB توسط میزبان آغاز می‌شود، کد میزبان معمولاً دستگاه را به صورت دوره‌ای نظرسنجی می‌کند و انتقالات IN وقفه‌ای را ارسال می‌کند که باعث می‌شود دستگاه در صورت وجود چیزی در صف وقفه (که توسط دستگاه نگهداری می‌شود) داده‌ها را پس بگیرد. usb.interruptTransfer دارای سه پارامتر است:

chrome.usb.interruptTransfer(connectionHandle, transferInfo, transferCallback);

مقادیر برای شی transferInfo :

مثال:

var transferInfo = {
  "direction": "in",
  "endpoint": 1,
  "length": 2
};
chrome.usb.interruptTransfer(connectionHandle, transferInfo, optionalCallback);

هشدارها

همه دستگاه ها از طریق USB API قابل دسترسی نیستند. به طور کلی، دستگاه ها قابل دسترسی نیستند زیرا هسته سیستم عامل یا یک درایور بومی آنها را از کد فضای کاربر دور نگه می دارد. برخی از نمونه ها دستگاه هایی با نمایه های HID در سیستم های OSX و درایوهای قلم USB هستند.

در اکثر سیستم های لینوکس، دستگاه های USB به طور پیش فرض با مجوزهای فقط خواندنی نقشه برداری می شوند. برای باز کردن یک دستگاه از طریق این API، کاربر شما باید به آن دسترسی نوشتن نیز داشته باشد. یک راه حل ساده تنظیم یک قانون udev است. یک فایل /etc/udev/rules.d/50-yourdevicename.rules با محتوای زیر ایجاد کنید:

SUBSYSTEM=="usb", ATTR{idVendor}=="[yourdevicevendor]", MODE="0664", GROUP="plugdev"

سپس، فقط udev daemon را مجددا راه اندازی کنید: service udev restart . با دنبال کردن مراحل زیر می توانید بررسی کنید که آیا مجوزهای دستگاه به درستی تنظیم شده است:

• lsusb را اجرا کنید تا شماره اتوبوس و دستگاه را پیدا کنید.
• ls -al /dev/bus/usb/[bus]/[device] را اجرا کنید. این فایل باید متعلق به گروه "plugdev" باشد و دارای مجوزهای نوشتن گروهی باشد.

برنامه شما نمی تواند این کار را به صورت خودکار انجام دهد زیرا این روش به دسترسی روت نیاز دارد. توصیه می کنیم دستورالعمل هایی را به کاربران نهایی ارائه دهید و برای توضیح به بخش هشدارها در این صفحه پیوند دهید.

در ChromeOS، فقط با usb.requestAccess تماس بگیرید. کارگزار مجوز این کار را برای شما انجام می دهد.