E-connect Python API

econnect-python是一个API适配器，用于通过编程方式控制类似于Elmo的报警系统。通过通用配置，客户端允许

• 检索访问令牌以进行API调用
• 获取/释放系统 Lock() 以拥有系统的独占控制权
• 武装/解除系统中注册的所有警报
• 查询系统并获取区域和输入的状态

要求

• Python 3.8+
• requests

支持的系统

此包针对类似于Elmo的报警系统。以下系统已知可以工作

• Elmo e-Connect
• IESS Metronet

入门

此包可在PyPI上找到

$ pip install econnect-python

用法

from elmo import query
from elmo.api.client import ElmoClient

# Initialize a new client to authenticate your connection
# and retrieve an access token used for the entire session.
client = ElmoClient()
client.auth("username", "password")

# To arm/disarm the system you must gain the exclusive Lock()
with client.lock("secret-code") as c:
    c.arm()                # Arm all alarms
    c.disarm()             # Disarm all alarms
    c.arm(sectors=[3, 4])  # Arm only sectors 3 and 4
    c.disarm(sectors=[3])  # Disarm only sector 3

# Query the system
sectors = client.query(query.SECTORS)
inputs = client.query(query.INPUTS)

访问令牌有效期为10分钟，之后您需要再次进行身份验证以刷新令牌。通过 client.lock("secret-code") 获取锁是武装或解除系统的强制要求，否则API将返回 403。 secret-code 是您从报警面板用于武装/解除系统的数字代码。

一旦获得锁，其他客户端无法连接到报警系统，并且仅允许在终端上进行手动覆盖。在上下文管理器外，锁会自动释放。

连接到系统

默认情况下，ElmoClient 构造函数将自动连接到Elmo e-Connect系统。但是，如果您需要连接到不同的系统，则 systems 模块提供了一份可用的报警系统列表供您选择。

以下是使用方法

from elmo.api.client import ElmoClient
from elmo.systems import ELMO_E_CONNECT, IESS_METRONET

# Connect to the default Elmo e-Connect system
client = ElmoClient()

# Explicitly connect to the Elmo e-Connect system
client = ElmoClient(base_url=ELMO_E_CONNECT)

# Connect to the IESS Metronet system
client = ElmoClient(base_url=IESS_METRONET)

注意：默认构造函数（无参数）保持不变，以确保向后兼容性，并且与显式调用 ELMO_E_CONNECT 的行为相同。

自定义URL

如果 https://connect.elmospa.com 或 https://metronet.iessonline.com 是您的认证页面，则无需配置，您可以跳过本节。

另一方面，如果您的认证页面类似于 https://connect3.elmospa.com/nwd，您必须按照以下方式配置您的客户端

from elmo.api.client import ElmoClient

# Override the default URL and domain
client = ElmoClient(base_url="https://connect3.elmospa.com", domain="nwd")
client.auth("username", "password")

如果您的 base_url 或 domain 没有正确设置，您的凭据将不起作用，并且您将收到一个 403 客户端错误，因为您的用户名和密码不正确。

贡献

我们非常欢迎社区的贡献——无论是快速修复一个错别字，还是完全新的功能！您不需要是 Python 专家就能提供有意义的改进。要了解如何开始，请首先查看我们的 贡献指南，如果您有问题，请在我们 Discord 频道 中寻求帮助。

开发

尽管该项目最初是为了个人使用，但我们欢迎外部贡献。如果您认为某些部分可以以更通用的接口公开，请打开 GitHub 问题 讨论您的建议。

开发环境

要在终端中创建虚拟环境并安装项目和其依赖项，请执行以下命令

# Create and activate a new virtual environment
python3 -m venv venv
source venv/bin/activate

# Upgrade pip and install all projects and their dependencies
pip install --upgrade pip
pip install -e '.[all]'

# Install pre-commit hooks
pre-commit install

编码指南

为了保持代码库的一致性，我们使用了 flake8 和 black。一致性至关重要，因为它有助于可读性，减少错误，并促进开发者之间的协作。

为了确保每次提交都符合我们的编码标准，我们已集成 pre-commit 钩子。这些钩子在每次提交前自动运行 flake8 和 black，确保所有代码更改都自动检查和格式化。

有关如何设置您的开发环境以利用这些钩子的详细信息，请参阅我们文档中的 开发 部分。

测试

确保我们代码的健壮性和可靠性至关重要。因此，所有贡献都必须包括至少一个测试来验证预期行为。

要本地运行测试，请使用以下命令执行测试套件

pytest tests/ --cov --cov-branch -vv

要使用 tox 运行全面测试，该测试与所有支持的 Python 版本的持续集成（CI）环境相匹配，请使用 tox

tox

注意：为了有效地使用 tox，请确保您已安装所有必要的 Python 版本。如果缺少任何版本，tox 将提供相关警告。