bachya/ecowitt2mqtt Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

🔘 ecowitt2mqtt: 将Ecowitt设备数据发送到MQTT代理

![PyPi]([] ![Docker Hub]([] ![Version]([] ![License]([] ![Code Coverage]([] ![Maintainability]([] ![Say Thanks]([***]

ecowitt2mqtt 是一个小型命令行界面/ Web服务器，允许将Ecowitt设备数据发送到MQTT代理。

• 安装
• Python版本
• 快速开始
• 配置
  • 命令行选项
  • 环境变量
  • 配置文件
  • 合并配置选项
• 高级用法
  • 电池配置
  • 单位系统
  • 原始数据
  • Home Assistant
  • 后台运行
  • Docker
• 贡献

安装

python
pip install ecowitt2mqtt

Python版本

ecowitt2mqtt 目前支持以下Python版本：

• Python 3.8
• Python 3.9
• Python 3.10

快速开始

请注意，本README假设：

• 您可以访问MQTT代理。
• 您已经通过Ecowitt的WS View Android/iOS应用配对了Ecowitt设备。

首先，通过pip安装ecowitt2mqtt：

bash
$ pip install ecowitt2mqtt

然后，在您的Android/iOS设备上打开WS View应用。在应用中查看设备时，选择“气象服务”：

!选择气象服务

按“下一步”直到进入“自定义”屏幕：

!WS View应用中的自定义屏幕

使用以下值填写表单并点击“保存”：

• “协议类型”：“Ecowitt”
• “服务器IP/主机名”：运行ecowitt2mqtt的设备的IP地址/主机名
• “路径”：/data/report（注意：与WS View应用中的默认值不同，此处不应有尾部斜杠）
• “端口”：8080（ecowitt2mqtt 提供服务的默认端口）
• “上传间隔”：60（更改此值可调整数据发布频率）

然后，在安装了ecowitt2mqtt的机器上运行它：

bash
$ ecowitt2mqtt \
    --mqtt-broker=192.168.1.101 \
    --mqtt-username=user \
    --mqtt-password=password \
    --mqtt-topic=ecowitt2mqtt/device_1

在“上传间隔”内，数据应开始出现在MQTT代理中。

配置

ecowitt2mqtt 可通过命令行选项、环境变量或（YAML或JSON）配置文件进行配置。

命令行选项

用法: ecowitt2mqtt [选项] 命令 [参数]...

  ecowitt2mqtt 将Ecowitt设备数据发送到MQTT代理。

选项:
  --battery-override TEXT         电池配置覆盖（格式：key,value）[环境变量:
                                  ECOWITT2MQTT_BATTERY_OVERRIDE]
  -c, --config FILE               配置文件路径。[环境变量: ECOWITT2MQTT_CONFIG]
  --default-battery-strategy TEXT
                                  使用的默认电池配置策略。[环境变量: ECOWITT2MQTT_DEFAULT_BATTERY_STRATEGY;
                                  默认值: boolean]
  -e, --endpoint TEXT             提供ecowitt2mqtt服务的相对端点/路径。[环境变量:
                                  ECOWITT2MQTT_ENDPOINT, ENDPOINT; 默认值: /data/report]
  --hass-discovery                以Home Assistant MQTT发现格式发布数据。
                                  [环境变量: ECOWITT2MQTT_HASS_DISCOVERY, HASS_DISCOVERY]
  --hass-discovery-prefix TEXT    使用的Home Assistant发现前缀。[环境变量: ECOWITT2MQTT_HASS_DISCOVERY_PREFIX,
                                  HASS_DISCOVERY_PREFIX; 默认值: homeassistant]
  --hass-entity-id-prefix TEXT    Home Assistant实体ID使用的前缀。[环境变量:
                                  ECOWITT2MQTT_HASS_ENTITY_ID_PREFIX, HASS_ENTITY_ID_PREFIX]
  --input-unit-system TEXT        设备使用的输入单位系统。[环境变量: ECOWITT2MQTT_INPUT_UNIT_SYSTEM,
                                  INPUT_UNIT_SYSTEM; 默认值: imperial]
  -b, --mqtt-broker TEXT          MQTT代理的主机名或IP地址。[环境变量: ECOWITT2MQTT_MQTT_BROKER,
                                  MQTT_BROKER]
  -p, --mqtt-password TEXT        MQTT代理的有效密码。[环境变量: ECOWITT2MQTT_MQTT_PASSWORD,
                                  MQTT_PASSWORD]
  --mqtt-port INTEGER             MQTT代理的监听端口。[环境变量: ECOWITT2MQTT_MQTT_PORT,
                                  MQTT_PORT; 默认值: 1883]
  -u, --mqtt-username TEXT        MQTT代理的有效用户名。[环境变量: ECOWITT2MQTT_MQTT_USERNAME,
                                  MQTT_USERNAME]
  -t, --mqtt-topic TEXT           发布设备数据的MQTT主题。[环境变量: ECOWITT2MQTT_MQTT_TOPIC,
                                  MQTT_TOPIC]
  --output-unit-system TEXT       输出中使用的单位系统。[环境变量: ECOWITT2MQTT_OUTPUT_UNIT_SYSTEM,
                                  OUTPUT_UNIT_SYSTEM; 默认值: imperial]
  --port INTEGER                  提供ecowitt2mqtt服务的端口。[环境变量: ECOWITT2MQTT_PORT, PORT;
                                  默认值: 8080]
  --raw-data                      返回原始数据（不尝试转换任何值）。[环境变量: ECOWITT2MQTT_RAW_DATA,
                                  RAW_DATA]
  -v, --verbose                   增加日志输出的详细程度。[环境变量: ECOWITT2MQTT_VERBOSE]
  --install-completion            为当前shell安装补全。
  --show-completion               显示当前shell的补全，以便复制或自定义安装。
  --help                          显示此消息并退出。

环境变量

• ECOWITT2MQTT_BATTERY_OVERRIDE：分号分隔的key=value电池覆盖列表
• ECOWITT2MQTT_CONFIG：YAML或JSON配置文件的路径
• ECOWITT2MQTT_DEFAULT_BATTERY_STRATEGY：使用的默认电池配置策略（默认值：boolean）
• ECOWITT2MQTT_ENDPOINT：提供ecowitt2mqtt服务的相对端点/路径（默认值：/data/report）
• ECOWITT2MQTT_HASS_DISCOVERY：以Home Assistant MQTT发现格式发布数据（默认值：false）
• ECOWITT2MQTT_HASS_DISCOVERY_PREFIX：使用的Home Assistant发现前缀（默认值：homeassistant）
• ECOWITT2MQTT_HASS_ENTITY_ID_PREFIX：Home Assistant实体ID使用的前缀
• ECOWITT2MQTT_INPUT_UNIT_SYSTEM：设备使用的输入单位系统（默认值：imperial）
• ECOWITT2MQTT_MQTT_BROKER：MQTT代理的主机名或IP地址
• ECOWITT2MQTT_MQTT_PASSWORD：MQTT代理的有效密码
• ECOWITT2MQTT_MQTT_PORT：MQTT代理的监听端口（默认值：1883）
• ECOWITT2MQTT_MQTT_TOPIC：发布设备数据的MQTT主题
• ECOWITT2MQTT_MQTT_USERNAME：MQTT代理的有效用户名
• ECOWITT2MQTT_OUTPUT_UNIT_SYSTEM：输出中使用的单位系统（默认值：imperial）
• ECOWITT2MQTT_PORT：提供ecowitt2mqtt服务的端口（默认值：8080）
• ECOWITT2MQTT_RAW_DATA：返回原始数据（不尝试转换任何值）
• ECOWITT2MQTT_VERBOSE：增加日志输出的详细程度

配置文件

配置文件可以格式化为YAML：

yaml
---
battery_override:
  battery_key1: boolean
default_battery_strategy: numeric
endpoint: /data/report
hass_discovery: false
hass_discovery_prefix: homeassistant
hass_entity_id_prefix: test_prefix
input_unit_system: imperial
mqtt_broker: 127.0.0.1
mqtt_password: password
mqtt_port: 1883
mqtt_topic: Test
mqtt_username: user
output_unit_system: imperial
port: 8080
raw_data: false
verbose: false

...或JSON：

json
{
  "battery_override": {
    "battery_key1": "boolean"
  },
  "default_battery_strategy": "numeric",
  "endpoint": "/data/report",
  "hass_discovery": false,
  "hass_discovery_prefix": "homeassistant",
  "hass_entity_id_prefix": "test_prefix",
  "input_unit_system": "imperial",
  "mqtt_broker": "127.0.0.1",
  "mqtt_password": "password",
  "mqtt_port": 1883,
  "mqtt_topic": "Test",
  "mqtt_username": "user",
  "output_unit_system": "imperial",
  "port": 8080,
  "raw_data": false,
  "verbose": false
}

合并配置选项

解析配置选项时，ecowitt2mqtt按以下顺序查看配置源：

1. 配置文件
2. 环境变量
3. 命令行选项

这允许您混合搭配源——例如，您可以在配置文件中设置“默认值”，并通过环境变量覆盖它们。

高级用法

电池配置

Ecowitt设备报告电池电量的方式非常不一致，难以自动将其值解析为有意义的内容。ecowitt2mqtt通过两种机制解决此问题：默认电池“策略”和电池覆盖。

默认电池策略

通过使用--default-battery-strategy配置参数，用户可以指定电池默认应如何处理：

• boolean：0表示“正常”（即电池状态正常），1表示“低电量”（即电池电量低）。
• numeric：原始数值被解释为电池中剩余的电压量。

电池覆盖

可以覆盖单个电池并为其指定新策略。这允许用户（例如）默认将所有电池解释为boolean，但将特定电池解释为numeric。实现方式因使用的配置方法略有不同：

• 命令行选项：提供一个或多个--battery-override "batt1=boolean"选项
• 环境变量：提供ECOWITT2MQTT_BATTERY_OVERRIDE变量，该变量是分号分隔的“key=value”字符串对（例如，ECOWITT2MQTT_BATTERY_OVERRIDE="batt1=boolean;batt2=numeric"）
• 配置文件：以YAML或JSON格式包含键/值对字典

示例

在此示例中，用户大多数电池应被视为boolean，但有一个电池wh60_batt1应被视为numeric。

命令行选项

$ ecowitt2mqtt --default-battery-strategy boolean --battery-override="wh60_batt1=numeric"

环境变量

$ ECOWITT2MQTT_DEFAULT_BATTERY_STRATEGY=boolean \
  ECOWITT2MQTT_BATTERY_OVERRIDE="wh60_batt1=numeric" \
  ecowitt2mqtt

配置文件

YAML格式：

yaml
---
default_battery_strategy: boolean
battery_override:
  wh60_batt1: numeric

JSON格式：

json
{
  "default_battery_strategy": "boolean",
  "battery_override": {
    "wh60_batt1": "numeric"
  }
}

单位系统

ecowitt2mqtt允许您指定设备的输入和输出单位系统。这非常直观，但请注意使用与设备提供的--input-unit-system一致的单位系统（否则，您的数据将非常“不准确”）。

原始数据

在某些情况下，可能希望阻止ecowitt2mqtt进行任何数据转换（将值转换为新单位系统、将二进制值（如电池可能使用的值）更改为“友好”值等）。传递--raw-data标志将实现此目的：数据将直接从Ecowitt设备传输到MQTT代理，不作任何修改。

请注意，--raw-data标志优先于任何可能导致数据转换的参数（例如--input-unit-system或--output-unit-system）。

Home Assistant

MQTT发现

Home Assistant用户可以通过使用MQTT发现快速添加Ecowitt设备的实体。

一旦Home Assistant配置为接受MQTT发现，ecowitt2mqtt只需使用--hass-discovery标志：

bash
$ ecowitt2mqtt \
    --mqtt-broker=192.168.1.101 \
    --mqtt-username=user \
    --mqtt-password=password \
    --hass-discovery

请注意，如果同时提供--hass-discovery和--mqtt-topic，--hass-discovery将优先。

自定义实体ID前缀

您可以通过--hass-entity-id-prefix配置参数为所有Home Assistant实体提供自定义前缀。

后台运行

ecowitt2mqtt本身不提供任何守护进程机制。建议的方法是使用其他应用程序。

supervisord

示例supervisord配置文件如下：

[supervisord]
nodaemon=true
loglevel=info
user=root

[program:ecowitt2mqtt]
command=ecowitt2mqtt --mqtt-broker=192.168.1.101 --mqtt-username=user --mqtt-password=password
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
redirect_stderr=true

systemd

/etc/systemd/system中的示例systemd服务文件如下：

[Unit]
Description=ECOWITT2MQTT守护进程
After=network.target

[Service]
Type=notify
ExecStart=ecowitt2mqtt --mqtt-broker=192.168.1.101 --mqtt-username=user --mqtt-password=password
ExecReload=kill -HUP $MAINPID
KillMode=process
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

要启用服务：

bash
$ systemctl enable ecowitt2mqtt

Docker

该库可通过Docker镜像（[`bachya/ecowitt2