Skip to content

Instantly share code, notes, and snippets.

@danielrosehill

danielrosehill/eaton-ups-nut-driver-fix.md

Created November 22, 2025 20:50
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save danielrosehill/86534253d4d2998756498f803f3f790b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save danielrosehill/86534253d4d2998756498f803f3f790b to your computer and use it in GitHub Desktop.
Download ZIP
Fix for Eaton UPS (5E) not connecting with NUT (Network UPS Tools) on Linux - kernel hid-generic driver conflict
Raw
eaton-ups-nut-driver-fix.md

Fixing Eaton UPS Connection Issues with NUT on Linux

Problem Description

The Network UPS Tools (NUT) driver fails to connect to an Eaton 5E UPS (and likely other Eaton USB-connected UPS models) despite the UPS being properly detected by the system. The driver continuously fails with permission errors.

Symptoms

  • nut-driver@*.service fails to start with exit code 1
  • Journalctl shows errors like: 
    libusb1: Could not open any HID devices: insufficient permissions on everything
libusb1: except 3 devices tried but not matching the requested criteria
No matching HID UPS found
  • UPS appears in lsusb output (e.g., Bus 001 Device XXX: ID 0463:ffff EATON 5E)
  • Running the driver manually shows string descriptor request failures: 
    nut_usb_get_string_descriptor: string descriptor 0 request failed, retrying...
nut_libusb_open: get Manufacturer string failed

Root Cause

The Linux kernel's generic HID driver (hid-generic) claims the Eaton UPS device during USB enumeration. This prevents NUT's libusb-based driver from accessing the device properly, even with correct udev permissions.

The kernel assigns the device to hid-generic and creates hidraw/hiddev nodes, but the NUT driver needs direct USB access via libusb, which conflicts with the kernel driver binding.

Kernel messages (from dmesg) show:

hid-generic 0003:0463:FFFF.XXXX: hiddev7,hidraw4: USB HID v1.10 Device [EATON 5E]
hid-generic 0003:0463:FFFF.XXXX: usb_submit_urb(ctrl) failed: -1
hid-generic 0003:0463:FFFF.XXXX: timeout initializing reports

Solution

Create a udev rule that prevents hid-generic from binding to the Eaton UPS device, allowing NUT to claim it directly.

Step 1: Create the udev rule

Create /etc/udev/rules.d/90-nut-eaton-unbind.rules:

# Prevent hid-generic from binding to Eaton UPS
# Unbind from hid-generic and prevent rebinding
ACTION=="add", SUBSYSTEM=="hid", ATTRS{idVendor}=="0463", ATTRS{idProduct}=="ffff", \
  RUN+="/bin/sh -c 'echo $kernel > /sys/bus/hid/drivers/hid-generic/unbind || true'"

# Set permissions for NUT
ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="0463", ATTRS{idProduct}=="ffff", \
  GROUP="nut", MODE="0664"

ACTION=="add", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0463", ATTRS{idProduct}=="ffff", \
  GROUP="nut", MODE="0664"

Note: Adjust idVendor and idProduct if you have a different Eaton model. Find yours with lsusb | grep -i eaton.

Step 2: Configure NUT

Ensure your /etc/nut/ups.conf is properly configured:

[eaton5e]
	driver = usbhid-ups
	port = auto
	vendorid = 0463
	productid = ffff
	desc = "Eaton 5E UPS"

Step 3: Apply the changes

# Reload udev rules
sudo udevadm control --reload-rules

# Stop the NUT driver
sudo systemctl stop nut-driver@eaton5e.service

# Unplug and replug the UPS USB cable to trigger the new udev rule
# (or trigger a USB reset if you can't physically access the cable)

# Start the NUT driver
sudo systemctl start nut-driver@eaton5e.service

Step 4: Verify the fix

Check that the driver is running:

systemctl status nut-driver@eaton5e.service

Query the UPS status:

upsc eaton5e

You should see detailed UPS information including:

  • Battery charge level
  • Input/output voltage
  • Load percentage
  • UPS status (OL = Online, CHRG = Charging)

Verification Output

When working correctly, you should see:

$ upsc eaton5e
battery.charge: 100
battery.runtime: 762
device.mfr: EATON
device.model: 5E 650i
ups.status: OL CHRG
ups.load: 31
input.voltage: 236.0
output.voltage: 236.0

And the service status should show:

● nut-driver@eaton5e.service - Network UPS Tools - device driver for NUT device 'eaton5e'
   Active: active (running)

Affected Models

This fix should work for various Eaton UPS models that use USB HID protocol, including:

  • Eaton 5E series
  • Possibly other Eaton USB-connected models with similar symptoms

Technical Notes

  • The udev rule unbinds the device from hid-generic when it's added to the system
  • This allows libusb (used by NUT) to claim the device directly
  • The fix persists across reboots and USB reconnections
  • No kernel driver blacklisting is needed; we only prevent binding to this specific device

Alternative Approaches Tried (That Didn't Work)

  • Adjusting udev permissions alone (device already had correct permissions)
  • Using usb_set_altinterface option in ups.conf
  • Specifying explicit subdriver in ups.conf
  • Using hiddev device path directly

These didn't work because the fundamental issue was the kernel driver claiming the device first.

System Information

This fix was tested on:

  • OS: Ubuntu 25.10 with KDE Plasma on Wayland
  • NUT Version: 2.8.3
  • Kernel: 6.17.0-6-generic
  • UPS Model: Eaton 5E 650i

References

Generated by Claude Code - This gist documents a technical fix discovered through system debugging. While the solution worked in this specific case, always verify applicability to your environment and test thoroughly before deploying in production systems.

Please validate this information against current NUT documentation and your specific hardware configuration.

Comments are disabled for this gist.