system2mqtt/README.md

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:

git clone https://github.com/yourusername/system2mqtt.git
cd system2mqtt

2. Install Python dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Configure the system:

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:

# 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:

{
    "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