@mcesystems/usb-device-listener 1.0.30 → 1.0.31

package/dist/types.d.ts

@@ -8,10 +8,17 @@
  */
 export interface DeviceInfo {
     /**
-     * Windows device instance ID
-     * Format: "USB\VID_xxxx&PID_xxxx\..."
+     * Device identifier
+     * For devices with USB serial numbers: the serial number (formatted with dash for iOS style)
+     * For devices without serial: platform-specific format "USB\VID_xxxx&PID_xxxx\..."
+     * iOS devices: formatted as "XXXXXXXX-XXXXXXXXXXXXXXXX" (e.g., "00008030-001234567890402E")
      */
     deviceId: string;
+    /**
+     * Raw USB serial number (without formatting)
+     * Empty string if the device doesn't expose a serial number
+     */
+    serialNumber: string;
     /**
      * USB Vendor ID (decimal)
      * Use .toString(16) to convert to hex string

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAE/B;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,YAAY,EAAE,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,YAAY,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAE7C;;;;;;;;OAQG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE/C;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAErD;;;;;;;;;;;;;;OAcG;IACH,WAAW,IAAI,UAAU,EAAE,CAAC;CAC5B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAE/B;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,YAAY,EAAE,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,YAAY,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAE7C;;;;;;;;OAQG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE/C;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAErD;;;;;;;;;;;;;;OAcG;IACH,WAAW,IAAI,UAAU,EAAE,CAAC;CAC5B"}

package/native/addon.cc

@@ -97,6 +97,7 @@ Napi::Value ListDevices(const Napi::CallbackInfo& info) {
 	for (size_t i = 0; i < devices.size(); i++) {
 		Napi::Object obj = Napi::Object::New(env);
 		obj.Set("deviceId", Napi::String::New(env, devices[i].deviceId));
+		obj.Set("serialNumber", Napi::String::New(env, devices[i].serialNumber));
 		obj.Set("vid", Napi::Number::New(env, devices[i].vid));
 		obj.Set("pid", Napi::Number::New(env, devices[i].pid));
 		obj.Set("locationInfo", Napi::String::New(env, devices[i].locationInfo));

package/native/usb_listener_common.h

@@ -14,7 +14,8 @@
  * Platform-agnostic: used by both Windows and macOS implementations
  */
 struct DeviceInfo {
-	std::string deviceId;       // Platform-specific device instance ID
+	std::string deviceId;       // Device ID (serial number if available, otherwise platform-specific)
+	std::string serialNumber;   // USB serial number (raw, without formatting)
 	uint16_t vid{0};            // Vendor ID
 	uint16_t pid{0};            // Product ID
 	std::string locationInfo;   // Physical port location (platform-specific format)

package/native/usb_listener_mac.cc

@@ -25,6 +25,66 @@ static const char* GetUSBDeviceClassName() {
 	return kIOUSBDeviceClassName;
 }
 
+/**
+ * Get the USB serial number from the IOKit service
+ * Returns empty string if serial number is not available
+ */
+static std::string GetSerialNumber(io_service_t service) {
+	// Try kUSBSerialNumberString first (standard USB property)
+	CFStringRef serialRef = (CFStringRef)IORegistryEntryCreateCFProperty(
+		service, CFSTR(kUSBSerialNumberString), kCFAllocatorDefault, 0);
+	
+	// Fallback to "USB Serial Number" property name
+	if (!serialRef) {
+		serialRef = (CFStringRef)IORegistryEntryCreateCFProperty(
+			service, CFSTR("USB Serial Number"), kCFAllocatorDefault, 0);
+	}
+	
+	if (!serialRef) {
+		return "";
+	}
+	
+	// Convert CFString to std::string
+	CFIndex length = CFStringGetLength(serialRef);
+	CFIndex maxSize = CFStringGetMaximumSizeForEncoding(length, kCFStringEncodingUTF8) + 1;
+	std::string result(maxSize, '\0');
+	
+	if (CFStringGetCString(serialRef, &result[0], maxSize, kCFStringEncodingUTF8)) {
+		result.resize(strlen(result.c_str()));
+	} else {
+		result.clear();
+	}
+	
+	CFRelease(serialRef);
+	return result;
+}
+
+/**
+ * Format serial number in iOS-style dash-separated format
+ * iOS UDIDs are typically 24-25 characters and formatted as: XXXXXXXX-XXXXXXXXXXXXXXXX
+ * Example: 00008030-001234567890402E
+ */
+static std::string FormatSerialAsDeviceId(const std::string& serial) {
+	if (serial.empty()) {
+		return "";
+	}
+	
+	// iOS serial numbers are typically 24-25 chars without dashes
+	// Format: first 8 chars, dash, remaining chars
+	// If it already contains dashes, return as-is
+	if (serial.find('-') != std::string::npos) {
+		return serial;
+	}
+	
+	// iOS UDID format: 8 chars + dash + rest (typically 16 chars)
+	if (serial.length() >= 24) {
+		return serial.substr(0, 8) + "-" + serial.substr(8);
+	}
+	
+	// For shorter serials (like Android), return as-is
+	return serial;
+}
+
 USBListener::USBListener() = default;
 
 USBListener::~USBListener() {
@@ -229,6 +289,7 @@ void USBListener::HandleDeviceAdded(io_iterator_t iterator) {
 				auto callback = [](Napi::Env env, Napi::Function jsCallback, DeviceInfo* data) {
 					Napi::Object obj = Napi::Object::New(env);
 					obj.Set("deviceId", Napi::String::New(env, data->deviceId));
+					obj.Set("serialNumber", Napi::String::New(env, data->serialNumber));
 					obj.Set("vid", Napi::Number::New(env, data->vid));
 					obj.Set("pid", Napi::Number::New(env, data->pid));
 					obj.Set("locationInfo", Napi::String::New(env, data->locationInfo));
@@ -280,6 +341,7 @@ void USBListener::HandleDeviceRemoved(io_iterator_t iterator) {
 			auto callback = [](Napi::Env env, Napi::Function jsCallback, DeviceInfo* data) {
 				Napi::Object obj = Napi::Object::New(env);
 				obj.Set("deviceId", Napi::String::New(env, data->deviceId));
+				obj.Set("serialNumber", Napi::String::New(env, data->serialNumber));
 				obj.Set("vid", Napi::Number::New(env, data->vid));
 				obj.Set("pid", Napi::Number::New(env, data->pid));
 				obj.Set("locationInfo", Napi::String::New(env, data->locationInfo));
@@ -336,12 +398,21 @@ bool USBListener::GetDeviceInfoFromService(io_service_t service, DeviceInfo& inf
 	// Get Location ID (used for physical port identification)
 	info.locationInfo = GetLocationId(service);
 	
-	// Create a unique device ID combining VID, PID, and location
-	std::ostringstream ss;
-	ss << "USB\\VID_" << std::uppercase << std::hex << std::setw(4) << std::setfill('0') << info.vid
-	   << "&PID_" << std::uppercase << std::hex << std::setw(4) << std::setfill('0') << info.pid
-	   << "\\" << info.locationInfo;
-	info.deviceId = ss.str();
+	// Get USB serial number
+	info.serialNumber = GetSerialNumber(service);
+	
+	// Use serial number as device ID if available (formatted for iOS style)
+	// Otherwise fall back to VID/PID/location combination
+	if (!info.serialNumber.empty()) {
+		info.deviceId = FormatSerialAsDeviceId(info.serialNumber);
+	} else {
+		// Fallback: Create a unique device ID combining VID, PID, and location
+		std::ostringstream ss;
+		ss << "USB\\VID_" << std::uppercase << std::hex << std::setw(4) << std::setfill('0') << info.vid
+		   << "&PID_" << std::uppercase << std::hex << std::setw(4) << std::setfill('0') << info.pid
+		   << "\\" << info.locationInfo;
+		info.deviceId = ss.str();
+	}
 	
 	return true;
 }

package/native/usb_listener_win.cc

@@ -187,6 +187,7 @@ void USBListener::HandleDeviceChange(WPARAM wParam, LPARAM lParam) {
 		auto callback = [](Napi::Env env, Napi::Function jsCallback, DeviceInfo* data) {
 			Napi::Object obj = Napi::Object::New(env);
 			obj.Set("deviceId", Napi::String::New(env, data->deviceId));
+			obj.Set("serialNumber", Napi::String::New(env, data->serialNumber));
 			obj.Set("vid", Napi::Number::New(env, data->vid));
 			obj.Set("pid", Napi::Number::New(env, data->pid));
 			obj.Set("locationInfo", Napi::String::New(env, data->locationInfo));
@@ -203,6 +204,7 @@ void USBListener::HandleDeviceChange(WPARAM wParam, LPARAM lParam) {
 		auto callback = [](Napi::Env env, Napi::Function jsCallback, DeviceInfo* data) {
 			Napi::Object obj = Napi::Object::New(env);
 			obj.Set("deviceId", Napi::String::New(env, data->deviceId));
+			obj.Set("serialNumber", Napi::String::New(env, data->serialNumber));
 			obj.Set("vid", Napi::Number::New(env, data->vid));
 			obj.Set("pid", Napi::Number::New(env, data->pid));
 			obj.Set("locationInfo", Napi::String::New(env, data->locationInfo));
@@ -267,9 +269,9 @@ bool USBListener::GetDeviceInfo(const std::string& devicePath, DeviceInfo& info)
 		if (SetupDiGetDeviceInstanceId(deviceInfoSet, &devInfoData, instanceId, MAX_PATH, nullptr)) {
 			if (_wcsicmp(instanceId, deviceIdW.c_str()) == 0) {
 				std::wstring idW = instanceId;
-				info.deviceId = std::string(idW.begin(), idW.end());
+				std::string fullDeviceId = std::string(idW.begin(), idW.end());
 				
-				if (!GetVidPid(info.deviceId, info.vid, info.pid)) {
+				if (!GetVidPid(fullDeviceId, info.vid, info.pid)) {
 					SetupDiDestroyDeviceInfoList(deviceInfoSet);
 					return false;
 				}
@@ -280,6 +282,14 @@ bool USBListener::GetDeviceInfo(const std::string& devicePath, DeviceInfo& info)
 					return false;
 				}
 				
+				// Get serial number and use as device ID if available
+				info.serialNumber = GetSerialNumber(deviceInfoSet, devInfoData);
+				if (!info.serialNumber.empty()) {
+					info.deviceId = FormatSerialAsDeviceId(info.serialNumber);
+				} else {
+					info.deviceId = fullDeviceId;
+				}
+				
 				SetupDiDestroyDeviceInfoList(deviceInfoSet);
 				return true;
 			}
@@ -324,6 +334,55 @@ bool USBListener::GetVidPid(const std::string& deviceId, uint16_t& vid, uint16_t
 	}
 }
 
+/**
+ * Get USB serial number from device instance ID
+ * The serial number is typically the last part after the last backslash
+ */
+std::string USBListener::GetSerialNumber(HDEVINFO deviceInfoSet, SP_DEVINFO_DATA& devInfoData) {
+	WCHAR instanceId[MAX_PATH];
+	if (!SetupDiGetDeviceInstanceId(deviceInfoSet, &devInfoData, instanceId, MAX_PATH, nullptr)) {
+		return "";
+	}
+	
+	std::wstring idW = instanceId;
+	std::string deviceId(idW.begin(), idW.end());
+	
+	// The serial number is typically after the last backslash in the device instance ID
+	// Format: USB\VID_XXXX&PID_XXXX\SERIAL_NUMBER
+	size_t lastBackslash = deviceId.rfind('\\');
+	if (lastBackslash != std::string::npos && lastBackslash + 1 < deviceId.length()) {
+		return deviceId.substr(lastBackslash + 1);
+	}
+	
+	return "";
+}
+
+/**
+ * Format serial number in iOS-style dash-separated format
+ * iOS UDIDs are typically 24-25 characters and formatted as: XXXXXXXX-XXXXXXXXXXXXXXXX
+ * Example: 00008030-001234567890402E
+ */
+static std::string FormatSerialAsDeviceId(const std::string& serial) {
+	if (serial.empty()) {
+		return "";
+	}
+	
+	// iOS serial numbers are typically 24-25 chars without dashes
+	// Format: first 8 chars, dash, remaining chars
+	// If it already contains dashes, return as-is
+	if (serial.find('-') != std::string::npos) {
+		return serial;
+	}
+	
+	// iOS UDID format: 8 chars + dash + rest (typically 16 chars)
+	if (serial.length() >= 24) {
+		return serial.substr(0, 8) + "-" + serial.substr(8);
+	}
+	
+	// For shorter serials (like Android), return as-is
+	return serial;
+}
+
 void USBListener::EnumerateConnectedDevices() {
 	HDEVINFO deviceInfoSet = SetupDiGetClassDevs(&GUID_DEVINTERFACE_USB_DEVICE, nullptr, nullptr, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);
 	if (deviceInfoSet == INVALID_HANDLE_VALUE) {
@@ -338,9 +397,9 @@ void USBListener::EnumerateConnectedDevices() {
 		if (SetupDiGetDeviceInstanceId(deviceInfoSet, &devInfoData, instanceId, MAX_PATH, nullptr)) {
 			DeviceInfo info;
 			std::wstring idW = instanceId;
-			info.deviceId = std::string(idW.begin(), idW.end());
+			std::string fullDeviceId = std::string(idW.begin(), idW.end());
 			
-			if (!GetVidPid(info.deviceId, info.vid, info.pid)) {
+			if (!GetVidPid(fullDeviceId, info.vid, info.pid)) {
 				continue;
 			}
 			
@@ -349,6 +408,14 @@ void USBListener::EnumerateConnectedDevices() {
 				continue;
 			}
 			
+			// Get serial number and use as device ID if available
+			info.serialNumber = GetSerialNumber(deviceInfoSet, devInfoData);
+			if (!info.serialNumber.empty()) {
+				info.deviceId = FormatSerialAsDeviceId(info.serialNumber);
+			} else {
+				info.deviceId = fullDeviceId;
+			}
+			
 			// Cache device with exclusive lock
 			{
 				std::unique_lock lock(m_cacheMutex);
@@ -359,6 +426,7 @@ void USBListener::EnumerateConnectedDevices() {
 				auto callback = [](Napi::Env env, Napi::Function jsCallback, DeviceInfo* data) {
 					Napi::Object obj = Napi::Object::New(env);
 					obj.Set("deviceId", Napi::String::New(env, data->deviceId));
+					obj.Set("serialNumber", Napi::String::New(env, data->serialNumber));
 					obj.Set("vid", Napi::Number::New(env, data->vid));
 					obj.Set("pid", Napi::Number::New(env, data->pid));
 					obj.Set("locationInfo", Napi::String::New(env, data->locationInfo));
@@ -394,9 +462,9 @@ std::vector<DeviceInfo> USBListener::ListAllDevices() {
 		if (SetupDiGetDeviceInstanceId(deviceInfoSet, &devInfoData, instanceId, MAX_PATH, nullptr)) {
 			DeviceInfo info;
 			std::wstring idW = instanceId;
-			info.deviceId = std::string(idW.begin(), idW.end());
+			std::string fullDeviceId = std::string(idW.begin(), idW.end());
 			
-			if (!GetVidPid(info.deviceId, info.vid, info.pid)) {
+			if (!GetVidPid(fullDeviceId, info.vid, info.pid)) {
 				continue;
 			}
 			
@@ -405,6 +473,14 @@ std::vector<DeviceInfo> USBListener::ListAllDevices() {
 				continue;
 			}
 			
+			// Get serial number and use as device ID if available
+			info.serialNumber = GetSerialNumber(deviceInfoSet, devInfoData);
+			if (!info.serialNumber.empty()) {
+				info.deviceId = FormatSerialAsDeviceId(info.serialNumber);
+			} else {
+				info.deviceId = fullDeviceId;
+			}
+			
 			devices.push_back(info);
 		}
 	}

package/native/usb_listener_win.h

@@ -74,6 +74,7 @@ private:
 	bool GetDeviceInfo(const std::string& devicePath, DeviceInfo& info);       // Get device info from Windows API (for connections)
 	bool GetDeviceInfoFromPath(const std::string& devicePath, DeviceInfo& info); // Parse device info from path (for disconnections)
 	bool GetLocationInfo(DEVINST devInst, std::string& locationInfo);          // Get physical port location
+	std::string GetSerialNumber(HDEVINFO deviceInfoSet, SP_DEVINFO_DATA& devInfoData); // Get USB serial number
 	bool GetVidPid(const std::string& deviceId, uint16_t& vid, uint16_t& pid); // Parse VID/PID from device ID string
 	void EnumerateConnectedDevices();                                          // Enumerate devices on startup
 	

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcesystems/usb-device-listener",
-  "version": "1.0.30",
+  "version": "1.0.31",
   "description": "Native cross-platform USB device listener for Windows and macOS",
   "main": "dist/index.js",
   "module": "dist/index.mjs",