{"id":50672833,"url":"https://github.com/ediminator/homematicip-hcu","last_synced_at":"2026-06-08T13:01:10.567Z","repository":{"id":315165781,"uuid":"1058375151","full_name":"Ediminator/homematicip-hcu","owner":"Ediminator","description":"This is a custom integration for Home Assistant that connects directly to your Homematic IP Home Control Unit (HCU) over your local network. It allows you to control and monitor your Homematic IP devices without relying on the cloud.","archived":false,"fork":false,"pushed_at":"2026-06-03T20:25:21.000Z","size":2116,"stargazers_count":69,"open_issues_count":6,"forks_count":5,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-06-03T21:13:49.672Z","etag":null,"topics":["eq3","hcu","hcu-plugin","home-assistant","homematic-ip"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ediminator.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Ediminator","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-09-17T02:25:35.000Z","updated_at":"2026-06-03T18:38:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"cabb15d0-c92d-4539-be5d-e60f2a807cf2","html_url":"https://github.com/Ediminator/homematicip-hcu","commit_stats":null,"previous_names":["ediminator/hacs-homematicip-hcu","ediminator/homematicip-hcu"],"tags_count":86,"template":false,"template_full_name":null,"purl":"pkg:github/Ediminator/homematicip-hcu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ediminator%2Fhomematicip-hcu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ediminator%2Fhomematicip-hcu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ediminator%2Fhomematicip-hcu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ediminator%2Fhomematicip-hcu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ediminator","download_url":"https://codeload.github.com/Ediminator/homematicip-hcu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ediminator%2Fhomematicip-hcu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34063159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eq3","hcu","hcu-plugin","home-assistant","homematic-ip"],"created_at":"2026-06-08T13:00:35.456Z","updated_at":"2026-06-08T13:01:10.531Z","avatar_url":"https://github.com/Ediminator.png","language":"Python","funding_links":["https://github.com/sponsors/Ediminator"],"categories":[],"sub_categories":[],"readme":"# Homematic IP Local (HCU) Integration for Home Assistant\n\n[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://github.com/hacs/integration)\n\n**Local control** for your Homematic IP devices via the Home Control Unit (HCU). No cloud required!\n\nThis integration connects directly to your HCU's local API, providing real-time control and status updates for all your Homematic IP devices through Home Assistant.\n\n\u003e **This is a passion project built entirely in personal spare time.** Its continued development depends on the community — every bug report, diagnostics file, and piece of user feedback directly shapes what gets supported and improved next. If this integration adds value to your setup, please consider giving back by sharing diagnostics, testing new features, or opening an issue on GitHub.\n\n---\n\n## 📋 Table of Contents\n\n- [Features](#-features)\n- [Connection Modes](#-connection-modes)\n- [Requirements](#-requirements)\n- [Installation](#-installation)\n- [Configuration](#-configuration-options)\n- [Group Types](#-group-types)\n- [Working with Buttons \u0026 Remote Controls](#-working-with-buttons--remote-controls)\n- [Available Actions](#-available-actions)\n- [User Message to HCU](#user-message-to-hcu)\n- [Use Internal On Time](#-use-internal-on-time)\n- [Ramp Time](#-ramp-time)\n- [Diagnostics \u0026 Troubleshooting](#-diagnostics--troubleshooting)\n- [FAQ](#-faq)\n- [Support](#-support)\n\n---\n\n## 🌟 Features\n\n- **🏠 Local Control**: Direct communication with your HCU - no cloud dependency\n- **⚡ Real-time Updates**: Instant device state changes via WebSocket\n- **🔌 Full Device Support**: Switches, lights, sensors, climate, covers, locks, and more\n- **🎛️ Advanced Climate Control**: Heating profiles, party mode, vacation mode\n- **🔘 Event-Based Buttons**: Stateless button devices trigger automation events\n- **🛡️ Security Integration**: Alarm control panel for your security system\n- **🔧 Extensive Services**: Play sounds, control rules, manage heating schedules\n- **📊 Diagnostics**: Built-in diagnostics for troubleshooting and device support\n- **🏗️ Group Support**: Automatic discovery of heating, switching, cover, and advanced system groups\n\n---\n\n## 🏗️ Group Types\n\nThe integration automatically discovers and exposes Homematic IP \"groups\" — virtual devices that the HCU uses to orchestrate physical hardware.\n\n### Standard Groups (always visible)\n\n| Group Type | Platform | Description |\n|---|---|---|\n| `HEATING` | `climate` | Room thermostat control with profiles, eco/party mode |\n| `SWITCHING` | `switch` | User-created Direct Connection switch groups |\n| `LIGHT` | `light` | User-created Direct Connection light groups |\n| `SHUTTER` / `EXTENDED_LINKED_SHUTTER` | `cover` | Roller shutter and blind groups |\n| `EXTENDED_LINKED_SWITCHING` | `switch` | Extended linked switching groups |\n\n### Advanced Groups (conditionally visible)\n\nThese groups only appear when the HCU has assigned physical devices to them. If they show up, it means they are active in your system.\n\n| Group Type | Platform | What it does |\n|---|---|---|\n| `HEATING_COOLING_DEMAND_BOILER` | `binary_sensor` | Aggregates all thermostat valve positions to indicate if the boiler needs to fire |\n| `HEATING_COOLING_DEMAND_PUMP` | `binary_sensor` | Indicates if the heating circulation pump should be running |\n| `HOT_WATER` | `switch` | Controls hot water profiles (requires a physical hot water actuator) |\n\n\u003e **💡 Tip:** Even without a Homematic IP boiler actuator (HmIP-WHS2), you can use the Heat Demand binary sensor to control a third-party relay (Shelly, Zigbee plug) connected to your boiler via Home Assistant automations.\n\n---\n\n## 🔌 Connection Modes\n\nThe integration supports three connection modes. The mode is selected during setup and can be changed at any time via **Settings → Integrations → Homematic IP HCU → Reconfigure**.\n\n| | DualBridge (App + Plugin) | App User | Plugin User |\n|---|---|---|---|\n| **Setup** | Both | Press blue button on the HCU | Activation key from HCU WebUI → Developer Mode |\n| **Developer Mode required** | ✅ Yes (for Plugin features) | ❌ No | ✅ Yes |\n| **Door Locks (Access Authorization)** | ✅ Yes | ✅ Yes | ✅ Yes |\n| **Device Configuration** ¹ | ✅ Yes | ✅ Yes | ❌ No |\n| **User Messages to Homematic IP app** | ✅ Yes | ❌ No | ✅ Yes |\n| **Discover / Control responses** | ✅ Yes | ❌ No | ✅ Yes |\n| **Recommendation** | ⭐ Recommended — full feature set | Simple setup, full device support | Plugin features only |\n\n\u003e ¹ Device Configuration includes per-device parameters settable via the App User REST API, e.g. `powerUpSwitchState` for actuators.\n\n### Which mode should I use?\n\n- **DualBridge** is the recommended choice. It combines the REST-based state loading of the App User with the plugin-specific features (user messages, discover/control) of the Plugin User.\n- **App User only** is the simplest setup — no Developer Mode needed. Choose this if you don't need plugin features.\n- **Plugin User only** is suitable if you only want plugin features and no App User REST access.\n\n---\n\n## 📦 Requirements\n\n- **Home Assistant** 2024.1.0 or newer\n- **Homematic IP Home Control Unit (HCU)** with firmware 1.x or later\n- **Local network access** to your HCU\n\n---\n\n## 🚀 Installation\n\n### Step 1: Install via HACS\n\n[![Open your Home Assistant instance and add this repository to HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=Ediminator\u0026repository=hacs-homematicip-hcu\u0026category=Integration)\n\nOr, add it manually:\n\n1. Open **HACS** in your Home Assistant sidebar\n2. Click on **Integrations**\n3. Click the **three dots** (⋮) in the top right corner\n4. Select **Custom repositories**\n5. Add the following details:\n   - **Repository:** `https://github.com/Ediminator/hacs-homematicip-hcu/`\n   - **Category:** `Integration`\n6. Click **ADD**\n7. Close the custom repositories window\n8. Search for **\"Homematic IP Local (HCU)\"** in HACS\n9. Click **DOWNLOAD** and confirm\n10. **Restart Home Assistant** when prompted\n\n---\n\n### Step 2: Enable the HCU Local API\n\nBefore adding the integration, you must enable the local API on your HCU.\n\n1. Open your HCU's web interface (HCUweb) in a browser:\n   - Try `https://hcu1-XXXX.local` (replace `XXXX` with the last 4 digits of your HCU's SGTIN)\n   - Or use your HCU's IP address: `https://YOUR_HCU_IP`\n   - **Note:** You may see a security warning about the certificate - this is normal, click \"Advanced\" and proceed\n\n2. Log in to your HCU\n\n3. Navigate to **Developer Mode** in the menu\n\n4. Toggle the switch to **activate Developer Mode**\n\n5. Toggle the switch to **Expose the Connect API WebSocket**\n   - ⚠️ **Important:** Sometimes the toggle is already activated even on first setup. Please **deactivate and activate the toggle** to ensure it's properly enabled.\n\n6. Leave this page open - you'll need it in the next step!\n\n---\n\n### Step 3: Add the Integration in Home Assistant\n\n💡 **Tip before Adding Integration:** If your **Home Assistant Area** names match your **Homematic IP Room** names (e.g., Living room = Living room), **newly discovered devices** will be created directly in the correct Home Assistant Area **automatically**.\n\n1. In Home Assistant, go to **Settings** → **Devices \u0026 Services**\n\n2. Click the **+ ADD INTEGRATION** button (bottom right)\n\n3. Search for `Homematic IP Local (HCU)` and select it\n\n4. **First Dialog - Connection Details:**\n   - Enter your **HCU's IP address** (e.g., `192.168.1.100`)\n   - Leave the ports at their default values unless you changed them:\n     - Authentication Port: `6969`\n     - WebSocket Port: `9001`\n   - Click **SUBMIT**\n\n5. **Second Dialog - Authorization:**\n   - Switch back to your HCU's web interface (from Step 2)\n   - Click the **\"Generate activation key\"** button\n   - A temporary key will appear (valid for a few minutes)\n   - **Copy the entire key** and paste it into Home Assistant\n   - Click **SUBMIT**\n\n6. The integration will now connect and discover all your devices! This may take a few moments.\n\n7. You should see a success message and your devices will start appearing in Home Assistant\n\n---\n\n### Step 4: Configure Door Lock PIN (Optional)\n\nIf you have a Homematic IP door lock (e.g., HmIP-DLD), you need to provide its PIN for the integration to control it.\n\n\u003e 💡 **Why?** The HCU requires a PIN for all lock operations for security reasons.\n\n1. Go to **Settings** → **Devices \u0026 Services**\n2. Find the **Homematic IP Local (HCU)** card\n3. Click **CONFIGURE**\n4. Enter your door lock's **Authorization PIN**\n5. Click **SUBMIT**\n\nYour door lock will now be available for control in Home Assistant!\n\n---\n\n## 🔧 Configuration Options\n\nAfter installation, you can adjust some settings:\n\n1. Go to **Settings** → **Devices \u0026 Services**\n2. Find the **Homematic IP Local (HCU)** card\n3. Click **CONFIGURE**\n\n### Available Options:\n\n- **Comfort Temperature:** Default temperature (in °C) used when switching from OFF to HEAT mode\n- **Third-Party Device Filters:** Show/hide devices from manufacturers other than eQ-3\n- **Group Filters** Show/hide groups\n---\n\n## 🔘 Working with Buttons \u0026 Remote Controls\n\n**⭐ This is the most common question, so read this section carefully!**\n\n### Understanding Button Devices\n\nStateless button devices (wall switches, remote controls, etc.) work differently from regular switches in Home Assistant:\n\n**❌ You will NOT see:**\n- Button entities in your entity list\n- Buttons in the device card\n- Toggle switches for each button\n\n**✅ You WILL get:**\n- Events fired on the Home Assistant event bus\n- Full control via automations\n- Support for multi-button scenarios\n\n**Why?** Stateless buttons don't maintain an on/off state - they only send momentary press signals. Home Assistant's standard approach for these devices is to use events, which provides much more flexibility for automations.\n\n---\n\n### Supported Button Devices\n\nThis integration supports button events for:\n\n**Wall Switches:**\n- HmIP-WGS (Wall-mounted Glass Switch)\n- HmIP-WRC2 (2-button Wall Remote)\n- HmIP-WRC6 (6-button Wall Remote)\n- HmIP-WRCC2 (Wall Remote with Display)\n- HmIP-BRC2 (2-button Remote Control)\n- And more...\n\n**Remote Controls:**\n- HmIP-KRC4 (4-button Key Ring Remote)\n- HmIP-RC8 (8-button Remote)\n- HmIP-KRCK (Key Ring Remote with Display)\n- And more...\n\n**Contact Interfaces (when configured as buttons):**\n- HmIP-FCI1 (Flush-mount Contact Interface 1)\n- HmIP-FCI6 (Flush-mount Contact Interface 6)\n- HmIP-SCI (Shutter Contact Interface)\n\n---\n\n### Step-by-Step: Testing Your Buttons\n\nBefore creating automations, verify your buttons are working:\n\n#### 1. Create a pseudo automation in the HCU with an empty action to enable button press events.\n- Important: You must create both key types if you want to use both short and long presses.\n   \n#### 2. Open the Events Monitor\n\n1. Go to **Developer Tools** → **Events** (in the sidebar)\n2. In the \"Listen to events\" section, type: `hcu_integration_event`\n3. Click **START LISTENING**\n\n#### 3. Press Your Buttons\n\n- Press any button on your Homematic IP device\n- You should immediately see an event appear in the event monitor\n\n#### 4. Understand the Event Data\n\nWhen a button is pressed, you'll see something like this:\n\n```yaml\nevent_type: hcu_integration_event\ndata:\n  device_id: 3014F711A00048240995D6BC\n  subtype: \"1\"\n  type: KEY_PRESS_SHORT\norigin: LOCAL\ntime_fired: 2025-10-26T10:30:45.123456+00:00\n```\n\n**What each field means:**\n- `device_id`: The unique ID of your button device (SGTIN)\n- `subtype`: Which button was pressed (1, 2, 3, etc.)\n   - **⚠️ Note (since v2.0.0):** Use subtype instead of channel to identify which button was pressed.\n- `type`: The type of the button event (`ring`, `press`, `press_short`, `press_long`, `press_long_start` or `press_long_stop`)\n   - **⚠️ Note (since v2.0.0):** type are now lowercase and no longer prefixed with a \"key_\")\n   - `ring`: fires once when the doorbell is pressed\n   - `press_short`: fires once on a short press\n   - `press_long_start`: fires once at the beginning of a long press\n   - `press_long`: fires repeatedly (~every 250 ms) while the button is held\n   - `press_long_stop`: fires once when the button is released after a long press\n\n\n\n#### 4. Note Down Your Device ID and Channels\n\n**Important:** You'll need these values for your automations!\n\n- Write down your `device_id`\n- Note which `subtype` corresponds to each physical button\n\n**💡 Tip:** You can find your device_id more easily in the diagnostics file - see the [Diagnostics section](#-diagnostics--troubleshooting) below.\n\n---\n\n### Creating Button Automations\n\nNow that you've confirmed your buttons work, let's create automations!\n\n#### Method 0: Device Triggers (Easiest — since v2.0.0)\n\nStarting with v2.0.0, this integration supports **Home Assistant Device Triggers**. This is the simplest way to create button automations — no YAML required.\n\n1. Go to **Settings** → **Automations \u0026 Scenes**\n2. Click **+ CREATE AUTOMATION** → **Create new automation**\n3. **Add Trigger:**\n   - Click **ADD TRIGGER**\n   - Select **Device**\n   - Choose your Homematic IP button device\n   - Select the trigger type, e.g. `Button 1 - Short press`\n4. **Add Action** and **Save**\n\n**Supported trigger types for buttons:** `press`, `press_short`, `press_long`, `press_long_start`, `press_long_stop`\n\n**Supported trigger types for doorbell:** `ring`\n\n\u003e 💡 **Tip:** Device Triggers use the same underlying events as the YAML method — they are just a convenient UI wrapper.\n\n---\n\n#### Method 1: Visual Editor (Recommended for Beginners)\n\n**Example: Turn on a light when button 1 is pressed**\n\n1. Go to **Settings** → **Automations \u0026 Scenes**\n2. Click **+ CREATE AUTOMATION** → **Create new automation**\n3. **Add Trigger:**\n   - Click **ADD TRIGGER**\n   - Select **Event**\n   - Event type: `hcu_integration_event`\n4. **Add Condition:**\n   - Click **ADD CONDITION**\n   - Select **Template**\n   - Template:\n     ```jinja\n     {{ trigger.event.data.device_id == '3014F711A00048240995D6BC' and trigger.event.data.subtype == '1' and trigger.event.data.type  == 'press_short' }}\n     ```\n   - Replace the `device_id` and `subtype` with your values!\n5. **Add Action:**\n   - Click **ADD ACTION**\n   - Select **Call service**\n   - Service: `light.turn_on`\n   - Target: Choose your light\n6. **Save** your automation with a descriptive name\n\n---\n\n#### Method 2: YAML (For Advanced Users)\n\n**Example 1: Simple Toggle**\n\n```yaml\nalias: Living Room - Button 1 Toggle Light\ndescription: Toggle living room light with wall switch button 1\nmode: single\ntriggers:\n  - event_type: hcu_integration_event\n    event_data:\n      device_id: 3014F711A00048240995D6BC\n      subtype: \"1\"\n      type: press_short\n    trigger: event\nactions:\n  - target:\n      entity_id: light.living_room\n    action: light.toggle\n```\n\n**Example 2: Multi-Button Control (Choose Action by Button)**\n\n```yaml\nalias: Kitchen Remote - 4 Buttons\ndescription: Control multiple lights with a 4-button remote\nmode: single\ntriggers:\n  - event_type: hcu_integration_event\n    event_data:\n      device_id: 3014F711A00048240995D6BC\n    trigger: event\nactions:\n  - choose:\n      - conditions:\n          - condition: template\n            value_template: \"{{ trigger.event.data.subtype == '1' and trigger.event.data.type  == 'press_short' }}\"\n        sequence:\n          - target:\n              entity_id: light.kitchen_main\n            action: light.turn_on\n      - conditions:\n          - condition: template\n            value_template: \"{{ trigger.event.data.subtype == '2' and trigger.event.data.type  == 'press_short' }}\"\n        sequence:\n          - target:\n              entity_id: light.kitchen_main\n            action: light.turn_off\n      - conditions:\n          - condition: template\n            value_template: \"{{ trigger.event.data.subtype == '3' and trigger.event.data.type  == 'press_short' }}\"\n        sequence:\n          - target:\n              entity_id: light.kitchen_cabinet\n            action: light.turn_on\n      - conditions:\n          - condition: template\n            value_template: \"{{ trigger.event.data.subtype == '4' and trigger.event.data.type  == 'press_short' }}\"\n        sequence:\n          - target:\n              entity_id: light.kitchen_cabinet\n            action: light.turn_off\n```\n\n**Example 3: Same Button for On/Off (Double Press Detection)**\n\n```yaml\nalias: Bedroom - Button 1 with Double Press\ndescription: Single press = dim light, double press = full brightness\nmode: restart\ntriggers:\n  - event_type: hcu_integration_event\n    event_data:\n      device_id: 3014F711A00048240995D6BC\n      subtype: \"1\"\n      type: press_short\n    trigger: event\nactions:\n  - if:\n      - condition: state\n        entity_id: timer.button_press_timer\n        state: active\n    then:\n      # Second press detected within 1 second\n      - target:\n          entity_id: light.bedroom\n        data:\n          brightness: 255\n        action: light.turn_on\n      - target:\n          entity_id: timer.button_press_timer\n        action: timer.cancel\n    else:\n      # First press - start timer\n      - target:\n          entity_id: timer.button_press_timer\n        data:\n          duration: \"00:00:01\"\n        action: timer.start\n      - wait_for_trigger:\n          - entity_id: timer.button_press_timer\n            to: idle\n            trigger: state\n        timeout: \"00:00:01\"\n      # Timer expired - this was a single press\n      - if:\n          - condition: state\n            entity_id: timer.button_press_timer\n            state: idle\n        then:\n          - target:\n              entity_id: light.bedroom\n            data:\n              brightness: 128\n            action: light.turn_on\n```\n\n*Note: For double-press detection, create a timer helper first:*\n1. Go to **Settings** → **Devices \u0026 Services** → **Helpers**\n2. Click **+ CREATE HELPER** → **Timer**\n3. Name: \"Button Press Timer\"\n4. Duration: \"00:00:01\"\n\n**Example 4: Switch or Dim (Using Short and Long Press Events)**\n\n```\nalias: Offic - Switch or Dim the light\ntriggers:\n  - event_type: hcu_integration_event\n    event_data:\n      device_id: 3014F711A00048240995D6BC\n      subtype: \"1\"\n    trigger: event\nactions:\n  - choose:\n      - conditions:\n          - condition: template\n            value_template: \"{{ trigger.event.data.type == 'press_short' }}\"\n        sequence:\n          - target:\n              entity_id: light.light_office\n            action: light.toggle\n      - conditions:\n          - condition: template\n            value_template: \"{{ trigger.event.data.type == 'press_long' }}\"\n        sequence:\n          - repeat:\n              while:\n                - condition: template\n                  value_template: |\n                    {{ trigger.event.data.type == 'press_long' }}\n              sequence:\n                - data:\n                    entity_id: light.light_office\n                    brightness_step: 10\n                  action: light.turn_on\n                - delay: \"0.2\"\nmode: restart\n```\n\n---\n\n### Finding Your Device ID and Channels\n\n**Easiest Method: Use Diagnostics**\n\n1. Go to **Settings** → **Devices \u0026 Services**\n2. Find the **Homematic IP Local (HCU)** card and click it\n3. Find your button device in the list and click it\n4. Click the **three dots** (⋮) in the top right\n5. Select **Download diagnostics** (or just look at the device info on the page)\n6. The device ID (SGTIN) is shown clearly\n\n**Manual Method: Diagnostics File**\n\n1. Download the full integration diagnostics:\n   - Settings → Devices \u0026 Services\n   - Click on the Homematic IP Local (HCU) card\n   - Three dots (⋮) → Download diagnostics\n\n2. Open the JSON file and search for your device name\n\n3. Look for the structure:\n   ```json\n   \"3014F711A00048240995D6BC\": {\n     \"label\": \"Living Room Wall Switch\",\n     \"functionalChannels\": {\n       \"0\": { \"functionalChannelType\": \"DEVICE_BASE\" },\n       \"1\": { \"functionalChannelType\": \"SINGLE_KEY_CHANNEL\" },\n       \"2\": { \"functionalChannelType\": \"SINGLE_KEY_CHANNEL\" },\n       \"3\": { \"functionalChannelType\": \"SINGLE_KEY_CHANNEL\" },\n       \"4\": { \"functionalChannelType\": \"SINGLE_KEY_CHANNEL\" }\n     }\n   }\n   ```\n\n4. Note:\n   - The long string is your `device_id`\n   - Channels 1, 2, 3, 4 are your buttons (ignore channel 0 - it's always the maintenance channel)\n\n---\n## User Message to HCU\n\n\u003cimg src=\"https://raw.githubusercontent.com/Ediminator/hacs-homematicip-hcu/refs/heads/main/images/usermessage.jpeg\" height=\"300\"\u003e \n\nWith the actions **hcu_integration.create_user_message_request** and **hcu_integration.delete_user_message_request**, you can create and delete user messages in the Homematic IP app.\nMore Information under **[Available Actions](#-available-actions)**\n\n### Listening for User Message Acknowledgements\n\nWhen a user acknowledges a message in the Homematic IP app, the HCU sends a `USER_MESSAGE_ACK_EVENT` back to the integration. The integration fires this as a Home Assistant bus event:\n\n**Event name:** `hcu_integration_user_message_ack`\n\n**Payload:**\n\n| Field | Description |\n|---|---|\n| `user_message_id` | The ID of the acknowledged message |\n| `ack_type` | The user's response: `OK`, `YES`, or `NO` |\n\n**Example automation trigger:**\n\n```yaml\ntrigger:\n  - platform: event\n    event_type: hcu_integration_user_message_ack\n    event_data:\n      user_message_id: MY_MESSAGE_ID\n      ack_type: \"YES\"\n```\n\nYou can access the payload values in actions via:\n\n```yaml\n{{ trigger.event.data.user_message_id }}\n{{ trigger.event.data.ack_type }}\n```\n\n\u003e **Note:** `ack_type` is only meaningful for messages created with `behavior_type: ACKNOWLEDGEABLE_BY_YES_NO`. For `ACKNOWLEDGEABLE_BY_OK` messages it will always be `OK`.\n\n---\n## 📊 Diagnostics \u0026 Troubleshooting\n\n### Downloading Diagnostics\n\nDiagnostics files are **extremely valuable** for troubleshooting and adding support for new devices.\n\n**When to download diagnostics:**\n- Before reporting an issue on GitHub\n- When buttons aren't working (v1.8.1 or later fixes most button issues)\n- When a device isn't working correctly\n- To help add support for a new device type\n\n**How to Download:**\n\n1. Go to **Settings** → **Devices \u0026 Services**\n2. Find the **Homematic IP Local (HCU)** integration card\n3. Click on the card to open the integration details\n4. In the top right, click the **three dots** (⋮)\n5. Select **Download diagnostics**\n6. Your browser downloads: `hcu_integration-XXXX.json`\n\n**What's in the file?**\n- Complete device inventory and current states\n- Heating groups and configurations\n- Entity mappings\n- Device capabilities\n\n**Privacy:** Sensitive data like PINs and tokens are automatically redacted (`**REDACTED**`).\n\n---\n\n### Debug Logging\n\nFor detailed troubleshooting, especially for button events:\n\n#### Method 1: Quick Debug (Recommended)\n\n1. Go to **Settings** → **Devices \u0026 Services**\n2. Find **Homematic IP Local (HCU)** card\n3. Click the **three dots** (⋮)\n4. Click **Enable debug logging**\n5. Reproduce the issue (e.g., press your buttons)\n6. Click the **three dots** (⋮) again\n7. Click **Disable debug logging**\n8. Your browser immediately downloads the log file\n\n**Look for these log entries for button debugging:**\n- `Button press detected via timestamp change` - Timestamp-based detection (old devices)\n- `Button press detected for stateless channel` - Event-based detection (HmIP-WGS, HmIP-WRC6, etc.)\n\n#### Method 2: Permanent Logging\n\nFor persistent debug logging:\n\n1. Edit your `configuration.yaml`:\n   ```yaml\n   logger:\n     default: info\n     logs:\n       custom_components.hcu_integration: debug\n   ```\n\n2. Restart Home Assistant\n3. View logs in **Settings** → **System** → **Logs**\n\n---\n\n## 🎮 Available Actions\n\n### `hcu_integration.play_sound`\n\nPlay a sound on compatible notification devices (e.g., HmIP-MP3P).\n\n**Example:**\n```yaml\naction: hcu_integration.play_sound\ntarget:\n  entity_id: switch.doorbell\ndata:\n  sound_file: \"ALARM_01\"\n  volume: 0.8\n  duration: 10\n```\n\n### `hcu_integration.set_rule_state`\n\nEnable or disable automation rules within the HCU.\n\n**Example:**\n```yaml\naction: hcu_integration.set_rule_state\ndata:\n  rule_id: \"00000000-0000-0000-0000-000000000000\"\n  enabled: true\n```\n\n### `hcu_integration.activate_party_mode`\n\nTemporarily override heating schedule for a specific room.\n\n**Example:**\n```yaml\naction: hcu_integration.activate_party_mode\ntarget:\n  entity_id: climate.living_room\ndata:\n  temperature: 22\n  duration: 14400  # 4 hours in seconds\n```\n\n### `hcu_integration.activate_vacation_mode`\n\nSystem-wide vacation mode for all heating groups.\n\n**Example:**\n```yaml\naction: hcu_integration.activate_vacation_mode\ndata:\n  temperature: 15\n  end_time: \"2025-12-24 18:00\"\n```\n\n### `hcu_integration.activate_eco_mode`\n\nActivate permanent absence (Eco) mode.\n\n**Example:**\n```yaml\naction: hcu_integration.activate_eco_mode\n```\n\n### `hcu_integration.deactivate_absence_mode`\n\nDeactivate any active absence mode.\n\n**Example:**\n```yaml\naction: hcu_integration.deactivate_absence_mode\n```\n\n### `hcu_integration.set_cooling_mode`\n\nActivates or deactivates cooling mode for all heating groups.\n\n```yaml\naction: hcu_integration.set_cooling_mode\ndata:\n  cooling: true\n```\n\n### `hcu_integration.send_api_command`\n\nSend raw api command to hcu.\n\n**Example:**\n```yaml\naction: hcu_integration.send_api_command\ndata:\n  path: /hmip/device/control/setOpticalSignal\n  body:\n    opticalSignalBehaviour: FLASH_MIDDLE\n    simpleRGBColorState: PURPLE\n    dimLevel: 0.42\n    channelIndex: 8\n    deviceId: 3014F711A00478E0C9A5E3456\n```\n### `hcu_integration.create_user_message_request`\n\nCreate a User Message that is displayed in the Homematic IP app. See the EQ3 API documentation for details.\n\n**Example:**\n```yaml\naction: hcu_integration.create_user_message_request\ndata:\n  body:\n     message_category: INFO\n     user_message_id: USER_MESSAGE\n     title: Message from Home Assistant\n     message: \"Test Message with Entity States {{ states('sensor.State') }}.\"\n     behavior_type: NOT_DISMISSIBLE\n```\nor \n\n```yaml\naction: hcu_integration.create_user_message_request\ndata:\n  body:\n     message_category: INFO\n     user_message_id: USER_MESSAGE\n     title:\n       en: Message from Home Assistant\n       de: Nachricht von Home Assistant\n     message:\n       en: \"Test Message with Entity States {{ states('sensor.State') }}.\"\n       de: \"Test Nachricht mit Entität Status {{ states('sensor.Status') }}.\"\n     behavior_type: NOT_DISMISSIBLE\n```\n\n### `hcu_integration.delete_user_message_request`\n\nDelete a previously created User Message from the Homematic IP app.\n\n**Example:**\n```yaml\naction: hcu_integration.delete_user_message_request\ndata:\n  user_message_id: USER_MESSAGE\n```\n---\n\n## 🔄 Updating the Integration\n\nWhen a new version is released:\n\n1. Open **HACS**\n2. Go to **Integrations**\n3. Find **Homematic IP Local (HCU)**\n4. If an update is available, click **UPDATE**\n5. **Restart Home Assistant**\n\n**Important:** Always check the CHANGELOG before updating for any breaking changes or new requirements.\n\n---\n\n## ❓ FAQ\n\n### Can I use both the cloud integration and this local integration?\n\nNot recommended. Running both simultaneously may cause conflicts. Choose one approach.\n\n### My device isn't appearing in Home Assistant\n\n1. Verify the device appears in the HCU web interface\n2. Check if it's a third-party device (may be filtered)\n3. Download diagnostics and check if the device is listed\n4. Create an issue on GitHub with your diagnostics file\n\n### The integration says \"Failed to connect\"\n\n- Verify the HCU's IP address is correct\n- Ensure Developer Mode is enabled on the HCU\n- Check \"Expose the Connect API WebSocket\" is enabled\n- Verify ports 6969 and 9001 are accessible\n- Try accessing the HCU web interface from the same machine running Home Assistant\n\n### Can I control the HCU itself (reboot, updates, etc.)?\n\nNo, this integration only controls devices connected to the HCU. HCU management must be done through the HCU web interface.\n\n---\n\n## ⏱️ Use Internal On Time\n\n\u003cimg src=\"https://raw.githubusercontent.com/Ediminator/hacs-homematicip-hcu/refs/heads/main/images/internalontime.png\" height=\"300\"\u003e \n\nSome switch and light channels in the Homematic IP app allow you to configure an **on-time** for the internal button — the duration after which the device turns itself off automatically.\n\nThis integration exposes a **\"Use Internal On Time\"** config switch entity per channel. When enabled, any `turn_on` command sent through Home Assistant will pass the configured `onTime` to the device, causing it to switch off automatically after the set duration — without needing a separate timer or automation.\n\n**Typical use cases:**\n- Staircase lighting (e.g. HmIP-DRSI1)\n- Water valves (e.g. HmIP-MOD-OC8)\n- Any channel where a fixed on-duration is configured in the Homematic IP app\n\n**Notes:**\n- The entity is **disabled by default** and only appears on channels that have an `onTime` value configured in the Homematic IP app.\n- Configure the on-time in the Homematic IP app first, then enable the entity in Home Assistant.\n- The enabled state is persisted across Home Assistant restarts.\n\n---\n\n## 💡 Ramp Time\n\nSome dimming actor channels support a **ramp time** — the duration in seconds over which the device transitions from its current brightness level to the target level when turning on or off.\n\nThis integration exposes a **\"Ramp Time\"** config number entity per dimming channel. When set to a value greater than `0`, any `turn_on` or `turn_off` command sent through Home Assistant will automatically pass the configured duration as `rampTime` to the device — without needing an explicit `transition` value in every service call.\n\n**Typical use cases:**\n- Soft fade-in/fade-out for ceiling or ambient lights\n- Consistent transition behaviour across automations and dashboards without per-call configuration\n\n**Notes:**\n- The entity is **disabled by default**. Enable it in Home Assistant for the channels where you want a fixed ramp time.\n- Valid range: `0.1–16383` seconds. A value of `0` disables the feature (no ramp time is passed to the device).\n- If a service call already includes an explicit `transition` value, that value always takes precedence over the configured ramp time.\n- The configured value is persisted across Home Assistant restarts.\n\n---\n\n## 💬 Support\n\n- **Issues \u0026 Bug Reports:** [GitHub Issues](https://github.com/Ediminator/hacs-homematicip-hcu/issues)\n- **Discussions:** [GitHub Discussions](https://github.com/Ediminator/hacs-homematicip-hcu/discussions)\n\n**When asking for help:**\n1. Always include your Home Assistant version\n2. Include your integration version\n3. Attach diagnostics file when possible\n4. Enable debug logging and include relevant log excerpts\n5. Clearly describe what you expected vs. what happened\n\n---\n\n## 📜 License\n\nThis project is provided as-is for personal use. Please check the repository for license details.\n\n---\n\n## 🙏 Credits\n\nCreated and maintained by [@Ediminator](https://github.com/Ediminator)\n\nSpecial thanks to all contributors and users who provide diagnostics files and feedback to improve the integration!\n\n---\n\n**Remember:** When in doubt, download diagnostics - it makes troubleshooting much faster! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fediminator%2Fhomematicip-hcu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fediminator%2Fhomematicip-hcu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fediminator%2Fhomematicip-hcu/lists"}