Guides d'installation → Agent Sunplug

Agent Sunplug

Un petit programme qui tourne sur votre propre réseau et lit votre matériel directement, toutes les trente secondes. Optionnel — Sunplug fonctionne aussi depuis le cloud de votre fabricant — mais c'est la différence entre suivre le soleil et y réagir longtemps après qu'il a bougé.

Pourquoi s'embêter

Une API cloud ne peut pas être plus fraîche que la fréquence d'envoi de l'onduleur lui-même, et pour la plupart des marques c'est cinq minutes — quinze pour SolarEdge. Un nuage passe, votre surplus est divisé par deux, et l'API cloud vous le dira dans quatre minutes.

L'agent, lui, interroge le matériel. Pas de quota, pas d'abonnement, pas de conditions d'utilisation d'un fabricant, et aucun identifiant de votre matériel ne sort de chez vous.

Ce qu'il gère

Docker

Sur n'importe quoi qui reste allumé et se trouve sur le même réseau que votre onduleur. L'image est publiée pour x86 et ARM, donc un Raspberry Pi ou un NAS fait l'affaire.

docker run -d --name sunplug-agent --network host \
  -v sunplug-agent:/data --restart unless-stopped \
  sunplugapp/sunplug-agent:latest

Puis ouvrez http://<cette machine>:8787 dans n'importe quel navigateur de votre réseau — votre téléphone convient très bien — et suivez la page. Elle cherche votre onduleur, vous montre ce qu'elle a trouvé et vous demande le code à six caractères de l'application. C'est toute l'installation.

Il n'y a pas de seconde commande à lancer. L'agent sert sa propre page de configuration et commence à lire dès qu'il est appairé ; la même adresse affiche ensuite ce qu'il lit. Si vous préférez le terminal, il est toujours là : docker exec -it sunplug-agent sunplug-agent setup.

Deux choses que cette commande règle et qu'un bouton « rechercher et installer » de NAS ne réglera pas. --network host, sans quoi l'agent ne voit pas votre sous-réseau et ne trouve rien. Et un volume sur /data, sans quoi l'appairage est perdu à chaque mise à jour du conteneur.

Compose

Si votre NAS a une fonction Compose ou Projets — Synology, QNAP et UGREEN en ont tous une — c'est la voie la plus simple, et elle règle les deux points ci-dessus pour vous.

services:
  agent:
    image: sunplugapp/sunplug-agent:latest
    network_mode: host
    restart: unless-stopped
    volumes:
      - agent_data:/data
volumes:
  agent_data:

Home Assistant

1. Paramètres → Modules complémentaires → Boutique → ⋮ → Dépôts
2. Ajoutez https://github.com/sunplug/sunplug
3. Installez Sunplug agent et démarrez-le
4. Cliquez sur Ouvrir l'interface web et suivez la page

La page de configuration apparaît comme un panneau dans Home Assistant : rien ne sort de l'interface où vous êtes déjà. Si vous préférez, l'onglet Configuration accepte toujours un code d'appairage et le reste des réponses.

Sans Docker

pip install "git+https://github.com/sunplug/sunplug.git#subdirectory=agent"
sunplug-agent run

Puis ouvrez http://localhost:8787, ou l'adresse de la machine depuis un autre appareil.

Appairage

Il n'y a pas de clé d'API à recopier. Dans l'application, Réglages → Équipement → Ajouter un agent affiche un code à six caractères ; l'agent le demande une fois et reçoit son propre jeton en échange.

Le code est à usage unique et expire au bout de quinze minutes — c'est un ticket, pas un identifiant. Le jeton de chaque machine peut être révoqué séparément depuis les Réglages, qui indiquent aussi la dernière fois que chaque agent s'est manifesté.

Commandes

sunplug-agent discover   lister le matériel sur ce réseau et s'arrêter
sunplug-agent setup      trouver le matériel, s'appairer, enregistrer
sunplug-agent run        interroger et envoyer, indéfiniment

Mettre à jour

Sunplug vous prévient dans l'application quand une nouvelle version de l'agent est disponible : rien ne se met à jour tout seul — un conteneur continue de tourner avec l'image sur laquelle il a démarré, aussi ancienne soit-elle.

Sur un NAS

La plupart des interfaces Docker de NAS cachent cela derrière un « re-pull » plutôt qu'un bouton de mise à jour, d'où l'impression qu'il n'y a pas d'option :

• UGREEN (UGOS) — Docker → Projet → votre projet → ⋯ → Paramètres → Configuration Compose → Redéployer, cochez Récupérer la dernière image, puis Déployer
• Synology — Container Manager → Vue d'ensemble signale les mises à jour disponibles ; pour un projet, Projet → Action → Générer, qui re-télécharge et recrée
• QNAP — Container Station → Images → Pull (sunplugapp/sunplug-agent, tag latest), puis Vue d'ensemble → Modifier l'application → Appliquer sans rien changer ; ce qui a changé est reconstruit
• Asustor — Portainer ou Docker Engine → Images → Pull, puis recréez le conteneur
• TrueNAS SCALE — Apps → l'application → Update, ou modifiez et enregistrez pour re-télécharger une app personnalisée
• Unraid — onglet Docker → Check for Updates → appliquer
• Portainer (tout NAS) — ouvrez le conteneur → Re-pull image → Recreate

Le point commun : presque aucun ne parle de « mise à jour ». Cherchez re-pull, rebuild ou redéployer — tous veulent dire récupérer l'image plus récente et redémarrer le conteneur avec.

Docker ou Compose

docker compose pull && docker compose up -d

Ou, sans Compose :

docker pull sunplugapp/sunplug-agent:latest
docker rm -f sunplug-agent
docker run -d --name sunplug-agent --network host \
  -v sunplug-agent:/data --restart unless-stopped \
  sunplugapp/sunplug-agent:latest

Le volume sur /data est ce qui rend l'opération sans risque : l'appairage y est stocké, donc un conteneur remplacé revient déjà appairé et reprend ses lectures. Rien à reconfigurer.

Home Assistant

Paramètres → Modules complémentaires → Sunplug agent → Mettre à jour, quand une mise à jour est proposée.

Vérifier que ça marche

docker logs -f sunplug-agent

Une ligne toutes les trente secondes, du genre pv=2.62kW grid=-0.31kW load=2.31kW soc=0.47. Sur le tableau de bord, l'indicateur de fraîcheur doit se stabiliser à quelques secondes.

Quand ça ne marche pas

Rien trouvé sur le réseau

En général la machine est sur un segment différent de l'onduleur — le Wi-Fi invité et les VLAN IoT sont les coupables habituels. Sautez la recherche avec sunplug-agent setup --host 192.168.1.50.

Il dit qu'il n'est pas configuré

run refuse de démarrer tant que setup n'a pas été fait, plutôt que de tourner en boucle sur un jeton manquant. Lancez la commande setup ci-dessus.

« L'accès de cet agent a été révoqué »

Quelqu'un l'a supprimé depuis Réglages → Équipement. Appairez-le à nouveau avec un code neuf.

Le tableau de bord affiche encore les données du cloud

Dès qu'un agent alimente Sunplug, celui-ci cesse d'interroger le cloud de votre fabricant — le relevé local est toujours meilleur, et mélanger les deux entrelacerait deux images de la même maison. La page Équipement le signale quand cela se produit.

Ce qui sort de votre réseau

Les relevés de puissance du site, et rien d'autre : production, réseau, consommation de la maison, puissance et niveau de charge de la batterie. Les identifiants de votre onduleur restent sur la machine, et la connexion est sortante uniquement — il n'y a aucun port à ouvrir et rien de chez vous n'est joignable depuis internet.

Si l'agent ne peut pas joindre votre matériel

Certaines installations n'ont aucune API locale — un onduleur qui ne parle qu'à son propre cloud, ou un compteur derrière une passerelle que l'agent ne connaît pas. Personne n'est écarté pour avoir choisi la mauvaise marque : envoyez les relevés vous-même, depuis un script, Node-RED, ou tout ce qui sait faire une requête HTTP. Envoyer vos propres relevés donne le format et un exemple qui marche.

Bloqué ? Écrivez-moi — joignez les logs et je vous dirai ce qu'ils veulent dire.