# bingete/esphome-paulmann-lights architecture

> Architecture diagram of the GitHub repository bingete/esphome-paulmann-lights, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bingete/esphome-paulmann-lights
- Repository: https://github.com/bingete/esphome-paulmann-lights

## Overview

This is an ESPHome custom component that exposes Paulmann BLE lights as ESPHome entities. The main workflow is configuration and entity registration, BLE connection and password authentication, then periodic device reads and user-control writes; returned state updates the light and diagnostic text sensors. Device controls and system-time writes share the BLE protocol layer. The sampled C++ excerpts show connection events, authentication, polling, writes, and light-state publication; the README documents the broader device-info capability. Some protocol details and sensor publishing code were not sampled.

Main entry points: [`components/paulmann_lights/__init__.py`](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/__init__.py) (Component Setup), [`components/paulmann_lights/paulmann_lights.cpp`](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/paulmann_lights.cpp) (Connect and Authenticate), [`components/paulmann_lights/light.py`](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/light.py) (Light Entity Adapter), [`components/paulmann_lights/sensor.py`](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/sensor.py) (Info Sensors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["ESPHome Setup"]
  node_runtime["ESPHome Runtime"]
  node_config["Component Setup<br/>[__init__.py]"]
  node_constants["UUIDs and Defaults<br/>[const.py]"]
  node_ble_tracker["BLE Tracker"]
end

subgraph group_entities["User Entities"]
  node_light_entity["Light Entity Adapter<br/>[light.py]"]
  node_number_entities["Control Numbers<br/>[number.py]"]
  node_info_entities["Info Sensors<br/>[sensor.py]"]
  node_text_sensor_alias["Text Sensor Alias<br/>[text_sensor.py]"]
  node_light_output["Light Output"]
end

subgraph group_protocol["BLE Protocol"]
  node_control_dispatch["Control Dispatch"]
  node_connection_auth["Connect and Authenticate"]
  node_poll_reads["Polling and Reads"]
  node_protocol_interface["Protocol Interface<br/>[paulmann_lights.h]"]
  node_ble_client["ESPHome BLE Client"]
end

subgraph group_device["Paulmann Device"]
  node_lamp["Paulmann BLE Lamp"]
end

node_user(("ESPHome User"))

node_user -->|"configures"| node_config
node_config -->|"registers component"| node_runtime
node_config -->|"registers client"| node_ble_tracker
node_config -->|"uses defaults"| node_constants
node_light_entity -->|"registers output"| node_light_output
node_number_entities -->|"sets controls"| node_control_dispatch
node_info_entities -->|"registers sensors"| node_poll_reads
node_text_sensor_alias -->|"re-exports"| node_info_entities
node_light_output -->|"writes light state"| node_control_dispatch
node_connection_auth -->|"uses BLE client"| node_ble_client
node_poll_reads -->|"reads characteristics"| node_ble_client
node_control_dispatch -->|"writes characteristics"| node_ble_client
node_connection_auth -->|"authenticates"| node_lamp
node_poll_reads -->|"polls device"| node_lamp
node_control_dispatch -->|"controls device"| node_lamp
node_light_output -->|"publishes state"| node_light_entity
node_protocol_interface -->|"declares protocol"| node_connection_auth
node_connection_auth -->|"implements interface"| node_protocol_interface

click node_config "https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/__init__.py"
click node_constants "https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/const.py"
click node_light_entity "https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/light.py"
click node_number_entities "https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/number.py"
click node_info_entities "https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/sensor.py"
click node_text_sensor_alias "https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/text_sensor.py"
click node_light_output "https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/paulmann_lights.cpp"
click node_control_dispatch "https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/paulmann_lights.cpp"
click node_connection_auth "https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/paulmann_lights.cpp"
click node_poll_reads "https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/paulmann_lights.cpp"
click node_protocol_interface "https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/paulmann_lights.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runtime,node_config,node_constants,node_ble_tracker,node_user toneBlue
class node_light_entity,node_number_entities,node_info_entities,node_text_sensor_alias,node_light_output toneAmber
class node_control_dispatch,node_connection_auth,node_poll_reads,node_protocol_interface,node_ble_client toneMint
class node_lamp toneRose
```

## Components

### ESPHome Setup

- **ESPHome Runtime**
- [Component Setup](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/__init__.py): `components/paulmann_lights/__init__.py`
- [UUIDs and Defaults](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/const.py): `components/paulmann_lights/const.py`
- **BLE Tracker**

### User Entities

- [Light Entity Adapter](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/light.py): `components/paulmann_lights/light.py`
- [Control Numbers](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/number.py): `components/paulmann_lights/number.py`
- [Info Sensors](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/sensor.py): `components/paulmann_lights/sensor.py`
- [Text Sensor Alias](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/text_sensor.py): `components/paulmann_lights/text_sensor.py`
- [Light Output](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/paulmann_lights.cpp): `components/paulmann_lights/paulmann_lights.cpp`

### BLE Protocol

- [Control Dispatch](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/paulmann_lights.cpp): `components/paulmann_lights/paulmann_lights.cpp`
- [Connect and Authenticate](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/paulmann_lights.cpp): `components/paulmann_lights/paulmann_lights.cpp`
- [Polling and Reads](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/paulmann_lights.cpp): `components/paulmann_lights/paulmann_lights.cpp`
- [Protocol Interface](https://github.com/bingete/esphome-paulmann-lights/blob/main/components/paulmann_lights/paulmann_lights.h): `components/paulmann_lights/paulmann_lights.h`
- **ESPHome BLE Client**

### Paulmann Device

- **Paulmann BLE Lamp**

### Other components

- **ESPHome User**

## Connections

- ESPHome User → Component Setup: configures (evidence: `README.md`)
- Component Setup → ESPHome Runtime: registers component (evidence: `components/paulmann_lights/__init__.py`)
- Component Setup → BLE Tracker: registers client (evidence: `components/paulmann_lights/__init__.py`)
- Component Setup → UUIDs and Defaults: uses defaults (evidence: `components/paulmann_lights/__init__.py`)
- Light Entity Adapter → Light Output: registers output (evidence: `components/paulmann_lights/light.py`)
- Control Numbers → Control Dispatch: sets controls (evidence: `components/paulmann_lights/number.py`)
- Info Sensors → Polling and Reads: registers sensors (evidence: `components/paulmann_lights/sensor.py`)
- Text Sensor Alias → Info Sensors: re-exports (evidence: `components/paulmann_lights/text_sensor.py`)
- Light Output → Control Dispatch: writes light state (evidence: `components/paulmann_lights/paulmann_lights.cpp`)
- Connect and Authenticate → ESPHome BLE Client: uses BLE client
- Polling and Reads → ESPHome BLE Client: reads characteristics (evidence: `components/paulmann_lights/paulmann_lights.cpp`)
- Control Dispatch → ESPHome BLE Client: writes characteristics (evidence: `components/paulmann_lights/paulmann_lights.cpp`)
- Connect and Authenticate → Paulmann BLE Lamp: authenticates (evidence: `components/paulmann_lights/paulmann_lights.cpp`)
- Polling and Reads → Paulmann BLE Lamp: polls device (evidence: `README.md`)
- Control Dispatch → Paulmann BLE Lamp: controls device (evidence: `README.md`)
- Light Output → Light Entity Adapter: publishes state (evidence: `components/paulmann_lights/paulmann_lights.cpp`)
- Protocol Interface → Connect and Authenticate: declares protocol (evidence: `components/paulmann_lights/paulmann_lights.h`)
- Connect and Authenticate → Protocol Interface: implements interface (evidence: `components/paulmann_lights/paulmann_lights.cpp`)