Plugin NUT Free (Jeedom)

IMPORTANT

S’il n’y a pas d’information sur la mise à jour, c’est que celle-ci concerne uniquement de la mise à jour de documentation, de traduction ou de texte.

Auteurs

Merci à SFY qui est à l’origine du plugin NUT Free, repris depuis février 2026 par TiTidom.

Présentation

Ce plugin permet de superviser un onduleur (UPS) via le protocole NUT (Network UPS Tools), en connexion TCP directe ou via SSH (avec le plugin SSH-Manager). Il récupère l’ensemble des variables exposées par le serveur NUT (état, charge batterie, autonomie, tensions d’entrée/sortie, température, puissance nominale, etc.) et les affiche sur le Dashboard de Jeedom.

Deux modes de connexion sont disponibles :

Mode NUT (TCP direct) : communication directe avec le daemon NUT via le réseau. Un démon Python persistant tourne en arrière-plan, avec un polling configurable et une surveillance temps-réel de ups.status (détection de coupure secteur en 2 à 5 secondes).

Mode SSH (via SSH-Manager) : collecte synchrone des données NUT via SSH sur la machine distante hébergeant le serveur NUT. Aucun démon — la fréquence de collecte est définie par une expression cron (minimum 1 minute).

MODE RECOMMANDÉ

Le mode NUT (TCP direct) est le mode préconisé. Il offre une réactivité bien supérieure (détection de coupure en quelques secondes) et une collecte en temps réel. Le mode SSH ne doit être utilisé qu’en solution de repli, lorsque l’accès TCP direct au démon NUT n’est pas possible (réseau restreint, équipement non exposé, etc.). Ses limitations sont décrites en fin de documentation.

Compatibilité

IMPORTANT

La version minimum du core de Jeedom requise pour le plugin est la version 4.4.8 avec un OS Debian 11 minimum.

Versions OS compatibles :

Debian 11, 12, 13

Plateformes compatibles :

Smart, Raspberry Pi, Docker, DIY, Atlas, V4

Demande d’aide sur Community

Pour toute demande d’aide, utilisez le bouton Post Community (icône bleue) disponible directement sur la page de configuration du plugin — il pré-remplit automatiquement votre message avec les informations essentielles.

Merci de fournir systématiquement les informations suivantes :

Une copie d’écran de la page Santé de Jeedom
Une copie d’écran de la page de configuration du plugin (avec notamment la version du plugin, SSH-Manager, Python et PyEnv)
Les logs en mode debug, ajoutés dans votre message avec le bouton “Texte préformaté” (pas de capture d’écran des logs, car elles sont inexploitables)

Configuration du plugin

Après installation du plugin, rendez-vous dans Plugins → Monitoring → NUT Free pour accéder à la liste des équipements.

Dépendances

Le plugin installe automatiquement ses dépendances Python (environnement pyenv + venv, Python 3.12.12, librairies pynutclient et requests) lors de l’installation ou d’une mise à jour si nécessaire. Si l’installation automatique a échoué, rendez-vous sur la page de configuration du plugin, section Dépendances, et cliquez sur Relancer.

NOTE

L’installation des dépendances inclut la compilation de Python via pyenv. La durée varie selon le matériel : quelques minutes sur une VM ou un système récent, jusqu’à 20 à 30 minutes sur des configurations plus modestes (Raspberry Pi, Smart…). Ne pas interrompre le processus.

Les logs d’installation se trouvent dans le fichier Nut_free_update accessible depuis la page de configuration du plugin, ou bien depuis le menu Analyse / Logs de Jeedom.

NOTE

Le plugin SSH-Manager est requis uniquement pour le mode de connexion SSH. Il n’est pas nécessaire pour le mode NUT (TCP direct).

Version du Plugin

A chaque version du plugin qui sort, un numéro est attribué sous la forme “version_majeure.version_mineure.version_patch” (par ex. : “2.2.0”). Vous pouvez retrouver cette information sur la page de configuration du plugin. Pour toute demande sur le Community, merci de préciser dans vos messages ce numéro de version du plugin, ainsi que les versions SSH-Manager, Python et PyEnv affichées sur cette même page.

Options générales

Désactiver les messages de MàJ : permet de désactiver les notifications de mise à jour du plugin dans le centre de messages Jeedom.

Démon (mode NUT — TCP direct uniquement)

NOTE

Toute modification d’un paramètre du démon nécessite un redémarrage du démon pour être prise en compte.

Port Socket Interne : port de communication interne entre PHP et le démon Python. Ne modifier qu’en cas de conflit. (Défaut : 55113)
Intervalle de polling (secondes) : fréquence de collecte complète de toutes les métriques de l’onduleur. (Défaut : 60)
Intervalle du surveillant de statut (secondes) : fréquence de surveillance de ups.status pour détecter une coupure secteur. Se réduit automatiquement à 2 s lorsque l’UPS passe sur batterie. (Défaut : 5)
Fréquence des cycles : facteur multiplicateur des cycles internes du démon. N’affecte pas le polling NUT ni la surveillance de statut. (Défaut : Normal (x1))

SSH (mode SSH uniquement)

Délai Aléatoire (collecte SSH) : délai maximal aléatoire (en secondes) ajouté avant chaque collecte SSH, pour éviter les exécutions simultanées avec d’autres plugins. 0 = désactivé, max = 30. (Défaut : 15)

Options de débogage des dépendances

Ces options sont à utiliser uniquement en cas de problème avec l’installation des dépendances. Après activation, il est nécessaire de relancer l’installation des dépendances.

Force les mises à jour Systèmes : force la mise à jour des paquets système lors de la prochaine installation des dépendances.
Force la réinitialisation de PyEnv : force la réinitialisation complète de l’environnement Python pyenv.
Force la réinitialisation de Venv : force la réinitialisation complète de l’environnement virtuel Python venv.

Installation d’un serveur NUT (Debian/Ubuntu)

Cette section décrit l’installation et la configuration minimale d’un serveur NUT sur Debian 12 (Bookworm), distribution de référence pour Jeedom. Les commandes et fichiers de configuration s’appliquent également à Debian 11/13 et aux distributions dérivées (Ubuntu, Raspberry Pi OS…).

NOTE

Si votre serveur NUT est déjà installé et fonctionnel (NAS Synology, autre distribution…), passez directement à la section Ajout et configuration d’un équipement.

1. Installation des paquets

sudo apt update
sudo apt install nut nut-server

2. Identification de l’onduleur

Utilisez nut-scanner pour détecter automatiquement votre onduleur (USB ou SNMP) :

sudo nut-scanner -U   # Détection USB
sudo nut-scanner -S   # Détection SNMP

Notez le driver et le port détectés — ils seront utilisés dans l’étape suivante.

Pour un onduleur USB, la sortie ressemble à :

[nutdev1]
    driver = "usbhid-ups"
    port = "auto"
    vendorid = "XXXX"
    productid = "XXXX"

3. Configuration du driver (`/etc/nut/ups.conf`)

Éditez le fichier /etc/nut/ups.conf et ajoutez une section pour votre onduleur :

[myups]
    driver = usbhid-ups
    port = auto
    desc = "Mon onduleur"

Remplacez myups par le nom que vous souhaitez donner à l’onduleur (ce nom sera utilisé dans le plugin), et usbhid-ups par le driver détecté à l’étape précédente.

NOTE

Si nut-scanner a retourné un vendorid et un productid, il est recommandé de les ajouter dans la configuration — en particulier si plusieurs périphériques USB sont connectés à la machine. Cela garantit que le bon onduleur est ciblé même si l’ordre des ports USB change au redémarrage :
[myups]
   driver = usbhid-ups
   port = auto
   vendorid = 0764
   productid = 0501
   desc = "Mon onduleur"

4. Mode réseau (`/etc/nut/nut.conf`)

Choisissez le mode selon votre configuration :

Jeedom sur la même machine que le serveur NUT → standalone suffit (upsd écoute uniquement sur localhost) :

MODE=standalone

Jeedom sur une machine différente → netserver est obligatoire (upsd expose le socket réseau selon la configuration de LISTEN dans upsd.conf) :

MODE=netserver

5. Adresse d’écoute (`/etc/nut/upsd.conf`)

Par défaut, upsd n’écoute que sur localhost. Pour le rendre accessible depuis Jeedom (sur une autre machine), ajoutez :

LISTEN 0.0.0.0 3493

Pour restreindre l’accès à une adresse spécifique (recommandé) — remplacez 192.168.1.50 par l’IP de votre machine Jeedom :

LISTEN 127.0.0.1 3493
LISTEN 192.168.1.50 3493

NOTE

Si Jeedom est sur la même machine que le serveur NUT, LISTEN 127.0.0.1 3493 suffit et aucune ouverture de pare-feu n’est nécessaire.

6. Utilisateurs NUT (`/etc/nut/upsd.users`)

La lecture des variables (upsc) ne nécessite pas d’authentification. En revanche, pour utiliser les variables RW (upsrw) ou les commandes instcmd (upscmd), un utilisateur avec les droits appropriés est requis.

Selon les fonctionnalités souhaitées :

Variables RW uniquement (upsrw) — actions = SET :

[nutuser]
    password = motdepasse
    actions = SET

Variables RW + commandes instcmd (upsrw et upscmd) — actions = SET INSTCMD :

[nutuser]
    password = motdepasse
    actions = SET INSTCMD
    instcmds = ALL

Dans cet exemple, nutuser est à renseigner dans le champ Utilisateur NUT et motdepasse dans le champ Mot de passe NUT de l’équipement dans le plugin.

7. Démarrage des services

sudo systemctl enable --now nut-server

Vérifiez que le service est actif :

sudo systemctl status nut-server

8. Test

Vérifiez que l’onduleur est bien détecté et que les variables remontent :

upsc myups@localhost

La commande doit retourner la liste des variables NUT de l’onduleur.

9. Pare-feu

Si Jeedom est sur une machine différente du serveur NUT, ouvrez le port 3493 en TCP sur le serveur NUT pour autoriser la connexion entrante depuis Jeedom :

# UFW
sudo ufw allow 3493/tcp

# iptables
sudo iptables -A INPUT -p tcp --dport 3493 -j ACCEPT

Ajout et configuration d’un équipement

Cliquez sur le bouton Ajouter en haut à gauche pour créer un nouvel équipement.

Saisissez le nom de l’équipement (ex. Onduleur_NAS), puis définissez :

Objet parent
Catégorie (optionnelle)
Activer (à cocher, sinon l’équipement ne sera pas opérationnel)
Visible (optionnel — si vous ne souhaitez pas l’afficher sur le Dashboard)

Protocole de connexion

Sélectionnez le mode de connexion souhaité dans la liste déroulante Protocole de connexion :

NUT (protocole TCP direct) : connexion directe au serveur NUT via le réseau (TCP)
SSH (via SSH-Manager) : collecte via SSH en passant par le plugin SSH-Manager

Mode NUT (TCP direct)

Adresse IP du serveur NUT : adresse IP ou hostname de la machine hébergeant le serveur NUT. Si le serveur NUT est installé sur la même machine que Jeedom, utilisez 127.0.0.1.
Port NUT : port TCP du serveur NUT. (Défaut : 3493)

Synology

Pour un NAS Synology, il faut autoriser l’IP de Jeedom à interroger l’onduleur : Panneau de configuration → Matériel et alimentation → UPS → Périphériques DiskStation autorisés

Mode SSH (via SSH-Manager)

Hôte SSH : sélectionnez un hôte SSH préconfiguré dans le plugin SSH-Manager. Le bouton + permet d’en créer un nouveau directement depuis la page de l’équipement.
Fréquence de polling : expression cron définissant la fréquence de collecte des données. (Défaut : * * * * * — toutes les minutes) Un assistant cron est disponible via le bouton associé.

IMPORTANT

Le mode SSH requiert que le plugin SSH-Manager soit installé et configuré. L’hôte SSH doit disposer d’un compte avec les droits suffisants pour exécuter les commandes upsc, upsrw et upscmd (généralement root).

Identifiants NUT (mode NUT et SSH)

Ces champs sont optionnels. Ils sont utilisés pour l’authentification auprès du daemon upsd (nécessaire uniquement pour les variables RW et les commandes instcmd).

Utilisateur NUT : nom d’utilisateur configuré dans upsd.users. (Laisser vide si non requis)
Mot de passe NUT : mot de passe associé. (Laisser vide si non requis)

Auto-détection de l’UPS

Oui (automatique) (défaut) : le nom de l’onduleur est détecté automatiquement via upsc -l. Fonctionne uniquement si un seul onduleur est présent sur le serveur NUT.
Non (manuel) : saisir manuellement le nom exact de l’onduleur tel qu’il est retourné par upsc -l.

Synchronisation des commandes

Après avoir sauvegardé l’équipement, cliquez sur Synchroniser les Commandes pour créer automatiquement dans Jeedom toutes les commandes supportées par votre onduleur (variables info, variables RW, commandes instcmd).

Le bouton Supprimer Commandes Synchronisées permet de supprimer toutes les commandes dynamiques (en conservant les commandes statiques).

NOTE

Après une synchronisation, il est nécessaire de rafraîchir la page (touche F5) pour que les nouvelles commandes apparaissent dans l’onglet Commandes.

Commandes

Commandes statiques

Ces commandes sont créées automatiquement à la sauvegarde de l’équipement :

logicalId	Nom	Type	Description
`refresh`	Rafraîchir	action	Déclenche une collecte immédiate
`device_mfr`	Fabricant	info string	`device.mfr` — fabricant de l’onduleur
`device_model`	Modèle	info string	`device.model` — modèle de l’onduleur
`ups_serial`	Numéro Série	info string	`ups.serial`
`ups_status`	Code NUT	info string	`ups.status` brut (`OL`, `OB`, `LB`…)
`ups_status_label`	Statut Onduleur	info string	Traduction française de `ups.status`
`ups_load`	Charge Onduleur	info numeric	`ups.load` (%)
`battery_charge`	Charge Batterie	info numeric	`battery.charge` (%)
`battery_runtime`	Autonomie Batterie	info numeric	`battery.runtime` (secondes)
`battery_runtime_min`	Autonomie Batterie (min)	info numeric	Dérivé de `battery_runtime`, converti en minutes
`cmd_result`	Retour Commande	info string	Résultat de la dernière commande RW ou instcmd

Commandes dynamiques

Créées via Synchroniser les Commandes, elles correspondent aux variables et commandes effectivement supportées par votre onduleur :

Variables info (upsc) : tensions, fréquences, températures, puissance, minuteurs d’arrêt…
Variables RW (upsrw) : variables modifiables de l’onduleur (ex. battery.charge.low)
Commandes instcmd (upscmd -l) : actions sur l’onduleur (beeper, test batterie, arrêt/redémarrage…)

INFO

Le plugin embarque une base de 198 variables et 32 commandes instcmd reconnues (mapping NUT avec labels FR, unités et icônes). Les commandes non présentes dans cette base sont également créées, mais sans libellé ni unité prédéfinis.

NOTE

Les commandes disponibles varient selon le modèle d’onduleur et le driver NUT utilisé. Certaines variables peuvent ne pas être exposées par votre serveur NUT même si elles sont communes sur d’autres installations.

Historisation

Pour les commandes de type info numérique, il est possible d’activer l’historisation dans les options de la commande, afin de visualiser les variations sous forme de courbe dans Jeedom.

Templates et affichage

Le plugin fournit un widget personnalisé qui s’applique automatiquement à l’équipement lors de sa création. Ce widget affiche sous forme de tuile les informations essentielles de l’onduleur : statut en temps réel avec code couleur, charge batterie, autonomie restante, et — en mode SSH — l’état de la connexion SSH.

Dans ce mode, l’option Afficher de chaque commande détermine si elle apparaît sur le widget ou non. Les commandes dont l’affichage est désactivé sont ignorées par le widget.

C’est le mode d’affichage recommandé pour le Dashboard.

Template de commandes (`Nut_free::ups`)

Chaque commande info créée par le plugin utilise un template individuel (Nut_free::ups). Lorsque le template widget de l’équipement est désactivé, chaque commande dont l’option Afficher est active s’affiche séparément sur le Dashboard avec ce template.

Par défaut, l’équipement affiche son widget personnalisé sur le Dashboard. Pour afficher à la place les commandes individuellement (et les personnaliser librement) :

Ouvrez l’équipement → Configuration avancée (roue crantée en haut à droite)
Onglet Informations
Décochez la case Template de widget
Sauvegardez

Vous pouvez alors modifier le template de chaque commande individuellement (onglet Affichage → ligne Widget dans le tableau des options) pour utiliser un template standard Jeedom ou un widget tiers.

NOTE

La commande cnx_ssh (Connexion SSH, mode SSH uniquement) est masquée par défaut (Afficher = non) car elle est utilisée en interne par le widget pour afficher l’icône de statut SSH. Il est toutefois possible de l’activer si vous souhaitez l’afficher comme commande individuelle.

Limitations du mode SSH

Le mode SSH est synchrone et cadencé par cron (fréquence minimale : 1 minute). Comparé au mode NUT :

La détection d’une coupure secteur peut prendre jusqu’à la prochaine exécution du cron (jusqu’à 1 minute), contre 2 à 5 secondes en mode NUT.
Il n’y a pas de surveillance temps-réel de ups.status entre deux collectes.
Les alertes et scénarios Jeedom fonctionnent normalement dès la collecte effectuée.
Sur les NAS Synology, les commandes upsrw et upscmd ne sont pas disponibles dans le shell DSM : le mode SSH est donc limité à la lecture seule (upsc uniquement). Les variables RW et les commandes instcmd ne sont pas accessibles via SSH sur Synology — seul le mode NUT (TCP direct) les supporte.

Ce mode est adapté aux installations où le serveur NUT est accessible uniquement via SSH et où une latence d’une minute sur la détection d’état est acceptable.

Utilisation dans un scénario

Les commandes du plugin peuvent être utilisées dans les scénarios Jeedom comme n’importe quelle autre commande.

Exemple : détecter une coupure de courant

Déclencheur par événement — la méthode la plus réactive : déclencher le scénario dès que la commande ups_status change de valeur. Dans l’onglet Déclencheur du scénario, ajoutez un déclencheur de type Événement sur la commande Code NUT.

Condition sur le code NUT — dans le corps du scénario, utilisez la commande Code NUT (ups_status) pour tester l’état. Le code OB (On Battery) indique que l’onduleur fonctionne sur batterie (coupure secteur), OL (On Line) indique le retour du secteur. Les codes peuvent être combinés : par exemple OB LB signifie batterie faible en cours de décharge.

NOTE

En mode NUT (TCP direct), la surveillance de ups.status s’effectue toutes les 5 secondes (configurable) — le scénario est déclenché très rapidement après la coupure. En mode SSH, la détection dépend de la fréquence de polling cron (1 minute par défaut).

FAQ

Quelle est la fréquence de rafraîchissement des informations ?

Mode NUT : le démon Python interroge l’onduleur toutes les 60 secondes (configurable) pour la collecte complète, et surveille ups.status toutes les 5 secondes (configurable) pour la détection de coupure.
Mode SSH : la collecte s’effectue selon l’expression cron définie sur l’équipement. Par défaut, toutes les 1 minute.

Quelle est la différence entre le mode NUT et le mode SSH ?

Le mode NUT utilise un démon Python persistant qui maintient une connexion TCP directe avec le serveur NUT. Il offre une détection quasi temps-réel des changements d’état (2 à 5 s). Le mode SSH exécute des commandes NUT via SSH à chaque tick cron, sans daemon — la latence est donc d’au moins 1 minute.

Faut-il renseigner le champ “Nom de l’UPS” ?

Seulement si plusieurs onduleurs sont connectés au même serveur NUT, ou si l’auto-détection échoue. Dans ce cas, renseignez le nom exact retourné par la commande upsc -l sur le serveur NUT.

Certaines valeurs ne remontent pas comparé à d’autres installations.

Il est probable que votre modèle d’onduleur ne supporte pas ces variables. Les données disponibles dépendent du modèle d’onduleur et du driver NUT utilisé. Utilisez Synchroniser les Commandes pour créer uniquement les commandes effectivement supportées par votre onduleur.

Après une mise à jour, de nouvelles commandes n’apparaissent pas.

Il faut éditer l’équipement et re-sauvegarder pour régénérer les commandes statiques, puis cliquer sur Synchroniser les Commandes pour les commandes dynamiques.

Mon onduleur est connecté à un NAS Synology. Comment le configurer ?

Mode NUT (TCP direct) : autorisez l’IP de votre Jeedom dans le panneau de configuration Synology : Matériel et alimentation → UPS → Périphériques DiskStation autorisés. Saisissez ensuite l’IP du NAS dans le champ “Adresse IP du serveur NUT”.

Mode SSH : configurez un hôte SSH dans SSH-Manager avec les identifiants root (mot de passe = mot de passe du compte admin Synology). Autorisez également 127.0.0.1 dans les périphériques DiskStation autorisés. Attention : les commandes upsrw et upscmd ne sont pas disponibles sur Synology DSM — le mode SSH est limité à la lecture des variables (upsc). Pour les variables RW et les commandes instcmd, utilisez le mode NUT (TCP direct).