josevi/arch-configs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

plasmoides KDE Store/GitHub (gnome-pager, kMenu, kvitals, windowtitle, claude, launchpad)

Browse Source
This commit is contained in:
Josevi
2026-07-08 20:47:59 +02:00
parent ca606377ee
commit dd3b0f6ae8
136 changed files with 20239 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dot_local/share/plasma/plasmoids/org.kde.plasma.kvitals/docs/architecture.md
+133
View File
@@ -0,0 +1,133 @@
# Architecture
KVitals is a KDE Plasma 6 widget (plasmoid) with a modular architecture connecting native **KSysGuard sensors** to a **QML UI** through dedicated sensor components.
## Data Flow
![KVitals Data Flow](dataflow.svg)
## Sensor Modules (`contents/ui/sensors/`)
Each system metric has its own QML component under `sensors/`. These components encapsulate all sensor subscriptions, data parsing, and value formatting for their metric.
| Module | Sensors | Exposed Properties |
|---|---|---|
| `CpuSensors.qml` | `cpu/all/usage` | `cpuValue` |
| `MemorySensors.qml` | `memory/physical/used`, `total` | `ramValue` |
| `TempSensors.qml` | `cpu/all/averageTemperature` | `tempValue` |
| `GpuSensors.qml` | `gpu/all/usage`, `totalVram`, `usedVram`, `temperature` | `gpuValue`, `gpuRamValue`, `gpuTempValue`, `gpuDisplayValue`, `hasGpuData` |
| `BatterySensors.qml` | `power/<device>/chargePercentage`, `chargeRate` | `batValue`, `powerValue` |
| `NetworkSensors.qml` | `network/<iface>/download`, `upload` | `netDownValue`, `netUpValue` |
A shared `Utils.qml` singleton provides formatting helpers (`formatBytes`, `formatRate`) and sensor-reading utilities (`sensorValueOrNaN`, `firstReadyNumber`, `maxReadyNumber`, `firstReadyVramPair`).
### Performance Benefits
1. **Zero Subprocesses**: No `bash`, `awk`, or `cat` commands are spawned.
2. **Stable File Descriptors**: No CLI pipes need to be kept open, eliminating Plasma 6 Wayland FD-exhaustion crashes.
3. **Low Latency**: The widget reads the exact same backend API as the official KDE System Monitor.
## Orchestrator (`main.qml`)
`main.qml` acts as a lightweight orchestrator:
1. **Reads configuration** from `Plasmoid.configuration`
2. **Instantiates sensor modules** with the configured `updateInterval`
3. **Builds metrics models** using the `orderedKeys` array (derived from the `metricOrder` config)
4. **Applies view-specific visibility rules** such as `compactShow*` settings and compact grouping
5. **Passes models** to `CompactView` and `FullView` for rendering
```
main.qml
├── CpuSensors { id: cpu }
├── MemorySensors { id: memory }
├── TempSensors { id: temp }
├── GpuSensors { id: gpu }
├── BatterySensors { id: battery }
├── NetworkSensors { id: network }
├── compactRepresentation: CompactView { metricsModel: ... }
└── fullRepresentation: FullView { metricsModel: ... }
```
## Views
### CompactView (Panel)
A `RowLayout` with a `Repeater` that renders each compact-visible metric as:
- **Icon** (optional, via `Kirigami.Icon` with `isMask: true`)
- **Label** (optional, e.g., "CPU:")
- **Value** (always shown, e.g., "26%")
- **Separator** (`|` between metrics)
Visibility of icons/labels is controlled by the `displayMode` property. Metric inclusion is controlled by both the metric-level `show*` settings and the compact-panel `compactShow*` settings, allowing a metric to remain visible in the popup/tooltip while being hidden from the panel.
The compact panel also supports horizontal and vertical delegates through the `layoutType` setting.
!!! tip
Icons use `isMask: true` to render as monochrome, matching the panel's text color regardless of the icon theme.
### FullView (Popup)
A `ColumnLayout` with a `Repeater` showing a detailed row per enabled metric with label and bold value, displayed when clicking the widget.
### Tooltip
Multi-line text showing all enabled metrics, displayed on hover. Compact-panel visibility settings do not filter the tooltip.
## Configuration System
```
config/main.xml ← Config schema (entry names, types, defaults)
config/config.qml ← Tab registration (General, Metrics, Icons, Colors)
ui/configGeneral.qml ← General tab (display mode, layout, font, interval)
ui/configMetrics.qml ← Metrics tab (show/hide toggles, compact panel visibility, metric order, grouping, network interface, battery device)
ui/configIcons.qml ← Icons tab (per-metric icon picker)
ui/configColors.qml ← Colors tab (font color, warning/critical colors, thresholds)
```
All config values are accessed in `main.qml` via `Plasmoid.configuration.<key>`.
!!! tip "Adding a New Sensor"
1. Create `contents/ui/sensors/NewSensor.qml` exposing formatted value properties
2. Register it in `sensors/qmldir`
3. Instantiate it in `main.qml`
4. Add it to the `orderedKeys` loop in compact/full/tooltip builders
5. Add `show*` and `compactShow*` config entries in `main.xml`
6. Add the metric and compact panel checkboxes in `configMetrics.qml`
## Project Structure
```
kvitals/
├── metadata.json # Plasmoid metadata (name, version, id)
├── install.sh # Local install script
├── install-remote.sh # Remote install (curl/wget)
├── CHANGELOG.md # Version history
├── docs/ # Documentation
│ ├── installation.md
│ ├── configuration.md
│ ├── architecture.md
│ ├── contributing.md
│ └── troubleshooting.md
└── contents/
├── config/
│ ├── config.qml # Tab registration
│ └── main.xml # Config schema
└── ui/
├── main.qml # Widget orchestrator
├── CompactView.qml # Panel representation
├── FullView.qml # Popup representation
├── configGeneral.qml # General settings tab
├── configMetrics.qml # Metrics settings tab
├── configIcons.qml # Icons settings tab
├── configColors.qml # Colors settings tab
└── sensors/ # Sensor modules
├── qmldir # QML module definition
├── CpuSensors.qml # CPU usage
├── MemorySensors.qml # RAM usage
├── TempSensors.qml # CPU temperature
├── GpuSensors.qml # GPU usage, VRAM, temp
├── BatterySensors.qml # Battery & power
├── NetworkSensors.qml # Network speed
└── Utils.qml # Shared formatting helpers
```
dot_local/share/plasma/plasmoids/org.kde.plasma.kvitals/docs/changelog.md
+250
View File
@@ -0,0 +1,250 @@
# Changelog
All notable changes to KVitals will be documented in this file.
## [2.10.1] - 2026-06-29
### Fixed
- **Plasmashell Boot Crashes**: Resolved a critical race condition that caused `plasmashell` to enter a crash loop during system boot. Sensor module loading is now deferred until after window attachment is fully complete, preventing the `KirigamiPlasmaStyle` SIGSEGV (#49).
## [2.10.0] - 2026-06-27
### Added
- **Fan Speed Monitoring** (`Metrics` settings): A new standalone "Fan" metric that dynamically discovers and reports fan speeds (including GPU and CPU fans) directly from the system (#47).
- Automatically identifies fans through `SensorTreeModel`.
- Supports RPM and Percentage display units (configurable in `General` settings).
- Fully integrates with compact panel, full popup, and tooltip views.
- Safely handles fans that do not report a maximum RPM by omitting them from percentage-based aggregations to prevent misleading data.
- **Display Mode 'None'** (`General` settings): A new display mode that completely hides the metric labels and icons, showing only the raw values to save space (#47).
- **Config UI Redesign** (`Metrics` settings): The metrics configuration page has been overhauled for better UX, with inline contextual settings (e.g. CPU, GPU, Network options expand directly under their respective metrics) and debounced sensor discovery to eliminate UI freezes on load (#48).
## [2.9.0] - 2026-06-19
### Added
- **Per-GPU Sub-metric Visibility** (`Metrics` settings — GPU Selection): Each GPU entry now has independent **Usage**, **VRAM**, and **Temperature** toggles, letting you show only the metrics you care about without disabling the GPU entirely (#44).
- Toggling a sub-metric off immediately stops polling those sensors — no unnecessary kernel data fetched.
- A **minimum-one** guard prevents all three sub-metrics from being deselected at once (the last checked box is disabled), keeping at least one value visible per GPU.
- Sub-metric checkboxes are automatically disabled when the parent GPU is deselected, matching visual state to functional reality.
- Storage format uses a compact pipe-separated string (`gpu0:usage,vram|gpu1:usage,temp`). GPUs using all defaults are omitted, keeping the config short. Empty string (default) = all three enabled for every GPU — fully backwards-compatible with existing configs.
## [2.8.1] - 2026-05-23
### Fixed
- **Installation via KDE Store leaving stale widget state** (`install-remote.sh`): Users who first installed via the KDE Store (or an older `install-remote.sh`) and then upgraded manually could end up with a mismatched `kpackage/generic/` registration. This caused settings like **Show in compact panel** to silently not apply, because KDE resolves widget configuration from the kpackage path, not the plasmoids path. The remote install script now mirrors the local `install.sh` behaviour exactly: it removes any previous entry under `~/.local/share/kpackage/generic/<id>` (including stale symlinks), creates the install directory under `~/.local/share/plasma/plasmoids/`, and creates a fresh symlink at the kpackage path pointing to it.
## [2.8.0] - 2026-05-22
### Added
- **Disk I/O & Temperature** (`Metrics` settings — Disk I/O & Temp): New metric showing real-time disk read/write rates and the highest drive temperature across all NVMe and SATA drives. Displayed as `DSK: ↓2.1MB ↑76KB · 42°C` in the compact panel (#36).
- Drive temperatures are discovered dynamically via `SensorTreeModel` + `lmsensors` (supports `nvme-pci-*` and `drivetemp-scsi-*` chips) — zero polling overhead when the metric is disabled.
- Dedicated **Disk Temp** threshold sliders added to the Colors settings page (default: warning 45°C, critical 60°C).
- **Unit Preferences** (`General` settings — Unit Preferences section): Choose display units globally across all metrics (#37).
- **Temperature**: Celsius (°C, default) or Fahrenheit (°F). Applies to CPU temp, GPU temp, and Disk temp everywhere — panel, popup, and tooltip.
- **Network / Disk I/O**: Bytes (KB/MB, default) or Bits (Kb/Mb). Applies to Network and Disk I/O rates. Suffix convention follows industry standard: uppercase `B` = bytes, lowercase `b` = bits.
- Threshold slider labels in the Colors settings page update live to reflect the chosen temperature unit (stored values remain in °C for correct sensor comparison).
## [2.7.0] - 2026-05-15
### Added
- **Multi-GPU Support** (`Metrics` settings — GPU Selection): On systems with more than one GPU, each GPU is now listed individually as a separate metric in both the compact panel and the full popup view (#22). Works automatically — no configuration needed on single-GPU machines.
- Each GPU is detected dynamically via `SensorTreeModel` metadata; no persistent subscriptions run during discovery.
- The GPU Selection section in settings shows all discovered GPUs with independent enable/disable checkboxes.
- **GPU Custom Labels** (`Metrics` settings — GPU Selection): On multi-GPU systems, each GPU entry in the panel shows a customizable label. Type a name in the **Label** field (e.g. `iGPU`, `dGPU`) to override the default `GPU 1` / `GPU 2` identifiers. Leave it empty to keep the default numbering.
- **Hybrid GPU power hint**: When two or more GPUs are detected, a contextual note appears in the GPU Selection section explaining that unchecking the discrete GPU prevents KVitals from polling it, allowing it to suspend when idle.
### Fixed
- **Unintended dGPU Wakeup** on hybrid GPU laptops (Intel/AMD + NVIDIA setups using `supergfxctl` / `asusctl`): The previous implementation used permanent `Sensors.Sensor` subscriptions for up to 6 hardcoded GPU slots. These subscriptions polled every GPU continuously, preventing the dGPU from entering its suspended/power-save state even when it was idle (#26).
- **New architecture**: Discovery uses `SensorTreeModel` + `KDescendantsProxyModel` (pure metadata query, no value subscriptions). Data polling uses a single `SensorDataModel` constrained strictly to the GPUs the user has selected.
- **Result**: Deselecting a GPU in settings stops all polling for that GPU immediately. On hybrid setups, unchecking the dGPU allows it to fully suspend.
- **Note**: If the dGPU remains active even after unchecking it in KVitals, the cause is likely unrelated — some Xwayland applications keep the GPU awake independently of any sensor polling. This is a system/compositor-level behavior outside the scope of KVitals.
## [2.6.0] - 2026-05-10
### Added
- **Compact Panel Visibility** (`Metrics` settings): Each metric now has an independent "Show in compact panel" toggle, allowing metrics to appear in the full popup view but stay hidden from the panel bar (#29, thanks @keiishu). Disabling a metric preserves its compact visibility state for when it is re-enabled.
- **CPU Frequency** (`Metrics` settings): Display the average CPU frequency in the widget. Auto-formats as GHz (≥ 1000 MHz) or MHz (#33).
- **Merge into CPU** (compact view): Appends frequency as a second segment next to CPU usage (`CPU: 34% · 3.20 GHz`). Compatible with Merge CPU & Temp — all three values appear as segments.
- **Full view sub-item**: When enabled, CPU Frequency appears as a dedicated row directly under CPU Usage in the popup.
- **Bold Font** (`General` settings): Toggle bold styling for all metric value labels across compact and full views (#30). Defaults to off.
### Fixed
- Inconsistent font weight across metrics in vertical layout: RAM and Network values (rendered via `SegmentsRow`) were always bold while CPU/GPU were not. All value labels now follow the new Bold Font setting uniformly.
## [2.5.0] - 2026-04-30
### Added
- **Layout Type** (`General` settings): Choose between **Horizontal** (default, unchanged) and **Vertical** layout for the compact panel view. In vertical mode, the metric value is displayed on top with the label/icon dimmed below — ideal for tall panels or icon-only display (#11).
- **Metric Grouping** (`Metrics` settings — Grouping section):
- **Merge CPU & Temp**: Combines CPU temperature as a second value next to CPU usage (`CPU: 45% · 62°C`), using the same segment display as GPU. The CPU Temperature entry is hidden from the metric order list while merged.
- **Merge Battery & Power**: Combines power consumption as a second value next to battery level (`BAT: 87% · 12.4W`). Power Consumption entry is hidden from the metric order list while merged.
- **Split GPU Metrics**: Optionally break GPU usage, VRAM and temperature into separate panel entries instead of the default grouped display (default: grouped).
### Changed
- Metric order list now hides absorbed metrics when grouping is active (e.g. "CPU Temperature" disappears when "Merge CPU & Temp" is enabled), keeping the list clean and non-redundant.
- `CompactView` refactored to use a `Loader`-based delegate system, enabling runtime layout switching without widget reload.
### Fixed
- `Unable to assign [undefined] to QColor` runtime error when CPU+Temp or Battery+Power merge was enabled — missing top-level `color` field on segmented metric objects.
- Defensive `|| baseTextColor` fallback added to all value label color bindings in `CompactView`.
## [2.4.0] - 2026-04-01
### Added
- **Custom Font Color**: Override the widget font color to match your panel theme (#20). Configurable via the new **Colors** settings tab.
- **Threshold-Based Coloring**: Metric values dynamically change color when they exceed configurable warning/critical thresholds (#12). Supported metrics:
- CPU usage (default: warning 70%, critical 90%)
- CPU temperature (default: warning 60°C, critical 85°C)
- RAM usage (default: warning 70%, critical 90%)
- GPU usage (default: warning 70%, critical 90%)
- GPU temperature (default: warning 60°C, critical 85°C)
- Battery level (inverted: warning below 30%, critical below 15%)
- **Colors Config Tab**: New settings page with color pickers for font/warning/critical colors and per-metric threshold sliders.
- Sensor modules now expose raw numeric values (`cpuNumericValue`, `tempNumericValue`, `ramPercentage`, `batNumericValue`) for threshold comparison.
- `Utils.resolveColor()` function for flexible threshold-triggered color resolution.
### Fixed
- Fixed the Colors tab color picker turning white after selecting a color; it now uses a stable native platform color dialog and preserves the selected swatch correctly.
### Notes
- Network and Power metrics are excluded from threshold coloring (no meaningful universal threshold).
- Both features are **opt-in** — disabled by default. Existing users are unaffected.
## [2.3.0] - 2026-03-13
### Changed
- **Sensor Module Architecture**: Extracted all sensor logic from `main.qml` into dedicated QML components under `contents/ui/sensors/`:
- `CpuSensors.qml` — CPU usage monitoring
- `MemorySensors.qml` — RAM usage monitoring
- `TempSensors.qml` — CPU temperature monitoring
- `GpuSensors.qml` — GPU usage, VRAM, and temperature monitoring
- `BatterySensors.qml` — Battery and power monitoring with auto-detection
- `NetworkSensors.qml` — Network download/upload speed monitoring
- `Utils.qml` — Shared formatting helpers (byte formatting, rate formatting)
- **View Separation**: Extracted compact and full representations into `CompactView.qml` and `FullView.qml`.
- **Reduced `main.qml`**: From ~700 lines to ~140 lines — now acts purely as an orchestrator.
### Notes
- No user-facing or configuration changes. The widget behaves identically to v2.2.1.
- This refactor improves maintainability and makes it easier to add new sensor types in the future.
## [2.2.1] - 2026-03-07
### Fixed
- **Battery Detection Hotfix**: Replaced `SensorTreeModel` with a crash-free **Two-Stage Hybrid Detection** system (#14):
- **Stage 1 (Silent Probe)**: Silently probes common battery paths (`BAT0`, `BAT1`, `BATT`, etc.) for instant detection without running any subprocesses.
- **Stage 2 (Fallback)**: If no standard battery is found, falls back to a single `qdbus` query to list all sensors, completely avoiding `PlasmaCore.DataSource` file descriptor leaks. Includes a manual config fallback if `qdbus` is unavailable.
## [2.2.0] - 2026-03-05
### Added
- **Custom Metric Order**: Added a new configuration option to arrange metrics (CPU, RAM, GPU, etc.) individually in whatever order you prefer (#7).
- **Dynamic Battery Detection**: Replaced hardcoded `BAT0`/`BAT1` sensors with dynamic `SensorTreeModel` discovery. The widget will now automatically find any battery your system has (BAT0, BATT, CMB0, macsmc-battery, etc.) (#14).
## [2.1.1] - 2026-03-03
### Fixed
- Fixed a "Detected anchors on an item that is managed by a layout" QML warning spanning the journal log caused by a `MouseArea` anchoring inside a `RowLayout` (#13).
## [2.1.0] - 2026-03-01
### Added
- **GPU Metrics Support**: Added VRAM usage and GPU temperature monitoring to the widget.
- GPU data is retrieved natively using KDE KSysGuard sensors (`org.kde.ksysguard.sensors`).
## [2.0.0] - 2026-02-27
### Changed
- **Major Architecture Overhaul**: Replaced the previous `sys-stats.sh` backend with native KDE KSysGuard sensors (`org.kde.ksysguard.sensors`).
- Completely eliminates "file descriptor leak" crashes (Issue #8) and improves overall performance by relying directly on the `ksystemstats` D-Bus daemon instead of constantly spawning bash processes.
- Automatic fallback for battery monitoring (BAT0 and BAT1) logic implemented directly in QML.
## [1.4.1] - 2026-02-24
### Fixed
- RAM usage showing empty on non-English locales — `free` translates its `Mem:` header based on locale, causing the parser to match nothing
- Switched RAM data source from `free -b` to `/proc/meminfo` (locale-independent, faster, more accurate)
## [1.4.0] - 2026-02-22
### Added
- **Display mode setting** — choose between Text, Icons, or Icons + Text for the panel
- **Custom icon picker** — select icons from your installed theme for each metric (via KDE's native icon picker)
- **Icon size slider** — adjust icon size (8–24px) when using icon mode
- **Font customization** — choose any system font and font size for the panel text
- **Settings tabs** — split configuration into General, Metrics, and Icons tabs
- **Reset to defaults** button on the Icons tab
- **CHANGELOG.md** — version history
- **Documentation** — MkDocs site with installation, configuration, architecture, contributing, and troubleshooting guides
## [1.3.0] - 2026-02-16
### Added
- Power consumption tracking (via `/sys/class/power_supply/`) — contributed by [@Pijuli](https://github.com/Pijuli)
### Fixed
- ShellCheck warnings from power consumption PR (SC2034, SC2155)
## [1.2.1] - 2026-02-16
### Fixed
- AMD CPU temperature detection — added `k10temp`, `zenpower`, `zenergy`, `amdgpu` to thermal_zone and hwmon detection
- lm-sensors fallback now matches AMD `Tccd1` label
- Reordered temperature fallback tiers to prioritize CPU-specific sources over generic thermal zones
## [1.2.0] - 2026-02-13
### Added
- Auto-detect network interface via `ip route` with manual override in settings
- Network interface selector in widget configuration
### Fixed
- ShellCheck warnings (SC2010, SC2155)
## [1.1.0] - 2026-02-12
### Changed
- Modularized `sys-stats.sh` into functions
- Enhanced CPU temperature detection with 4-tier fallback (thermal_zone → hwmon → lm-sensors → generic)
## [1.0.0] - 2026-02-12
### Added
- Initial release
- CPU usage (delta-based from `/proc/stat`)
- RAM usage (from `/proc/meminfo`)
- CPU temperature (multi-source detection)
- Battery status with emoji indicators
- Network speed (delta-based from `/proc/net/dev`)
- Configurable update interval
- Toggle visibility per metric
dot_local/share/plasma/plasmoids/org.kde.plasma.kvitals/docs/configuration.md
+156
View File
@@ -0,0 +1,156 @@
# Configuration
Right-click the widget → **Configure KVitals...** to open the settings dialog. Settings are organized into four tabs.
## General Tab
| Setting | Description | Default |
|---------------------|--------------------------------------------------------------------------------|--------------------|
| **Display mode** | How metrics are shown in the panel | Text |
| **Layout** | Compact panel layout direction | Horizontal |
| **Icon size** | Icon dimensions in pixels (only visible when using icons) | 12 px |
| **Font** | Font family for all panel text (searchable dropdown of system fonts, editable) | monospace |
| **Font size** | Text size in pixels. `0` uses the system default | 0 (system default) |
| **Update interval** | How often stats are refreshed | 2.0 seconds |
### Display Modes
| Mode | Description |
|------------------|---------------------------------------------------------------|
| **Text** | Labels + values: `CPU: 26% \| RAM: 8.8/39.0G` |
| **Icons** | Icons + values only: `🖥 26% \| 🧠 8.8/39.0G` |
| **Icons + Text** | Icons + labels + values: `🖥 CPU: 26% \| 🧠 RAM: 8.8/39.0G` |
!!! tip "Saving Panel Space"
**Icons** mode is the most compact — great for small panels or when you have many metrics enabled.
### Layout Types
| Layout | Description |
|----------------|--------------------------------------------------------------|
| **Horizontal** | Shows each compact metric in a single row, separated by `\|` |
| **Vertical** | Stacks the value above the icon |
## Metrics Tab
| Setting | Description | Default |
|---------------------------|-----------------------------------------------------------------------------------|--------------------------------------|
| **Metric Order** | Use the up/down buttons to rearrange metrics in the panel | CPU, RAM, Temp, GPU, Bat, Power, Net |
| **Metric enable toggles** | Enables or disables each metric | On |
| **Show in compact panel** | Controls whether each enabled metric appears in the panel representation | On |
| **Network interface** | Select network interface (`auto` or manual) | auto |
| **Battery device** | Leave empty for automatic battery detection, or enter a sensor device id manually | auto |
### Supported Metrics
| Metric | Compact Label | Description |
|-----------------------|---------------|-----------------------------------------------------|
| **CPU Usage** | `CPU:` | CPU utilization percentage |
| **RAM Usage** | `RAM:` | Used/total memory |
| **CPU Temperature** | `TEMP:` | CPU temperature in °C |
| **GPU Metrics** | `GPU:` / `<name>:` | GPU usage %, VRAM used/total, and GPU temperature. On multi-GPU systems, each selected GPU appears as a separate labeled entry. |
| **Battery Status** | `BAT:` | Battery percentage |
| **Power Consumption** | `PWR:` | Power draw in watts |
| **Network Speed** | `NET:` | Download/upload speeds |
### Compact Panel Visibility
Each metric has two visibility controls:
| Control | Effect |
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| **Metric checkbox** | Enables the metric globally. |
| **Show in compact panel** | Hides or shows the metric in the panel widget. The metric remains available in the dropdown menu and tooltip while enabled. |
Use this when you still want to track a metric in the tooltip or dropdown but want to hide it from the panel to save
space.
### Grouping
| Setting | Description | Default |
|---------------------------|-----------------------------------------------------------------------------------------------------------|---------|
| **Merge CPU & Temp** | Shows CPU temperature as a second value next to CPU usage in the widget | Off |
| **Merge Battery & Power** | Shows power consumption as a second value next to battery level in the widget | Off |
| **Split GPU metrics** | Shows GPU usage, VRAM, and GPU temperature as separate compact panel entries instead of one grouped entry | Off |
Merged compact rows only absorb the second metric when both metrics are enabled and selected for the compact panel.
### Network Interface
When set to `auto`, the widget natively aggregates the traffic across all active network connections using KDE's
`network/all` sensor. This handles VPN routing and switching networks automatically.
You can manually select a specific interface (e.g., `wlan0`, `enp3s0`) from the dropdown if you only want to monitor a
single device.
!!! note
The manual interface list is populated dynamically from `/sys/class/net/`.
### GPU Selection
When the **GPU Metrics** metric is enabled, a **GPU Selection** section appears listing every GPU detected on your
system. GPUs are discovered dynamically via the KDE sensor tree — no polling is required during discovery.
| Control | Description |
|------------------|-----------------------------------------------------------------------------------------------|
| **Checkbox** | Enable or disable monitoring for each individual GPU |
| **Label field** | Override the display name for a GPU. Leave empty to use the name reported by ksystemstats. |
**Label resolution order**: custom label → ksystemstats-provided name (e.g. `GPU 1`) → `GPU N` fallback.
!!! tip "Hybrid GPU Laptops (Intel/AMD + NVIDIA)"
On hybrid setups using tools such as `supergfxctl` or `asusctl`, KVitals will only poll the GPUs whose
checkboxes are ticked. **Unchecking the discrete GPU** stops all polling for it, allowing it to enter its
suspended/power-save state when idle.
## Icons Tab
Each metric has its own icon that can be customized:
| Metric | Default Icon | Icon Name |
|-------------|--------------|-----------------------|
| CPU | 🖥 | `cpu` |
| RAM | 🧠 | `memory` |
| Temperature | 🌡 | `temperature-normal` |
| GPU | GPU | `video-card` |
| Battery | 🔋 | `battery-good` |
| Power | ⚡ | `battery-charging-60` |
| Network | 📶 | `network-wireless` |
Click **"Change..."** to open KDE's native icon picker, which lets you browse and search all icons from your installed
icon theme (Breeze, Papirus, Tela, etc.).
Click **"Reset to defaults"** to restore all icons to their default values.
!!! note "Monochrome Rendering"
Icons are rendered with `isMask: true`, meaning they adopt the panel's text color (monochrome). This ensures
visibility on both light and dark panels.
!!! tip "Finding Icons"
The icon picker shows all icons from your installed theme. Use the search bar to find icons by name — try keywords
like "chip", "thermometer", "download", or "lightning".
## Colors Tab
| Setting | Description | Default |
|-------------------------------|--------------------------------------------------------------|-------------------------|
| **Use custom font color** | Overrides the widget text color with a custom color | Off |
| **Color** | Font color as a picked or typed `#RRGGBB` value | Plasma theme text color |
| **Enable threshold coloring** | Changes color of supported metric values based on thresholds | Off |
| **Warning color** | Color used when a warning threshold is reached | `#e5a50a` |
| **Critical color** | Color used when a critical threshold is reached | `#da4453` |
Threshold coloring supports CPU usage, CPU temperature, RAM usage, GPU usage, GPU temperature, and battery level.
| Metric | Default warning color | Default critical color |
|-----------------|-----------------------|------------------------|
| CPU usage | 70% | 90% |
| CPU temperature | 60°C | 85°C |
| RAM usage | 70% | 90% |
| GPU usage | 70% | 90% |
| GPU temperature | 60°C | 85°C |
| Battery level | 30% | 15% |
!!! note "Battery Thresholds"
Battery thresholds are inverted: warning and critical states trigger when the battery level falls _below_ the
configured values.
dot_local/share/plasma/plasmoids/org.kde.plasma.kvitals/docs/contributing.md
+86
View File
@@ -0,0 +1,86 @@
# Contributing
Thanks for your interest in contributing to KVitals!
## Getting Started
1. Fork the repository
2. Clone your fork:
```bash
git clone https://github.com/<your-username>/kvitals.git
cd kvitals
```
3. Install locally for development:
```bash
bash install.sh
```
## Development Workflow
### Making Changes
1. Edit files in the project directory
2. Reinstall and test:
```bash
bash install.sh
kquitapp6 plasmashell && kstart plasmashell &
```
3. Check for QML errors:
```bash
journalctl -b --no-pager | grep kvitals
```
!!! tip "Fast Iteration"
You don't always need to restart plasmashell. For config-only changes, just reopen the settings dialog. For QML changes, a restart is required.
### Adding a New Metric
1. **Sensors** — Find the relevant `org.kde.ksysguard.sensors` sensor ID using `kstatsviewer`
2. **Settings** — Add `show*` and `compactShow*` entries to `contents/config/main.xml`
3. **Configuration UI** — Add the metric and compact visibility checkboxes to `configMetrics.qml`
4. **Icons** — Add an icon picker to `configIcons.qml`
5. **UI** — Add property bindings and model entries in `main.qml`
!!! note
Don't forget to add a default icon name for the new metric in `configIcons.qml`'s reset button handler.
### Adding a New Setting
1. Add the entry to `contents/config/main.xml` with a default value
2. Add the UI control to the appropriate config tab (`configGeneral.qml`, `configMetrics.qml`, `configIcons.qml`, or `configColors.qml`)
3. Bind the value in `main.qml` via `Plasmoid.configuration.<key>`
## Pull Requests
1. Create a feature branch: `git checkout -b feat/my-feature`
2. Make your changes and test locally
3. Ensure ShellCheck passes
4. Push and open a PR against `master`
!!! tip "Commit Messages"
Use conventional commits for clear history:
- `feat:` — New feature
- `fix:` — Bug fix
- `chore:` — Maintenance
- `docs:` — Documentation
## Code Style
- **QML** — Follow KDE's QML conventions, use `Kirigami` components where possible
- **Commits** — Use conventional commits: `feat:`, `fix:`, `chore:`, `docs:`
## Reporting Issues
When filing a bug report, please include:
- KDE Plasma version (`plasmashell --version`)
- Linux distribution and version
- Whether you're using Intel or AMD CPU
- Relevant journal output (`journalctl -b | grep kvitals`)
!!! note "Debugging Output"
To capture detailed logs for a bug report:
```bash
journalctl -b --no-pager | grep -i "kvitals\|sys-state" > kvitals-debug.log
```
dot_local/share/plasma/plasmoids/org.kde.plasma.kvitals/docs/dataflow.svg
+119
View File
File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

dot_local/share/plasma/plasmoids/org.kde.plasma.kvitals/docs/index.md
+30
View File
@@ -0,0 +1,30 @@
# KVitals
A lightweight KDE Plasma 6 panel widget that displays live system vitals directly in your top bar.
```
CPU: 26% | RAM: 8.8/39.0G | TEMP: 96°C | 🔋BAT: 78% | PWR: +20W | NET: ↓82.2K ↑58.9K
```
## Features
- **Live monitoring** — CPU, RAM, temperature, GPU, battery, power, network
- **Display modes** — Text, Icons, or Icons + Text
- **Custom icons** — Pick any icon from your installed KDE theme
- **Font customization** — Choose any system font and size
- **Settings tabs** — General, Metrics, Icons, and Colors
- **Minimal footprint** — Native KSysGuard integration + QML, no heavy dependencies
## Quick Start
```bash
git clone https://github.com/yassine20011/kvitals.git
cd kvitals && bash install.sh
```
Then right-click your panel → **Add Widgets** → search **KVitals**.
## Links
- [GitHub Repository](https://github.com/yassine20011/kvitals)
- [KDE Store](https://www.pling.com/p/2347917/)
dot_local/share/plasma/plasmoids/org.kde.plasma.kvitals/docs/installation.md
+58
View File
@@ -0,0 +1,58 @@
# Installation
## KDE Store (Recommended)
Install directly from the KDE Store:
👉 **[Get KVitals on the KDE Store](https://www.pling.com/p/2347917/)**
Or from within KDE Plasma:
1. Right-click on the panel → **Add Widgets...**
2. Click **Get New Widgets...** → **Download New Plasma Widgets...**
3. Search for **"KVitals"**
4. Click **Install**
## Quick Install (curl)
```bash
curl -fsSL https://github.com/yassine20011/kvitals/releases/latest/download/install-remote.sh | bash
```
## Quick Install (wget)
```bash
wget -qO- https://github.com/yassine20011/kvitals/releases/latest/download/install-remote.sh | bash
```
## Manual Install
```bash
git clone https://github.com/yassine20011/kvitals.git
cd kvitals
bash install.sh
```
Then add the widget:
1. Right-click on the panel → **Add Widgets...**
2. Search for **KVitals**
3. Drag it onto your panel
!!! note "Restart Required"
You may need to restart Plasma for the widget to appear:
```bash
plasmashell --replace &
```
## Requirements
- KDE Plasma 6.0+
## Uninstall
```bash
rm -rf ~/.local/share/plasma/plasmoids/org.kde.plasma.kvitals
plasmashell --replace &
```
!!! warning
This permanently removes the widget and all its configuration. Your settings will not be preserved.
dot_local/share/plasma/plasmoids/org.kde.plasma.kvitals/docs/robots.txt
+39
View File
@@ -0,0 +1,39 @@
# As a condition of accessing this website, the website operator
# explicitly GRANTS permission for the following content signals:
# search: building a search index and providing search results
# ai-input: inputting content into one or more AI models
# ai-train: training or fine-tuning AI models.
# BEGIN Content Signals
User-agent: *
Content-Signal: search=yes,ai-input=yes,ai-train=yes
Allow: /
# END Content Signals
# Explicitly welcoming popular AI scrapers and search bots
User-agent: Amazonbot
Allow: /
User-agent: Applebot-Extended
Allow: /
User-agent: Bytespider
Allow: /
User-agent: CCBot
Allow: /
User-agent: ClaudeBot
Allow: /
User-agent: Google-Extended
Allow: /
User-agent: GPTBot
Allow: /
User-agent: meta-externalagent
Allow: /
Sitemap: https://kvitals.dev/sitemap.xml
dot_local/share/plasma/plasmoids/org.kde.plasma.kvitals/docs/troubleshooting.md
+141
View File
@@ -0,0 +1,141 @@
# Troubleshooting
## Temperature Shows "--"
**Cause:** The widget couldn't find a temperature source on your system.
**Fix:** Check which thermal sources are available:
```bash
# Check thermal zones
cat /sys/class/thermal/thermal_zone*/type 2>/dev/null
# Check hwmon
for d in /sys/class/hwmon/hwmon*/; do
echo "$(cat "$d/name" 2>/dev/null): $d"
done
# Check lm-sensors
sensors 2>/dev/null | head -20
```
!!! tip "AMD Systems"
If you're on AMD, make sure `k10temp` or `zenpower` kernel module is loaded:
```bash
sudo modprobe k10temp
```
To load it automatically on boot, add `k10temp` to `/etc/modules-load.d/k10temp.conf`.
## RAM Shows Empty (versions ≤ 1.4.0)
**Cause:** On versions before 1.4.1, RAM was read by parsing the `free` command, which translates its output headers (e.g. `Mem:`) based on your system locale. Non-English locales caused the parser to match nothing.
**Fix:** Update to KVitals 1.4.1+, which reads directly from `/proc/meminfo` (always English, locale-independent).
## Battery/Power Shows Nothing
**Cause:** No battery detected (e.g., desktop systems without a battery or UPS).
**Behavior in KVitals (v2.2.0+):** The widget uses KDE's native `SensorTreeModel` to dynamically scan your system's hardware tree for any connected battery (including `BAT0`, `BAT1`, `BATT`, `CMB0`, `macsmc-battery`, etc.). If nothing shows up, it means the KDE `ksystemstats` daemon cannot find a battery API on your machine.
!!! note
This is expected behavior on desktop systems. Disable battery and power metrics in **Settings → Metrics** tab to hide the empty entries.
## Network Speed Shows 0
**Cause:** Wrong network interface selected.
**Fix:**
1. Open **Settings → Metrics** and ensure the network interface is set to `auto`.
2. If you want to monitor a specific connection, select it from the dropdown list.
!!! tip
If you use multiple connections (WiFi + Ethernet), set the interface manually to the one you want to monitor.
## GPU Shows Only Usage (or Missing VRAM/Temp)
**Cause:** GPU sensor availability depends on your driver/backend. Some systems expose only usage, while VRAM or temperature sensors are missing or report no data.
**Behavior in KVitals:** The widget now shows only the GPU fields that are available on your system (no placeholder `...` / `--` for unsupported GPU sub-metrics).
**Fix/Debug:** List GPU sensor IDs reported by Plasma KSystemStats:
```bash
qdbus --literal org.kde.ksystemstats1 /org/kde/ksystemstats1 org.kde.ksystemstats1.allSensors \
| rg -o '"gpu/[^"]+"' | tr -d '"' | sort -u
```
Then test a specific sensor value:
```bash
qdbus --literal org.kde.ksystemstats1 /org/kde/ksystemstats1 org.kde.ksystemstats1.sensorData gpu/all/usage
```
!!! tip
On multi-GPU systems, per-GPU sensors such as `gpu/gpu1/*` may exist even when aggregate sensors are partial.
## Metric Shows in Popup But Not Panel
**Cause:** The metric is enabled, but its **Show in compact panel** checkbox is disabled in the Metrics settings.
**Fix:**
1. Open **Settings → Metrics**.
2. Find the metric in the order list.
3. Enable **Show in compact panel** under that metric.
!!! note
Compact grouping also depends on compact visibility. For example, **Merge CPU & Temp** only shows temperature next to CPU when both metrics are enabled and selected for the compact panel.
## Widget Shows "KVitals" or "..."
**Cause:** The KSysGuard daemon hasn't returned sensor data yet.
**Fix:** Wait a few seconds for the data to populate. If it still doesn't, try restarting the `plasma-ksystemstats` service:
```bash
systemctl --user restart plasma-ksystemstats.service
```
## Icons Not Visible on Panel
**Cause:** Icons are rendered with `isMask: true` (monochrome). If your panel background is the same color as the text color, icons may be invisible.
!!! tip
Try switching to a different Plasma theme, or adjust the panel opacity. You can also switch to **Text** display mode if icons aren't working well with your theme.
## Settings Dialog Shows Warnings in Journal
!!! note "Harmless Warnings"
You may see `cfg_*Default` warnings in the journal. These are harmless Plasma 6 KCM warnings about default property injection and **do not affect functionality**.
## Widget Not Appearing After Install
**Fix:**
1. Restart plasmashell:
```bash
kquitapp6 plasmashell && kstart plasmashell &
```
2. If still missing, check the install path:
```bash
ls ~/.local/share/plasma/plasmoids/org.kde.plasma.kvitals/
```
!!! warning
If the directory doesn't exist, the install failed. Re-run `bash install.sh` from the project directory.
## Custom Font Not Applying
**Cause:** The font name might not match exactly.
**Fix:**
1. Check available fonts: `fc-list | grep -i "font-name"`
2. In settings, use the exact family name from the dropdown
3. Font size `0` means "use system default" — set a specific value if needed
!!! tip
The font dropdown is searchable — start typing the font name to filter the list. You can also type a custom font name directly.