@mcesystems/usbmuxd-instance-manager 1.0.72 → 1.0.74

package/README.md

@@ -109,6 +109,22 @@ await service.stop();
 | `verboseLogging` | boolean | true | Enable verbose output |
 | `appleVendorId` | string | '05AC' | Apple vendor ID (hex) |
 
+### Lockdown sync
+
+The manager automatically syncs lockdown (pairing) files between the native Apple/iTunes lockdown directory and Alpine so devices that were already paired on Windows can be used without pairing again in WSL.
+
+The lockdown directory is resolved per platform:
+- **Windows**: `C:\ProgramData\Apple\Lockdown` (same directory used by iTunes / Apple Mobile Device)
+- **macOS**: `/var/db/lockdown`
+- **Linux**: `/var/lib/lockdown`
+
+Sync behavior:
+
+- **To Alpine**: When a device is assigned, that device's plist (`{UDID}.plist`) and `SystemConfiguration.plist` are copied from the Apple lockdown directory to Alpine `/var/lib/lockdown`.
+- **From Alpine**: When the service stops, plists for all devices that were assigned this session (plus `SystemConfiguration.plist` if present) are copied from Alpine back to the Apple lockdown directory so they are available for the next run.
+
+**Alpine permissions**: `/var/lib/lockdown` is often root-owned. The sync tries a normal copy first; if that fails (e.g. permission denied), it retries with `sudo cp`. Ensure the WSL user has passwordless sudo for these commands, or that the Alpine image has `/var/lib/lockdown` writable by the default user. If both fail, a warning is logged and device assignment continues (pairing can still be done manually).
+
 ## CLI Options
 
 ```
@@ -118,7 +134,8 @@ Options:
   --batchSize <n>        Number of devices per instance (default: 4)
   --basePort <port>      Base TCP port for first instance (default: 27015)
   --maxInstances <n>     Maximum number of instances (default: 20)
-  --usbmuxdPath <path>   Path to usbmuxd executable
+  --usbmuxdPath <path>   Path to usbmuxd executable (WSL: default usbmuxd)
+  --wslDistribution <n>  WSL distribution name (default: alpine-usbmuxd-build)
   --verbose <true|false> Enable verbose logging (default: true)
   --appleVid <vid>       Apple Vendor ID in hex (default: 05AC)
   -h, --help             Show this help message
@@ -162,6 +179,65 @@ When all devices disconnect from Instance 2:
 - Instance 2 automatically terminates
 - Frees resources
 
+## Flow: Working with usbipd and WSL
+
+On Windows, the same physical USB device can be used by **either** Windows (e.g. iTunes, Apple Mobile Device) **or** WSL (usbmuxd), not both. usbipd-win is what moves the device between the two.
+
+### Device ownership
+
+| State | Who has the device | iTunes / Windows | usbmuxd (WSL) |
+|-------|--------------------|------------------|---------------|
+| Not shared | Windows | ✓ | ✗ |
+| Bound + attached to WSL | WSL | ✗ | ✓ |
+| Bound but detached | Neither (held by usbipd) | ✗ | ✗ |
+
+### Giving the device to usbmuxd (instance manager)
+
+1. **WSL** must be running (e.g. the manager starts it, or run `wsl -d alpine-usbmuxd-build -- echo ok`).
+2. **Bind** the device (take it from Windows):  
+   `usbipd bind --busid <BUSID> --force`
+3. **Attach** to WSL:  
+   `usbipd attach --wsl=<distro> --busid=<BUSID>`
+
+The instance manager does steps 2–3 automatically when it sees an iOS device. You can also use the script:
+
+```powershell
+# From packages/usbmuxd-instance-manager
+.\scripts\attach-device.ps1
+```
+
+### Giving the device back to Windows (e.g. for iTunes)
+
+1. **Detach** from WSL (stops forwarding to Linux):  
+   `usbipd detach --busid <BUSID>`  
+   Or detach all:  
+   `usbipd detach -a`
+2. **Unbind** so Windows gets the device back:  
+   `usbipd unbind --busid <BUSID>`
+
+Until you unbind, the device stays "Shared (forced)" and Windows/iTunes will not see it.
+
+### Useful usbipd commands
+
+```powershell
+$usbipd = "C:\Program Files\usbipd-win\usbipd.exe"
+
+# List devices and their state (Shared / Not shared, Attached / Not attached)
+& $usbipd list
+
+# Detach from WSL (device still bound to usbipd)
+& $usbipd detach --busid 2-5
+& $usbipd detach -a
+
+# Unbind so Windows can use the device again (e.g. iTunes)
+& $usbipd unbind --busid 2-5
+```
+
+### Quick reference
+
+- **Use device with usbmuxd-instance-manager** → bind + attach (manager or script does this when you connect a device).
+- **Use device with iTunes on Windows** → detach then unbind for that bus ID; then iTunes will see it.
+
 ## Requirements
 
 ### Runtime