gfx-enocean/README.md

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

---

> **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 11** (PowerShell 5.1 est inclus par défaut, rien à installer)
- Un accès réseau aux automates Eclypse Gen 1 (HTTP ou HTTPS)
- Les identifiants de connexion aux automates (par défaut : `admin` / mot de passe vide)

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

---

## Utilisation avec cadMasterCLI

Ce script peut être piloté depuis **[cadMasterCLI](https://git.cadjou.net/DistechControls/cadMasterCLI)**, qui évite d'avoir à utiliser PowerShell manuellement.

Quand ce script est sélectionné dans cadMasterCLI :

- Ce `README.md` s'affiche dans le panneau de gauche, dans la langue active de l'interface.
- Les paramètres sont détectés automatiquement et affichés sous forme de champs :
  - `Action` : RadioButtons `Read` / `Write` (valeurs du `[ValidateSet]`)
  - `CsvInput` : bouton "Parcourir" + zone de collage d'IPs (conversion automatique en CSV)
  - `Username`, `Password` : champs texte
- Il suffit de renseigner les champs puis de lancer l'exécution depuis l'interface — aucune commande PowerShell à taper, aucune politique d'exécution à modifier manuellement.

Se référer à la section suivante pour le détail des paramètres, du format du CSV attendu et du dépannage.

---

## Utilisation en autonome


### 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-04_10h07.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_15h30.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://192.168.1.11/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 192.168.1.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.

<!-- EN -->
# EnoceanCLI

Command-line tool to read and write EnOcean configurations on **Distech Controls Eclypse Gen 1** controllers via their REST API.

---

> **IMPORTANT: This project is an independent personal development.**
>
> 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 requests will be handled by Distech Controls.
> Distech Controls provides no warranty or technical assistance for this project.

---

## Prerequisites

- **Windows 10 or 11** (PowerShell 5.1 is included by default, nothing to install)
- Network access to the Eclypse Gen 1 controllers (HTTP or HTTPS)
- Login credentials for the controllers (default: `admin` / empty password)

## What this tool does

- **Read**: Connects to each controller listed in a CSV, retrieves the EnOcean configuration (DeviceId, DeviceType of each sensor), and generates an output CSV file.
- **Write**: Takes a CSV containing the desired DeviceId values and applies them to each controller. **Only the DeviceId is modified** — all existing configuration on the controller (Points, MaxReceiveTime, Description, etc.) is preserved.

---

## Using with cadMasterCLI

This script can be run from **[cadMasterCLI](https://git.cadjou.net/DistechControls/cadMasterCLI)**, which avoids having to use PowerShell manually.

When this script is selected in cadMasterCLI:

- This `README.md` is displayed in the left-hand panel, in the interface's active language.
- Parameters are detected automatically and rendered as input fields:
  - `Action`: RadioButtons `Read` / `Write` (values from `[ValidateSet]`)
  - `CsvInput`: a "Browse" button plus an IP paste area (automatic conversion to CSV)
  - `Username`, `Password`: text fields
- Simply fill in the fields and launch the run from the interface — no PowerShell command to type, no execution policy to change manually.

See the next section for parameter details, the expected CSV format, and troubleshooting.

---

## Standalone usage

### Check that PowerShell is available

Open a terminal (`Windows` key + `R`, type `powershell`, then `Enter`) and type:

```powershell
$PSVersionTable.PSVersion
```

The `Major` number must be **5 or higher**.

### Installation

No installation required. Download or clone the project folder:

```
gfxEnocean/
├── EnoceanCLI.ps1          <- Main script
├── modules/                <- Modules (do not modify)
│   ├── Logger.psm1
│   ├── CsvHandler.psm1
│   ├── ApiClient.psm1
│   ├── XmlParser.psm1
│   └── ZipBuilder.psm1
└── README.md
```

### Usage

#### Open PowerShell in the right folder

1. Open File Explorer and navigate to the `gfxEnocean` folder
2. Click in the address bar, type `powershell`, then press `Enter`

Or in a PowerShell terminal:

```powershell
cd "C:\path\to\gfxEnocean"
```

#### Execution policy

The first time, PowerShell may block script execution. Allow it for the current session:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

This command is safe: it only allows scripts for the current PowerShell window.

#### Read action — Read controller configuration

```powershell
.\EnoceanCLI.ps1 -Action Read -CsvInput ".\my_file.csv"
```

With a password:

```powershell
.\EnoceanCLI.ps1 -Action Read -CsvInput ".\my_file.csv" -Password "MyPassword"
```

**Result**: A file `enocean_YYYY-MM-DD_HHhMM.csv` is created in the current folder with the DeviceId and DeviceType of each EnOcean sensor.

#### Write action — Write DeviceId values to the controllers

```powershell
.\EnoceanCLI.ps1 -Action Write -CsvInput ".\enocean_2026-03-04_10h07.csv" -Password "MyPassword"
```

**What happens**:
1. The script connects to each controller
2. It retrieves the existing EnOcean configuration (full XML with Points, etc.)
3. It replaces **only the DeviceId** with the value from the CSV
4. It sends the modified configuration back to the controller

**What is preserved**: Points, MaxReceiveTime, Description, Name, ResourceNumber, DeviceType — everything except the DeviceId.

#### Built-in help

```powershell
Get-Help .\EnoceanCLI.ps1 -Detailed
```

### Input CSV format

The CSV file uses a **semicolon** (`;`) as separator.

#### Required columns

| Column | Description |
|---------|-------------|
| `Hostname` | Controller name |
| `Current Ip` | Controller IP address |
| `HttpPort` | HTTP port (`80` or `-1` if disabled) |
| `HttpsPort` | HTTPS port (`443` or `-1` if disabled) |

#### Optional columns

| Column | Description |
|---------|-------------|
| `RestServiceURL` | API path (default: `/api/rest/v1/`) |
| `Username` | Login specific to this controller |
| `Password` | Password specific to this controller |

#### Columns for the Write action

| Column | Description |
|---------|-------------|
| `DeviceId_1` | DeviceId to write to the 1st EnOcean sensor |
| `DeviceType_1` | DeviceType of the 1st sensor (for verification) |
| `DeviceId_2` | DeviceId to write to the 2nd sensor |
| `DeviceType_2` | DeviceType of the 2nd sensor |
| ... | As many pairs as there are sensors |

#### CSV example

```csv
"Hostname";"Current Ip";"HttpPort";"HttpsPort";"RestServiceURL";"DeviceId_1";"DeviceType_1";"DeviceId_2";"DeviceType_2"
"MY-CONTROLLER-01";"192.168.1.11";"-1";"443";"/api/rest/v1/";"99864513";"A50401";"65313272";"A5100C"
"MY-CONTROLLER-02";"192.168.1.12";"80";"-1";"/api/rest/v1/";"45678912";"A53001";"";""
```

**Note**: Empty DeviceId/DeviceType columns are ignored — the corresponding sensor is not modified.

### Typical workflow

#### 1. Prepare the input CSV

Start from an existing export (XNU Export, network inventory...) containing at least the `Hostname`, `Current Ip`, `HttpPort`, `HttpsPort` columns.

#### 2. Read the current configuration

```powershell
.\EnoceanCLI.ps1 -Action Read -CsvInput ".\controllers.csv" -Password "MyPassword"
```

This generates a CSV with the current DeviceId of each controller.

#### 3. Edit the DeviceId values in the CSV

Open the generated CSV in Excel or a text editor. Edit the `DeviceId_1`, `DeviceId_2`, etc. columns with the new values.

**Warning**: Do not modify the `DeviceType_N` columns. They are for reference only. If the CSV's DeviceType differs from the controller's, a warning will be shown in the logs.

#### 4. Write the new configuration

```powershell
.\EnoceanCLI.ps1 -Action Write -CsvInput ".\enocean_modified.csv" -Password "MyPassword"
```

#### 5. Verify

Run a Read again to confirm the DeviceId values have changed:

```powershell
.\EnoceanCLI.ps1 -Action Read -CsvInput ".\controllers.csv" -Password "MyPassword"
```

### Logs

Each run generates a log file in the current folder:

```
enocean_2026-03-04_15h30.log
```

#### Log levels

| Level | Console color | Meaning |
|--------|----------------|---------------|
| `INFO` | Cyan | Normal operation |
| `SUCCESS` | Green | Successful operation |
| `WARN` | Yellow | Warning (different DeviceType, missing column...) |
| `ERROR` | Red | Error (connection failed, controller unreachable...) |

#### Log example (Write action)

```
[2026-03-04 00:17:43] [INFO]    === EnoceanCLI demarre - Action: Write ===
[2026-03-04 00:17:43] [INFO]    [MY-CONTROLLER-01] https://192.168.1.11/api/rest/v1 (user: admin)
[2026-03-04 00:17:43] [INFO]    [MY-CONTROLLER-01] 3 device(s) existant(s) sur l'automate
[2026-03-04 00:17:43] [INFO]    [MY-CONTROLLER-01] Device enoceandevice1.xml : 12345678 -> 99864513
[2026-03-04 00:17:43] [INFO]    [MY-CONTROLLER-01] Device enoceandevice2.xml : 87654321 -> 65313272
[2026-03-04 00:17:44] [WARN]    [MY-CONTROLLER-01] Device enoceandevice3.xml : DeviceType CSV (D50001) differe du XML (A50401)
[2026-03-04 00:17:44] [INFO]    [MY-CONTROLLER-01] Device enoceandevice3.xml : 11112222 -> 32602064
[2026-03-04 00:17:44] [SUCCESS] [MY-CONTROLLER-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]    ============================
```

> Note: log messages are generated by the script in French (see `modules/Logger.psm1`); the example above is shown as-is.

### Parameters summary

```
.\EnoceanCLI.ps1 -Action <Read|Write> -CsvInput <path> [-Username <login>] [-Password <password>]
```

| Parameter | Required | Default | Description |
|-----------|:-----------:|--------|-------------|
| `-Action` | Yes | — | `Read` or `Write` |
| `-CsvInput` | Yes | — | Path to the input CSV file |
| `-Username` | No | `admin` | API login (overridable by the CSV) |
| `-Password` | No | *(empty)* | API password (overridable by the CSV) |

### Troubleshooting

#### "Cannot run the script because script execution is disabled"

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

#### "No valid HTTP/HTTPS port"

Check that the CSV's `HttpPort` and `HttpsPort` columns contain valid values. A port set to `-1` means "disabled". At least one of the two must be active.

#### "No existing EnOcean device on the controller"

The controller has no EnOcean sensors configured. The Write action cannot modify devices that do not yet exist — they must first be created via the EC-gfxProgram software.

#### Timeout or connection error

- Check that the controller is reachable (`ping 192.168.1.x`)
- Check the credentials (Username / Password)
- Check that the port is correct (HTTP 80 or HTTPS 443)

#### The WARN "DeviceType CSV differs from XML"

This is an informational warning. The DeviceId will be applied anyway. This message means the sensor type indicated in the CSV does not match the one configured on the controller. Check that the correct DeviceId is associated with the correct sensor.