160 lines
4.0 KiB
Markdown
160 lines
4.0 KiB
Markdown
# 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
|
|
```
|
|
|
|
## Usage
|
|
|
|
The system is controlled via the `run.sh` script:
|
|
|
|
```bash
|
|
# Start the system
|
|
./run.sh start
|
|
|
|
# Stop the system
|
|
./run.sh stop
|
|
|
|
# Clean up MQTT topics
|
|
./run.sh cleanup
|
|
```
|
|
|
|
## 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 |