system2mqtt/.github/copilot-instructions.md

Copilot / AI Agent Instructions for system2mqtt

Short, actionable guidance so an AI coding agent can be immediately productive.

1. Purpose

• This repo collects host metrics and publishes them to Home Assistant over MQTT.
• Main entry point: system2mqtt console script (defined in setup.py).

2. How to run (development)

• Create a venv and install deps:

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

• Run the service with the provided entry point:

  system2mqtt
  

• Environment override: set SYSTEM2MQTT_CONFIG to point to a config.yaml path.

3. Big-picture architecture

• system2mqtt.main (console entry) loads configuration, connects to MQTT, discovers collector modules under src/system2mqtt/collectors/, and loops to:
  • call each collector's collect_metrics()
  • publish Home Assistant discovery payloads and state/attributes topics
  • publish availability to system2mqtt/{HOSTNAME}/status
• Collectors are pure Python modules (examples: collectors/system_metrics.py, collectors/cpu_temperature.py, collectors/zfs_pools.py). The main program imports them dynamically via collectors.<name> and expects a collect_metrics() function.

4. Collector conventions (exact, follow these)

• Each collector should expose collect_metrics() -> Dict which returns a dict with an entities list.
• Each entity must include at least: sensor_id, name, value, state_class, unit_of_measurement, device_class, and attributes.
• Optional: module-level DEFAULT_INTERVAL can be present (collectors include this today), but note: current main does not use per-collector intervals (see "Notable quirks").
• Example entity (from system_metrics.py):

  {
    "sensor_id": "cpu_usage",
    "name": "CPU Usage",
    "value": "12.3",
    "state_class": "measurement",
    "unit_of_measurement": "%",
    "device_class": "power_factor",
    "attributes": {"friendly_name": "CPU Usage"}
  }
  

5. Configuration and secrets

• Default config path: ~/.config/system2mqtt/config.yaml (created from config.yaml.example on first run).
• SYSTEM2MQTT_CONFIG env var can override the config file location.
• Required config keys under mqtt: host, port, username, password, client_id, discovery_prefix.

6. MQTT topics & discovery (concrete examples)

• Discovery topic format published by main: {discovery_prefix}/sensor/system2mqtt_{HOSTNAME}_{sensor_id}/config
• State topic format: system2mqtt/{HOSTNAME}/{sensor_id}/state
• Attributes topic: system2mqtt/{HOSTNAME}/{sensor_id}/attributes (JSON)
• Availability: system2mqtt/{HOSTNAME}/status with online / offline payloads (retained)

7. Integration points & dependencies

• MQTT client: paho-mqtt (callback handlers in main.py).
• System metrics: psutil used by collectors/system_metrics.py.
• ZFS collectors call zpool binaries via subprocess (requires ZFS tools present on host).

8. Notable quirks & places to be careful

• The README mentions per-collector update intervals, and collector modules define DEFAULT_INTERVAL, but main.py currently uses a fixed time.sleep(60) and does not schedule collectors individually. If changing scheduling, update main.py to read collector DEFAULT_INTERVAL or config collectors.intervals.
• main.py lists collectors from the relative collectors directory using os.listdir('collectors'). For correct imports:
  • Run from package-installed environment (pip install -e .) and call system2mqtt (recommended), or
  • Ensure working directory / PYTHONPATH is set so collectors import works.
• On first run the code copies config.yaml.example to the user config dir and exits — tests or CI should populate a config before invoking system2mqtt.

9. Suggested tasks for AI agents (concrete, small changes)

• Implement per-collector scheduling using DEFAULT_INTERVAL or config['collectors']['intervals'].
• Add unit tests around collector collect_metrics() return schema (validate required keys).
• Improve error handling around dynamic imports (log which path was attempted).

10. Where to look in the code

• Entry point & runtime: src/system2mqtt/main.py
• Collector examples: src/system2mqtt/collectors/*.py (system_metrics.py, cpu_temperature.py, zfs_pools.py)
• Example config: config.yaml.example
• Packaging / console script: setup.py (entry point system2mqtt)

If anything here is unclear or you want the instructions to emphasize other areas (tests, CI, packaging), tell me which part to expand or correct.