Skip to content

Commit c06cf1a

Browse files
devprbttdevprbtt
authored
Revise README for clarity and additional details
Updated README.md to improve formatting and clarity, added installation and configuration details, and enhanced the CSV to YAML converter section.
1 parent dfd5da8 commit c06cf1a

1 file changed

Lines changed: 220 additions & 57 deletions

File tree

‎README.md‎

Lines changed: 220 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,176 @@
1-
# DINPLUG – Home Assistant Integration (YAML)
1+
# DINPLUG - Home Assistant Integration (YAML)
2+
3+
This custom integration for Home Assistant allows you to control **DINPLUG** lighting modules via Telnet (port 23).
4+
5+
It enables the control of individual loads from DINPLUG modules as `light` entities, including:
6+
- On/Off lights
7+
- Dimmers (0–100%)
8+
- Multiple modules and channels
9+
- Real-time status updates via `R:LOAD` telemetry
10+
11+
> 📌 This is the **YAML-based** version (no Config Flow). Ideal for simple, direct, and professional installations.
12+
13+
---
14+
15+
## 📦 Installation
16+
17+
1. Download this repository.
18+
2. Copy the folder:
19+
20+
`custom_components/dinplug`
21+
22+
into your Home Assistant configuration directory:
23+
24+
`/config/custom_components/dinplug`
25+
26+
The final structure should look like this:
27+
28+
```
29+
/config
30+
└── custom_components
31+
└── dinplug
32+
├── __init__.py
33+
├── const.py
34+
├── light.py
35+
└── manifest.json
36+
```
37+
38+
3. Restart Home Assistant.
39+
40+
---
41+
42+
## ⚙️ Configuration (YAML)
43+
44+
Add the following to your `configuration.yaml` file:
45+
46+
```yaml
47+
light:
48+
- platform: dinplug
49+
host: 192.168.51.30
50+
port: 23
51+
lights:
52+
- name: "Living Room Ceiling"
53+
device: 104
54+
channel: 1
55+
dimmer: true
56+
57+
- name: "Kitchen Spots"
58+
device: 107
59+
channel: 4
60+
dimmer: false
61+
```
62+
63+
### Available Fields
64+
| Field | Type | Required | Description |
65+
|-----------|---------|---------------|--------------------------------------|
66+
| `host` | string | ✔ Yes | IP address of the DINPLUG controller |
67+
| `port` | number | ✖ No (23) | Telnet port |
68+
| `lights` | list | ✔ Yes | List of loads |
69+
| `device` | number | ✔ Yes | Module address (e.g., 104) |
70+
| `channel` | number | ✔ Yes | Module channel (1–n) |
71+
| `name` | string | ✔ Yes | Entity name in Home Assistant |
72+
| `dimmer` | boolean | ✖ No (true) | `true` = dimmer, `false` = on/off |
73+
74+
---
75+
76+
## 🛠️ CSV to YAML Converter Tool
77+
78+
For installations with many lights, this repository includes a utility to quickly generate the YAML configuration from a CSV file.
79+
80+
### How to Use
81+
82+
1. **Run the script:**
83+
* If you have Python installed, run `python csv-to-yaml.py`.
84+
* On Windows, you can use the executable: `csv-to-yaml.exe`.
85+
86+
2. **Prepare the CSV file:**
87+
The CSV file must have the following columns: `Entity`, `Address`, `Button Type`, and `Label`.
88+
* `Entity`: Use `Switch` for on/off lights or `Dimmer` for dimmable lights.
89+
* `Address`: The module and channel in the format `device:channel` (e.g., `104:1`).
90+
* `Button Type`: Use `Dimmer` to set the light as dimmable. Any other value will result in a standard on/off switch.
91+
* `Label`: The desired name for the light.
92+
93+
**Example `lights.csv`:**
94+
```csv
95+
Entity,Label,Address,Button Type
96+
Dimmer,"Living Room Ceiling",104:1,Dimmer
97+
Switch,"Kitchen Spots",107:4,Rocker Switch
98+
Dimmer,"Bedroom Lamp",104:2,Dimmer
99+
```
100+
101+
3. **Generate the YAML:**
102+
* Open the tool, select your CSV file, enter the controller's IP address, and click "Convert to YAML".
103+
* You can then copy the generated configuration to your clipboard or save it as a `.yaml` file.
104+
105+
---
106+
107+
### 💡 How It Works
108+
109+
Home Assistant establishes a TCP connection with the DINPLUG controller and:
110+
111+
**Sends commands:**
112+
`LOAD <device> <channel> <level>`
113+
- `level = 0` → OFF
114+
- `level = 1–100` → dimmer
115+
- `level = 100` → ON
116+
117+
**Receives telemetry:**
118+
`R:LOAD <device> <channel> <level>`
119+
This instantly updates the entity's state in Home Assistant.
120+
121+
**Maintains connection:**
122+
- Periodically sends `STA` to keep the connection alive.
123+
- Monitors `R:MODULE STATUS` for availability.
124+
125+
Everything is push-based—no polling.
126+
127+
---
128+
129+
### ✔️ Supported Features
130+
131+
- [x] ON/OFF control
132+
- [x] Dimmer control (brightness)
133+
- [x] Instant status updates via telemetry
134+
- [x] No polling
135+
- [x] Multiple modules and channels
136+
- [x] Online/offline availability per module
137+
138+
### 🚧 Roadmap (Future Releases)
139+
140+
- [ ] Auto-discovery of loads via `REFRESH`
141+
- [ ] UI-based configuration (Config Flow)
142+
- [ ] Scene support (`SCN`)
143+
- [ ] Shade support (`SHADE`)
144+
- [ ] HVAC support
145+
- [ ] Automatic `Device` creation per module
146+
147+
---
148+
149+
### 🐞 Debugging (Optional)
150+
151+
To enable detailed logs for the integration, add this to your `configuration.yaml`:
152+
153+
```yaml
154+
logger:
155+
default: warning
156+
logs:
157+
custom_components.dinplug: debug
158+
```
159+
160+
---
161+
---
162+
163+
# DINPLUG – Integração Home Assistant (YAML)
2164

3165
Integração customizada do Home Assistant para controlar módulos de iluminação **DINPLUG** via Telnet (porta 23).
4166

5167
Esta integração permite controlar cargas individuais dos módulos DINPLUG como entidades `light`, incluindo:
6-
- Luzes On/Off
7-
- Dimmers (0–100%)
8-
- Múltiplos módulos e múltiplos canais
168+
- Luzes On/Off
169+
- Dimmers (0–100%)
170+
- Múltiplos módulos e múltiplos canais
9171
- Atualizações em tempo real por telemetria `R:LOAD`
10172

11-
> 📌 Esta é a versão baseada em **YAML** (sem Config Flow).
12-
>
13-
> Ideal para instalações profissionais, simples e diretas.
173+
> 📌 Esta é a versão baseada em **YAML** (sem Config Flow). Ideal para instalações profissionais, simples e diretas.
14174

15175
---
16176

@@ -61,71 +221,74 @@ light:
61221
channel: 4
62222
dimmer: false
63223
```
64-
### Campos disponíveis
65-
| Campo | Tipo | Obrigatório | Descrição |
66-
| --- | --- | --- | --- |
67-
| `host` | string | ✔ Sim | IP do controlador DINPLUG |
68-
| `port` | número | ✖ Não (23) | Porta Telnet |
69-
| `lights` | lista | ✔ Sim | Lista de cargas |
70-
| `device` | número | ✔ Sim | Endereço do módulo (ex: 104) |
71-
| `channel` | número | ✔ Sim | Canal do módulo (1–n) |
72-
| `name` | string | ✔ Sim | Nome da entidade no HA |
73-
| `dimmer` | booleano | ✖ Não (true) | `TRUE` = dimmer, `FALSE` = on/off |
74-
75-
### 💡 Como funciona
224+
225+
### Campos Disponíveis
226+
| Campo | Tipo | Obrigatório | Descrição |
227+
|----------|-----------|-------------|-------------------------------------|
228+
| `host` | string | ✔ Sim | IP do controlador DINPLUG |
229+
| `port` | número | ✖ Não (23) | Porta Telnet |
230+
| `lights` | lista | ✔ Sim | Lista de cargas |
231+
| `device` | número | ✔ Sim | Endereço do módulo (ex: 104) |
232+
| `channel`| número | ✔ Sim | Canal do módulo (1–n) |
233+
| `name` | string | ✔ Sim | Nome da entidade no HA |
234+
| `dimmer` | booleano | ✖ Não (true)| `true` = dimmer, `false` = on/off |
235+
236+
---
237+
238+
## 🛠️ Ferramenta Conversora CSV para YAML
239+
240+
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.
241+
242+
### Como Usar
243+
244+
1. **Execute o script:**
245+
* Se você tem Python instalado, execute `python csv-to-yaml.py`.
246+
* No Windows, você pode usar o executável: `csv-to-yaml.exe`.
247+
248+
2. **Prepare o arquivo CSV:**
249+
O arquivo CSV deve ter as seguintes colunas: `Entity`, `Address`, `Button Type`, e `Label`.
250+
* `Entity`: Use `Switch` para luzes on/off ou `Dimmer` para luzes dimerizáveis.
251+
* `Address`: O módulo e o canal no formato `device:channel` (ex: `104:1`).
252+
* `Button Type`: Use `Dimmer` para definir a luz como dimerizável. Qualquer outro valor resultará em uma luz on/off.
253+
* `Label`: O nome desejado para a luz.
254+
255+
**Exemplo `luzes.csv`:**
256+
```csv
257+
Entity,Label,Address,Button Type
258+
Dimmer,"Sala Teto",104:1,Dimmer
259+
Switch,"Spots Cozinha",107:4,Rocker Switch
260+
Dimmer,"Luz Quarto",104:2,Dimmer
261+
```
262+
263+
3. **Gere o YAML:**
264+
* Abra a ferramenta, selecione seu arquivo CSV, insira o endereço IP do controlador e clique em "Convert to YAML".
265+
* Você pode copiar a configuração gerada ou salvá-la em um arquivo `.yaml`.
266+
267+
---
268+
269+
### 💡 Como Funciona
76270

77271
O Home Assistant abre uma conexão TCP com o controlador DINPLUG e:
78272

79273
**Envia comandos:**
80-
81274
`LOAD <device> <channel> <level>`
82-
83275
- `level = 0` → OFF
84276
- `level = 1–100` → dimmer
85277
- `level = 100` → ON
86278

87279
**Recebe telemetria:**
88-
89280
`R:LOAD <device> <channel> <level>`
90281
Atualiza o estado instantaneamente no HA.
91282

92-
**Mantém conexão viva:**
93-
94-
- Envia `STA` periodicamente
95-
- Monitora `R:MODULE STATUS` para disponibilidade
283+
**Mantém a conexão:**
284+
- Envia `STA` periodicamente para manter a conexão ativa.
285+
- Monitora `R:MODULE STATUS` para disponibilidade.
96286

97287
Tudo é push-based — sem polling.
98288

99-
### 🔌 Exemplo completo
100-
```yaml
101-
light:
102-
- platform: dinplug
103-
host: 192.168.51.30
104-
port: 23
105-
lights:
106-
- name: "Sala Teto"
107-
device: 104
108-
channel: 1
109-
dimmer: true
110-
111-
- name: "Sala Arandela"
112-
device: 104
113-
channel: 2
114-
dimmer: false
115-
116-
- name: "Spots Cozinha"
117-
device: 107
118-
channel: 4
119-
dimmer: true
120-
121-
- name: "Corredor"
122-
device: 105
123-
channel: 3
124-
dimmer: false
125-
```
126289
---
127290

128-
### ✔️ Recursos suportados
291+
### ✔️ Recursos Suportados
129292

130293
- [x] Controle ON/OFF
131294
- [x] Controle de dimmer (brightness)
@@ -134,7 +297,7 @@ light:
134297
- [x] Múltiplos módulos e canais
135298
- [x] Disponibilidade online/offline por módulo
136299

137-
### 🚧 Roadmap (próximas versões)
300+
### 🚧 Roadmap (Próximas Versões)
138301

139302
- [ ] Auto-descoberta de loads via `REFRESH`
140303
- [ ] Configuração via UI (Config Flow)
@@ -145,9 +308,9 @@ light:
145308

146309
---
147310

148-
### 🐞 Debug (opcional)
311+
### 🐞 Debug (Opcional)
149312

150-
Para ativar logs detalhados da integração:
313+
Para ativar logs detalhados da integração, adicione ao `configuration.yaml`:
151314

152315
```yaml
153316
logger:

0 commit comments

Comments
 (0)