---
name: conky_widget
lang: lua
domain: infra
version: 0.1.0
description: "Widget de escritorio Conky con pestañas clickeables (Red / Sistema / Docker) y botones que lanzan herramientas de análisis de red."
tags: [conky, widget, desktop, monitoring, network, lua, launcher-buttons]
uses_functions: []
uses_types: []
framework: "conky"
entry_point: "conky.conf"
dir_path: "apps/conky_widget"
repo_url: "https://gitea-dgg044oo04woo4ggcsws4gk0.organic-machine.com/dataforge/conky_widget"
e2e_checks:
  - id: lint_install
    cmd: "bash -n install.sh"
    timeout_s: 10
  - id: lint_launch
    cmd: "bash -n lua/launch.sh"
    timeout_s: 10
  - id: lua_parse
    cmd: "luac -p lua/widget.lua 2>/dev/null || lua -e \"assert(loadfile('lua/widget.lua'))\""
    timeout_s: 10
    severity: warning
---

# conky_widget

Visualizador de escritorio basado en Conky (1.19, X11 + Lua + Cairo) que muestra
el estado del PC en vivo en la esquina superior derecha del monitor primario.
El contenido está organizado en tres pestañas clickeables y, en la pestaña de
red, incluye botones que abren herramientas de análisis de paquetes.

## Pestañas

| Pestaña | Contenido |
|---|---|
| **Red** | Velocidad de bajada/subida de `enp5s0`, gráfico histórico en vivo (60 s), conexiones TCP/UDP establecidas, total descargado/subido, y botones [Wireshark] [ntopng] [nethogs]. |
| **Sistema** | CPU total + barras por core, RAM, Swap, uso de disco `/`, temperatura, load average y uptime. |
| **Docker** | Número de contenedores en marcha / totales y lista de nombres activos (lectura sin sudo). |

## Cómo funciona

- `conky.conf` posiciona la ventana (`own_window_type = normal` para recibir
  clics) y delega todo el dibujo a `lua/widget.lua`.
- `lua/widget.lua` dibuja con Cairo en el hook `conky_draw` y gestiona los clics
  en el hook `conky_mouse`: la barra superior cambia de pestaña y los botones de
  la pestaña Red lanzan la herramienta correspondiente.
- `lua/launch.sh` comprueba si el binario existe antes de lanzarlo; si falta,
  muestra un `notify-send` indicando el paquete a instalar.

## Instalación

```bash
cd apps/conky_widget
./install.sh                 # symlink en ~/.config/conky + autostart XFCE
conky -c ~/.config/conky/conky_widget/conky.conf &   # arrancar ahora
```

Parar: `pkill -f conky_widget/conky.conf`

## Configuración

- **Monitor**: editar `xinerama_head` en `conky.conf` (`0` = HDMI-0 primario,
  `1` = DP-1).
- **Interfaz de red**: cambiar `NIF` al inicio de `lua/widget.lua`.
- **Botones**: editar la tabla `BTNS` en `lua/widget.lua` (etiqueta, binario a
  comprobar, paquete apt y comando shell).

## Requisitos

- `conky` compilado con Lua bindings + Cairo (verificable con `conky --version`).
- Sesión X11 (en Wayland los clics y `own_window` no funcionan).
- Opcional para los botones: `wireshark`, `ntopng`, `nethogs`. Sin ellos el
  widget funciona igual; los botones avisan de cómo instalarlos.

## Notas

- El botón Wireshark abre `/var/log/pktcap/cap.pcapng` (buffer rotativo de 10
  min) si existe; en caso contrario abre Wireshark en vivo. Ese buffer lo genera
  un servicio `dumpcap` aparte (pendiente de montar).
- El historial del gráfico de red se mantiene en memoria mientras Conky corre;
  al reiniciar el widget se empieza de cero.