访问core

介绍

在开发HA时，您将看到一个无处不在的变量:hass。这是Home Assistant实例，它将允许您访问系统的所有不同部分

The `hass` object

Home Assistant实例包含四个对象，以帮助您与系统交互。

对象	描述
hass	HA的示例，允许启动，停止和排队新的工作. See available methods.
hass.config	这是显示位置、温度首选项和配置目录路径的Home Assistant的核心配置，See available methods.
hass.states	这是状态机。它允许您设置状态并跟踪它们的更改，See available methods.
hass.bus	事件总线，它允许您触发和监听事件。See available methods.
hass.services	服务注册表，它允许你注册服务。See available methods.

Where to find `hass`

根据您正在编写的内容，有不同的方法可以使hass对象可用。

Component, 传递到setup(hass, config)或async_setup(hass, config)。

Platform, 传入setup_platform(hass, config, add_devices, discovery_info=None)或async_setup_platform(hass, config, async_add_devices, discovery_info=None)。

Entity, 当实体在平台中通过add_devices回调被添加时，该实体可用为self.hass。

使用事件

HA核心是由事件驱动的。这意味着如果你想对发生的事情做出反应，你就必须对事件做出反应。大多数时候，您不会直接与事件系统交互，而是使用event listener helpers.之一。

事件系统非常灵活。事件类型没有限制，只要它是字符串。每个事件都可以包含数据。数据是一个字典，可以包含任何数据，只要它是JSON可序列化的。这意味着你可以使用数字，字符串，字典和列表。

List of events that Home Assistant fires.

触发事件

要触发一个事件，您必须与事件总线交互。事件总线在Home Assistant实例上是可用的，如has.bus。请注意我们在 Data Science portal上记录的数据结构

加载时将触发事件的示例组件。请注意，自定义事件名称以组件名称作为前缀。

DOMAIN = "example_component"


def setup(hass, config):
    """Set up is called when Home Assistant is loading our component."""

    # Fire event example_component_my_cool_event with event data answer=42
    hass.bus.fire("example_component_my_cool_event", {"answer": 42})

    # Return successful setup
    return True

监听事件

大多数时候，您不会触发事件，而是侦听事件。例如，实体的状态变化被作为一个事件传播出去。

DOMAIN = "example_component"


def setup(hass, config):
    """Set up is called when Home Assistant is loading our component."""
    count = 0

    # Listener to handle fired events
    def handle_event(event):
        nonlocal count
        count += 1
        print(f"Answer {count} is: {event.data.get('answer')}")

    # Listen for when example_component_my_cool_event is fired
    hass.bus.listen("example_component_my_cool_event", handle_event)

    # Return successful setup
    return True

助手

HA有很多捆绑的助手来听特定类型的事件。有一些助手可以跟踪时间点、时间间隔、状态变化或日落。 See available methods.

使用状态

Home Assistant在状态机中跟踪实体的状态。状态机的需求非常少:

每个状态都与一个由实体id标识的实体相关。这个id由域和对象id组成。例如light.kitchen_ceiling。您可以任意组合域和对象id，甚至重写已存在状态。
每个状态都有一个描述实体状态的主属性。在灯的例子中，这可以是“开”和“关”。你可以在状态中存储任何你想要的东西，只要它是一个字符串(如果不是将被转换)。
通过设置属性，可以存储实体的更多信息。属性是一个字典，可以包含您想要的任何数据。唯一的要求是它是JSON可序列化的，所以你只能使用数字、字符串、字典和列表。

Description of the state object.

在组件中使用状态

这是一个关于如何创建和设置状态的简单教程/示例。我们将在一个名为“hello_state”的组件中进行工作。这个组件的目的是在前端显示给定的文本。

首先，创建文件<config dir>/custom_components/hello_state.py并复制以下示例代码。

"""
Support for showing text in the frontend.

For more details about this component, please refer to the documentation at
https://developers.home-assistant.io/docs/dev_101_states
"""
import logging

_LOGGER = logging.getLogger(__name__)

DOMAIN = "hello_state"


def setup(hass, config):
    """Setup the Hello State component. """
    _LOGGER.info("The 'hello state' component is ready!")

    return True

在文件头中，我们决定添加一些细节:一个简短的描述和文档链接。
我们想做一些日志记录。这意味着我们要导入Python日志模块并创建一个别名。
组件名称等于域名。
setup函数将负责组件的初始化。组件将只写入日志消息。请记住，你有几个选项的严重性:
1. _LOGGER.info(msg)
2. _LOGGER.warning(msg)
3. _LOGGER.error(msg)
4. _LOGGER.critical(msg)
5. _LOGGER.exception(msg)
如果一切ok返回True

将该组件添加到configuration.yaml文件

1	hello_state:

启动或重新启动Home Assistant之后，组件将在日志中创建一个条目。

1	16-03-12 14:16:42 INFO (MainThread) [custom_components.hello_state] The 'hello state' component is ready!

下一步是引入配置选项。用户可以通过configuration.yaml向我们的组件传递配置选项。要使用它们，我们将使用传递给setup方法的config变量。

import logging

_LOGGER = logging.getLogger(__name__)

DOMAIN = "hello_state"

CONF_TEXT = "text"
DEFAULT_TEXT = "No text!"


def setup(hass, config):
    """Set up the Hello State component. """
    # Get the text from the configuration. Use DEFAULT_TEXT if no name is provided.
    text = config[DOMAIN].get(CONF_TEXT, DEFAULT_TEXT)

    # States are in the format DOMAIN.OBJECT_ID
    hass.states.set("hello_state.Hello_State", text)

    return True

要使用组件的最新特性，请更新configuration.yaml文件中的配置选项

1 2	hello_state: text: 'Hello, World!'

多亏了DEFAULT_TEXT变量，即使configuration.yaml中没有使用text:字段，组件也会启动。通常需要一些变量。检查是否提供了所有必需的配置变量是很重要的。如果没有，设置应该会失败。我们将使用voluptuous作为一个助手来实现这一点。下一个清单显示了基本部分。

import voluptuous as vol

import homeassistant.helpers.config_validation as cv

CONFIG_SCHEMA = vol.Schema(
    {DOMAIN: vol.Schema({vol.Required(CONF_TEXT): cv.string,})}, extra=vol.ALLOW_EXTRA
)

现在，当配置中缺少text:时，Home Assistant将提醒用户，而不是设置组件。

启动或重新启动Home Assistant后，如果configuration.yam文件是最新的,则该组件将在前端中可见。

为了公开平台的属性，你需要在实体类上定义一个名为extra_state_attributes的属性，它将返回一个属性字典:

@property
def extra_state_attributes(self):
    """Return entity specific state attributes."""
    return self._attributes

实体也有一个类似的属性state_attributes，它不应该被集成覆盖。基本实体组件使用此属性向状态添加标准属性集。例如:light组件使用state_attributes将亮度添加到状态字典中。如果要设计一个新的集成，则应该定义extra_state_attributes。

要将您的集成包含在HA版本中，请遵循提交您的工作部分中描述的步骤。基本上，你只需要将你的集成移动到你的fork的homeassistant/component/目录下，并创建一个Pull Request。

使用配置

根据您在代码中的位置，配置可以意味着各种各样的事情。

在hass对象上

在hass对象上，它是Config类的一个实例。Config类包含用户首选的单元、配置目录的路径以及要加载的组件。 See available methods.

传递给组件启动的配置

传递给组件设置的config参数是一个包含所有用户提供的配置的字典。字典的键是组件名称，值是另一个带有组件配置的字典。

该对象将已经使用CONFIG_SCHEMA或PLATFORM_SCHEMA(如果可用的话)验证过了。如果你已经定义了一个PLATFORM_SCHEMA，所有对你的组件的引用(例如light 2: etc)将被修改为config[DOMAIN]下的列表。

如果您的配置文件包含以下行:

1 2	example: host: paulusschoutsen.nl

然后在组件的setup方法中，你可以参考config['example']['host']来获得paulusschoutsen.nl的值。

传递给平台启动的配置

传递给平台设置函数的config参数只是该特定平台的配置。

介绍

The hass object

Where to find hass