Linux Issues

Each section below opens with the exact message pcu shows on Linux, followed by how to clear it. Most access problems are solved by the installer and its status doctor; see Install on Linux for the full setup.

”Permission denied: /dev/i2c-…” (CQ20)

A hardware command fails because your user cannot open the SMBus device:

ERROR: Permission denied: /dev/i2c-3. Run the installer (sudo bash pcu-setup.sh) and log out/in, or add your user to the 'i2c' group: sudo usermod -aG i2c $USER (then re-login).

The bus number (i2c-3 above) depends on your SMBus adapter. The GUI shows the same detail under an Access denied. heading on the splash and sidebar.

This almost always means your user is in the i2c group but the current login session has not picked it up yet. Group membership only applies to new sessions.

1. Log out and back in (or reboot), then retry.
2. To fix a single shell without logging out: newgrp i2c.
3. If you were never added, run the installer or sudo usermod -aG i2c $USER, then log out and in.

The i2c group grants privileged access to the SMBus. See the caution on Install on Linux.

”The i2c-dev kernel module is not loaded.”

From a terminal, pcu-cli offers to load the module:

The i2c-dev kernel module is not loaded.
This module is required to access the SMBus from userspace.
Load it now? (requires root) [y/N]

Declining prints the manual steps:

Aborted. Load manually: sudo modprobe i2c-dev
To load at boot: echo 'i2c-dev' | sudo tee /etc/modules-load.d/i2c-dev.conf

The GUI, which has no prompt, shows instead:

SMBus not available. The i2c-dev kernel module isn't loaded yet.

Reboot (the installer set it to load at boot), or load it now with: sudo modprobe i2c-dev

The installer configures the module to load at every boot, so the usual cause is a fresh install that has not been rebooted.

1. Reboot, or load it now with sudo modprobe i2c-dev.
2. Re-run pcu.

”No /dev/i2c-* nodes”

The status doctor reports:

  [WARN] No /dev/i2c-* nodes (module not loaded, or no adapter)

Either the i2c-dev module is not loaded, or this machine has no SMBus adapter (it is not a CQ20).

1. Load the module: sudo modprobe i2c-dev, or reboot.
2. Re-run bash pcu-setup.sh status. If the nodes still do not appear, confirm the hardware is a CQ20; see Supported Platforms.

”Permission denied opening /dev/port” (CQ40)

CQ40 digital I/O uses raw port access, which the kernel gates on a capability that file permissions cannot grant:

ERROR: Permission denied opening /dev/port. Raw port I/O needs the CAP_SYS_RAWIO capability: run as root (sudo), or grant it once with sudo setcap cap_sys_rawio+ep /opt/pcu/pcu-cli (and /opt/pcu/pcu for the GUI). Kernel lockdown under Secure Boot can also block /dev/port even for root.

1. For the CLI, the simplest fix is to run under sudo.
2. For the GUI (which cannot elevate under Wayland), grant the capability once: sudo bash pcu-setup.sh caps, or install with sudo bash pcu-setup.sh install --with-portio.

CAP_SYS_RAWIO is effectively root-level hardware access. See the caution on Install on Linux before granting it.

Stopped working after a pcu update

CQ40 port I/O that worked before an update suddenly needs sudo again, or the GUI can no longer reach /dev/port. This is expected: the CAP_SYS_RAWIO capability lives on the binary file and is lost whenever the binary is replaced by an update.

1. Re-apply it: sudo bash pcu-setup.sh caps.
2. Or run sudo bash pcu-setup.sh repair, which re-applies the setup and preserves a capability that was granted before.

Re-run this after every pcu update on a CQ40. The CQ20 SMBus path is unaffected.

/dev/port denied even with sudo (Secure Boot)

If /dev/port is denied for CQ40 port I/O even when running as root, and the CAP_SYS_RAWIO grant above made no difference, the kernel is blocking raw port access through its lockdown feature.

Note

Kernel lockdown, which is enabled automatically when Secure Boot is on, can block /dev/port for every process including root. This affects CQ40 port I/O only; the CQ20 SMBus path does not use /dev/port and is unaffected.

To use CQ40 digital I/O on such a system, disable Secure Boot in the firmware setup, or boot a kernel that is not in lockdown. This is a firmware and kernel policy, not a pcu setting.

Run the setup doctor

pcu-setup.sh status is a read-only health check (“doctor”) that needs no root. Run it from the unpacked release folder to see exactly which step is failing. A healthy CQ20 looks like this (a banner is printed first):

$ bash pcu-setup.sh status

==> Installation
  [ OK ] Binaries installed in /opt/pcu
  [ OK ] CLI on PATH (/usr/local/bin/pcu-cli)
  [ OK ] Desktop entry present
  [ OK ] Icon installed

==> SMBus access (i2c)
  [ OK ] udev rule present
  [ OK ] modules-load drop-in present
  [ OK ] i2c-dev module loaded
  [ OK ] Found 2 /dev/i2c-* node(s)
  [ OK ] Nodes group 'i2c' (mode 660)
  [ OK ] Intel I801 SMBus adapter detected

==> Port I/O access (CQ40, optional)
  /dev/port not present (only needed for CQ40 GPIO)
  No CAP_SYS_RAWIO set -- CQ40 GPIO needs sudo, or grant it: sudo bash pcu-setup.sh caps

==> Group membership
  [ OK ] Group 'i2c' exists
  [ OK ] User 'user' is in 'i2c'
  [ OK ] Membership active in this session

All checks passed.

Each check prints [ OK ], [WARN], or [FAIL]; warnings and failures add an actionable hint below the line. The command’s exit code reflects the worst result: 0 when all checks pass, 1 when there are warnings, and 2 when there are problems. Run it as your normal user (no sudo) so it can confirm the live session’s group membership.

GUI errors on Linux

The Linux GUI has no crash dialog. Fatal errors and the single-instance message (pcu is already running.) are written to standard error. If the GUI closes or fails to start with no visible reason, launch it from a terminal to see the output:

$ /opt/pcu/pcu

Connection problems still appear in the app: on the splash screen during startup, and in the sidebar afterwards.