# HWInfo TUI
A [gping](https://github.com/orf/gping)-inspired terminal visualization tool for monitoring real-time hardware sensor data from HWInfo.
```bash
# top left pane
hwinfo-tui monitor sensors.CSV "CPU Package Power" "Total System Power" "GPU Power" --time-window 120 --refresh-rate 1
# bottom left pane
hwinfo-tui monitor sensors.CSV "Physical Memory Load" "Total CPU Usage" "GPU D3D Usage" --time-window 120 --refresh-rate 1
# top right pane
hwinfo-tui monitor sensors.CSV "Core Temperatures" "CPU Package" "GPU Temperature" --time-window 120 --refresh-rate 1
# bottom right pane
hwinfo-tui monitor sensors.CSV "Core Thermal Throttling" "Core Critical Temperature" "Package/Ring Thermal Throttling" --time-window 120 --refresh-rate 1
```
## Features
- **Real-time Monitoring**: Live sensor data visualization with configurable refresh rates
- **gping-inspired UI**: Clean interface with statistics table and interactive chart
- **Unit-based Filtering**: Automatically groups sensors by units, supports up to 2 units simultaneously
- **Dual Y-axes**: Charts can display different units on left and right axes
- **Clean Interface**: Focused visualization without unnecessary interactive distractions
- **Responsive Design**: Automatically adapts to terminal size with compact mode
- **Fuzzy Sensor Matching**: Partial sensor name matching with suggestions
- **Rich Statistics**: Min, max, average, and 95th percentile calculations
## Installation
### From Source (Development)
#### Quick Setup (Recommended)
**Windows:**
```bash
git clone https://github.com/hwinfo-tui/hwinfo-tui.git
cd hwinfo-tui
# Command Prompt
setup.bat
# PowerShell
.\setup.ps1
```
**Linux/macOS:**
```bash
git clone https://github.com/hwinfo-tui/hwinfo-tui.git
cd hwinfo-tui
./setup.sh
```
#### Manual Setup
```bash
git clone https://github.com/hwinfo-tui/hwinfo-tui.git
cd hwinfo-tui
# Create and activate virtual environment
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate
# Install in development mode
pip install -e .
```
## Quick Start
1. **Generate HWInfo CSV**: Configure HWInfo to log sensor data to a CSV file
2. **Run HWInfo TUI**: Monitor your desired sensors
```bash
# Basic usage - monitor CPU temperature
hwinfo-tui monitor sensors.csv "CPU Package"
# Monitor multiple temperature sensors
hwinfo-tui monitor sensors.csv "Core Temperatures (avg)" "GPU Temperature" "CPU Package"
# Mixed units - CPU usage and temperature
hwinfo-tui monitor sensors.csv "Total CPU Usage" "Core Temperatures"
# Custom settings
hwinfo-tui monitor sensors.csv "GPU Temperature" --refresh-rate 0.5 --time-window 600
```
## Usage Examples
### Single Unit Monitoring
```bash
# All temperature sensors
hwinfo-tui monitor sensors.csv "Core Temperatures (avg)" "GPU Temperature" "CPU Package"
# All percentage sensors
hwinfo-tui monitor sensors.csv "Total CPU Usage" "GPU Core Load" "GPU Memory Usage"
```
### Dual Unit Monitoring
```bash
# Temperature and percentage
hwinfo-tui monitor sensors.csv "Core Temperatures (avg)" "Total CPU Usage" "GPU Temperature"
# Power and temperature
hwinfo-tui monitor sensors.csv "CPU Package Power" "CPU Package" "GPU Power"
```
### Discover Available Sensors
```bash
# List all sensors in CSV
hwinfo-tui list-sensors sensors.csv
# Filter by unit
hwinfo-tui list-sensors sensors.csv --unit "°C"
# Limit results
hwinfo-tui list-sensors sensors.csv --limit 20
```
## Command Line Reference
### Main Command
```bash
Usage: hwinfo-tui [OPTIONS] COMMAND [ARGS]...
A gping-inspired terminal visualization tool for monitoring real-time
hardware sensor data from HWInfo
+- Options -------------------------------------------------------------------+
| --version Show version information and exit |
| --install-completion Install completion for the current shell. |
| --show-completion Show completion for the current shell, to |
| copy it or customize the installation. |
| --help Show this message and exit. |
+-----------------------------------------------------------------------------+
+- Commands ------------------------------------------------------------------+
| monitor Monitor hardware sensors in real-time |
| list-sensors List all available sensors in the CSV file. |
+-----------------------------------------------------------------------------+
```
### Monitor Command
```bash
Usage: hwinfo-tui monitor [OPTIONS] CSV_FILE SENSOR_NAMES...
Monitor hardware sensors in real-time
+- Arguments -----------------------------------------------------------------+
| * csv_file FILE Path to HWInfo sensors.csv file |
| [default: None] |
| [required] |
| * sensor_names SENSOR_NAMES... One or more sensor names to monitor |
| (supports partial matching) |
| [default: None] |
| [required] |
+-----------------------------------------------------------------------------+
+- Options -------------------------------------------------------------------+
| --refresh-rate -r FLOAT RANGE Update frequency in |
| [0.1<=x<=60.0] seconds (0.1-60.0) |
| [default: 1.0] |
| --time-window -w INTEGER RANGE History window in seconds |
| [10<=x<=7200] (10-7200) |
| [default: 300] |
| --theme -t TEXT Color theme |
| (default/dark/matrix) |
| [default: default] |
| --help Show this message and |
| exit. |
+-----------------------------------------------------------------------------+
```
### List Sensors Command
```bash
Usage: hwinfo-tui list-sensors [OPTIONS] CSV_FILE
List all available sensors in the CSV file.
This command helps you discover sensor names for monitoring.
+- Arguments -----------------------------------------------------------------+
| * csv_file FILE Path to HWInfo sensors.csv file [default: None] |
| [required] |
+-----------------------------------------------------------------------------+
+- Options -------------------------------------------------------------------+
| --unit -u TEXT Filter sensors by unit (e.g., |
| '°C', '%', 'W') |
| [default: None] |
| --limit -l INTEGER RANGE [1<=x<=1000] Maximum number of sensors to |
| display |
| [default: 50] |
| --help Show this message and exit. |
+-----------------------------------------------------------------------------+
```
## HWInfo Setup
1. Download and install [HWInfo64](https://www.hwinfo.com/)
2. Run HWInfo64 and go to **Sensors**
3. Click **File → Start Logging**
4. Choose CSV format and select your desired location
5. Configure logging interval (1-2 seconds recommended)
6. Use the generated CSV file with HWInfo TUI
## Unit Filtering
HWInfo TUI automatically filters sensors based on their units to create clean, readable charts:
- **Single Unit**: All sensors with the same unit (e.g., all temperatures in °C)
- **Dual Units**: Up to 2 different units displayed on separate Y-axes
- **Auto-exclusion**: Sensors with incompatible units are automatically excluded with clear warnings
### Example Unit Filtering
```bash
# This command would exclude the [W] sensor and show a warning
hwinfo-tui monitor sensors.csv "Core Temperatures" "Total CPU Usage" "CPU Power"
# Output: "Excluded sensor 'CPU Power [W]' with unit [W] - chart limited to units [°C] and [%]"
```
## System Requirements
- **Python**: 3.8 or higher
- **Terminal**: Any modern terminal with color support
- **Platform**: Windows, macOS, Linux
- **Dependencies**: typer, rich, plotext, pandas, watchdog
## Performance
- **Memory Usage**: < 50MB baseline, < 100MB with full data retention
- **CPU Overhead**: < 2% of single core during normal operation
- **Startup Time**: < 2 seconds from launch to first display
- **Update Frequency**: Configurable from 0.1 to 60 seconds
## Troubleshooting
### Common Issues
**"No matching sensors found"**
```bash
# Check available sensors first
hwinfo-tui list-sensors sensors.csv
# Use partial names for fuzzy matching
hwinfo-tui monitor sensors.csv "CPU" "GPU"
```
**"Too many units excluded"**
- HWInfo TUI supports maximum 2 different units
- Group sensors by similar units for best results
**"File not found"**
- Ensure HWInfo is actively logging to the CSV file
- Check file path and permissions
**Poor performance**
```bash
# Reduce refresh rate
hwinfo-tui monitor sensors.csv "CPU" --refresh-rate 2.0
# Reduce time window
hwinfo-tui monitor sensors.csv "CPU" --time-window 120
```
### Debug Mode
```bash
# Enable verbose logging
HWINFO_TUI_LOG_LEVEL=DEBUG hwinfo-tui monitor sensors.csv "CPU"
```
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### Development Setup
**Quick Setup:**
```bash
git clone https://github.com/hwinfo-tui/hwinfo-tui.git
cd hwinfo-tui
# Windows
setup.bat
# Linux/macOS
./setup.sh
```
**Manual Setup:**
```bash
python -m venv venv
# Activate venv (see above)
pip install -e ".[dev]"
pytest
```
**Daily Development:**
```bash
# Windows Command Prompt
activate.bat
# Windows PowerShell
.\activate.ps1
# Linux/macOS
source ./activate.sh
# Run tests
pytest
# or: .\test.ps1 (PowerShell with extra features)
# Run the app
hwinfo-tui --help
hwinfo-tui monitor sensors.csv "CPU"
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Acknowledgments
- Inspired by [gping](https://github.com/orf/gping) for the clean TUI design
- Built with [Rich](https://github.com/Textualize/rich) for beautiful terminal output
- Uses [plotext](https://github.com/piccolomo/plotext) for ASCII charts
- Powered by [Typer](https://github.com/tiangolo/typer) for the CLI interface
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
Raw data
{
"_id": null,
"home_page": null,
"name": "hwinfo-tui",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "hardware, monitoring, tui, sensors, hwinfo, visualization",
"author": "JuanjoFuchs",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/80/b3/c1727297f09e2629a309ce8c59707bc43156737397ba297e74755e4b7c59/hwinfo_tui-1.0.1.tar.gz",
"platform": null,
"description": "# HWInfo TUI\n\nA [gping](https://github.com/orf/gping)-inspired terminal visualization tool for monitoring real-time hardware sensor data from HWInfo.\n\n\n\n```bash\n# top left pane\nhwinfo-tui monitor sensors.CSV \"CPU Package Power\" \"Total System Power\" \"GPU Power\" --time-window 120 --refresh-rate 1\n\n# bottom left pane\nhwinfo-tui monitor sensors.CSV \"Physical Memory Load\" \"Total CPU Usage\" \"GPU D3D Usage\" --time-window 120 --refresh-rate 1\n\n# top right pane\nhwinfo-tui monitor sensors.CSV \"Core Temperatures\" \"CPU Package\" \"GPU Temperature\" --time-window 120 --refresh-rate 1\n\n# bottom right pane\nhwinfo-tui monitor sensors.CSV \"Core Thermal Throttling\" \"Core Critical Temperature\" \"Package/Ring Thermal Throttling\" --time-window 120 --refresh-rate 1\n```\n\n## Features\n\n- **Real-time Monitoring**: Live sensor data visualization with configurable refresh rates\n- **gping-inspired UI**: Clean interface with statistics table and interactive chart\n- **Unit-based Filtering**: Automatically groups sensors by units, supports up to 2 units simultaneously\n- **Dual Y-axes**: Charts can display different units on left and right axes\n- **Clean Interface**: Focused visualization without unnecessary interactive distractions\n- **Responsive Design**: Automatically adapts to terminal size with compact mode\n- **Fuzzy Sensor Matching**: Partial sensor name matching with suggestions\n- **Rich Statistics**: Min, max, average, and 95th percentile calculations\n\n## Installation\n\n### From Source (Development)\n\n#### Quick Setup (Recommended)\n\n**Windows:**\n\n```bash\ngit clone https://github.com/hwinfo-tui/hwinfo-tui.git\ncd hwinfo-tui\n\n# Command Prompt\nsetup.bat\n\n# PowerShell\n.\\setup.ps1\n```\n\n**Linux/macOS:**\n\n```bash\ngit clone https://github.com/hwinfo-tui/hwinfo-tui.git\ncd hwinfo-tui\n./setup.sh\n```\n\n#### Manual Setup\n\n```bash\ngit clone https://github.com/hwinfo-tui/hwinfo-tui.git\ncd hwinfo-tui\n\n# Create and activate virtual environment\npython -m venv venv\n\n# Windows\nvenv\\Scripts\\activate\n# Linux/macOS \nsource venv/bin/activate\n\n# Install in development mode\npip install -e .\n```\n\n## Quick Start\n\n1. **Generate HWInfo CSV**: Configure HWInfo to log sensor data to a CSV file\n2. **Run HWInfo TUI**: Monitor your desired sensors\n\n```bash\n# Basic usage - monitor CPU temperature\nhwinfo-tui monitor sensors.csv \"CPU Package\"\n\n# Monitor multiple temperature sensors\nhwinfo-tui monitor sensors.csv \"Core Temperatures (avg)\" \"GPU Temperature\" \"CPU Package\"\n\n# Mixed units - CPU usage and temperature\nhwinfo-tui monitor sensors.csv \"Total CPU Usage\" \"Core Temperatures\"\n\n# Custom settings\nhwinfo-tui monitor sensors.csv \"GPU Temperature\" --refresh-rate 0.5 --time-window 600\n```\n\n## Usage Examples\n\n### Single Unit Monitoring\n\n```bash\n# All temperature sensors\nhwinfo-tui monitor sensors.csv \"Core Temperatures (avg)\" \"GPU Temperature\" \"CPU Package\"\n\n# All percentage sensors\nhwinfo-tui monitor sensors.csv \"Total CPU Usage\" \"GPU Core Load\" \"GPU Memory Usage\"\n```\n\n### Dual Unit Monitoring\n\n```bash\n# Temperature and percentage\nhwinfo-tui monitor sensors.csv \"Core Temperatures (avg)\" \"Total CPU Usage\" \"GPU Temperature\"\n\n# Power and temperature\nhwinfo-tui monitor sensors.csv \"CPU Package Power\" \"CPU Package\" \"GPU Power\"\n```\n\n### Discover Available Sensors\n\n```bash\n# List all sensors in CSV\nhwinfo-tui list-sensors sensors.csv\n\n# Filter by unit\nhwinfo-tui list-sensors sensors.csv --unit \"\u00b0C\"\n\n# Limit results\nhwinfo-tui list-sensors sensors.csv --limit 20\n```\n\n## Command Line Reference\n\n### Main Command\n\n```bash\n Usage: hwinfo-tui [OPTIONS] COMMAND [ARGS]...\n\n A gping-inspired terminal visualization tool for monitoring real-time\n hardware sensor data from HWInfo\n\n+- Options -------------------------------------------------------------------+\n| --version Show version information and exit |\n| --install-completion Install completion for the current shell. |\n| --show-completion Show completion for the current shell, to |\n| copy it or customize the installation. |\n| --help Show this message and exit. |\n+-----------------------------------------------------------------------------+\n+- Commands ------------------------------------------------------------------+\n| monitor Monitor hardware sensors in real-time |\n| list-sensors List all available sensors in the CSV file. |\n+-----------------------------------------------------------------------------+\n```\n\n### Monitor Command\n\n```bash\n Usage: hwinfo-tui monitor [OPTIONS] CSV_FILE SENSOR_NAMES...\n\n Monitor hardware sensors in real-time\n\n+- Arguments -----------------------------------------------------------------+\n| * csv_file FILE Path to HWInfo sensors.csv file |\n| [default: None] |\n| [required] |\n| * sensor_names SENSOR_NAMES... One or more sensor names to monitor |\n| (supports partial matching) |\n| [default: None] |\n| [required] |\n+-----------------------------------------------------------------------------+\n+- Options -------------------------------------------------------------------+\n| --refresh-rate -r FLOAT RANGE Update frequency in |\n| [0.1<=x<=60.0] seconds (0.1-60.0) |\n| [default: 1.0] |\n| --time-window -w INTEGER RANGE History window in seconds |\n| [10<=x<=7200] (10-7200) |\n| [default: 300] |\n| --theme -t TEXT Color theme |\n| (default/dark/matrix) |\n| [default: default] |\n| --help Show this message and |\n| exit. |\n+-----------------------------------------------------------------------------+\n```\n\n### List Sensors Command\n\n```bash\n Usage: hwinfo-tui list-sensors [OPTIONS] CSV_FILE\n\n List all available sensors in the CSV file.\n\n This command helps you discover sensor names for monitoring.\n\n+- Arguments -----------------------------------------------------------------+\n| * csv_file FILE Path to HWInfo sensors.csv file [default: None] |\n| [required] |\n+-----------------------------------------------------------------------------+\n+- Options -------------------------------------------------------------------+\n| --unit -u TEXT Filter sensors by unit (e.g., |\n| '\u00b0C', '%', 'W') |\n| [default: None] |\n| --limit -l INTEGER RANGE [1<=x<=1000] Maximum number of sensors to |\n| display |\n| [default: 50] |\n| --help Show this message and exit. |\n+-----------------------------------------------------------------------------+\n```\n\n\n## HWInfo Setup\n\n1. Download and install [HWInfo64](https://www.hwinfo.com/)\n2. Run HWInfo64 and go to **Sensors**\n3. Click **File \u2192 Start Logging**\n4. Choose CSV format and select your desired location\n5. Configure logging interval (1-2 seconds recommended)\n6. Use the generated CSV file with HWInfo TUI\n\n## Unit Filtering\n\nHWInfo TUI automatically filters sensors based on their units to create clean, readable charts:\n\n- **Single Unit**: All sensors with the same unit (e.g., all temperatures in \u00b0C)\n- **Dual Units**: Up to 2 different units displayed on separate Y-axes\n- **Auto-exclusion**: Sensors with incompatible units are automatically excluded with clear warnings\n\n### Example Unit Filtering\n\n```bash\n# This command would exclude the [W] sensor and show a warning\nhwinfo-tui monitor sensors.csv \"Core Temperatures\" \"Total CPU Usage\" \"CPU Power\"\n# Output: \"Excluded sensor 'CPU Power [W]' with unit [W] - chart limited to units [\u00b0C] and [%]\"\n```\n\n## System Requirements\n\n- **Python**: 3.8 or higher\n- **Terminal**: Any modern terminal with color support\n- **Platform**: Windows, macOS, Linux\n- **Dependencies**: typer, rich, plotext, pandas, watchdog\n\n## Performance\n\n- **Memory Usage**: < 50MB baseline, < 100MB with full data retention\n- **CPU Overhead**: < 2% of single core during normal operation\n- **Startup Time**: < 2 seconds from launch to first display\n- **Update Frequency**: Configurable from 0.1 to 60 seconds\n\n## Troubleshooting\n\n### Common Issues\n\n**\"No matching sensors found\"**\n\n```bash\n# Check available sensors first\nhwinfo-tui list-sensors sensors.csv\n# Use partial names for fuzzy matching\nhwinfo-tui monitor sensors.csv \"CPU\" \"GPU\"\n```\n\n**\"Too many units excluded\"**\n\n- HWInfo TUI supports maximum 2 different units\n- Group sensors by similar units for best results\n\n**\"File not found\"**\n\n- Ensure HWInfo is actively logging to the CSV file\n- Check file path and permissions\n\n**Poor performance**\n\n```bash\n# Reduce refresh rate\nhwinfo-tui monitor sensors.csv \"CPU\" --refresh-rate 2.0\n# Reduce time window\nhwinfo-tui monitor sensors.csv \"CPU\" --time-window 120\n```\n\n### Debug Mode\n\n```bash\n# Enable verbose logging\nHWINFO_TUI_LOG_LEVEL=DEBUG hwinfo-tui monitor sensors.csv \"CPU\"\n```\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n**Quick Setup:**\n\n```bash\ngit clone https://github.com/hwinfo-tui/hwinfo-tui.git\ncd hwinfo-tui\n\n# Windows\nsetup.bat\n\n# Linux/macOS\n./setup.sh\n```\n\n**Manual Setup:**\n\n```bash\npython -m venv venv\n# Activate venv (see above)\npip install -e \".[dev]\"\npytest\n```\n\n**Daily Development:**\n\n```bash\n# Windows Command Prompt\nactivate.bat\n\n# Windows PowerShell\n.\\activate.ps1\n\n# Linux/macOS \nsource ./activate.sh\n\n# Run tests\npytest\n# or: .\\test.ps1 (PowerShell with extra features)\n\n# Run the app\nhwinfo-tui --help\nhwinfo-tui monitor sensors.csv \"CPU\"\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by [gping](https://github.com/orf/gping) for the clean TUI design\n- Built with [Rich](https://github.com/Textualize/rich) for beautiful terminal output\n- Uses [plotext](https://github.com/piccolomo/plotext) for ASCII charts\n- Powered by [Typer](https://github.com/tiangolo/typer) for the CLI interface\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and updates.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A gping-inspired terminal visualization tool for monitoring real-time hardware sensor data from HWInfo",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/JuanjoFuchs/hwinfo-tui",
"Issues": "https://github.com/JuanjoFuchs/hwinfo-tui/issues",
"Repository": "https://github.com/JuanjoFuchs/hwinfo-tui.git"
},
"split_keywords": [
"hardware",
" monitoring",
" tui",
" sensors",
" hwinfo",
" visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b37f4cc365e8bcf5db9b283125568c13e69977f6f2e55bb287a7e62fd4f049c1",
"md5": "4c0547066fa4df6e8df67f18bccdc033",
"sha256": "ff2bc8cb3774a5bdd31a27a187e2cc4fa09d44b7055f58e2309336daace0bf53"
},
"downloads": -1,
"filename": "hwinfo_tui-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c0547066fa4df6e8df67f18bccdc033",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 38362,
"upload_time": "2025-08-15T20:21:45",
"upload_time_iso_8601": "2025-08-15T20:21:45.198867Z",
"url": "https://files.pythonhosted.org/packages/b3/7f/4cc365e8bcf5db9b283125568c13e69977f6f2e55bb287a7e62fd4f049c1/hwinfo_tui-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "80b3c1727297f09e2629a309ce8c59707bc43156737397ba297e74755e4b7c59",
"md5": "fd004151254ae1a659c7e3d6b4db61df",
"sha256": "354f895ce571d207e41b214d7edfd8999f9db60f7a1d0cb7c40b60df08993a9d"
},
"downloads": -1,
"filename": "hwinfo_tui-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "fd004151254ae1a659c7e3d6b4db61df",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 40442,
"upload_time": "2025-08-15T20:21:46",
"upload_time_iso_8601": "2025-08-15T20:21:46.566228Z",
"url": "https://files.pythonhosted.org/packages/80/b3/c1727297f09e2629a309ce8c59707bc43156737397ba297e74755e4b7c59/hwinfo_tui-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 20:21:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JuanjoFuchs",
"github_project": "hwinfo-tui",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hwinfo-tui"
}
JSON
