Skip to content

Commit ad40d08

Browse files
soulripper13soulripper13
committed
Add LICENSE, docs, and UI metadata
Add MIT LICENSE and new info.md. Revamp README with badges, installation instructions, Apple Home usage, and bump version to 0.4.0. Update manifest.json to point to the new repository/issue tracker, bump integration version, and add configuration metadata. Add configuration_url metadata to several entity device_info (binary_sensor, button, select, sensor, switch) by importing CONF_HOST so devices link to the OpenClash LuCI dashboard. Update hacs.json to declare domains and minimum Home Assistant version.
1 parent ce81392 commit ad40d08

12 files changed

Lines changed: 141 additions & 40 deletions

File tree

‎.github/workflows/hacs.yaml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: HACS Action
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
hacs:
9+
name: HACS Action
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout Home Assistant integration
13+
uses: actions/checkout@v4
14+
15+
- name: HACS Action
16+
uses: hacs/action@main
17+
with:
18+
category: integration

‎.github/workflows/hassfest.yaml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: Validate with hassfest
2+
3+
on:
4+
push:
5+
pull_request:
6+
schedule:
7+
- cron: "0 0 * * *"
8+
9+
jobs:
10+
validate:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout Home Assistant integration
14+
uses: actions/checkout@v4
15+
16+
- name: Hassfest validation
17+
uses: home-assistant/actions/hassfest@master

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 soulripper13
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 43 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,59 @@
11
# OpenClash Manager
22

3-
Home Assistant custom integration for managing and switching OpenClash configurations on OpenWrt routers via SSH.
3+
[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg?style=for-the-badge)](https://github.com/hacs/integration)
4+
![Version](https://img.shields.io/badge/version-0.4.0-blue.svg?style=for-the-badge)
45

5-
## Features
6-
7-
- **Config Switching**: Select and apply different Clash YAML configurations.
8-
- **Master Switch**: Enable or disable OpenClash globally.
9-
- **Operation Mode**: Quickly switch between `rule`, `global`, and `direct` modes.
10-
- **Service Control**: Restart OpenClash directly from Home Assistant.
11-
- **Updates**: Trigger subscription and core updates.
12-
- **Status Monitoring**: Real-time status sensor (running/stopped) and version information.
13-
- **HomeKit Friendly**: Automatically creates individual switches for each configuration file, making it easy to expose specific configs to Apple Home.
14-
15-
## How it works
6+
OpenClash Manager is a powerful Home Assistant custom integration designed to give you full control over your OpenClash configuration on OpenWrt routers via SSH.
167

17-
The integration connects to your OpenWrt router over SSH and uses `uci` commands and service scripts to manage OpenClash.
18-
19-
- **Config Switching**: Sets `openclash.config.config_path` and restarts the service.
20-
- **Mode Switching**: Sets `openclash.config.operation_mode`.
21-
- **Master Toggle**: Sets `openclash.config.enable`.
22-
23-
## Install
8+
## Features
249

25-
Copy `custom_components/openclash_manager` into your Home Assistant `custom_components` directory, then restart Home Assistant.
10+
- **🚀 Smart Config Switching**: Select and apply different Clash YAML configurations. Switch names are automatically cleaned up (removing `.yaml`) for a polished look.
11+
- **🛡️ Enable Toggle**: Turn OpenClash on or off globally with a simple switch.
12+
- **📡 Operation Modes**: Quickly switch between `Rule`, `Global`, and `Direct` modes.
13+
- **🔄 Service Control**: Restart OpenClash directly from Home Assistant buttons.
14+
- **🆙 Automatic Updates**: Trigger subscription updates and core updates from your dashboard.
15+
- **📶 Status Monitoring**: Real-time status sensor using the `CONNECTIVITY` class (perfect for HomeKit).
16+
- **🍏 Apple Home (HomeKit) Optimized**:
17+
- Entities are named and categorized for the best Apple Home experience.
18+
- Group multiple config switches into a single tile for a "Pro" device feel.
19+
- Includes a **Configuration URL** link directly to your router's OpenClash Luci dashboard.
2620

27-
## Setup
21+
## Installation
2822

29-
In Home Assistant, go to **Settings > Devices & services > Add integration** and search for **OpenClash Manager**.
23+
### Method 1: HACS (Recommended)
3024

31-
Default settings:
25+
1. Open **HACS** in Home Assistant.
26+
2. Click the three dots in the top right and select **Custom repositories**.
27+
3. Add `https://github.com/soulripper13/openclash_manager` with the category **Integration**.
28+
4. Click **Install**.
29+
5. Restart Home Assistant.
3230

33-
- SSH port: `22`
34-
- SSH username: `root`
35-
- Config directory: `/etc/openclash/config`
36-
- Restart command: `/etc/init.d/openclash restart`
31+
### Method 2: Manual
3732

38-
The SSH user needs permission to run `uci`, read the config directory, and restart OpenClash.
33+
1. Download the latest release.
34+
2. Copy the `custom_components/openclash_manager` folder to your HA `custom_components` directory.
35+
3. Restart Home Assistant.
3936

40-
## Dashboard
37+
## Configuration
4138

42-
After setup, you can use the built-in entities in your dashboard. The integration also auto-registers a custom dashboard card resource (if available in `www/`) at:
39+
1. Go to **Settings > Devices & Services**.
40+
2. Click **Add Integration** and search for **OpenClash Manager**.
41+
3. Enter your router's SSH details:
42+
- **Host**: Your router's IP address.
43+
- **Port**: SSH port (default `22`).
44+
- **Username**: SSH username (usually `root`).
45+
- **Password**: SSH password.
46+
- **Config Directory**: Path to your Clash configs (default `/etc/openclash/config`).
47+
- **Restart Command**: The command used to restart OpenClash (default `/etc/init.d/openclash restart`).
4348

44-
```text
45-
/openclash_manager/openclash-config-card.js
46-
```
49+
## Usage in Apple Home
4750

48-
## Apple Home (HomeKit)
51+
To get the best experience in Apple Home:
52+
1. Add the **HomeKit Bridge** integration in Home Assistant.
53+
2. Include the `switch.enable` and all `switch.*_config` entities.
54+
3. In the Apple Home app, long-press the **Enable** tile and select **Group with Other Accessories**.
55+
4. Group all OpenClash-related switches together. This creates a single professional-looking tile that expands to show all controls.
4956

50-
The integration creates one `switch` entity for each Clash config file. In the HomeKit Bridge options, include these generated switch entities to allow easy switching from Apple Home.
57+
## License
5158

52-
Turn on a config switch in Apple Home to apply that config. Turning off the active config switch is ignored because Clash requires one active config.
59+
MIT License. See [LICENSE](LICENSE) for details.

‎custom_components/openclash_manager/binary_sensor.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
BinarySensorEntity,
88
)
99
from homeassistant.config_entries import ConfigEntry
10+
from homeassistant.const import CONF_HOST
1011
from homeassistant.core import HomeAssistant
1112
from homeassistant.helpers.entity import EntityCategory
1213
from homeassistant.helpers.entity_platform import AddEntitiesCallback
@@ -53,6 +54,7 @@ def __init__(
5354
"manufacturer": "OpenClash",
5455
"model": "OpenClash Manager",
5556
"sw_version": coordinator.data.version if coordinator.data else None,
57+
"configuration_url": f"http://{entry.data[CONF_HOST]}/cgi-bin/luci/admin/services/openclash",
5658
}
5759

5860
@property

‎custom_components/openclash_manager/button.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
from homeassistant.components.button import ButtonEntity
88
from homeassistant.config_entries import ConfigEntry
9+
from homeassistant.const import CONF_HOST
910
from homeassistant.core import HomeAssistant
1011
from homeassistant.helpers.entity import EntityCategory
1112
from homeassistant.helpers.entity_platform import AddEntitiesCallback
@@ -52,6 +53,7 @@ def __init__(
5253
"manufacturer": "OpenClash",
5354
"model": "OpenClash Manager",
5455
"sw_version": coordinator.data.version if coordinator.data else None,
56+
"configuration_url": f"http://{entry.data[CONF_HOST]}/cgi-bin/luci/admin/services/openclash",
5557
}
5658

5759

‎custom_components/openclash_manager/manifest.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@
44
"after_dependencies": ["frontend", "http", "lovelace"],
55
"codeowners": [],
66
"config_flow": true,
7-
"documentation": "https://github.com/katoaroosultan/openclash_config_switcher",
7+
"documentation": "https://github.com/soulripper13/openclash_manager",
88
"integration_type": "hub",
99
"iot_class": "local_polling",
10-
"issue_tracker": "https://github.com/katoaroosultan/openclash_config_switcher/issues",
10+
"issue_tracker": "https://github.com/soulripper13/openclash_manager/issues",
1111
"loggers": ["paramiko"],
1212
"requirements": ["paramiko>=3.4.0"],
13-
"version": "0.3.4"
13+
"version": "0.4.0"
1414
}

‎custom_components/openclash_manager/select.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
from homeassistant.components.select import SelectEntity
66
from homeassistant.config_entries import ConfigEntry
7+
from homeassistant.const import CONF_HOST
78
from homeassistant.core import HomeAssistant
89
from homeassistant.helpers.entity import EntityCategory
910
from homeassistant.helpers.entity_platform import AddEntitiesCallback
@@ -52,6 +53,7 @@ def __init__(
5253
"manufacturer": "OpenClash",
5354
"model": "OpenClash Manager",
5455
"sw_version": coordinator.data.version if coordinator.data else None,
56+
"configuration_url": f"http://{entry.data[CONF_HOST]}/cgi-bin/luci/admin/services/openclash",
5557
}
5658

5759
@property
@@ -101,6 +103,7 @@ def __init__(
101103
"manufacturer": "OpenClash",
102104
"model": "OpenClash Manager",
103105
"sw_version": coordinator.data.version if coordinator.data else None,
106+
"configuration_url": f"http://{entry.data[CONF_HOST]}/cgi-bin/luci/admin/services/openclash",
104107
}
105108

106109
@property

‎custom_components/openclash_manager/sensor.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
from homeassistant.components.sensor import SensorEntity
66
from homeassistant.config_entries import ConfigEntry
7+
from homeassistant.const import CONF_HOST
78
from homeassistant.core import HomeAssistant
89
from homeassistant.helpers.entity import EntityCategory
910
from homeassistant.helpers.entity_platform import AddEntitiesCallback
@@ -47,6 +48,7 @@ def __init__(
4748
"manufacturer": "OpenClash",
4849
"model": "OpenClash Manager",
4950
"sw_version": coordinator.data.version if coordinator.data else None,
51+
"configuration_url": f"http://{entry.data[CONF_HOST]}/cgi-bin/luci/admin/services/openclash",
5052
}
5153

5254
@property

‎custom_components/openclash_manager/switch.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77

88
from homeassistant.components.switch import SwitchEntity
99
from homeassistant.config_entries import ConfigEntry
10+
from homeassistant.const import CONF_HOST
1011
from homeassistant.core import HomeAssistant, callback
1112
from homeassistant.helpers.entity_platform import AddEntitiesCallback
1213
from homeassistant.helpers.update_coordinator import CoordinatorEntity
@@ -70,6 +71,7 @@ def __init__(
7071
"manufacturer": "OpenClash",
7172
"model": "OpenClash Manager",
7273
"sw_version": coordinator.data.version if coordinator.data else None,
74+
"configuration_url": f"http://{entry.data[CONF_HOST]}/cgi-bin/luci/admin/services/openclash",
7375
}
7476

7577
@property
@@ -120,6 +122,7 @@ def __init__(
120122
"manufacturer": "OpenClash",
121123
"model": "OpenClash Manager",
122124
"sw_version": coordinator.data.version if coordinator.data else None,
125+
"configuration_url": f"http://{entry.data[CONF_HOST]}/cgi-bin/luci/admin/services/openclash",
123126
}
124127

125128
@property

0 commit comments

Comments
 (0)