From 796db19b96eb5dfcc439031da9f1f06650c7ce5a 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 09:08:05 +0000 Subject: [PATCH] docs: Update README.md with detailed integration info Updates the README.md file with comprehensive information about the M4 DINPLUG Home Assistant integration, including installation, configuration, and usage examples. Also renames the integration directory from 'dinplug' to 'm4_dinplug' to align with the documentation. --- README.md | 173 ++++++++++++++++-- .../{dinplug => m4_dinplug}/__init__.py | 0 .../{dinplug => m4_dinplug}/const.py | 0 .../{dinplug => m4_dinplug}/hub.py | 0 .../{dinplug => m4_dinplug}/light.py | 0 .../{dinplug => m4_dinplug}/manifest.json | 0 6 files changed, 160 insertions(+), 13 deletions(-) rename custom_components/{dinplug => m4_dinplug}/__init__.py (100%) rename custom_components/{dinplug => m4_dinplug}/const.py (100%) rename custom_components/{dinplug => m4_dinplug}/hub.py (100%) rename custom_components/{dinplug => m4_dinplug}/light.py (100%) rename custom_components/{dinplug => m4_dinplug}/manifest.json (100%) diff --git a/README.md b/README.md index 73c6d5b..cbf454f 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,164 @@ -# DINPLUG Lighting (YAML) +# M4 DINPLUG – Home Assistant Integration (YAML) -Integração customizada do Home Assistant para controlar módulos de iluminação DINPLUG via Telnet (porta 23). +Integração customizada do Home Assistant para controlar módulos de iluminação **M4 / DINPLUG** via Telnet (porta 23). -## Instalação +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` -1. Copie a pasta `custom_components/dinplug` deste repositório para a pasta - `custom_components` da configuração do seu Home Assistant. Fica assim: +> 📌 Esta é a versão baseada em **YAML** (sem Config Flow). +> +> Ideal para instalações profissionais, simples e diretas. - ```text - /config/ - custom_components/ - dinplug/ - __init__.py - const.py - light.py - manifest.json +--- + +## 📦 Instalação + +1. Baixe este repositório. +2. Copie a pasta: + + + +custom_components/m4_dinplug + + +para dentro do diretório de configuração do Home Assistant: + + + +/config/custom_components/m4_dinplug + + +A estrutura final deve ficar assim: + + + +/config +└── custom_components +└── m4_dinplug +├── init.py +├── const.py +├── light.py +└── manifest.json + + +3. Reinicie o Home Assistant. + +--- + +## ⚙️ Configuração via YAML + +Adicione ao `configuration.yaml`: + +```yaml +light: + - platform: m4_dinplug + host: 192.168.51.30 + port: 23 + lights: + - name: "Sala Teto" + device: 104 + channel: 1 + dimmer: true + + - name: "Cozinha 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 + +O Home Assistant abre uma conexão TCP com o controlador M4 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 conexão viva:** + +- Envia `STA` periodicamente +- Monitora `R:MODULE STATUS` para disponibilidade + +Tudo é push-based — sem polling. + +### 🔌 Exemplo completo +```yaml +light: + - platform: m4_dinplug + host: 192.168.51.30 + port: 23 + lights: + - name: "Sala Teto" + device: 104 + channel: 1 + dimmer: true + + - name: "Sala Arandela" + device: 104 + channel: 2 + dimmer: false + + - name: "Spots Cozinha" + device: 107 + channel: 4 + dimmer: true + + - name: "Corredor" + device: 105 + channel: 3 + dimmer: false +``` +--- + +### ✔️ Recursos suportados + +- [x] Controle ON/OFF +- [x] Controle de dimmer (brightness) +- [x] Atualização instantânea por telemetria +- [x] Sem polling +- [x] Múltiplos módulos e canais +- [x] Disponibilidade online/offline por módulo + +### 🚧 Roadmap (próximas versões) + +- [ ] Auto-descoberta de loads via `REFRESH` +- [ ] Configuração via UI (Config Flow) +- [ ] Suporte a Scenes (`SCN`) +- [ ] Suporte a Cortinas (`SHADE`) +- [ ] Suporte a HVAC +- [ ] Criação automática de `Devices` por módulo + +--- + +### 🐞 Debug (opcional) + +Para ativar logs detalhados da integração: + +```yaml +logger: + default: warning + logs: + custom_components.m4_dinplug: debug +``` diff --git a/custom_components/dinplug/__init__.py b/custom_components/m4_dinplug/__init__.py similarity index 100% rename from custom_components/dinplug/__init__.py rename to custom_components/m4_dinplug/__init__.py diff --git a/custom_components/dinplug/const.py b/custom_components/m4_dinplug/const.py similarity index 100% rename from custom_components/dinplug/const.py rename to custom_components/m4_dinplug/const.py diff --git a/custom_components/dinplug/hub.py b/custom_components/m4_dinplug/hub.py similarity index 100% rename from custom_components/dinplug/hub.py rename to custom_components/m4_dinplug/hub.py diff --git a/custom_components/dinplug/light.py b/custom_components/m4_dinplug/light.py similarity index 100% rename from custom_components/dinplug/light.py rename to custom_components/m4_dinplug/light.py diff --git a/custom_components/dinplug/manifest.json b/custom_components/m4_dinplug/manifest.json similarity index 100% rename from custom_components/dinplug/manifest.json rename to custom_components/m4_dinplug/manifest.json