270 lines
8.9 KiB
Markdown
270 lines
8.9 KiB
Markdown
# EnoceanCLI
|
|
|
|
Outil en ligne de commande pour lire et écrire les configurations EnOcean sur les automates **Distech Controls Eclypse Gen 1** via leur API REST.
|
|
|
|
## Ce que fait cet outil
|
|
|
|
- **Read** : Se connecte à chaque automate listé dans un CSV, récupère la configuration EnOcean (DeviceId, DeviceType de chaque capteur), et génère un fichier CSV de sortie.
|
|
- **Write** : Prend un CSV contenant les DeviceId souhaités et les applique sur chaque automate. **Seul le DeviceId est modifié** — toute la configuration existante sur l'automate (Points, MaxReceiveTime, Description, etc.) est préservée.
|
|
|
|
---
|
|
|
|
## Prérequis
|
|
|
|
- **Windows 10 ou 11** (PowerShell 5.1 est inclus par défaut, rien à installer)
|
|
- Un accès réseau aux automates Eclypse (HTTP ou HTTPS)
|
|
- Les identifiants de connexion aux automates (par défaut : `admin` / mot de passe vide)
|
|
|
|
### Vérifier que PowerShell est disponible
|
|
|
|
Ouvrir un terminal (touche `Windows` + `R`, taper `powershell`, puis `Entrée`) et taper :
|
|
|
|
```powershell
|
|
$PSVersionTable.PSVersion
|
|
```
|
|
|
|
Le numéro `Major` doit être **5 ou plus**.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
Aucune installation requise. Télécharger ou cloner le dossier du projet :
|
|
|
|
```
|
|
gfxEnocean/
|
|
├── EnoceanCLI.ps1 <- Script principal
|
|
├── modules/ <- Modules (ne pas modifier)
|
|
│ ├── Logger.psm1
|
|
│ ├── CsvHandler.psm1
|
|
│ ├── ApiClient.psm1
|
|
│ ├── XmlParser.psm1
|
|
│ └── ZipBuilder.psm1
|
|
└── README.md
|
|
```
|
|
|
|
---
|
|
|
|
## Utilisation
|
|
|
|
### Ouvrir PowerShell dans le bon dossier
|
|
|
|
1. Ouvrir l'explorateur de fichiers et naviguer dans le dossier `gfxEnocean`
|
|
2. Cliquer dans la barre d'adresse, taper `powershell`, puis appuyer sur `Entrée`
|
|
|
|
Ou bien dans un terminal PowerShell :
|
|
|
|
```powershell
|
|
cd "C:\chemin\vers\gfxEnocean"
|
|
```
|
|
|
|
### Politique d'exécution
|
|
|
|
Si c'est la première fois, PowerShell peut bloquer l'exécution des scripts. Autoriser pour la session en cours :
|
|
|
|
```powershell
|
|
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
|
|
```
|
|
|
|
Cette commande est sans risque : elle n'autorise les scripts que pour la fenêtre PowerShell en cours.
|
|
|
|
---
|
|
|
|
### Action Read — Lire la configuration des automates
|
|
|
|
```powershell
|
|
.\EnoceanCLI.ps1 -Action Read -CsvInput ".\mon_fichier.csv"
|
|
```
|
|
|
|
Avec un mot de passe :
|
|
|
|
```powershell
|
|
.\EnoceanCLI.ps1 -Action Read -CsvInput ".\mon_fichier.csv" -Password "MonMotDePasse"
|
|
```
|
|
|
|
**Résultat** : Un fichier `enocean_YYYY-MM-DD_HHhMM.csv` est créé dans le dossier courant avec les DeviceId et DeviceType de chaque capteur EnOcean.
|
|
|
|
---
|
|
|
|
### Action Write — Écrire les DeviceId sur les automates
|
|
|
|
```powershell
|
|
.\EnoceanCLI.ps1 -Action Write -CsvInput ".\enocean_2026-03-03_23h07.csv" -Password "MonMotDePasse"
|
|
```
|
|
|
|
**Ce qui se passe** :
|
|
1. Le script se connecte à chaque automate
|
|
2. Il récupère la configuration EnOcean existante (XML complet avec Points, etc.)
|
|
3. Il remplace **uniquement le DeviceId** par la valeur du CSV
|
|
4. Il renvoie la configuration modifiée à l'automate
|
|
|
|
**Ce qui est préservé** : Points, MaxReceiveTime, Description, Name, ResourceNumber, DeviceType — tout sauf le DeviceId.
|
|
|
|
---
|
|
|
|
### Aide intégrée
|
|
|
|
```powershell
|
|
Get-Help .\EnoceanCLI.ps1 -Detailed
|
|
```
|
|
|
|
---
|
|
|
|
## Format du CSV d'entrée
|
|
|
|
Le fichier CSV utilise le **point-virgule** (`;`) comme séparateur.
|
|
|
|
### Colonnes obligatoires
|
|
|
|
| Colonne | Description |
|
|
|---------|-------------|
|
|
| `Hostname` | Nom de l'automate |
|
|
| `Current Ip` | Adresse IP de l'automate |
|
|
| `HttpPort` | Port HTTP (`80` ou `-1` si désactivé) |
|
|
| `HttpsPort` | Port HTTPS (`443` ou `-1` si désactivé) |
|
|
|
|
### Colonnes optionnelles
|
|
|
|
| Colonne | Description |
|
|
|---------|-------------|
|
|
| `RestServiceURL` | Chemin API (défaut : `/api/rest/v1/`) |
|
|
| `Username` | Login spécifique à cet automate |
|
|
| `Password` | Mot de passe spécifique à cet automate |
|
|
|
|
### Colonnes pour l'action Write
|
|
|
|
| Colonne | Description |
|
|
|---------|-------------|
|
|
| `DeviceId_1` | DeviceId à écrire sur le 1er capteur EnOcean |
|
|
| `DeviceType_1` | DeviceType du 1er capteur (pour vérification) |
|
|
| `DeviceId_2` | DeviceId à écrire sur le 2e capteur |
|
|
| `DeviceType_2` | DeviceType du 2e capteur |
|
|
| ... | Autant de paires que de capteurs |
|
|
|
|
### Exemple de CSV
|
|
|
|
```csv
|
|
"Hostname";"Current Ip";"HttpPort";"HttpsPort";"RestServiceURL";"DeviceId_1";"DeviceType_1";"DeviceId_2";"DeviceType_2"
|
|
"MON-AUTOMATE-01";"192.168.1.11";"-1";"443";"/api/rest/v1/";"99864513";"A50401";"65313272";"A5100C"
|
|
"MON-AUTOMATE-02";"192.168.1.12";"80";"-1";"/api/rest/v1/";"45678912";"A53001";"";""
|
|
```
|
|
|
|
**Note** : Les colonnes DeviceId/DeviceType vides sont ignorées — le capteur correspondant n'est pas modifié.
|
|
|
|
---
|
|
|
|
## Workflow typique
|
|
|
|
### 1. Préparer le CSV d'entrée
|
|
|
|
Partir d'un export existant (XNU Export, inventaire réseau...) contenant au minimum les colonnes `Hostname`, `Current Ip`, `HttpPort`, `HttpsPort`.
|
|
|
|
### 2. Lire la configuration actuelle
|
|
|
|
```powershell
|
|
.\EnoceanCLI.ps1 -Action Read -CsvInput ".\automates.csv" -Password "MonMotDePasse"
|
|
```
|
|
|
|
Cela génère un CSV avec les DeviceId actuels de chaque automate.
|
|
|
|
### 3. Modifier les DeviceId dans le CSV
|
|
|
|
Ouvrir le CSV généré dans Excel ou un éditeur de texte. Modifier les colonnes `DeviceId_1`, `DeviceId_2`, etc. avec les nouvelles valeurs.
|
|
|
|
**Attention** : Ne pas modifier les colonnes `DeviceType_N`. Elles servent uniquement de référence. Si le DeviceType du CSV diffère de celui de l'automate, un avertissement sera affiché dans les logs.
|
|
|
|
### 4. Écrire la nouvelle configuration
|
|
|
|
```powershell
|
|
.\EnoceanCLI.ps1 -Action Write -CsvInput ".\enocean_modifie.csv" -Password "MonMotDePasse"
|
|
```
|
|
|
|
### 5. Vérifier
|
|
|
|
Relancer un Read pour confirmer que les DeviceId ont bien changé :
|
|
|
|
```powershell
|
|
.\EnoceanCLI.ps1 -Action Read -CsvInput ".\automates.csv" -Password "MonMotDePasse"
|
|
```
|
|
|
|
---
|
|
|
|
## Logs
|
|
|
|
Chaque exécution génère un fichier log dans le dossier courant :
|
|
|
|
```
|
|
enocean_2026-03-04_14h30.log
|
|
```
|
|
|
|
### Niveaux de log
|
|
|
|
| Niveau | Couleur console | Signification |
|
|
|--------|----------------|---------------|
|
|
| `INFO` | Cyan | Opération normale |
|
|
| `SUCCESS` | Vert | Opération réussie |
|
|
| `WARN` | Jaune | Avertissement (DeviceType différent, colonne manquante...) |
|
|
| `ERROR` | Rouge | Erreur (connexion échouée, automate injoignable...) |
|
|
|
|
### Exemple de log (action Write)
|
|
|
|
```
|
|
[2026-03-04 00:17:43] [INFO] === EnoceanCLI demarre - Action: Write ===
|
|
[2026-03-04 00:17:43] [INFO] [MON-AUTOMATE-01] https://10.60.105.42/api/rest/v1 (user: admin)
|
|
[2026-03-04 00:17:43] [INFO] [MON-AUTOMATE-01] 3 device(s) existant(s) sur l'automate
|
|
[2026-03-04 00:17:43] [INFO] [MON-AUTOMATE-01] Device enoceandevice1.xml : 12345678 -> 99864513
|
|
[2026-03-04 00:17:43] [INFO] [MON-AUTOMATE-01] Device enoceandevice2.xml : 87654321 -> 65313272
|
|
[2026-03-04 00:17:44] [WARN] [MON-AUTOMATE-01] Device enoceandevice3.xml : DeviceType CSV (D50001) differe du XML (A50401)
|
|
[2026-03-04 00:17:44] [INFO] [MON-AUTOMATE-01] Device enoceandevice3.xml : 11112222 -> 32602064
|
|
[2026-03-04 00:17:44] [SUCCESS] [MON-AUTOMATE-01] Configuration envoyee avec succes
|
|
[2026-03-04 00:17:44] [INFO] ========== RESUME ==========
|
|
[2026-03-04 00:17:44] [INFO] Automates traites : 1
|
|
[2026-03-04 00:17:44] [INFO] Automates en erreur : 0
|
|
[2026-03-04 00:17:44] [INFO] Devices traites : 3
|
|
[2026-03-04 00:17:44] [INFO] Duree totale : 00:00:01.23
|
|
[2026-03-04 00:17:44] [INFO] ============================
|
|
```
|
|
|
|
---
|
|
|
|
## Résumé des paramètres
|
|
|
|
```
|
|
.\EnoceanCLI.ps1 -Action <Read|Write> -CsvInput <chemin> [-Username <login>] [-Password <mdp>]
|
|
```
|
|
|
|
| Paramètre | Obligatoire | Défaut | Description |
|
|
|-----------|:-----------:|--------|-------------|
|
|
| `-Action` | Oui | — | `Read` ou `Write` |
|
|
| `-CsvInput` | Oui | — | Chemin du fichier CSV d'entrée |
|
|
| `-Username` | Non | `admin` | Login API (surchargeable par le CSV) |
|
|
| `-Password` | Non | *(vide)* | Mot de passe API (surchargeable par le CSV) |
|
|
|
|
---
|
|
|
|
## Dépannage
|
|
|
|
### "Impossible d'exécuter le script car l'exécution de scripts est désactivée"
|
|
|
|
```powershell
|
|
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
|
|
```
|
|
|
|
### "Aucun port HTTP/HTTPS valide"
|
|
|
|
Vérifier que les colonnes `HttpPort` et `HttpsPort` du CSV contiennent des valeurs valides. Un port à `-1` signifie "désactivé". Au moins un des deux doit être actif.
|
|
|
|
### "Aucun device Enocean existant sur l'automate"
|
|
|
|
L'automate n'a pas de capteurs EnOcean configurés. L'action Write ne peut pas modifier des devices qui n'existent pas encore — ils doivent d'abord être créés via le logiciel EC-gfxProgram.
|
|
|
|
### Timeout ou erreur de connexion
|
|
|
|
- Vérifier que l'automate est joignable (`ping 10.60.x.x`)
|
|
- Vérifier les identifiants (Username / Password)
|
|
- Vérifier que le port est correct (HTTP 80 ou HTTPS 443)
|
|
|
|
### Le WARN "DeviceType CSV diffère du XML"
|
|
|
|
C'est un avertissement informatif. Le DeviceId sera quand même appliqué. Ce message signifie que le type de capteur indiqué dans le CSV ne correspond pas à celui configuré sur l'automate. Vérifier que le bon DeviceId est associé au bon capteur.
|