इस दस्तावेज़ में बताया गया है कि यूएसबी डिवाइसों से संपर्क करने के लिए, यूएसबी एपीआई का इस्तेमाल कैसे करें. कुछ डिवाइस यूएसबी एपीआई से ऐक्सेस नहीं किए जा सकते. ज़्यादा जानकारी के लिए, नीचे दिए गए चेतावनियां सेक्शन देखें. Chrome ऐप्लिकेशन, serial और ब्लूटूथ डिवाइसों से भी कनेक्ट किए जा सकते हैं.
देखें.यूएसबी के बारे में जानकारी पाने के लिए, यूएसबी की जानकारी देखें. Nut Shell में यूएसबी एक किफ़ायती क्रैश कोर्स है, जिससे आपको मदद मिल सकती है.
मेनिफ़ेस्ट फ़ाइल के लिए ज़रूरी शर्तें
यूएसबी एपीआई को मेनिफ़ेस्ट फ़ाइल में "usb" अनुमति की ज़रूरत है:
"permissions": [
"usb"
]
इसके अलावा, फ़िंगरप्रिंट की सुविधा को रोकने के लिए, आपको मेनिफ़ेस्ट फ़ाइल में उन सभी डिवाइस टाइप के बारे में बताना होगा जिन्हें आपको ऐक्सेस करना है. हर तरह का यूएसबी डिवाइस, वेंडर आईडी/प्रॉडक्ट आईडी (VID/PID) पेयर से जुड़ा होता है. usb.getDevices का इस्तेमाल करके, डिवाइसों के VID/PID पेयर के हिसाब से सूची बनाई जा सकती है.
आपको अपने ऐप्लिकेशन की मेनिफ़ेस्ट फ़ाइल में, usbDevices अनुमति के तहत हर तरह के डिवाइस के लिए, वीआईडी/पीआईडी पेयर का एलान करना होगा. इसका उदाहरण नीचे दिया गया है:
"permissions": [
{
"usbDevices": [
{
"vendorId": 123,
"productId": 456
}
]
}
]
Chrome 57 से, ChromeOS कीऑस्क ऐप्लिकेशन के तौर पर काम करने वाले ऐप्लिकेशन के लिए, ऐप्लिकेशन मेनिफ़ेस्ट में सभी तरह के डिवाइसों के बारे में जानकारी देने की ज़रूरी शर्त में कुछ छूट दी गई है. कीऑस्क ऐप्लिकेशन के लिए, interfaceClass की अनुमति वाली प्रॉपर्टी का इस्तेमाल करके, ऐसे यूएसबी डिवाइसों को ऐक्सेस करने की अनुमति मांगी जा सकती है जो:
- किसी खास इंटरफ़ेस क्लास का यूएसबी इंटरफ़ेस लागू करें
- की एक खास यूएसबी डिवाइस क्लास है
उदाहरण के लिए, यहां दी गई usbDevices अनुमति से, किसी ऐप्लिकेशन को प्रिंटर इंटरफ़ेस (इंटरफ़ेस क्लास कोड 7) लागू करने वाले सभी यूएसबी डिवाइसों और यूएसबी हब डिवाइसों (डिवाइस क्लास कोड
9) का ऐक्सेस मिलेगा:
"permissions": [
{
"usbDevices": [
{"interfaceClass": 7},
{"interfaceClass": 9}
]
}
]
स्वीकार किए जाने वाले interfaceClass वैल्यू की सूची के लिए, यूएसबी क्लास कोड देखें.
किसी खास वेंडर के सिर्फ़ यूएसबी डिवाइसों का ऐक्सेस पाने के लिए, interfaceClass प्रॉपर्टी को vendorId प्रॉपर्टी के साथ जोड़ा जा सकता है. इस उदाहरण में, यह बताया गया है:
"permissions": [
{
"usbDevices": [
{
"vendorId": 123,
"interfaceClass": 7
}
]
}
]
कोई डिवाइस ढूंढा जा रहा है
एक या एक से ज़्यादा खास डिवाइस उपयोगकर्ता के सिस्टम से कनेक्ट हैं या नहीं, यह पता लगाने के लिए usb.getDevices तरीके का इस्तेमाल करें:
chrome.usb.getDevices(enumerateDevicesOptions, callback);
| पैरामीटर (टाइप) | ब्यौरा |
|---|---|
| Enumerate DevicesOptions (ऑब्जेक्ट) | एक ऑब्जेक्ट, जिसमें vendorId (लॉन्ग) और productId (लॉन्ग), दोनों के बारे में जानकारी होती है. इस ऑब्जेक्ट की मदद से, बस में मौजूद सही डिवाइस का पता लगाया जाता है. आपके मेनिफ़ेस्ट को usbDevices अनुमति सेक्शन के बारे में बताना होगा. इसमें उन सभी vendorId और deviceId पेयर की जानकारी शामिल होनी चाहिए जिन्हें आपका ऐप्लिकेशन ऐक्सेस करना चाहता है. |
| कॉलबैक (फ़ंक्शन) | डिवाइस की गिनती पूरी होने पर कॉल किया जाता है. कॉलबैक एक पैरामीटर के साथ एक्ज़ीक्यूट होगा, जो तीन प्रॉपर्टी वाले Device ऑब्जेक्ट की एक कैटगरी है: device, vendorId, productId. डिवाइस प्रॉपर्टी, कनेक्ट किए गए डिवाइस का स्थायी आइडेंटिफ़ायर है. यह तब तक नहीं बदलेगा, जब तक डिवाइस को पावर सॉकेट से कनेक्ट नहीं कर दिया जाता. आइडेंटिफ़ायर की जानकारी ओपेक है और इसमें बदलाव किया जा सकता है. ज़रूरी नहीं है कि इसके मौजूदा टाइप पर भरोसा करें.कोई भी डिवाइस न मिलने पर, कलेक्शन खाली रहेगा. |
उदाहरण:
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 का इस्तेमाल करके डिवाइस को खोलें. आप सिर्फ़ कनेक्शन हैंडल का इस्तेमाल करके, यूएसबी डिवाइसों से बातचीत कर सकते हैं.
| प्रॉपर्टी | ब्यौरा |
|---|---|
| device | usb.getDevices कॉलबैक में ऑब्जेक्ट मिला है. |
| डेटा (arrayबफ़र) | इसमें वह डेटा शामिल होता है जो डिवाइस से भेजा गया था. ऐसा तब होता है, जब डेटा इनबाउंड था. |
उदाहरण:
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);
}
});
});
})
});
यूएसबी ट्रांसफ़र और डिवाइस से डेटा पाना
यूएसबी प्रोटोकॉल चार तरह के ट्रांसफ़र के बारे में बताता है: कंट्रोल, बल्क, इसोक्रोनस, और इंटरप्ट. इन ट्रांसफ़र के बारे में नीचे बताया गया है.
डेटा ट्रांसफ़र इन दोनों तरीकों से हो सकता है: डिवाइस-टू-होस्ट (इनबाउंड) और होस्ट-टू-डिवाइस (आउटबाउंड). यूएसबी प्रोटोकॉल के मुताबिक, इनबाउंड और आउटबाउंड, दोनों मैसेज, होस्ट (Chrome ऐप्लिकेशन चलाने वाला कंप्यूटर) की मदद से शुरू होने चाहिए. इनबाउंड (डिवाइस-टू-होस्ट) मैसेज के लिए, होस्ट (आपके JavaScript कोड से शुरू किया गया) डिवाइस को "इनबाउंड" के तौर पर फ़्लैग किया गया मैसेज भेजता है. मैसेज की जानकारी डिवाइस पर निर्भर करती है, लेकिन आम तौर पर इस बात की कुछ जानकारी होगी कि आप उससे क्या अनुरोध कर रहे हैं. इसके बाद, डिवाइस, अनुरोध किए गए डेटा के साथ जवाब देता है. डिवाइस के रिस्पॉन्स को Chrome मैनेज करता है और ट्रांसफ़र के तरीके में बताए गए कॉलबैक को एसिंक्रोनस तरीके से डिलीवर करता है. आउटबाउंड (होस्ट-टू-डिवाइस) से जुड़ा मैसेज एक जैसा ही होता है. हालांकि, जवाब में डिवाइस से मिला डेटा शामिल नहीं होता.
डिवाइस से मिलने वाले हर मैसेज के लिए, बताए गए कॉलबैक को नीचे दी गई प्रॉपर्टी के साथ एक इवेंट ऑब्जेक्ट मिलेगा:
| प्रॉपर्टी | ब्यौरा |
|---|---|
| resultCode (पूर्णांक) | 0 का मतलब है कि नतीजे नहीं मिले. अन्य वैल्यू से पता चलता है कि ऐसा नहीं हुआ. गड़बड़ी का पता चलने पर chrome.extension.lastError से गड़बड़ी वाली स्ट्रिंग को पढ़ा जा सकता है. |
| डेटा (arrayबफ़र) | इसमें वह डेटा शामिल होता है जो डिवाइस से भेजा गया था. ऐसा तब होता है, जब डेटा इनबाउंड था. |
उदाहरण:
var onTransferCallback = function(event) {
if (event && event.resultCode === 0 && event.data) {
console.log("got " + event.data.byteLength + " bytes");
}
};
chrome.usb.bulkTransfer(connectionHandle, transferInfo, onTransferCallback);
CONTROL ट्रांसफ़र
आम तौर पर, कंट्रोल ट्रांसफ़र का इस्तेमाल किसी यूएसबी डिवाइस पर कॉन्फ़िगरेशन या कमांड पैरामीटर भेजने या पाने के लिए किया जाता है. कंट्रोल ट्रांसफ़र करने का तरीका, हमेशा एंडपॉइंट 0 से रीड या रीड को भेजता है. साथ ही, किसी दावे के इंटरफ़ेस की ज़रूरत नहीं होती. यह तरीका आसान है और इसे तीन पैरामीटर मिलते हैं:
chrome.usb.controlTransfer(connectionHandle, transferInfo, transferCallback)
| पैरामीटर (टाइप) | ब्यौरा |
|---|---|
| connectionHandle | usb.openDevice कॉलबैक में ऑब्जेक्ट मिला. |
| transferInfo | नीचे दी गई टेबल से वैल्यू के साथ पैरामीटर ऑब्जेक्ट. ज़्यादा जानकारी के लिए, अपने यूएसबी डिवाइस के प्रोटोकॉल की खास बातें देखें. |
| transferCallback() | ट्रांसफ़र पूरा होने पर शुरू किया जाता है. |
transferInfo ऑब्जेक्ट के लिए वैल्यू:
| वैल्यू | ब्यौरा |
|---|---|
| requestType (स्ट्रिंग) | "वेंडर", "स्टैंडर्ड", "क्लास" या "रिज़र्व्ड". |
| ईमेल पाने वाला (स्ट्रिंग) | "डिवाइस", "इंटरफ़ेस", "एंडपॉइंट" या "अन्य". |
| दिशा (स्ट्रिंग) | "में" या "बाहर" हो. "इन" निर्देश का इस्तेमाल, डिवाइस को यह सूचना देने के लिए किया जाता है कि इसे होस्ट को जानकारी भेजनी चाहिए. यूएसबी बस पर सभी कम्यूनिकेशन होस्ट की मदद से शुरू किए जाते हैं. इसलिए, "इन" ट्रांसफ़र का इस्तेमाल करें, ताकि किसी डिवाइस को जानकारी वापस भेजने की अनुमति दी जा सके. |
| अनुरोध (पूर्णांक) | यह आपके डिवाइस के प्रोटोकॉल के हिसाब से तय किया जाता है. |
| वैल्यू (पूरी संख्या) | यह आपके डिवाइस के प्रोटोकॉल के हिसाब से तय किया जाता है. |
| इंडेक्स (इंटीजर) | यह आपके डिवाइस के प्रोटोकॉल के हिसाब से तय किया जाता है. |
| लंबाई (पूर्णांक) | इसका इस्तेमाल सिर्फ़ तब किया जाता है, जब दिशा "इन" हो. यह, डिवाइस को यह सूचना देता है कि रिस्पॉन्स में होस्ट को इतने डेटा की उम्मीद है. |
| डेटा (arrayबफ़र) | यह आपके डिवाइस के प्रोटोकॉल के मुताबिक तय किया जाता है. यह तब ज़रूरी होता है, जब दिशा "आउट" हो. |
उदाहरण:
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);
ISOCHRONOUS ट्रांसफ़र
आइसोक्रोनस ट्रांसफ़र, यूएसबी ट्रांसफ़र का सबसे जटिल तरीका है. आम तौर पर, इनका इस्तेमाल वीडियो और आवाज़ जैसे डेटा की स्ट्रीम के लिए किया जाता है. आइसोक्रोनस ट्रांसफ़र (इनबाउंड या आउटबाउंड) शुरू करने के लिए, आपको usb.isochronousTransfer तरीके का इस्तेमाल करना होगा:
chrome.usb.isochronousTransfer(connectionHandle, isochronousTransferInfo, transferCallback)
| पैरामीटर | ब्यौरा |
|---|---|
| connectionHandle | usb.openDevice कॉलबैक में ऑब्जेक्ट मिला. |
| isochronousTransferInfo | नीचे दी गई टेबल में दी गई वैल्यू के साथ पैरामीटर ऑब्जेक्ट. |
| transferCallback() | ट्रांसफ़र पूरा होने पर शुरू किया जाता है. |
isochronousTransferInfo ऑब्जेक्ट के लिए वैल्यू:
| वैल्यू | ब्यौरा |
|---|---|
| trafficInfo (ऑब्जेक्ट) | इन एट्रिब्यूट वाला ऑब्जेक्ट: निर्देश (स्ट्रिंग): "in" या "out". एंडपॉइंट (इंटीजर): इसे आपके डिवाइस ने तय किया है. आम तौर पर, यूएसबी की जांच करने वाले टूल की मदद से, इसका पता लगाया जा सकता है, जैसे कि lsusb -vलंबाई (पूर्णांक): इसका इस्तेमाल सिर्फ़ तब किया जाता है, जब दिशा "in" हो. डिवाइस को यह सूचना देता है कि यह डेटा उतना ही होना चाहिए जितना होस्ट, जवाब में डेटा की उम्मीद करता है. कम से कम packets × packetLength होना चाहिए.डेटा (अरेबफ़र): यह डेटा आपके डिवाइस के प्रोटोकॉल के हिसाब से तय होता है. इसका इस्तेमाल सिर्फ़ तब किया जाता है, जब दिशा "आउट" हो. |
| पैकेट (इंटीजर) | इस ट्रांसफ़र में पैकेट की कुल संख्या. |
| पैकेट की लंबाई (इंटीजर) | इस ट्रांसफ़र में, हर पैकेट के लिए ज़रूरी लंबाई. |
उदाहरण:
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);
| पैरामीटर | ब्यौरा |
|---|---|
| connectionHandle | usb.openDevice कॉलबैक में ऑब्जेक्ट मिला. |
| transferInfo | नीचे दी गई टेबल में दी गई वैल्यू के साथ पैरामीटर ऑब्जेक्ट. |
| transferCallback | ट्रांसफ़र पूरा होने पर शुरू किया जाता है. |
transferInfo ऑब्जेक्ट के लिए वैल्यू:
| वैल्यू | ब्यौरा |
|---|---|
| दिशा (स्ट्रिंग) | "में" या "बाहर" हो. |
| एंडपॉइंट (पूरी संख्या) | यह आपके डिवाइस के प्रोटोकॉल के हिसाब से तय किया जाता है. |
| लंबाई (पूर्णांक) | इसका इस्तेमाल सिर्फ़ तब किया जाता है, जब दिशा "इन" हो. यह, डिवाइस को यह सूचना देता है कि रिस्पॉन्स में होस्ट को इतने डेटा की उम्मीद है. |
| डेटा (ArrayBuffer) | यह आपके डिवाइस के प्रोटोकॉल के हिसाब से तय होता है. इसे सिर्फ़ तब इस्तेमाल किया जाता है, जब दिशा "बाहर" हो. |
उदाहरण:
var transferInfo = {
"direction": "out",
"endpoint": 1,
"data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer
};
डेटा ट्रांसफ़र करने में रुकावट
रुकावट के मैसेज भेजने की सुविधा का इस्तेमाल, संवेदनशील जानकारी के बेहद कम हिस्से के लिए किया जाता है. सभी यूएसबी कम्यूनिकेशन, होस्ट की तरफ़ से शुरू किए जाते हैं, इसलिए होस्ट कोड आम तौर पर डिवाइस का पोल समय-समय पर करता है. अगर रुकावट की वजह से कम्यूनिकेशन में रुकावट आती है, तो रुकावट की सूची में कुछ होने पर डिवाइस, डेटा वापस भेज देता हैusb.interruptTransfer
chrome.usb.interruptTransfer(connectionHandle, transferInfo, transferCallback);
| पैरामीटर | ब्यौरा |
|---|---|
| connectionHandle | usb.openDevice कॉलबैक में ऑब्जेक्ट मिला. |
| transferInfo | नीचे दी गई टेबल में दी गई वैल्यू के साथ पैरामीटर ऑब्जेक्ट. |
| transferCallback | ट्रांसफ़र पूरा होने पर शुरू किया जाता है. ध्यान दें कि इस कॉलबैक में डिवाइस का रिस्पॉन्स शामिल नहीं है. कॉलबैक का मकसद सिर्फ़ आपके कोड को यह बताना है कि एसिंक्रोनस ट्रांसफ़र अनुरोध को प्रोसेस कर दिया गया है. |
transferInfo ऑब्जेक्ट के लिए वैल्यू:
| वैल्यू | ब्यौरा |
|---|---|
| दिशा (स्ट्रिंग) | "में" या "बाहर" हो. |
| एंडपॉइंट (पूरी संख्या) | यह आपके डिवाइस के प्रोटोकॉल के हिसाब से तय किया जाता है. |
| लंबाई (पूर्णांक) | इसका इस्तेमाल सिर्फ़ तब किया जाता है, जब दिशा "इन" हो. यह, डिवाइस को यह सूचना देता है कि रिस्पॉन्स में होस्ट को इतने डेटा की उम्मीद है. |
| डेटा (ArrayBuffer) | यह आपके डिवाइस के प्रोटोकॉल के हिसाब से तय होता है. इसे सिर्फ़ तब इस्तेमाल किया जाता है, जब दिशा "बाहर" हो. |
उदाहरण:
var transferInfo = {
"direction": "in",
"endpoint": 1,
"length": 2
};
chrome.usb.interruptTransfer(connectionHandle, transferInfo, optionalCallback);
ध्यान दें
यूएसबी एपीआई की मदद से सभी डिवाइसों को ऐक्सेस नहीं किया जा सकता. आम तौर पर, डिवाइस ऐक्सेस नहीं किए जा सकते, क्योंकि या तो ऑपरेटिंग सिस्टम का कर्नेल होता है या फिर कोई नेटिव ड्राइवर, उन्हें यूज़र स्पेस कोड से दूर रखता है. उदाहरण के लिए, ओएसएस सिस्टम पर एचआईडी प्रोफ़ाइल वाले डिवाइस और यूएसबी पेन ड्राइव.
ज़्यादातर Linux सिस्टम पर, यूएसबी डिवाइसों को डिफ़ॉल्ट रूप से रीड ओनली अनुमति के साथ मैप किया जाता है. इस एपीआई से किसी डिवाइस को खोलने के लिए, आपके उपयोगकर्ता के पास उसमें लिखने का ऐक्सेस होना चाहिए. udev नियम सेट करना
इसका आसान तरीका है. इस कॉन्टेंट के साथ /etc/udev/rules.d/50-yourdevicename.rules फ़ाइल बनाएं:
SUBSYSTEM=="usb", ATTR{idVendor}=="[yourdevicevendor]", MODE="0664", GROUP="plugdev"
इसके बाद, udev डीमन को रीस्टार्ट करें: service udev restart. डिवाइस की अनुमतियां सही तरीके से सेट की गई हैं या नहीं, यह देखने के लिए यह तरीका अपनाएं:
- बस और डिवाइस के नंबर ढूंढने के लिए,
lsusbचलाएं. ls -al /dev/bus/usb/[bus]/[device]चलाएं. इस फ़ाइल का मालिकाना हक, "प्लगडेव" के पास होना चाहिए. साथ ही, उस फ़ाइल में ग्रुप में लिखने की अनुमतियां होनी चाहिए.
आपका ऐप्लिकेशन अपने-आप यह काम नहीं कर सकता, क्योंकि इस प्रोसेस के लिए रूट ऐक्सेस की ज़रूरत होती है. हमारा सुझाव है कि आप असली उपयोगकर्ताओं को निर्देश दें. साथ ही, ज़्यादा जानकारी पाने के लिए, इस पेज पर चेतावनियों वाले सेक्शन का लिंक दें.
ChromeOS पर, बस usb.requestAccess को कॉल करें. यह काम, अनुमति का ब्रोकर आपके लिए करता है.