cpu-loader 0.0.3__tar.gz → 0.1.3__tar.gz

{cpu_loader-0.0.3/src/cpu_loader.egg-info → cpu_loader-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cpu-loader
-Version: 0.0.3
+Version: 0.1.3
 Summary: A tool to generate CPU load on a system with runtime configuration through a WebUI and REST API
 Author-email: the78mole <the78mole@users.noreply.github.com>
 License: MIT
@@ -33,6 +33,7 @@ Requires-Dist: pydantic==2.10.0
 Requires-Dist: requests==2.32.3
 Requires-Dist: psutil>=5.9.0
 Requires-Dist: websockets>=12.0
+Requires-Dist: paho-mqtt>=2.1.0
 Dynamic: license-file
 
 # CPU Loader
@@ -42,7 +43,7 @@ Dynamic: license-file
 [![Python Version](https://img.shields.io/pypi/pyversions/cpu-loader)](https://pypi.org/project/cpu-loader/)
 [![License](https://img.shields.io/github/license/the78mole/cpu-loader)](https://github.com/the78mole/cpu-loader/blob/main/LICENSE)
 
-A high-performance CPU load generator with **per-thread control** through an intuitive WebUI and REST API. Built with a native C extension using pthreads for accurate, nanosecond-precision load generation.
+A tool to generate CPU load on a system with runtime configuration through a WebUI and REST API.
 
 ## ✨ Key Features
 
@@ -53,6 +54,7 @@ A high-performance CPU load generator with **per-thread control** through an int
 - **🚀 REST API**: Complete programmatic control for automation and testing
 - **📱 Responsive Design**: Works seamlessly on desktop and mobile devices
 - **🔄 Instant Updates**: Changes take effect immediately with sub-second response time
+- 📡 **MQTT Integration**: Publish metrics and settings to MQTT broker for IoT/monitoring systems
 
 ## 🖼️ Screenshots
 
@@ -133,6 +135,22 @@ uv run src/main.py
 
 The server will start on `http://localhost:8000`
 
+#### Command-Line Options
+
+```bash
+uv run src/main.py --help
+```
+
+**Available Options:**
+- `--host HOST`: Host to bind the server to (default: 0.0.0.0)
+- `--port PORT`: Port to bind the server to (default: 8000)
+- `--mqtt-broker-host HOST`: MQTT broker hostname
+- `--mqtt-broker-port PORT`: MQTT broker port (default: 1883)
+- `--mqtt-username USER`: MQTT username
+- `--mqtt-password PASS`: MQTT password
+- `--mqtt-topic-prefix PREFIX`: MQTT topic prefix (default: cpu-loader)
+- `--mqtt-client-id ID`: MQTT client ID (default: cpu-loader)
+
 ### WebUI
 
 Open your browser and navigate to `http://localhost:8000`
@@ -188,6 +206,88 @@ curl -X POST http://localhost:8000/api/threads \
 
 Once the server is running, visit `http://localhost:8000/docs` for interactive API documentation powered by Swagger UI.
 
+## MQTT Publishing
+
+CPU Loader can publish real-time CPU metrics and load control settings to an MQTT broker for integration with home automation systems, monitoring tools, or custom applications.
+
+### MQTT Topics
+
+The application publishes to two topics:
+
+1. **`{prefix}/cpu_metrics`**: Published every second with current CPU utilization
+   ```json
+   {
+     "total_cpu_percent": 25.5,
+     "per_cpu_percent": [25.0, 26.0, 25.3, 25.7]
+   }
+   ```
+
+2. **`{prefix}/load_settings`**: Published when load settings change (retained message)
+   ```json
+   {
+     "num_threads": 4,
+     "loads": {"0": 25.0, "1": 25.0, "2": 25.0, "3": 25.0},
+     "average_load": 25.0
+   }
+   ```
+
+### Configuration
+
+MQTT can be configured using environment variables or command-line arguments. Command-line arguments take precedence over environment variables.
+
+#### Using Environment Variables
+
+```bash
+export MQTT_BROKER_HOST=mqtt.example.com
+export MQTT_BROKER_PORT=1883
+export MQTT_USERNAME=myuser
+export MQTT_PASSWORD=mypassword
+export MQTT_TOPIC_PREFIX=cpu-loader
+export MQTT_CLIENT_ID=cpu-loader-001
+
+uv run src/main.py
+```
+
+#### Using Command-Line Arguments
+
+```bash
+uv run src/main.py \
+  --mqtt-broker-host mqtt.example.com \
+  --mqtt-broker-port 1883 \
+  --mqtt-username myuser \
+  --mqtt-password mypassword \
+  --mqtt-topic-prefix cpu-loader \
+  --mqtt-client-id cpu-loader-001
+```
+
+#### Testing with Mosquitto
+
+To test MQTT publishing locally:
+
+```bash
+# Install mosquitto
+sudo apt-get install mosquitto mosquitto-clients
+
+# Start CPU Loader with MQTT
+uv run src/main.py --mqtt-broker-host localhost
+
+# Subscribe to all topics (in another terminal)
+mosquitto_sub -h localhost -t "cpu-loader/#" -v
+```
+
+### MQTT Settings
+
+| Setting | Environment Variable | CLI Argument | Default | Description |
+|---------|---------------------|--------------|---------|-------------|
+| Broker Host | `MQTT_BROKER_HOST` | `--mqtt-broker-host` | None | MQTT broker hostname or IP |
+| Broker Port | `MQTT_BROKER_PORT` | `--mqtt-broker-port` | 1883 | MQTT broker port |
+| Username | `MQTT_USERNAME` | `--mqtt-username` | None | MQTT authentication username |
+| Password | `MQTT_PASSWORD` | `--mqtt-password` | None | MQTT authentication password |
+| Topic Prefix | `MQTT_TOPIC_PREFIX` | `--mqtt-topic-prefix` | cpu-loader | Prefix for all MQTT topics |
+| Client ID | `MQTT_CLIENT_ID` | `--mqtt-client-id` | cpu-loader | MQTT client identifier |
+
+**Note:** If no MQTT broker host is configured, MQTT publishing will be disabled and the application will function normally without it.
+
 ## Example Script
 
 An example script (`src/example.py`) is provided to demonstrate programmatic control:
@@ -212,6 +312,7 @@ The example demonstrates:
 - **src/cpu_loader_core.c**: High-performance C implementation using pthreads for CPU load generation
 - **src/cpu_loader.py**: Python wrapper providing a clean API to the C extension
 - **src/main.py**: FastAPI application with REST API and embedded WebUI
+- **src/mqtt_publisher.py**: MQTT client for publishing metrics and settings
 - **Threading Model**: Native pthreads for maximum efficiency and precise timing
 - **Load Algorithm**: High-resolution busy-wait loops with nanosecond precision
 
@@ -221,6 +322,7 @@ The example demonstrates:
 - FastAPI 0.115.0+
 - Uvicorn 0.32.0+
 - Pydantic 2.10.0+
+- paho-mqtt 2.1.0+ (for MQTT publishing)
 - C compiler (gcc or clang) for building the extension
 
 ## Use Cases
@@ -230,6 +332,8 @@ The example demonstrates:
 - **Thermal Testing**: Check cooling system effectiveness
 - **Power Consumption Analysis**: Measure power usage at different load levels
 - **Benchmarking**: Create reproducible load scenarios
+- **IoT Integration**: Integrate with Home Assistant, Node-RED, or other MQTT-based systems
+- **Monitoring**: Feed CPU metrics into monitoring dashboards via MQTT
 
 ## Development
 

{cpu_loader-0.0.3 → cpu_loader-0.1.3}/README.md

@@ -5,7 +5,7 @@
 [![Python Version](https://img.shields.io/pypi/pyversions/cpu-loader)](https://pypi.org/project/cpu-loader/)
 [![License](https://img.shields.io/github/license/the78mole/cpu-loader)](https://github.com/the78mole/cpu-loader/blob/main/LICENSE)
 
-A high-performance CPU load generator with **per-thread control** through an intuitive WebUI and REST API. Built with a native C extension using pthreads for accurate, nanosecond-precision load generation.
+A tool to generate CPU load on a system with runtime configuration through a WebUI and REST API.
 
 ## ✨ Key Features
 
@@ -16,6 +16,7 @@ A high-performance CPU load generator with **per-thread control** through an int
 - **🚀 REST API**: Complete programmatic control for automation and testing
 - **📱 Responsive Design**: Works seamlessly on desktop and mobile devices
 - **🔄 Instant Updates**: Changes take effect immediately with sub-second response time
+- 📡 **MQTT Integration**: Publish metrics and settings to MQTT broker for IoT/monitoring systems
 
 ## 🖼️ Screenshots
 
@@ -96,6 +97,22 @@ uv run src/main.py
 
 The server will start on `http://localhost:8000`
 
+#### Command-Line Options
+
+```bash
+uv run src/main.py --help
+```
+
+**Available Options:**
+- `--host HOST`: Host to bind the server to (default: 0.0.0.0)
+- `--port PORT`: Port to bind the server to (default: 8000)
+- `--mqtt-broker-host HOST`: MQTT broker hostname
+- `--mqtt-broker-port PORT`: MQTT broker port (default: 1883)
+- `--mqtt-username USER`: MQTT username
+- `--mqtt-password PASS`: MQTT password
+- `--mqtt-topic-prefix PREFIX`: MQTT topic prefix (default: cpu-loader)
+- `--mqtt-client-id ID`: MQTT client ID (default: cpu-loader)
+
 ### WebUI
 
 Open your browser and navigate to `http://localhost:8000`
@@ -151,6 +168,88 @@ curl -X POST http://localhost:8000/api/threads \
 
 Once the server is running, visit `http://localhost:8000/docs` for interactive API documentation powered by Swagger UI.
 
+## MQTT Publishing
+
+CPU Loader can publish real-time CPU metrics and load control settings to an MQTT broker for integration with home automation systems, monitoring tools, or custom applications.
+
+### MQTT Topics
+
+The application publishes to two topics:
+
+1. **`{prefix}/cpu_metrics`**: Published every second with current CPU utilization
+   ```json
+   {
+     "total_cpu_percent": 25.5,
+     "per_cpu_percent": [25.0, 26.0, 25.3, 25.7]
+   }
+   ```
+
+2. **`{prefix}/load_settings`**: Published when load settings change (retained message)
+   ```json
+   {
+     "num_threads": 4,
+     "loads": {"0": 25.0, "1": 25.0, "2": 25.0, "3": 25.0},
+     "average_load": 25.0
+   }
+   ```
+
+### Configuration
+
+MQTT can be configured using environment variables or command-line arguments. Command-line arguments take precedence over environment variables.
+
+#### Using Environment Variables
+
+```bash
+export MQTT_BROKER_HOST=mqtt.example.com
+export MQTT_BROKER_PORT=1883
+export MQTT_USERNAME=myuser
+export MQTT_PASSWORD=mypassword
+export MQTT_TOPIC_PREFIX=cpu-loader
+export MQTT_CLIENT_ID=cpu-loader-001
+
+uv run src/main.py
+```
+
+#### Using Command-Line Arguments
+
+```bash
+uv run src/main.py \
+  --mqtt-broker-host mqtt.example.com \
+  --mqtt-broker-port 1883 \
+  --mqtt-username myuser \
+  --mqtt-password mypassword \
+  --mqtt-topic-prefix cpu-loader \
+  --mqtt-client-id cpu-loader-001
+```
+
+#### Testing with Mosquitto
+
+To test MQTT publishing locally:
+
+```bash
+# Install mosquitto
+sudo apt-get install mosquitto mosquitto-clients
+
+# Start CPU Loader with MQTT
+uv run src/main.py --mqtt-broker-host localhost
+
+# Subscribe to all topics (in another terminal)
+mosquitto_sub -h localhost -t "cpu-loader/#" -v
+```
+
+### MQTT Settings
+
+| Setting | Environment Variable | CLI Argument | Default | Description |
+|---------|---------------------|--------------|---------|-------------|
+| Broker Host | `MQTT_BROKER_HOST` | `--mqtt-broker-host` | None | MQTT broker hostname or IP |
+| Broker Port | `MQTT_BROKER_PORT` | `--mqtt-broker-port` | 1883 | MQTT broker port |
+| Username | `MQTT_USERNAME` | `--mqtt-username` | None | MQTT authentication username |
+| Password | `MQTT_PASSWORD` | `--mqtt-password` | None | MQTT authentication password |
+| Topic Prefix | `MQTT_TOPIC_PREFIX` | `--mqtt-topic-prefix` | cpu-loader | Prefix for all MQTT topics |
+| Client ID | `MQTT_CLIENT_ID` | `--mqtt-client-id` | cpu-loader | MQTT client identifier |
+
+**Note:** If no MQTT broker host is configured, MQTT publishing will be disabled and the application will function normally without it.
+
 ## Example Script
 
 An example script (`src/example.py`) is provided to demonstrate programmatic control:
@@ -175,6 +274,7 @@ The example demonstrates:
 - **src/cpu_loader_core.c**: High-performance C implementation using pthreads for CPU load generation
 - **src/cpu_loader.py**: Python wrapper providing a clean API to the C extension
 - **src/main.py**: FastAPI application with REST API and embedded WebUI
+- **src/mqtt_publisher.py**: MQTT client for publishing metrics and settings
 - **Threading Model**: Native pthreads for maximum efficiency and precise timing
 - **Load Algorithm**: High-resolution busy-wait loops with nanosecond precision
 
@@ -184,6 +284,7 @@ The example demonstrates:
 - FastAPI 0.115.0+
 - Uvicorn 0.32.0+
 - Pydantic 2.10.0+
+- paho-mqtt 2.1.0+ (for MQTT publishing)
 - C compiler (gcc or clang) for building the extension
 
 ## Use Cases
@@ -193,6 +294,8 @@ The example demonstrates:
 - **Thermal Testing**: Check cooling system effectiveness
 - **Power Consumption Analysis**: Measure power usage at different load levels
 - **Benchmarking**: Create reproducible load scenarios
+- **IoT Integration**: Integrate with Home Assistant, Node-RED, or other MQTT-based systems
+- **Monitoring**: Feed CPU metrics into monitoring dashboards via MQTT
 
 ## Development
 

{cpu_loader-0.0.3 → cpu_loader-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cpu-loader"
-version = "0.0.3"
+version = "0.1.3"
 description = "A tool to generate CPU load on a system with runtime configuration through a WebUI and REST API"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -33,10 +33,11 @@ dependencies = [
     "requests==2.32.3",
     "psutil>=5.9.0",
     "websockets>=12.0",
+    "paho-mqtt>=2.1.0",
 ]
 
 [project.scripts]
-cpu-loader = "main:run"
+cpu-loader = "cpu_loader.__main__:run"
 
 [project.urls]
 Homepage = "https://github.com/the78mole/cpu-loader"
@@ -50,4 +51,4 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
 package-dir = {"" = "src"}
-py-modules = ["cpu_loader", "main", "example"]
+packages = ["cpu_loader"]

{cpu_loader-0.0.3 → cpu_loader-0.1.3}/setup.py

@@ -9,8 +9,8 @@ if platform.system() != 'Windows':
     extra_link_args = ['-pthread']
 
 module = Extension(
-    'cpu_loader_core',
-    sources=['src/cpu_loader_core.c'],
+    'cpu_loader.cpu_loader_core',
+    sources=['src/cpu_loader/cpu_loader_core.c'],
     extra_compile_args=extra_compile_args,
     extra_link_args=extra_link_args,
 )

cpu_loader-0.1.3/src/cpu_loader/__init__.py

@@ -0,0 +1,5 @@
+"""CPU Loader - Generate configurable CPU load with WebUI and REST API."""
+
+from .cpu_loader import CPULoader
+
+__all__ = ["CPULoader"]

cpu_loader-0.1.3/src/cpu_loader/__main__.py

@@ -0,0 +1,6 @@
+"""Main entry point for CPU Loader application."""
+
+from cpu_loader.main import run
+
+if __name__ == "__main__":
+    run()

{cpu_loader-0.0.3/src → cpu_loader-0.1.3/src/cpu_loader}/cpu_loader.py

@@ -7,7 +7,7 @@ import multiprocessing
 from typing import Dict
 
 try:
-    import cpu_loader_core
+    from cpu_loader import cpu_loader_core  # type: ignore[attr-defined]
 except ImportError:
     raise ImportError(
         "cpu_loader_core module not found. Please build the C extension with: "