@@ -28,121 +28,38 @@ async def ha_call_service(
2828 return_response : bool | str = False ,
2929 ) -> dict [str , Any ]:
3030 """
31- Execute Home Assistant services with comprehensive validation and examples .
31+ Execute Home Assistant services to control entities and trigger automations .
3232
33- This is the universal tool for controlling all Home Assistant entities and executing automations.
33+ This is the universal tool for controlling all Home Assistant entities. Services follow
34+ the pattern domain.service (e.g., light.turn_on, climate.set_temperature).
3435
35- **Common Usage Examples:**
36-
37- **Light Control:**
36+ **Basic Usage:**
3837 ```python
39- # Turn on light
38+ # Turn on a light
4039 ha_call_service("light", "turn_on", entity_id="light.living_room")
4140
42- # Turn on with brightness and color
43- ha_call_service("light", "turn_on", entity_id="light.bedroom",
44- data={"brightness_pct": 75, "color_temp_kelvin": 2700})
45-
46- # Turn off all lights
47- ha_call_service("light", "turn_off")
48- ```
49-
50- **Climate Control:**
51- ```python
52- # Set temperature
41+ # Set temperature with parameters
5342 ha_call_service("climate", "set_temperature",
5443 entity_id="climate.thermostat", data={"temperature": 22})
5544
56- # Change mode
57- ha_call_service("climate", "set_hvac_mode",
58- entity_id="climate.living_room", data={"hvac_mode": "heat"})
59- ```
60-
61- **Automation Control:**
62- ```python
63- # Trigger automation (replaces ha_trigger_automation)
45+ # Trigger automation
6446 ha_call_service("automation", "trigger", entity_id="automation.morning_routine")
6547
66- # Turn automation on/off
67- ha_call_service("automation", "turn_off", entity_id="automation.night_mode")
68- ha_call_service("automation", "turn_on", entity_id="automation.security_check")
69- ```
70-
71- **Scene Activation:**
72- ```python
73- # Activate scene
74- ha_call_service("scene", "turn_on", entity_id="scene.movie_night")
75- ha_call_service("scene", "turn_on", entity_id="scene.bedtime")
76- ```
77-
78- **Input Helpers:**
79- ```python
80- # Set input number
81- ha_call_service("input_number", "set_value",
82- entity_id="input_number.temp_offset", data={"value": 2.5})
83-
84- # Toggle input boolean
85- ha_call_service("input_boolean", "toggle", entity_id="input_boolean.guest_mode")
86-
87- # Set input text
88- ha_call_service("input_text", "set_value",
89- entity_id="input_text.status", data={"value": "Away"})
90- ```
91-
92- **Universal Controls (works with any entity):**
93- ```python
94- # Universal toggle
48+ # Universal controls work with any entity
9549 ha_call_service("homeassistant", "toggle", entity_id="switch.porch_light")
96-
97- # Universal turn on/off
98- ha_call_service("homeassistant", "turn_on", entity_id="media_player.spotify")
99- ha_call_service("homeassistant", "turn_off", entity_id="fan.ceiling_fan")
10050 ```
10151
102- **Script Execution :**
103- ```python
104- # Run script
105- ha_call_service("script", "turn_on", entity_id="script.bedtime_routine")
106- ha_call_service("script", "good_night_sequence")
107- ```
52+ **Parameters :**
53+ - **domain**: Service domain (light, climate, automation, etc.)
54+ - **service**: Service name (turn_on, set_temperature, trigger, etc.)
55+ - **entity_id**: Optional target entity. For some services (e.g., light.turn_off), omitting this targets all entities in the domain
56+ - **data**: Optional dict of service-specific parameters
57+ - **return_response**: Set to True for services that return data
10858
109- **Media Player Control:**
110- ```python
111- # Volume control
112- ha_call_service("media_player", "volume_set",
113- entity_id="media_player.living_room", data={"volume_level": 0.5})
114-
115- # Play media
116- ha_call_service("media_player", "play_media",
117- entity_id="media_player.spotify",
118- data={"media_content_type": "music", "media_content_id": "spotify:playlist:123"})
119- ```
120-
121- **Cover Control:**
122- ```python
123- # Open/close covers
124- ha_call_service("cover", "open_cover", entity_id="cover.garage_door")
125- ha_call_service("cover", "close_cover", entity_id="cover.living_room_blinds")
126-
127- # Set position
128- ha_call_service("cover", "set_cover_position",
129- entity_id="cover.bedroom_curtains", data={"position": 50})
130- ```
131-
132- **Services with Response Data:**
133- ```python
134- # Some services return response data (e.g., custom components)
135- ha_call_service("ha_mcp_tools", "list_files",
136- data={"path": "www/"}, return_response=True)
137- # Returns: {"service_response": {"success": true, "files": [...]}}
138- ```
59+ **For detailed service documentation and parameters, use ha_get_domain_docs(domain).**
13960
140- **Parameter Guidelines:**
141- - **entity_id**: Optional for services that affect all entities of a domain
142- - **data**: Service-specific parameters (brightness, temperature, volume, etc.)
143- - **return_response**: Set to True for services that return data (SupportsResponse.ONLY/OPTIONAL)
144- - Use ha_get_state() first to check current values and supported features
145- - Use ha_get_domain_docs() for detailed service documentation
61+ Common patterns: Use ha_get_state() to check current values before making changes.
62+ Use ha_search_entities() to find correct entity IDs.
14663 """
14764 try :
14865 # Parse JSON data if provided as string
0 commit comments