From eabf0a7bf49d560603150ee7cc08bf530f5231c8 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 29 Nov 2025 23:53:05 +0000 Subject: [PATCH] Docs: Add English translation and document CSV converter This commit significantly updates the `README.md` to be more accessible and comprehensive. Key changes: - Adds a full English translation of the documentation, which now appears before the Portuguese version. - Adds a new section detailing the purpose and usage of the `csv-to-yaml.py` converter tool, including a CSV format example. - Ensures both language versions are consistent and include all recent updates. --- README.md | 302 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 229 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index fd5908c..d2b932e 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,47 @@ -# M4 DINPLUG – Home Assistant Integration (YAML) +# DINPLUG - Home Assistant Integration (YAML) -Integração customizada do Home Assistant para controlar módulos de iluminação **M4 / DINPLUG** via Telnet (porta 23). +This custom integration for Home Assistant allows you to control **DINPLUG** lighting modules via Telnet (port 23). -Esta integração permite controlar cargas individuais dos módulos M4 como entidades `light`, incluindo: -- Luzes On/Off -- Dimmers (0–100%) -- Múltiplos módulos e múltiplos canais -- Atualizações em tempo real por telemetria `R:LOAD` +It enables the control of individual loads from DINPLUG modules as `light` entities, including: +- On/Off lights +- Dimmers (0–100%) +- Multiple modules and channels +- Real-time status updates via `R:LOAD` telemetry -> 📌 Esta é a versão baseada em **YAML** (sem Config Flow). -> -> Ideal para instalações profissionais, simples e diretas. +> 📌 This is the **YAML-based** version (no Config Flow). Ideal for simple, direct, and professional installations. --- -## 📦 Instalação - -1. Baixe este repositório. -2. Copie a pasta: - - - -custom_components/dinplug +## 📦 Installation +1. Download this repository. +2. Copy the folder: -para dentro do diretório de configuração do Home Assistant: - - - -/config/custom_components/dinplug +`custom_components/dinplug` +into your Home Assistant configuration directory: -A estrutura final deve ficar assim: - +`/config/custom_components/dinplug` +The final structure should look like this: +``` /config └── custom_components -└── dinplug -├── init.py -├── const.py -├── light.py -└── manifest.json - + └── dinplug + ├── __init__.py + ├── const.py + ├── light.py + └── manifest.json +``` -3. Reinicie o Home Assistant. +3. Restart Home Assistant. --- -## ⚙️ Configuração via YAML +## ⚙️ Configuration (YAML) -Adicione ao `configuration.yaml`: +Add the following to your `configuration.yaml` file: ```yaml light: @@ -58,52 +49,162 @@ light: host: 192.168.51.30 port: 23 lights: - - name: "Sala Teto" + - name: "Living Room Ceiling" device: 104 channel: 1 dimmer: true - - name: "Cozinha Spots" + - name: "Kitchen Spots" device: 107 channel: 4 dimmer: false ``` -### Campos disponíveis -| Campo | Tipo | Obrigatório | Descrição | -| --- | --- | --- | --- | -| `host` | string | ✔ Sim | IP do controlador DINPLUG | -| `port` | número | ✖ Não (23) | Porta Telnet | -| `lights` | lista | ✔ Sim | Lista de cargas | -| `device` | número | ✔ Sim | Endereço do módulo (ex: 104) | -| `channel` | número | ✔ Sim | Canal do módulo (1–n) | -| `name` | string | ✔ Sim | Nome da entidade no HA | -| `dimmer` | booleano | ✖ Não (true) | `TRUE` = dimmer, `FALSE` = on/off | -### 💡 Como funciona +### Available Fields +| Field | Type | Required | Description | +|-----------|---------|---------------|--------------------------------------| +| `host` | string | ✔ Yes | IP address of the DINPLUG controller | +| `port` | number | ✖ No (23) | Telnet port | +| `lights` | list | ✔ Yes | List of loads | +| `device` | number | ✔ Yes | Module address (e.g., 104) | +| `channel` | number | ✔ Yes | Module channel (1–n) | +| `name` | string | ✔ Yes | Entity name in Home Assistant | +| `dimmer` | boolean | ✖ No (true) | `true` = dimmer, `false` = on/off | -O Home Assistant abre uma conexão TCP com o controlador M4 e: +--- -**Envia comandos:** +## 🛠️ CSV to YAML Converter Tool -`LOAD ` +For installations with many lights, this repository includes a utility to quickly generate the YAML configuration from a CSV file. + +### How to Use + +1. **Run the script:** + * If you have Python installed, run `python csv-to-yaml.py`. + * On Windows, you can use the executable: `csv-to-yaml.exe`. + +2. **Prepare the CSV file:** + The CSV file must have the following columns: `Entity`, `Address`, `Button Type`, and `Label`. + * `Entity`: Use `Switch` for on/off lights or `Dimmer` for dimmable lights. + * `Address`: The module and channel in the format `device:channel` (e.g., `104:1`). + * `Button Type`: Use `Dimmer` to set the light as dimmable. Any other value will result in a standard on/off switch. + * `Label`: The desired name for the light. + + **Example `lights.csv`:** + ```csv + Entity,Label,Address,Button Type + Dimmer,"Living Room Ceiling",104:1,Dimmer + Switch,"Kitchen Spots",107:4,Rocker Switch + Dimmer,"Bedroom Lamp",104:2,Dimmer + ``` + +3. **Generate the YAML:** + * Open the tool, select your CSV file, enter the controller's IP address, and click "Convert to YAML". + * You can then copy the generated configuration to your clipboard or save it as a `.yaml` file. + +--- + +### 💡 How It Works +Home Assistant establishes a TCP connection with the DINPLUG controller and: + +**Sends commands:** +`LOAD ` - `level = 0` → OFF - `level = 1–100` → dimmer - `level = 100` → ON -**Recebe telemetria:** - +**Receives telemetry:** `R:LOAD ` -Atualiza o estado instantaneamente no HA. +This instantly updates the entity's state in Home Assistant. -**Mantém conexão viva:** +**Maintains connection:** +- Periodically sends `STA` to keep the connection alive. +- Monitors `R:MODULE STATUS` for availability. -- Envia `STA` periodicamente -- Monitora `R:MODULE STATUS` para disponibilidade +Everything is push-based—no polling. -Tudo é push-based — sem polling. +--- + +### ✔️ Supported Features + +- [x] ON/OFF control +- [x] Dimmer control (brightness) +- [x] Instant status updates via telemetry +- [x] No polling +- [x] Multiple modules and channels +- [x] Online/offline availability per module + +### 🚧 Roadmap (Future Releases) + +- [ ] Auto-discovery of loads via `REFRESH` +- [ ] UI-based configuration (Config Flow) +- [ ] Scene support (`SCN`) +- [ ] Shade support (`SHADE`) +- [ ] HVAC support +- [ ] Automatic `Device` creation per module + +--- + +### 🐞 Debugging (Optional) + +To enable detailed logs for the integration, add this to your `configuration.yaml`: + +```yaml +logger: + default: warning + logs: + custom_components.dinplug: debug +``` + +--- +--- + +# DINPLUG – Integração Home Assistant (YAML) + +Integração customizada do Home Assistant para controlar módulos de iluminação **DINPLUG** via Telnet (porta 23). + +Esta integração permite controlar cargas individuais dos módulos DINPLUG como entidades `light`, incluindo: +- Luzes On/Off +- Dimmers (0–100%) +- Múltiplos módulos e múltiplos canais +- Atualizações em tempo real por telemetria `R:LOAD` + +> 📌 Esta é a versão baseada em **YAML** (sem Config Flow). Ideal para instalações profissionais, simples e diretas. + +--- + +## 📦 Instalação + +1. Baixe este repositório. +2. Copie a pasta: + +`custom_components/dinplug` + +para dentro do diretório de configuração do Home Assistant: + +`/config/custom_components/dinplug` + +A estrutura final deve ficar assim: + +``` +/config +└── custom_components + └── dinplug + ├── __init__.py + ├── const.py + ├── light.py + └── manifest.json +``` + +3. Reinicie o Home Assistant. + +--- + +## ⚙️ Configuração via YAML + +Adicione ao `configuration.yaml`: -### 🔌 Exemplo completo ```yaml light: - platform: dinplug @@ -115,24 +216,79 @@ light: channel: 1 dimmer: true - - name: "Sala Arandela" - device: 104 - channel: 2 - dimmer: false - - - name: "Spots Cozinha" + - name: "Cozinha Spots" device: 107 channel: 4 - dimmer: true - - - name: "Corredor" - device: 105 - channel: 3 dimmer: false ``` + +### Campos Disponíveis +| Campo | Tipo | Obrigatório | Descrição | +|----------|-----------|-------------|-------------------------------------| +| `host` | string | ✔ Sim | IP do controlador DINPLUG | +| `port` | número | ✖ Não (23) | Porta Telnet | +| `lights` | lista | ✔ Sim | Lista de cargas | +| `device` | número | ✔ Sim | Endereço do módulo (ex: 104) | +| `channel`| número | ✔ Sim | Canal do módulo (1–n) | +| `name` | string | ✔ Sim | Nome da entidade no HA | +| `dimmer` | booleano | ✖ Não (true)| `true` = dimmer, `false` = on/off | + +--- + +## 🛠️ Ferramenta Conversora CSV para YAML + +Para instalações com muitas luzes, este repositório inclui um utilitário para gerar rapidamente a configuração YAML a partir de um arquivo CSV. + +### Como Usar + +1. **Execute o script:** + * Se você tem Python instalado, execute `python csv-to-yaml.py`. + * No Windows, você pode usar o executável: `csv-to-yaml.exe`. + +2. **Prepare o arquivo CSV:** + O arquivo CSV deve ter as seguintes colunas: `Entity`, `Address`, `Button Type`, e `Label`. + * `Entity`: Use `Switch` para luzes on/off ou `Dimmer` para luzes dimerizáveis. + * `Address`: O módulo e o canal no formato `device:channel` (ex: `104:1`). + * `Button Type`: Use `Dimmer` para definir a luz como dimerizável. Qualquer outro valor resultará em uma luz on/off. + * `Label`: O nome desejado para a luz. + + **Exemplo `luzes.csv`:** + ```csv + Entity,Label,Address,Button Type + Dimmer,"Sala Teto",104:1,Dimmer + Switch,"Spots Cozinha",107:4,Rocker Switch + Dimmer,"Luz Quarto",104:2,Dimmer + ``` + +3. **Gere o YAML:** + * Abra a ferramenta, selecione seu arquivo CSV, insira o endereço IP do controlador e clique em "Convert to YAML". + * Você pode copiar a configuração gerada ou salvá-la em um arquivo `.yaml`. + +--- + +### 💡 Como Funciona + +O Home Assistant abre uma conexão TCP com o controlador DINPLUG e: + +**Envia comandos:** +`LOAD ` +- `level = 0` → OFF +- `level = 1–100` → dimmer +- `level = 100` → ON + +**Recebe telemetria:** +`R:LOAD ` +Atualiza o estado instantaneamente no HA. + +**Mantém a conexão:** +- Envia `STA` periodicamente para manter a conexão ativa. +- Monitora `R:MODULE STATUS` para disponibilidade. + +Tudo é push-based — sem polling. + --- -### ✔️ Recursos suportados +### ✔️ Recursos Suportados - [x] Controle ON/OFF - [x] Controle de dimmer (brightness) @@ -141,7 +297,7 @@ light: - [x] Múltiplos módulos e canais - [x] Disponibilidade online/offline por módulo -### 🚧 Roadmap (próximas versões) +### 🚧 Roadmap (Próximas Versões) - [ ] Auto-descoberta de loads via `REFRESH` - [ ] Configuração via UI (Config Flow) @@ -152,9 +308,9 @@ light: --- -### 🐞 Debug (opcional) +### 🐞 Debug (Opcional) -Para ativar logs detalhados da integração: +Para ativar logs detalhados da integração, adicione ao `configuration.yaml`: ```yaml logger: