EditOffsetCLI/README.md

<!-- FR -->
# 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.

---

> **IMPORTANT : Ce projet est un développement personnel indépendant.**
>
> Ce projet a été développé par Charles-Arthur DAVID à titre personnel.
> Distech Controls n'est pas responsable de ce projet et ne le supporte pas.
> Aucune demande de support ne sera prise en charge par Distech Controls.
> Distech Controls ne fournit aucune garantie ni assistance technique pour ce projet.

---

## Prérequis

- Windows 10 ou Windows 11
- Automates **Distech Controls ECY Facilities (V2)**
- Ê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)

---

## 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.

---

## 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)

Windows bloque par sécurité les fichiers téléchargés depuis internet. Cette étape n'est à faire **qu'une seule fois**.

1. Faites un **clic droit** sur le fichier `EditOffsetCLI.ps1`
2. Cliquez sur **Propriétés**
3. En bas de la fenêtre, cochez la case **Débloquer**
4. Cliquez sur **OK**

> 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)

#### 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

Créez un fichier texte nommé `automates.csv` dans le même dossier que le script.

Ouvrez-le avec **le Bloc-notes** (pas Excel) et collez ce contenu en adaptant vos données :

```
Hostname;Current Ip
Automate-Bureau-101;192.168.1.10
Automate-Bureau-102;192.168.1.11
Automate-Salle-Conf;192.168.1.12
```

#### Détail des colonnes

| Colonne | Obligatoire | Description | Exemple |
|---------|:-----------:|-------------|---------|
| `Current Ip` | ✅ | Adresse IP de l'automate | `192.168.1.10` |
| `Hostname` | ❌ | Nom libre pour identifier l'automate dans les logs | `Automate-Bureau-101` |
| `Username` | ❌ | Identifiant si différent du paramètre `-Username` | `technicien` |
| `Password` | ❌ | Mot de passe si différent du paramètre `-Password` | `motdepasse` |

> Les automates ECY Facilities V2 communiquent toujours en HTTPS — le script le gère automatiquement.

#### Identifiants différents par automate (optionnel)

Si certains automates ont des identifiants différents, ajoutez les colonnes `Username` et `Password` :

```
Hostname;Current Ip;Username;Password
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

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)
3. Tapez `powershell` puis appuyez sur **Entrée**

Une fenêtre PowerShell s'ouvre directement dans le bon dossier.

### É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 :

```powershell
.\EditOffsetCLI.ps1 -CsvInput ".\automates.csv" -Offset 3
```

#### 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ètre | Obligatoire | Description |
|-----------|:-----------:|-------------|
| `-CsvInput` | ✅ | Chemin vers votre fichier CSV |
| `-Offset` | ✅ | Valeur de l'offset (ex: `3` → plage de -3 à +3°C) |
| `-Username` | ❌ | Identifiant API (défaut : `admin`) |
| `-Password` | ❌ | Mot de passe API (défaut : vide) |
| `-UpdateGfx` | ❌ | Modifier aussi le fichier GFx de l'automate (interface graphique) |

> **Que fait l'offset ?** Si vous entrez `-Offset 3`, le script configure :
> - Limite haute : **+3°C**
> - Limite basse : **-3°C**
> - Consigne relative : **3°C**

#### Avec mise à jour du fichier GFx (interface graphique)

Pour synchroniser aussi les limites dans l'interface graphique de l'automate, ajoutez `-UpdateGfx` :

```powershell
.\EditOffsetCLI.ps1 -CsvInput ".\automates.csv" -Offset 3 -UpdateGfx
```

> Sans `-UpdateGfx`, seule la configuration BLE est modifiée. Recommandé de tester sans `-UpdateGfx` d'abord.

### Étape 5 — Suivre l'exécution

Pendant l'exécution, le script affiche les opérations en temps réel avec des couleurs :

| Couleur | Signification |
|---------|---------------|
| 🔵 Cyan | Information (opération en cours) |
| 🟢 Vert | Succès |
| 🟡 Jaune | Avertissement (automate ignoré, port invalide…) |
| 🔴 Rouge | Erreur |

À la fin, un résumé s'affiche :

```
[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
```

### Fichier journal (log)

Un fichier de log est créé automatiquement dans le même dossier, nommé :

```
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

#### ❌ "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** :

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

Puis relancez le script normalement.

#### ❌ "Fichier CSV introuvable"

Vérifiez que :
- Le fichier `automates.csv` est bien dans le **même dossier** que `EditOffsetCLI.ps1`
- Le nom du fichier est exactement `automates.csv` (pas `automates.csv.txt`)

> Dans l'Explorateur de fichiers, activez **Affichage → Extensions de noms de fichiers** pour voir l'extension réelle.

#### ❌ Tous les automates sont en erreur

Vérifiez que :
- Votre PC est bien connecté au réseau des automates
- Les adresses IP dans le CSV sont correctes
- Le port renseigné correspond au protocole actif sur l'automate (HTTP ou HTTPS)
- Les identifiants sont corrects

#### ❌ "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

Fichier `automates.csv` :
```
Hostname;Current Ip
Salle-A101;10.0.1.50
Salle-A102;10.0.1.51
Salle-B201;10.0.1.52
```

Commande :
```powershell
.\EditOffsetCLI.ps1 -CsvInput ".\automates.csv" -Offset 4 -Username "admin" -Password "Distech2024"
```

Résultat attendu : les 3 automates sont configurés avec une plage de -4°C à +4°C.

<!-- EN -->
# 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.