From 0235c22df55acdf161841243c50e0e74db14de5e Mon Sep 17 00:00:00 2001 From: Charles Date: Mon, 6 Jul 2026 01:45:35 +0200 Subject: [PATCH] Rend le README bilingue FR/EN et compatible cadMasterCLI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ajoute une section d'utilisation via cadMasterCLI (formulaire auto-généré, lien vers le depot) avant la procedure PowerShell manuelle existante, pour chaque langue. --- README.md | 323 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 280 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 01f11eb..823c97d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + # EditOffsetCLI — Modification de la consigne relative des BLE Device (Multi-capteur/Unitouch) en masse Outil de configuration automatique de la plage de réglage de consigne relative des BLE Device (Multi-capteur/Unitouch) sur automates Distech Controls Eclypse. @@ -20,20 +21,40 @@ Outil de configuration automatique de la plage de réglage de consigne relative - Être connecté au même réseau que les automates (réseau local ou VPN) - Avoir les identifiants de connexion aux automates (nom d'utilisateur et mot de passe) -Aucune installation de logiciel supplémentaire n'est nécessaire. +--- + +## Utilisation avec cadMasterCLI (recommandé) + +Ce script peut être piloté depuis **[cadMasterCLI](https://git.cadjou.net/DistechControls/cadMasterCLI)**, qui évite d'avoir à utiliser PowerShell manuellement. + +1. Lancez `cadMasterCLI.ps1` +2. Sélectionnez **EditOffsetCLI** dans la liste des scripts à gauche +3. Remplissez le formulaire affiché à droite : + +| Paramètre | Obligatoire | Ce qu'il faut faire | +|-----------|:-----------:|----------------------| +| `CsvInput` | ✅ | Cliquez sur **Parcourir...** pour sélectionner votre fichier CSV, ou utilisez la zone de collage d'IPs pour le générer automatiquement | +| `Offset` | ✅ | Saisissez la valeur de l'offset souhaitée (ex : `3`) | +| `Username` | ❌ | Identifiant API, si différent de la valeur par défaut (`admin`) | +| `Password` | ❌ | Mot de passe API | +| `UpdateGfx` | ❌ | Cochez la case pour synchroniser aussi l'interface graphique de l'automate | + +4. Cliquez sur **Lancer le script** et suivez la progression dans le journal d'exécution intégré + +> Voir la section **Format du fichier CSV** ci-dessous pour préparer votre liste d'automates. --- -## Contenu du dossier +## Utilisation seule (sans cadMasterCLI) + +### Contenu du dossier ``` EditOffsetCLI.ps1 ← script principal (fichier unique à exécuter) votre_liste.csv ← export XNU ou fichier CSV de votre choix (voir ci-dessous) ``` ---- - -## Étape 1 — Débloquer le script (première utilisation uniquement) +### Étape 1 — Débloquer le script (première utilisation uniquement) Windows bloque par sécurité les fichiers téléchargés depuis internet. Cette étape n'est à faire **qu'une seule fois**. @@ -44,15 +65,13 @@ Windows bloque par sécurité les fichiers téléchargés depuis internet. Cette > Si vous ne voyez pas la case "Débloquer", le fichier est déjà autorisé, passez à l'étape suivante. ---- +### Étape 2 — Préparer la liste des automates (fichier CSV) -## Étape 2 — Préparer la liste des automates (fichier CSV) - -### Option A — Utiliser un export XpressNetwork Utility (recommandé) +#### Option A — Utiliser un export XpressNetwork Utility (recommandé) Si vous disposez de **XpressNetwork Utility**, exportez directement votre liste d'automates en CSV : le fichier est utilisable tel quel sans modification. -### Option B — Créer le fichier manuellement +#### Option B — Créer le fichier manuellement Créez un fichier texte nommé `automates.csv` dans le même dossier que le script. @@ -65,7 +84,7 @@ Automate-Bureau-102;192.168.1.11 Automate-Salle-Conf;192.168.1.12 ``` -### Détail des colonnes +#### Détail des colonnes | Colonne | Obligatoire | Description | Exemple | |---------|:-----------:|-------------|---------| @@ -76,7 +95,7 @@ Automate-Salle-Conf;192.168.1.12 > Les automates ECY Facilities V2 communiquent toujours en HTTPS — le script le gère automatiquement. -### Identifiants différents par automate (optionnel) +#### Identifiants différents par automate (optionnel) Si certains automates ont des identifiants différents, ajoutez les colonnes `Username` et `Password` : @@ -86,9 +105,7 @@ Automate-Bureau-101;192.168.1.10;admin;motdepasse1 Automate-Bureau-102;192.168.1.11;technicien;motdepasse2 ``` ---- - -## Étape 3 — Ouvrir PowerShell dans le bon dossier +### Étape 3 — Ouvrir PowerShell dans le bon dossier 1. Ouvrez l'**Explorateur de fichiers** et naviguez jusqu'au dossier contenant `EditOffsetCLI.ps1` 2. Cliquez dans la **barre d'adresse** en haut (là où est affiché le chemin du dossier) @@ -96,9 +113,7 @@ Automate-Bureau-102;192.168.1.11;technicien;motdepasse2 Une fenêtre PowerShell s'ouvre directement dans le bon dossier. ---- - -## Étape 4 — Lancer le script +### Étape 4 — Lancer le script Dans la fenêtre PowerShell, tapez la commande suivante en remplaçant `3` par la valeur d'offset souhaitée : @@ -106,13 +121,13 @@ Dans la fenêtre PowerShell, tapez la commande suivante en remplaçant `3` par l .\EditOffsetCLI.ps1 -CsvInput ".\automates.csv" -Offset 3 ``` -### Avec identifiants (si tous les automates ont le même mot de passe) +#### Avec identifiants (si tous les automates ont le même mot de passe) ```powershell .\EditOffsetCLI.ps1 -CsvInput ".\automates.csv" -Offset 3 -Username "admin" -Password "votre_mot_de_passe" ``` -### Paramètres disponibles +#### Paramètres disponibles | Paramètre | Obligatoire | Description | |-----------|:-----------:|-------------| @@ -127,7 +142,7 @@ Dans la fenêtre PowerShell, tapez la commande suivante en remplaçant `3` par l > - Limite basse : **-3°C** > - Consigne relative : **3°C** -### Avec mise à jour du fichier GFx (interface graphique) +#### Avec mise à jour du fichier GFx (interface graphique) Pour synchroniser aussi les limites dans l'interface graphique de l'automate, ajoutez `-UpdateGfx` : @@ -137,9 +152,7 @@ Pour synchroniser aussi les limites dans l'interface graphique de l'automate, aj > Sans `-UpdateGfx`, seule la configuration BLE est modifiée. Recommandé de tester sans `-UpdateGfx` d'abord. ---- - -## Étape 5 — Suivre l'exécution +### Étape 5 — Suivre l'exécution Pendant l'exécution, le script affiche les opérations en temps réel avec des couleurs : @@ -162,9 +175,7 @@ GFx mis a jour : 5 Duree totale : 00:00:12.34 ``` ---- - -## Fichier journal (log) +### Fichier journal (log) Un fichier de log est créé automatiquement dans le même dossier, nommé : @@ -174,11 +185,9 @@ editoffset_2026-06-24_14h30.log Ce fichier contient l'historique complet de toutes les opérations effectuées. En cas de problème, transmettez ce fichier à votre référent technique. ---- +### Problèmes courants -## Problèmes courants - -### ❌ "L'exécution de scripts est désactivée sur ce système" +#### ❌ "L'exécution de scripts est désactivée sur ce système" Windows bloque l'exécution des scripts par politique de sécurité. Lancez cette commande dans PowerShell **en tant qu'administrateur** : @@ -188,9 +197,7 @@ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser Puis relancez le script normalement. ---- - -### ❌ "Fichier CSV introuvable" +#### ❌ "Fichier CSV introuvable" Vérifiez que : - Le fichier `automates.csv` est bien dans le **même dossier** que `EditOffsetCLI.ps1` @@ -198,9 +205,7 @@ Vérifiez que : > Dans l'Explorateur de fichiers, activez **Affichage → Extensions de noms de fichiers** pour voir l'extension réelle. ---- - -### ❌ Tous les automates sont en erreur +#### ❌ Tous les automates sont en erreur Vérifiez que : - Votre PC est bien connecté au réseau des automates @@ -208,15 +213,11 @@ Vérifiez que : - Le port renseigné correspond au protocole actif sur l'automate (HTTP ou HTTPS) - Les identifiants sont corrects ---- - -### ❌ "Erreur SSL/TLS" ou "certificat" +#### ❌ "Erreur SSL/TLS" ou "certificat" Le script gère automatiquement les certificats auto-signés des automates Distech. Si l'erreur persiste, vérifiez que `curl.exe` est disponible sur votre système (inclus dans Windows 10 v1803+ et Windows 11). ---- - -## Exemple complet +### Exemple complet Fichier `automates.csv` : ``` @@ -232,3 +233,239 @@ Commande : ``` Résultat attendu : les 3 automates sont configurés avec une plage de -4°C à +4°C. + + +# EditOffsetCLI — Bulk update of the BLE Device (Multi-sensor/Unitouch) relative setpoint + +Automated configuration tool for the relative setpoint adjustment range of BLE Devices (Multi-sensor/Unitouch) on Distech Controls Eclypse controllers. + +--- + +> **IMPORTANT: This project is an independent personal project.** +> +> This project was developed by Charles-Arthur DAVID on a personal basis. +> Distech Controls is not responsible for this project and does not support it. +> No support request will be handled by Distech Controls. +> Distech Controls provides no warranty or technical assistance for this project. + +--- + +## Prerequisites + +- Windows 10 or Windows 11 +- **Distech Controls ECY Facilities (V2)** controllers +- Connected to the same network as the controllers (local network or VPN) +- Controller login credentials (username and password) + +--- + +## Using it with cadMasterCLI (recommended) + +This script can be run from **[cadMasterCLI](https://git.cadjou.net/DistechControls/cadMasterCLI)**, which avoids having to use PowerShell manually. + +1. Launch `cadMasterCLI.ps1` +2. Select **EditOffsetCLI** in the script list on the left +3. Fill in the form on the right: + +| Parameter | Required | What to do | +|-----------|:--------:|------------| +| `CsvInput` | ✅ | Click **Browse...** to pick your CSV file, or use the IP paste box to generate it automatically | +| `Offset` | ✅ | Enter the desired offset value (e.g. `3`) | +| `Username` | ❌ | API username, if different from the default (`admin`) | +| `Password` | ❌ | API password | +| `UpdateGfx` | ❌ | Check this box to also sync the controller's graphical interface | + +4. Click **Run script** and follow the progress in the built-in execution log + +> See the **CSV file format** section below to prepare your controller list. + +--- + +## Using it standalone (without cadMasterCLI) + +### Folder contents + +``` +EditOffsetCLI.ps1 ← main script (single file to run) +your_list.csv ← XNU export or CSV file of your choice (see below) +``` + +### Step 1 — Unblock the script (first use only) + +Windows blocks files downloaded from the internet for security reasons. This step is only needed **once**. + +1. **Right-click** the `EditOffsetCLI.ps1` file +2. Click **Properties** +3. At the bottom of the window, check the **Unblock** box +4. Click **OK** + +> If you don't see the "Unblock" checkbox, the file is already allowed — move on to the next step. + +### Step 2 — Prepare the controller list (CSV file) + +#### Option A — Use an XpressNetwork Utility export (recommended) + +If you have **XpressNetwork Utility**, export your controller list directly as CSV: the file can be used as-is, no changes needed. + +#### Option B — Create the file manually + +Create a text file named `automates.csv` in the same folder as the script. + +Open it with **Notepad** (not Excel) and paste this content, adapting it to your data: + +``` +Hostname;Current Ip +Controller-Room-101;192.168.1.10 +Controller-Room-102;192.168.1.11 +Controller-Conf-Room;192.168.1.12 +``` + +#### Column details + +| Column | Required | Description | Example | +|--------|:--------:|-------------|---------| +| `Current Ip` | ✅ | Controller IP address | `192.168.1.10` | +| `Hostname` | ❌ | Free-form name to identify the controller in the logs | `Controller-Room-101` | +| `Username` | ❌ | Login, if different from the `-Username` parameter | `technician` | +| `Password` | ❌ | Password, if different from the `-Password` parameter | `password` | + +> ECY Facilities V2 controllers always communicate over HTTPS — the script handles this automatically. + +#### Different credentials per controller (optional) + +If some controllers have different credentials, add the `Username` and `Password` columns: + +``` +Hostname;Current Ip;Username;Password +Controller-Room-101;192.168.1.10;admin;password1 +Controller-Room-102;192.168.1.11;technician;password2 +``` + +### Step 3 — Open PowerShell in the right folder + +1. Open **File Explorer** and navigate to the folder containing `EditOffsetCLI.ps1` +2. Click in the **address bar** at the top (where the folder path is shown) +3. Type `powershell` and press **Enter** + +A PowerShell window opens directly in the right folder. + +### Step 4 — Run the script + +In the PowerShell window, type the following command, replacing `3` with the desired offset value: + +```powershell +.\EditOffsetCLI.ps1 -CsvInput ".\automates.csv" -Offset 3 +``` + +#### With credentials (if all controllers share the same password) + +```powershell +.\EditOffsetCLI.ps1 -CsvInput ".\automates.csv" -Offset 3 -Username "admin" -Password "your_password" +``` + +#### Available parameters + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `-CsvInput` | ✅ | Path to your CSV file | +| `-Offset` | ✅ | Offset value (e.g. `3` → range of -3 to +3°C) | +| `-Username` | ❌ | API username (default: `admin`) | +| `-Password` | ❌ | API password (default: empty) | +| `-UpdateGfx` | ❌ | Also update the controller's GFx file (graphical interface) | + +> **What does the offset do?** If you enter `-Offset 3`, the script configures: +> - High limit: **+3°C** +> - Low limit: **-3°C** +> - Relative setpoint: **3°C** + +#### With GFx file update (graphical interface) + +To also sync the limits in the controller's graphical interface, add `-UpdateGfx`: + +```powershell +.\EditOffsetCLI.ps1 -CsvInput ".\automates.csv" -Offset 3 -UpdateGfx +``` + +> Without `-UpdateGfx`, only the BLE configuration is changed. It's recommended to test without `-UpdateGfx` first. + +### Step 5 — Follow the execution + +While running, the script displays operations in real time with colors: + +| Color | Meaning | +|-------|---------| +| 🔵 Cyan | Information (operation in progress) | +| 🟢 Green | Success | +| 🟡 Yellow | Warning (skipped controller, invalid port…) | +| 🔴 Red | Error | + +At the end, a summary is displayed: + +``` +[RESUME] +Automates traites : 5 +Automates en erreur : 0 +Local-values mises a jour : 10 +Configurations mises a jour : 5 +GFx mis a jour : 5 +Duree totale : 00:00:12.34 +``` + +### Log file + +A log file is automatically created in the same folder, named: + +``` +editoffset_2026-06-24_14h30.log +``` + +This file contains the complete history of all operations performed. In case of an issue, send this file to your technical contact. + +### Common issues + +#### ❌ "Running scripts is disabled on this system" + +Windows blocks script execution due to security policy. Run this command in PowerShell **as administrator**: + +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser +``` + +Then run the script again normally. + +#### ❌ "CSV file not found" + +Check that: +- The `automates.csv` file is in the **same folder** as `EditOffsetCLI.ps1` +- The file name is exactly `automates.csv` (not `automates.csv.txt`) + +> In File Explorer, enable **View → File name extensions** to see the real extension. + +#### ❌ All controllers show an error + +Check that: +- Your PC is connected to the controllers' network +- The IP addresses in the CSV are correct +- The port used matches the active protocol on the controller (HTTP or HTTPS) +- The credentials are correct + +#### ❌ "SSL/TLS error" or "certificate" + +The script automatically handles Distech controllers' self-signed certificates. If the error persists, check that `curl.exe` is available on your system (included in Windows 10 v1803+ and Windows 11). + +### Full example + +`automates.csv` file: +``` +Hostname;Current Ip +Room-A101;10.0.1.50 +Room-A102;10.0.1.51 +Room-B201;10.0.1.52 +``` + +Command: +```powershell +.\EditOffsetCLI.ps1 -CsvInput ".\automates.csv" -Offset 4 -Username "admin" -Password "Distech2024" +``` + +Expected result: the 3 controllers are configured with a range of -4°C to +4°C.