First commit
This commit is contained in:
174
README.md
Normal file
174
README.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# system2mqtt
|
||||
|
||||
A system for monitoring hosts by collecting metrics and sending them to Home Assistant via MQTT.
|
||||
|
||||
## Features
|
||||
|
||||
- Modular structure for metric collectors
|
||||
- Easy extensibility through new collectors
|
||||
- Automatic discovery in Home Assistant
|
||||
- Encrypted MQTT communication
|
||||
- Detailed device information in Home Assistant
|
||||
- Individual update intervals per collector
|
||||
|
||||
## Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/yourusername/system2mqtt.git
|
||||
cd system2mqtt
|
||||
```
|
||||
|
||||
2. Install Python dependencies:
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
3. Configure the system:
|
||||
```yaml
|
||||
mqtt:
|
||||
host: "mqtt.example.com" # MQTT Broker Address
|
||||
port: 1883 # MQTT Port
|
||||
username: "your_username"
|
||||
password: "your_password"
|
||||
client_id: "system2mqtt"
|
||||
discovery_prefix: "homeassistant" # Home Assistant Discovery Prefix
|
||||
|
||||
collectors:
|
||||
# Default interval for all collectors (in seconds)
|
||||
default_interval: 60
|
||||
|
||||
# Specific intervals for individual collectors
|
||||
intervals:
|
||||
zfs_pools: 300 # ZFS Pools every 5 minutes
|
||||
cpu_temperature: 30 # CPU Temperature every 30 seconds
|
||||
system_metrics: 60 # System Metrics every minute
|
||||
```
|
||||
|
||||
## Configuration via environment variables
|
||||
|
||||
You can override configuration values using environment variables.
|
||||
|
||||
Precedence: **defaults (code) < config file (YAML) < environment variables (ENV)**.
|
||||
|
||||
Recognized environment variables include:
|
||||
|
||||
- `SYSTEM2MQTT_CONFIG` — path to a YAML config file (overrides default lookup)
|
||||
- `MQTT_HOST` — MQTT server host (default: `localhost`)
|
||||
- `MQTT_PORT` — MQTT server port (default: `1883`)
|
||||
- `MQTT_USERNAME`, `MQTT_PASSWORD` — MQTT credentials
|
||||
- `MQTT_CLIENT_ID` — MQTT client id template (supports `{hostname}`)
|
||||
- `MQTT_DISCOVERY_PREFIX` — Home Assistant discovery prefix (default: `homeassistant`)
|
||||
- `COLLECTORS_DEFAULT_INTERVAL` — override global collectors default interval
|
||||
- `COLLECTOR_<NAME>_INTERVAL` — override per-collector interval (e.g. `COLLECTOR_system_metrics_INTERVAL=30`)
|
||||
|
||||
## Usage
|
||||
|
||||
Run the system directly or as a systemd service (see [SYSTEMD_SETUP.md](SYSTEMD_SETUP.md)):
|
||||
|
||||
```bash
|
||||
# Direct execution
|
||||
python3 system2mqtt.py
|
||||
|
||||
# Or use the run script
|
||||
./run.sh
|
||||
```
|
||||
|
||||
## Collectors
|
||||
|
||||
### System Metrics
|
||||
|
||||
Collects basic system metrics:
|
||||
- Last Boot Time
|
||||
- Load Average (1, 5, 15 minutes)
|
||||
- Memory Usage (Total, Available, Used)
|
||||
- Swap Usage (Total, Available, Used)
|
||||
- CPU Usage
|
||||
- Memory Usage
|
||||
- Swap Usage
|
||||
|
||||
Default Update Interval: 60 seconds
|
||||
|
||||
### CPU Temperature
|
||||
|
||||
Collects CPU temperature data:
|
||||
- Supports Linux and FreeBSD
|
||||
- Automatic OS detection
|
||||
- Correct unit (°C) and device class (temperature)
|
||||
|
||||
Default Update Interval: 30 seconds
|
||||
|
||||
### ZFS Pools
|
||||
|
||||
Collects information about ZFS pools:
|
||||
- Pool Health
|
||||
- Total Size
|
||||
- Used Space
|
||||
- Free Space
|
||||
- Usage Percentage
|
||||
- Additional Attributes (readonly, dedup, altroot)
|
||||
|
||||
Default Update Interval: 300 seconds (5 minutes)
|
||||
|
||||
## Update Intervals
|
||||
|
||||
Each collector has a predefined default update interval that can be overridden in the configuration file:
|
||||
|
||||
1. Default intervals are defined in the collector files
|
||||
2. These intervals can be customized per collector in `config.yaml`
|
||||
3. If no specific interval is defined in the configuration, the collector's default interval is used
|
||||
4. If no default interval is defined in the collector, the global `default_interval` from the configuration is used
|
||||
|
||||
## Data Format
|
||||
|
||||
The data exchange format is versioned and follows Home Assistant specifications. Each collector returns a JSON object with the following structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"entities": [
|
||||
{
|
||||
"sensor_id": "unique_sensor_id",
|
||||
"name": "Sensor Name",
|
||||
"value": "sensor_value",
|
||||
"state_class": "measurement",
|
||||
"unit_of_measurement": "unit",
|
||||
"device_class": "device_class",
|
||||
"icon": "mdi:icon",
|
||||
"attributes": {
|
||||
"friendly_name": "Friendly Name",
|
||||
"additional_attributes": "values"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Fields
|
||||
|
||||
- `sensor_id`: Unique ID for the sensor (used for MQTT topics)
|
||||
- `name`: Display name of the sensor
|
||||
- `value`: Current value of the sensor
|
||||
- `state_class`: Type of measurement (measurement, total, total_increasing)
|
||||
- `unit_of_measurement`: Unit of measurement
|
||||
- `device_class`: Type of sensor (temperature, humidity, pressure, etc.)
|
||||
- `icon`: Material Design Icon name (mdi:...)
|
||||
- `entity_category`: Category of the sensor (diagnostic, config, system)
|
||||
- `attributes`: Additional information as key-value pairs
|
||||
|
||||
### Versioning
|
||||
|
||||
The format is versioned to allow for future extensions. The current version is 1.0.
|
||||
|
||||
## Home Assistant Integration
|
||||
|
||||
The system uses Home Assistant's MQTT Discovery feature. Sensors are automatically detected and appear in Home Assistant with:
|
||||
- Correct name and icon
|
||||
- Current values
|
||||
- Historical data
|
||||
- Detailed device information
|
||||
|
||||
## License
|
||||
|
||||
MIT License
|
||||
Reference in New Issue
Block a user