Document firing events (#720)

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

docs/device_automation_action.md

@@ -14,14 +14,14 @@ Home Assistant includes a template to get started with device actions. To get st
 
 The template will create a new file `device_action.py` in your integration folder and a matching test file. The file contains the following functions and constants:
 
-## `ACTION_SCHEMA`
+#### `ACTION_SCHEMA`
 
 This is the schema for actions. The base schema should be extended from `homeassistant.helpers.config_validation.DEVICE_ACTION_BASE_SCHEMA`.
 
-## `async async async_get_actions(hass, device_id)`
+#### `async def async_get_actions(hass, device_id)`
 
 Return a list of actions that this device supports.
 
-## `async async_call_action_from_config(hass, config, variables, context)`
+#### `async def async_call_action_from_config(hass, config, variables, context)`
 
 Execute the passed in action.

docs/device_automation_condition.md

@@ -14,14 +14,14 @@ Home Assistant includes a template to get started with device conditions. To get
 
 The template will create a new file `device_condition.py` in your integration folder and a matching test file. The file contains the following functions and constants:
 
-## `CONDITION_SCHEMA`
+#### `CONDITION_SCHEMA`
 
 This is the schema for conditions. The base schema should be extended from `homeassistant.helpers.config_validation.DEVICE_CONDITION_BASE_SCHEMA`.
 
-## `async async_get_conditions(hass, device_id)`
+#### `async def async_get_conditions(hass, device_id)`
 
 Return a list of conditions that this device supports.
 
-## `async async_condition_from_config(config, config_validation)`
+#### `async def async_condition_from_config(config, config_validation)`
 
 Create a condition function from a function. The condition functions should be an async-friendly callback that evaluates the condition and returns a `bool`.

docs/device_automation_trigger.md

@@ -14,14 +14,14 @@ Home Assistant includes a template to get started with device triggers. To get s
 
 The template will create a new file `device_trigger.py` in your integration folder and a matching test file. The file contains the following functions and constants:
 
-## `TRIGGER_SCHEMA`
+#### `TRIGGER_SCHEMA`
 
 This is a voluptuous schema that verifies that a specific dictionary represents a config that your integration can handle. This should extend the TRIGGER_BASE_SCHEMA from `device_automation/__init__.py`.
 
-## `async async_get_triggers(hass, device_id)`
+#### `async def async_get_triggers(hass, device_id)`
 
 Return a list of triggers.
 
-## `async async_attach_trigger(hass, config, action, automation_info)`
+#### `async def async_attach_trigger(hass, config, action, automation_info)`
 
 Given one of your own trigger configs, make it so the `action` is called whenever the trigger is triggered. Return value is a function that detaches the trigger.

docs/device_registry_index.md

@@ -64,6 +64,8 @@ class HueLight(LightEntity):
         }
 ```
 
+### Manual Registration
+
 Components are also able to register devices in the case that there are no entities representing them. An example is a hub that communicates with the lights.
 
 ```python

docs/integration_events.md

@@ -0,0 +1,21 @@
+---
+title: "Firing events"
+---
+
+Some integration represents a device or service that has events, like when motion is detected or a momentary button is pushed. An integration can make these available to users by firing them as events in Home Assistant.
+
+Your integration should fire events of type `<domain>_event`. For example, the ZHA integration fires `zha_event` events.
+
+If the event is related to a specific device/service, it should be correctly attributed. Do this by adding a `device_id` attribute to the event data that contains the device identifier from the device registry.
+
+If a device or service only fires events, you need to [manually register it in the device registry](device_registry_index.md#manual-registration).
+
+## Making events accessible to users
+
+[Device triggers](device_automation_trigger.md) should be used to make events accessible to users. With a device trigger a user will be able to see all available events for the device and use it in their automations.
+
+## What not to do
+
+Event related code should not be part of the entity logic of your integration. You want to enable the logic of converting your integration events to Home Assistant events from inside `async_setup_entry` inside `__init__.py`.
+
+Entity state should not represent events. For example, you don't want to have a binary sensor that is `on` for 30 seconds when an event happens.

sidebars.js

@@ -119,6 +119,7 @@ module.exports = {
       "creating_component_generic_discovery",
       "reproduce_state_index",
       "integration_fetching_data",
+      "integration_events",
     ],
     "Development Checklist": [
       "development_checklist",