农业环境监测 — 部署指南

AI 辅助通道

还没定硬件?还是设备已到手准备安装?

不想在网页上手动勾选或敲命令?你可以让 AI 助手根据现场情况自动核算主机与配件,或者在设备通电后一键运行脚本自动安装。

方案自助咨询与部署
套餐

SenseCAP 云

SenseCAP S21xx 节点已通过 SenseCAP M2 网关上报到 SenseCAP 云,射频侧不做改动。桥容器从云端拉取历史与实时数据,发布为本地 Home Assistant 实体。

  • 主机: 一台装 Docker 的 Linux 主机,运行 Home Assistant、MQTT broker 和桥。
  • 账号: SenseCAP Portal 账号和一对 API 密钥。
  • 已知限制: 云 MQTT 有两个候选域名,部署时二选一,首次部署后先看桥的日志确认连接成功。
1

部署 Home Assistant 与 broker

在一台主机上启动 Home Assistant 和 Mosquitto broker。已有这两样且桥能连上现有 broker 时可跳过。

前置条件
  1. 主机至少 8 GB 可用磁盘。
  2. 8123 与 1883 端口空闲,或在本步骤的输入里改端口。
  3. 设定一个 broker 密码并记下,桥那一步要填同一个值。
故障排查
现象处理
8123 或 1883 已被占用停掉已有的 Home Assistant 或 Mosquitto,或在本步骤的输入里改端口
Mosquitto 反复重启并报 Unable to open pwfile把密码文件属主改为 mosquitto 用户
Home Assistant 一直不响应 8123首次启动需要几分钟,执行 docker logs agri-env-homeassistant 查看
部署连不上确认 SSH 可达、用户名正确(Raspberry Pi OS 用 pi,reComputer 用 recomputer)
部署方式

通过 SSH 部署到一台装 Docker 的 Linux 主机,amd64 或 arm64 均可。

部署时需要填写(在 SenseCraft Solution 应用里填)
  • 主机地址*

    将要运行 Home Assistant 与 broker 的那台机器

  • SSH 用户名*默认 pi

    常见默认值:pi(Raspberry Pi OS)、recomputer(Seeed reComputer)、ubuntu。

  • SSH 密码*
  • 时区*默认 Asia/Shanghai

    IANA 时区名——决定看板上时间戳的显示

  • Home Assistant 端口*默认 8123

    如果这台机器上 8123 已被占用,改成别的端口

  • MQTT 端口*默认 1883
  • MQTT 用户名*默认 agrienv

    Home Assistant 的 MQTT 集成与桥都用这一组;broker 不接受匿名连接

  • MQTT 密码*

    记下来——下一步还要填同一个值

2

部署云桥接

部署读取 SenseCAP 云的桥,它会列出账号下的设备、回填历史,然后订阅实时数据。

前置条件
  1. SenseCAP API 密钥(Access ID 与 Access Key),在 SenseCAP Portal「安全 → Access API Keys」获取。
  2. 步骤 1 的 broker 地址、端口、用户名与密码。桥在另一台机器上时,地址填局域网 IP,不要填 127.0.0.1。
  3. 回填窗口:最多三个月,窗口越长请求越多。
故障排查
现象处理
桥的日志显示云端域名 DNS 失败在 MQTT 域名选择框换另一个域名重新部署
桥的日志显示认证失败检查 Access ID 与 Access Key 是否配对、密钥是否已在 Portal 吊销
设备出现了但没有数值回填只写入每个实体的最新值;节点按小时上报时,第一条实时更新最多等一小时
部署时报 no such image自建了 BRIDGE_IMAGE 时,先在本地构建再重跑
broker 里没有数据桥不在 Home Assistant 主机上时,broker 地址改填局域网 IP
部署方式

通过 SSH 把桥部署到一台装 Docker 的主机。

部署时需要填写(在 SenseCraft Solution 应用里填)
  • 桥的主机地址*

    运行桥容器的机器——通常就是运行 Home Assistant 的那台

  • SSH 用户名*默认 pi
  • SSH 密码*
  • 时区*默认 Asia/Shanghai
  • MQTT Broker 地址*默认 127.0.0.1

    与 Home Assistant 一起部署的那个 broker。桥不在同一台机器上时,填局域网地址而不是 127.0.0.1。

  • MQTT 端口*默认 1883
  • MQTT 用户名*默认 agrienv
  • MQTT 密码*

    与 Home Assistant 那一步填的是同一个值

  • SenseCAP Access ID*

    在 SenseCAP Portal 的「安全 → Access API Keys」里获取

  • SenseCAP Access Key*

    API 密钥对的密钥部分。只写入目标主机上权限 600 的 .env 文件。

  • SenseCAP 云 MQTT 地址*默认 sensecap-openstream.seeed.cc
    2 项可选
    • · sensecap-openstream.seeed.cc——已上线 Seeed 方案在用的值
    • · openstream.api.sensecap.seeed.cc——文档里出现的值

    目前流传两个域名。先用默认值;如果桥的日志显示 DNS 或认证失败,改用另一个重新部署。

  • 回填范围*默认 1
    3 项可选
    • · 不回填——只取实时数据
    • · 1 个月
    • · 3 个月——接口上限

    首次启动时向前拉多久的历史。OpenAPI 最多回溯三个月、单次一个月,窗口越长请求越多。

  • 离线判定时长(秒)*默认 7200

    超过这么久没有上行就在 Home Assistant 里标记为离线。默认是 S210x 两个上报周期加余量——节点上报间隔超过一小时就调大。

3

在 Home Assistant 里核对数据

打开 Home Assistant,确认节点以设备和实体出现。

故障排查
现象处理
MQTT 集成连上了但没有设备执行 docker logs agri-env-bridge-cloud,确认有云端连接成功的日志
实体一出现就是 unavailable确认节点在上报,且离线判定时长不短于上报间隔
某个实体没有单位把它的 measurementId 加进 assets/config/measurements.yaml
旧的实体 ID 总是回来同时清掉 broker 的 retained 消息和 Home Assistant 的实体注册表

部署完成后

账号下每个节点是一台名为 SenseCAP <DevEUI> 的 Home Assistant 设备,每个测量项一个实体。

快速验证

  1. 登录 Home Assistant,全新安装时先完成引导向导。
  2. 「设置 → 设备与服务 → 添加集成 → MQTT」,broker 填运行本套服务的主机、端口 1883、步骤 1 的用户名密码。已配过 MQTT 就跳过。
  3. 打开 MQTT 集成,打开一台设备,实体带单位(°C、%、dS/m)。
  4. 导入看板:「概览 → 右上角三点 → 编辑仪表板 → 三点 → 原始配置编辑器」,粘贴 assets/homeassistant/agri_env_dashboard.yaml,把示例 DevEUI 换成自己的。
  5. 导入阈值告警:把 assets/homeassistant/automations.yaml 并入 Home Assistant 的 automations.yaml 并重载自动化。随包的 for: 持续时间为零,现场使用前按需调整阈值与持续时间,避免单次读数抖动误报。

下一步

  • 把离线判定时长调成与节点上报间隔匹配。默认按每小时上报设置,每六小时上报的节点会在两次上行之间被标为离线。
  • 把需要据以操作的实体单独放一个视图。