From 29e077a575c97a41991a3904a136da24c8996f48 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Wed, 5 Feb 2020 11:07:12 -0800 Subject: [PATCH] Document platform services (#401) --- docs/dev_101_services.md | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/dev_101_services.md b/docs/dev_101_services.md index 17ea7f18..116bc8b2 100644 --- a/docs/dev_101_services.md +++ b/docs/dev_101_services.md @@ -69,8 +69,39 @@ set_speed: # Description of the field description: Name(s) of the entities to set # Example value that can be passed for this field - example: 'fan.living_room' + example: "fan.living_room" speed: description: Speed setting - example: 'low' + example: "low" +``` + +## Entity Services + +Sometimes you want to provide extra services to control your entities. For example, the Sonos integration provides services to group and ungroup devices. Entity services are special because there are many different ways a user can specify entities. It can use areas, a group or a list of entities. + +You need to register entity services in your platforms, like `/media_player.py`. These services will be made available under your domain and not the media player domain. Example code: + +```python +from homeassistant.helpers import config_validation as cv, entity_platform, service + +async def async_setup_entry(hass, entry): + """Set up the media player platform for Sonos.""" + + platform = entity_platform.current_platform.get() + + # This will call Entity.set_sleep_timer(sleep_time=VALUE) + platform.async_register_entity_service( + SERVICE_SET_TIMER, + { + vol.Required('sleep_time'): cv.time_period, + }, + "set_sleep_timer", + ) +``` + +If you need more control over the service call, you can also pass an async function that instead of `"set_sleep_timer"`: + +```python +async def custom_set_sleep_timer(entity, service_call): + await entity.set_sleep_timer(service_call.data['sleep_time']) ```