inno-installers/PrinterInstaller/TROUBLESHOOTING_HID.md

# HID Card Printer Installation Troubleshooting

## Common Error: "The arguments are invalid"

**Cause:** Driver name mismatch between code and INF file

**Solution:** ✅ Fixed - Driver name updated to "DTC4500e Card Printer"

### How to Verify Driver Name from INF File

```powershell
# Find the driver name in the INF file
Select-String -Path "DTC4500e.inf" -Pattern "^\[Strings\]" -Context 0,10
```

Look for the line like:
```
DTC4500e = "DTC4500e Card Printer"
```

The value in quotes is the exact driver name Windows expects.

## Testing the Driver Installation Manually

### Step 1: Extract Driver Files
```powershell
# Navigate to where driver files are located
cd C:\path\to\drivers\hid_dtc4500e_x64
```

### Step 2: Install Driver Package
```powershell
# Use pnputil to add the driver
pnputil /add-driver DTC4500e.inf /install

# Expected output:
# Microsoft PnP Utility
# Adding driver package...
# Driver package added successfully.
# Published Name: oem123.inf
```

### Step 3: Verify Driver is Installed
```powershell
# List all printer drivers
Get-PrinterDriver | Where-Object {$_.Name -like "*DTC*"}

# Should show:
# Name                  PrinterEnvironment
# ----                  ------------------
# DTC4500e Card Printer Windows x64
```

### Step 4: Test USB Detection
1. Plug in the HID FARGO DTC4500e via USB
2. Windows should detect it automatically
3. Check Device Manager → Printers
4. Should see "DTC4500e Card Printer"

## Other Common Issues

### Issue: "Driver not found" after pnputil
**Cause:** Catalog file (.cat) missing or invalid signature

**Solution:**
```powershell
# Check if catalog file exists
Test-Path "DTC4500e_x64.cat"

# Verify INF references correct catalog
Select-String -Path "DTC4500e.inf" -Pattern "CatalogFile"
```

### Issue: "Access Denied"
**Cause:** Not running as Administrator

**Solution:**
```powershell
# Check if running as admin
([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

# Should return: True
```

### Issue: Driver installs but USB device not detected
**Cause:** USB device may need specific VID/PID

**Check INF for USB IDs:**
```powershell
Select-String -Path "DTC4500e.inf" -Pattern "USBPRINT"
```

Should show:
```
USBPRINT\HID_GlobalDTC4500e050F,HID_GlobalDTC4500e050F
```

**Verify USB Device:**
```powershell
# Check what Windows sees when device is plugged in
Get-PnpDevice | Where-Object {$_.FriendlyName -like "*HID*" -or $_.FriendlyName -like "*Fargo*"}
```

## PowerShell Test Script

Use this to test driver installation manually:

```powershell
# Test-HIDDriverInstallation.ps1
$ErrorActionPreference = "Stop"

Write-Host "Testing HID FARGO DTC4500e Driver Installation" -ForegroundColor Cyan
Write-Host ""

# 1. Check admin rights
if (-not ([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
    Write-Host "ERROR: Must run as Administrator" -ForegroundColor Red
    exit 1
}
Write-Host "✓ Running as Administrator" -ForegroundColor Green

# 2. Check INF file exists
$infPath = "DTC4500e.inf"
if (-not (Test-Path $infPath)) {
    Write-Host "ERROR: DTC4500e.inf not found in current directory" -ForegroundColor Red
    exit 1
}
Write-Host "✓ INF file found: $infPath" -ForegroundColor Green

# 3. Install driver
Write-Host "Installing driver package..." -ForegroundColor Yellow
try {
    $result = pnputil /add-driver $infPath /install 2>&1
    Write-Host "✓ Driver package installed" -ForegroundColor Green
} catch {
    Write-Host "ERROR: pnputil failed - $_" -ForegroundColor Red
    exit 1
}

# 4. Verify driver is installed
Write-Host "Verifying driver installation..." -ForegroundColor Yellow
Start-Sleep -Seconds 2

$driver = Get-PrinterDriver -Name "DTC4500e Card Printer" -ErrorAction SilentlyContinue
if ($driver) {
    Write-Host "✓ Driver installed successfully!" -ForegroundColor Green
    Write-Host "  Driver Name: $($driver.Name)" -ForegroundColor Gray
    Write-Host "  Environment: $($driver.PrinterEnvironment)" -ForegroundColor Gray
} else {
    Write-Host "WARNING: Driver not found via Get-PrinterDriver" -ForegroundColor Yellow
    Write-Host "This may be normal - driver might only activate when USB device is connected" -ForegroundColor Yellow
}

Write-Host ""
Write-Host "Next Steps:" -ForegroundColor Cyan
Write-Host "1. Plug in HID FARGO DTC4500e via USB" -ForegroundColor Gray
Write-Host "2. Windows should detect and configure automatically" -ForegroundColor Gray
Write-Host "3. Check Devices and Printers" -ForegroundColor Gray
```

## Installation Verification Checklist

After running the installer:

- [ ] No error messages during installation
- [ ] PowerShell window shows "Driver installed successfully"
- [ ] `Get-PrinterDriver` shows "DTC4500e Card Printer"
- [ ] USB device plugged in
- [ ] Device appears in Device Manager
- [ ] Printer appears in Devices and Printers
- [ ] Can print test page

## Getting Help

If issues persist:

1. **Check Windows Event Viewer:**
   - Windows Logs → System
   - Look for errors from "User Plug and Play" source

2. **Check pnputil output:**
   ```powershell
   pnputil /enum-drivers | Select-String "DTC4500e" -Context 3
   ```

3. **Verify all driver files are present:**
   ```powershell
   Get-ChildItem -Path "hid_dtc4500e_x64" -Recurse | Measure-Object
   # Should show 100+ files
   ```

## Fixed Issues Log

### 2025-10-24: Driver Name Mismatch
- **Error:** "The arguments are invalid"
- **Root Cause:** Code used "HID FARGO DTC4500e Card Printer" but INF defines "DTC4500e Card Printer"
- **Fix:** Updated both Install-PrinterDriver and Install-NetworkPrinter functions with correct name
- **Status:** ✅ Resolved