{"id":18304917,"url":"https://github.com/jaganathanb/node-usbspy","last_synced_at":"2026-05-10T03:52:46.873Z","repository":{"id":84089823,"uuid":"115725198","full_name":"jaganathanb/node-usbspy","owner":"jaganathanb","description":"An event based node.js c++ addon/binding to retrive the connected usb storage devices and detect the storage device insertion/removal and notifify the subscribed apps.","archived":false,"fork":false,"pushed_at":"2018-07-17T11:39:37.000Z","size":68,"stargazers_count":1,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T12:48:10.799Z","etag":null,"topics":["addon","cpp","javascript","n-api","nodejs"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaganathanb.png","metadata":{"files":{"readme":"ReadMe.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-29T13:38:12.000Z","updated_at":"2020-09-04T09:52:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"971d0348-9d08-4874-ae2f-052f147f7356","html_url":"https://github.com/jaganathanb/node-usbspy","commit_stats":{"total_commits":33,"total_committers":2,"mean_commits":16.5,"dds":0.4545454545454546,"last_synced_commit":"be97224097dbbebd5ab3a89af41b672cbc8cbc9e"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaganathanb%2Fnode-usbspy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaganathanb%2Fnode-usbspy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaganathanb%2Fnode-usbspy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaganathanb%2Fnode-usbspy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaganathanb","download_url":"https://codeload.github.com/jaganathanb/node-usbspy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248021916,"owners_count":21034768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["addon","cpp","javascript","n-api","nodejs"],"created_at":"2024-11-05T15:31:30.389Z","updated_at":"2026-05-10T03:52:46.823Z","avatar_url":"https://github.com/jaganathanb.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"##### Note: Designed for Windows\n\n# node-usbspy\nAn event based node.js c++ addon/binding to retrive the connected usb storage devices and detect the storage device insertion/removal and notifify the subscribed apps.\n\n## Prerequisties for installation\nBefore installing this package, make sure you have Node.js addon build tool [node-gyp](https://github.com/nodejs/node-gyp) installed in your machine.\n\nAs `node-gyp` uses `Python 2.x`, make sure it is installed in your machine and it is on your EVN path.\n\nIf you dont have the python installed, then it is recommanded to install the `windows-build-tools`. To installl windows build tool, open CLI as adminstrator and execute the below command as per the issue discussed [here](https://github.com/felixrieseberg/windows-build-tools/issues/56).\n\n```\nnpm --add-python-to-path='true' --debug install --global windows-build-tools\n```\n\nThe above command would install pythin 2.x and build tools needed for windows. It would take few mins to complete the installation.\n\n\n## Installation\nTo install `node-usbspy` execute the below command\n\nif you prefer `npm`\n```\nnpm install node-usbspy\n```\n\nfor `yarn`,\n\n```\nyarn add node-usbspy\n```\nUpon installation, `node-gyp` would start generating the c++ addon project as per the configuration we set in `binding.gyp` and compile the same. If the compilation is successfull, it would have generated the executable lib files in the `build`folder with `Release` configuration.\n\n## How to use it\n\n`require('node-usbspy')` would populate the usbspy object which is of event type.\n\n### Activating the detection(spying on the usb controller)\n\n```\nvar usbspy = require('node-usbspy');\n\nusbspy.spyOn().then(() =\u003e {\n    ...\n})\n```\n\n### Deactivating the detection\n\n```\nusbspy.spyOff() // would stop listening for the usb detection.\n```\n\n### Listening for change\nThere is an event `change` which would be emitted when a usb device is inserted or removed. You can subscribe for the event and do necessory action upon the event.\n\n```\nusbspy.on('change', (device) =\u003e {\n    console.log(device);\n    /* { device_number: 1,\n         device_status: 1,\n         device_letter: 'D:\\\\',\n         vendor_id: 'SanDisk ',\n         serial_number: '4C530001250818',\n         product_id: 'Cruze'\n       } */\n});\n\nusbspy.on('end', () =\u003e {\n    // would be triggered when you call `spyOff` function.\n})\n```\n\n## API\n\n### Properties\nWhen an usb device is inserted, an `Device` object would be generated and emitted.\n\n`Device` object has,\n\n* `device_status` - It is an integer type property. The possible values for this property is 0 or 1 when 0 indicates the device is been removed from the system and the 1 indicated the device is been added.\n* `device_letter` - It is an string type property. The letter assigned to device by the operating system when the usb device is inserted.\n*  `device_number` - It is an integer type property. The unique number assigned to every usb storage device inserted into the system by OS. Number starts from 1.\n*   `serial_number` - It is an string type property. The unique albha-numeric assigned to the usb storage device by the manufacturer.\n*    `vendor_id` - It is an string type property. The vendor id is assigned by the USB Implementers Forum to a specific company.\n*    `product_id` - It is an string type property. The product id is assigned by the company for the individual product.\n\n\n### Methods\nThere are four methods available in `usbspy`.\n\n#### spyOn([callback])\n`spyOn` method takes a callback as parameter and returns a promise object. Here `callback` is optional. Since spyOn returns promise, you can use `then` to kick start the detection. \n\nWhen the addon is ready, `callback` would be called with `true` which indicates everything is OK if passed otherwise the promise would be resolve/rejected.\n\n#### spyOff()\n`spyOff` should be called when you wanted to stop listening for the usb device change.\n\n#### getAvailableUSBStorageDevices()\n`getAvailableUSBStorageDevices` would written list of `Device` objects if available otherwise empty list would be returned. This method does not take any arguments.\n\n#### getUSBStorageDeviceByPropertyName(propertyName\u003cstring\u003e, value\u003cstring|number\u003e)\nThis method takes two arguments. The `propertyName` could be any of the `Device` properties. The `value` should be the actual value of the property. This method returns `Device` object if the property/value passed matches any of the available usb storage devices.\n    \n\n### Events\nThere are two events emitted from the `usbspy` module. \n\n#### change - usbspy.on('change' callback(device))\nWhen any usb storage device is been inserted/removed into/from the machine, `change` event would be triggered with the `Device` object.\n\n#### end - usbspy.on('end', callback)\nWhen the `spyOff` method is called, the `end` event would be triggered.\n\n## Example\n\nYou can have a look into `example/test.js` for usage and example.\n\n```\nvar usbspy = require('../index');\n\nusbspy.spyOn().then(function() {\n\n    usbspy.on('change', function(data) {\n        console.log(data);\n    });\n    \n    usbspy.on('end', function(data) {\n        console.log(data);\n    });\n\n    console.log(usbspy.getAvailableUSBStorageDevices());\n\n    console.log(usbspy.getUSBStorageDeviceByPropertyName('device_letter', 'D:\\\\'));\n\n    console.log(usbspy.getUSBStorageDeviceByPropertyName('device_number', 1));\n});\n\nsetTimeout(() =\u003e {\n    usbspy.spyOff();\n}, 5000); // after 5 secs, would stop wathcing for device change.\n```\n##### Note:\nWhen you DEBUG the c++ code, you have to comment the line#18 in the `usbspy.h`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaganathanb%2Fnode-usbspy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaganathanb%2Fnode-usbspy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaganathanb%2Fnode-usbspy/lists"}