WhatCable para Linux: inspecciona tus puertos USB en Raspberry Pi OS

Todo empezó con un post de Microsiervos sobre WhatCable, una pequeña utilidad para macOS que lee los cables USB-C conectados y explica exactamente qué capacidades tiene cada uno. Velocidad real, potencia máxima, si el cable lleva e-marker o no. Todo lo que el conector no cuenta por sí mismo. La app es de darrylmorley y funciona sobre la API IOKit de Apple, así que en principio era solo para Mac.

Sin embargo, buscando un poco más, apareció en Hacker News un port para KDE Plasma hecho por Zetaphor. Está escrito en C++ con QML y requiere KDE Frameworks 6. Y luego, buscando más, apareció otro port de nedrichards, este específicamente para GNOME: Python, GTK4 y libadwaita. Orientado a Flatpak y con cara de acabar en Flathub en algún momento. Es este último el que he probado en Raspberry Pi OS Bookworm.

Qué hace WhatCable por dentro

En Linux, la información sobre puertos y cables USB-C llega a través del kernel, concretamente de la clase typec, que expone sus datos en /sys/class/typec/. Si el driver del controlador USB-C del sistema registra el puerto correctamente en esa clase, ahí aparece todo: velocidad del cable, PDOs de carga, identidad del cable si lleva e-marker, modo alternativo si lo hay. Además, la información de dispositivos conectados a puertos USB-A viaja por /sys/bus/usb/devices/, que es el sysfs USB estándar de toda la vida.

El port de nedrichards lee ambas fuentes. También lee /sys/kernel/debug/usb/devices para datos adicionales de topología. No necesita root para nada de esto. En teoría, debería funcionar igual en cualquier distribución Linux moderna, incluido Raspberry Pi OS.

El problema con el USB-C de la Raspberry Pi

Aquí viene la parte que no es obvia. Tanto la Raspberry Pi 4 como la Raspberry Pi 5 tienen puerto USB-C, pero ese puerto lo gestiona el firmware del bootloader, no un driver de kernel. La negociación de USB-C Power Delivery —qué PDOs pide la placa, qué corriente puede entregar la fuente— ocurre antes de que el sistema operativo ni siquiera haya arrancado. El propio Raspberry Pi Ltd lo confirma en su white paper sobre USB PD: la Pi 5 solo pide PDOs a 5V y esa lógica vive en el EEPROM del bootloader.

Como resultado, /sys/class/typec/ está vacío en ambas placas. No hay driver UCSI, no hay TCPM, no hay nada que registre el puerto USB-C como typec_port en el kernel. WhatCable arranca sin problema, pero el apartado de puertos USB-C aparece vacío. No es un bug de la app: es una limitación arquitectónica de estas placas que no tiene solución desde userspace.

Lo que sí funciona: los cuatro puertos USB-A

Por otro lado, los puertos USB-A sí exponen toda su información. Y en el contexto de una Raspberry Pi, eso es bastante útil. Tanto la Pi 4 como la Pi 5 tienen un presupuesto de corriente limitado para los periféricos USB. Los problemas de alimentación USB en Raspberry Pi vienen de lejos, y poder ver de un vistazo cuánta corriente declara consumir cada dispositivo conectado ayuda a detectar situaciones comprometidas antes de que empiecen los problemas.

Por cada dispositivo conectado, WhatCable muestra el fabricante y nombre de producto, la velocidad negociada (12, 480 o 5000 Mbps según el puerto), la versión USB, el consumo declarado en el descriptor del dispositivo, la clase de dispositivo y el driver de kernel activo. Además, expone la topología completa: en la Pi 4, por ejemplo, aparece el hub VL805 de VIA Labs como hub raíz del bus USB 3.0, con los dispositivos conectados colgando de él como ramas. En la Pi 5, el mismo papel lo hace el chip RP1.

Eso sí, el consumo que muestra es el bMaxPower del descriptor USB, no el consumo real en ese momento. Es lo que el dispositivo dice que puede necesitar, no lo que está usando. Para consumo real hace falta un vatímetro USB en serie. Aun así, como referencia para dimensionar qué cabe dentro del presupuesto de la placa, es un dato útil.

Instalación en Raspberry Pi OS Bookworm

Raspberry Pi OS Bookworm es Debian 12. Tiene GTK4 y libadwaita en repos, así que el software corre sin problemas. El único obstáculo es que el paquete meson del sistema es la versión 1.0.1, y el proyecto exige >= 1.2.0. Se resuelve instalando meson desde pip.

Primero, las dependencias:

sudo apt install git ninja-build python3-pip \
    python3-gi python3-gi-cairo \
    gir1.2-gtk-4.0 gir1.2-adw-1

Después, meson actualizado:

pip3 install meson --break-system-packages
meson --version

La versión debe ser 1.2.0 o superior. A continuación, clonar e instalar:

git clone https://github.com/nedrichards/whatcable-linux.git
cd whatcable-linux
meson setup build --prefix="$HOME/.local"
meson install -C build

Los ajustes necesarios para que funcione bien

Meson instala el módulo Python en ~/.local/lib/python3/dist-packages/, que es la ruta de Debian pero no está en el sys.path por defecto. Sin ese path, el ejecutable falla con un ModuleNotFoundError. La solución es añadirlo al .bashrc:

echo 'export PYTHONPATH="$HOME/.local/lib/python3/dist-packages:$PYTHONPATH"' >> ~/.bashrc
source ~/.bashrc

Con eso, el CLI funciona desde terminal. Sin embargo, las aplicaciones lanzadas desde el escritorio no cargan el .bashrc, así que el menú de inicio sigue sin arrancar la app. La solución más limpia es reemplazar el ejecutable por un wrapper que lleve el entorno incorporado:

cat > ~/.local/bin/whatcable-linux << 'EOF'
#!/bin/bash
export PYTHONPATH="$HOME/.local/lib/python3/dist-packages:$PYTHONPATH"
export GTK_A11Y=none
exec python3 -m whatcable_linux "$@"
EOF
chmod +x ~/.local/bin/whatcable-linux

La variable GTK_A11Y=none silencia un warning inofensivo sobre el bus de accesibilidad, que no está disponible en Raspberry Pi OS por defecto.

Por último, el archivo .desktop que crea meson usa el nombre del comando sin ruta absoluta. En el entorno gráfico eso falla porque ~/.local/bin no siempre está en el PATH de la sesión. Se corrige así:

sed -i \
    "s|Exec=whatcable-linux|Exec=/home/$USER/.local/bin/whatcable-linux|" \
    ~/.local/share/applications/com.nedrichards.WhatCable.desktop

update-desktop-database ~/.local/share/applications/

Después de esto, la app arranca tanto desde terminal como desde el menú de aplicaciones.

Un ejemplo real de salida

Con los ajustes hechos, esto es lo que muestra WhatCable en la Raspberry Pi 4 con tres periféricos conectados: el hub interno VL805 del chip USB 3.0, un adaptador USB con tarjeta SD dentro y el receptor Logitech Unifying del teclado y ratón inalámbrico.

El primer dispositivo que aparece en la lista es el hub USB 2.0 interno (2109:3431). Es el VIA Labs VL805, el controlador que gestiona los cuatro puertos USB-A de la Pi 4. Aparece a 480 Mbps y con 100 mA declarados, lo esperable en un hub de bus alimentado por la propia placa.

El segundo es el adaptador USB con tarjeta SD (090c:6200, Silicon Motion). Esta Pi 4 tiene el slot microSD dañado, así que el almacenamiento principal va por USB mediante un adaptador. WhatCable lo identifica correctamente como dispositivo de almacenamiento con driver usb-storage, 480 Mbps y 500 mA declarados. Esos 500 mA son el máximo que el adaptador dice que puede necesitar; en la práctica consume bastante menos.

El tercero es el receptor Logitech Unifying (046d:c52b). Negocia a 12 Mbps, que es Full Speed, lo normal para dispositivos HID. Lo interesante aquí son las tres interfaces: una para el teclado, otra para el ratón y una tercera para el canal de datos del protocolo Unifying. Todo visible en el panel de detalle. Consume 98 mA declarados.

El apartado typec_ports llega vacío en los tres casos, exactamente como se esperaba. La app muestra 8 dispositivos en total porque también cuenta el hub raíz del bus USB 3.0 y los nodos internos del xHCI, que aparecen en la sección Advanced Sources.

La app tiene menos de dos semanas de vida y ya es funcional en Raspberry Pi OS con cuatro ajustes concretos. Para lo que cuesta instalarlo, ver de un vistazo el consumo declarado de cada periférico USB conectado a la Pi vale la pena, especialmente si tienes un disco externo, un hub o varios dispositivos enchufados a la vez y quieres saber si estás cerca del límite de los 600 mA que da la placa con una fuente de 3A. También me ha servido para ver que algunos cables USB que tenía eran bastante malos en cuestión de velocidad, así que compré un par de Amazon Basics que realmente funcionan y ha sido un descubrimiento.

El repositorio del port GNOME está en github.com/nedrichards/whatcable-linux. El port para KDE Plasma 6 en github.com/Zetaphor/whatcable-linux. Y la app original para macOS en github.com/darrylmorley/whatcable.