SenseCAP S21xx 节点已通过 SenseCAP M2 网关上报到 SenseCAP 云,射频侧不做改动。桥容器从云端拉取历史与实时数据,发布为本地 Home Assistant 实体。
- 主机: 一台装 Docker 的 Linux 主机,运行 Home Assistant、MQTT broker 和桥。
- 账号: SenseCAP Portal 账号和一对 API 密钥。
- 已知限制: 云 MQTT 有两个候选域名,部署时二选一,首次部署后先看桥的日志确认连接成功。
不想在网页上手动勾选或敲命令?你可以让 AI 助手根据现场情况自动核算主机与配件,或者在设备通电后一键运行脚本自动安装。
SenseCAP S21xx 节点已通过 SenseCAP M2 网关上报到 SenseCAP 云,射频侧不做改动。桥容器从云端拉取历史与实时数据,发布为本地 Home Assistant 实体。
在一台主机上启动 Home Assistant 和 Mosquitto broker。已有这两样且桥能连上现有 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 均可。
将要运行 Home Assistant 与 broker 的那台机器
pi常见默认值:pi(Raspberry Pi OS)、recomputer(Seeed reComputer)、ubuntu。
Asia/ShanghaiIANA 时区名——决定看板上时间戳的显示
8123如果这台机器上 8123 已被占用,改成别的端口
1883agrienvHome Assistant 的 MQTT 集成与桥都用这一组;broker 不接受匿名连接
记下来——下一步还要填同一个值
部署读取 SenseCAP 云的桥,它会列出账号下的设备、回填历史,然后订阅实时数据。
127.0.0.1。| 现象 | 处理 |
|---|---|
| 桥的日志显示云端域名 DNS 失败 | 在 MQTT 域名选择框换另一个域名重新部署 |
| 桥的日志显示认证失败 | 检查 Access ID 与 Access Key 是否配对、密钥是否已在 Portal 吊销 |
| 设备出现了但没有数值 | 回填只写入每个实体的最新值;节点按小时上报时,第一条实时更新最多等一小时 |
部署时报 no such image | 自建了 BRIDGE_IMAGE 时,先在本地构建再重跑 |
| broker 里没有数据 | 桥不在 Home Assistant 主机上时,broker 地址改填局域网 IP |
通过 SSH 把桥部署到一台装 Docker 的主机。
运行桥容器的机器——通常就是运行 Home Assistant 的那台
piAsia/Shanghai127.0.0.1与 Home Assistant 一起部署的那个 broker。桥不在同一台机器上时,填局域网地址而不是 127.0.0.1。
1883agrienv与 Home Assistant 那一步填的是同一个值
在 SenseCAP Portal 的「安全 → Access API Keys」里获取
API 密钥对的密钥部分。只写入目标主机上权限 600 的 .env 文件。
sensecap-openstream.seeed.cc目前流传两个域名。先用默认值;如果桥的日志显示 DNS 或认证失败,改用另一个重新部署。
1首次启动时向前拉多久的历史。OpenAPI 最多回溯三个月、单次一个月,窗口越长请求越多。
7200超过这么久没有上行就在 Home Assistant 里标记为离线。默认是 S210x 两个上报周期加余量——节点上报间隔超过一小时就调大。
打开 Home Assistant,确认节点以设备和实体出现。
| 现象 | 处理 |
|---|---|
| MQTT 集成连上了但没有设备 | 执行 docker logs agri-env-bridge-cloud,确认有云端连接成功的日志 |
实体一出现就是 unavailable | 确认节点在上报,且离线判定时长不短于上报间隔 |
| 某个实体没有单位 | 把它的 measurementId 加进 assets/config/measurements.yaml |
| 旧的实体 ID 总是回来 | 同时清掉 broker 的 retained 消息和 Home Assistant 的实体注册表 |
账号下每个节点是一台名为 SenseCAP <DevEUI> 的 Home Assistant 设备,每个测量项一个实体。
°C、%、dS/m)。assets/homeassistant/agri_env_dashboard.yaml,把示例 DevEUI 换成自己的。assets/homeassistant/automations.yaml 并入 Home Assistant 的 automations.yaml 并重载自动化。随包的 for: 持续时间为零,现场使用前按需调整阈值与持续时间,避免单次读数抖动误报。一个专门的运维控制台,把 agri-env 桥发布的规范化数据渲染成专门的看板——与 Home Assistant 并行的专注视图。只需一个容器,无需云账号:它订阅桥的 MQTT 输出,显示桥解码出的数据。
assets/custom_dashboard/MISSION-PACK.md。部署看板桥,订阅 agri-env 桥的规范化 MQTT 输出。它通过 HTTP 提供运维控制台,并通过 WebSocket 推送实时更新。
| 现象 | 处理 |
|---|---|
| 看板日志显示 MQTT 认证失败 | 核对 broker 用户名和密码,以及该账号是否有权读取传感器主题 |
| 看板日志显示连接被拒绝或超时 | 核对 broker 地址和端口,并确认这台主机能访问到 broker(不在同一台机器时用局域网 IP,不要用 127.0.0.1) |
| 页面能打开但每个来源都显示“无数据” | 按小时上报的传感器可能要等最多一小时;在 /admin 查看每个来源的数据健康 |
部署时报 no such image | 使用自建 OPS_DASHBOARD_IMAGE 时,先在本地构建再重新部署 |
| 端口被占用 | 停掉占用端口的程序,或在本步的输入里改用其他 HTTP 端口(reComputer R1000 上用 8001) |
通过 SSH 部署到一台装了 Docker 的 Linux 主机;amd64 和 arm64 都可以。
Asia/Shanghai8000运维控制台对外服务的端口。在 reComputer R1000 上 8000 被占用,请改用 8001。
8765你的传感网关已经在上报的那个 broker。填这台主机能访问到的局域网 IP 或域名。
18830如果 broker 允许匿名读取可留空
只写入目标主机上权限 600 的 .env 文件
如果你的 relay 使用前缀,会加在传感器主题前面。没有则留空。
agri_env/+/+/stateagri-env 桥发布的规范化状态主题。三个接入套餐(或单独的桥)之一必须在运行——本看板读取它的输出。
打开运维控制台,确认你的传感器出现。
| 现象 | 处理 |
|---|---|
| 页面打不开 | 确认容器在运行(docker ps),且 HTTP 端口是你设置的那个 |
| MQTT 显示未连接 | 重新核对第 1 步的 broker 地址、端口和凭据 |
| 来源一直显示“无数据” | 确认传感器在上报,且主题 / 前缀与你的 relay 发布的一致 |
看板订阅你的 broker,渲染它解码出的每一条读数,历史保存在主机上。
http://<主机>:<http_port>/ops,页面加载出运维控制台。/admin 上查看。自建 LoRaWAN 网络服务器(ChirpStack 或 The Things Stack),适用于完全离网私有化部署。可使用 SenseCAP M2 网关内置的 ChirpStack,或在 reComputer R12 系列网关上通过 Docker 运行 ChirpStack 或 The Things Stack,SenseCAP S21xx 节点数据全程不经外网。
在一台主机上启动 Home Assistant 和 Mosquitto broker。已有这两样且桥能连上现有 broker 时可跳过。
| 现象 | 处理 |
|---|---|
| 8123 或 1883 已被占用 | 停掉占用端口的进程,或在本步骤的输入里改端口 |
Mosquitto 反复重启并报 Unable to open pwfile | 把密码文件属主改为 mosquitto 用户 |
| Home Assistant 一直不响应 8123 | 首次启动需要几分钟,执行 docker logs agri-env-homeassistant 查看 |
| 部署连不上 | 检查 SSH 与所用系统镜像的用户名 |
通过 SSH 部署到一台装 Docker 的 Linux 主机。
将要运行 Home Assistant 与 broker 的那台机器
pi常见默认值:pi(Raspberry Pi OS)、recomputer(Seeed reComputer)、ubuntu。
Asia/ShanghaiIANA 时区名——决定看板上时间戳的显示
8123如果这台机器上 8123 已被占用,改成别的端口
1883agrienvHome Assistant 的 MQTT 集成与桥都用这一组;broker 不接受匿名连接
记下来——下一步还要填同一个值
让 M2 脱离云端并打开内置的 ChirpStack。如果使用 R12 网关,可跳过本步骤。
LoRa → LoRa Network,与此不同时先核对固件版本。| 现象 | 处理 |
|---|---|
| Portal 里不再出现上行 | 本地模式下属正常 |
| 内置 ChirpStack 里没有 application | 在步骤 7 入网前先建好 tenant、application 与 device profile |
上行到了但没有 object | 把节点系列对应的 SenseCAP decoder 粘进 device profile 的 codec |
使用 reComputer R12 系列网关搭配 ChirpStack 时进行本步骤:接好天线、确认 SPI 设备并将 packet forwarder 指向本地 ChirpStack 桥。如果使用 M2 网关或搭配 The Things Stack 的 R12,可跳过此步。
/dev/spidev0.0 存在,没有就打开 SPI 后重启。| 现象 | 处理 |
|---|---|
| forwarder 退出且没打印 EUI | 确认 SPI 已打开,再核对 reset 引脚 |
网关的 Last seen 一直不更新 | 检查防火墙是否放行 UDP 1700 |
| concentratord 起来了但 gateway bridge 收不到数据 | 先改用 UDP packet forwarder 跑通上行,再排查容器内能否访问 concentratord 的 ZMQ 端点 |
使用 reComputer R12 系列网关搭配 The Things Stack 时进行本步骤:在 R12 上接好天线、确认 SPI 设备,并运行指向 The Things Stack 的 packet forwarder。如果使用 M2 网关或搭配 ChirpStack 的 R12,可跳过此步。
/dev/spidev0.0 存在,没有就打开 SPI 后重启。| 现象 | 处理 |
|---|---|
| forwarder 退出且没打印 EUI | 确认 /dev/spidev0.0 存在,再核对 reset 引脚 |
| Console 里网关一直未连接 | 检查防火墙是否放行到 stack 主机的 UDP 1700 |
| 集中器起来了但没有上行 | 核对网关频段、频率计划与节点频段是否一致 |
选 m2 只启动桥;选 local 则在本机同时启动 ChirpStack。如果选择使用 The Things Stack(步骤 6),可跳过本步骤。
m2 路线:步骤 2 里 M2 的 broker 地址、端口、用户名与密码。local 路线:至少 8 GB 可用磁盘,频率计划与网关和节点一致。+ 订阅该 broker 上的所有 application。| 现象 | 处理 |
|---|---|
桥的日志里没有 ChirpStack MQTT connected | m2 路线核对网关 LoRa Network 页面上的地址与凭据;local 路线执行 docker compose --profile local-lns ps |
local 路线上 ChirpStack 服务没起来 | 确认 lns_mode 选的是 local 后重跑本步骤 |
| 8080 上的 Web 界面访问不到 | 只有 local 路线有该界面,m2 路线在网关的 Web 界面操作 |
部署时报 no such image | 自建了 BRIDGE_IMAGE 时,先在本地构建再重跑 |
通过 SSH 部署到运行桥的主机。
运行桥的那台机器——第一条路线是 R1000,M2 路线上任意一台 Linux 主机都行
piAsia/Shanghaim2网关自带网络服务器就选 `m2`,本机只起桥。选 `local` 则在 reComputer R12 系列网关上跑 ChirpStack。
eu868只在 `local` 路线用。必须同时与集中器频段和节点频段一致——不一致的表现就是网关什么都收不到。
chirpstack-mosquittoM2 路线填 M2 自己的地址。`local` 路线保留默认值——那是本 compose 项目里的 broker。
1883`local` 路线留空。M2 路线填网关 LoRa Network 页面上显示的凭据。
+桥要订阅的 ChirpStack application UUID。填 `+` 表示订阅该 broker 上的所有 application——单租户部署这样最省事。
与 Home Assistant 一起部署的那个 Mosquitto——桥把实体发到这里
1883agrienv7200超过这么久没有上行就在 Home Assistant 里标记为离线
如果选择使用 The Things Stack,启动 The Things Stack(含 Postgres 与 Redis)并初始化,同时启动桥。首次运行预留 15–30 分钟。如果已在步骤 5 部署 ChirpStack,可跳过本步骤。
127.0.0.1,否则其他机器无法登录 Console)。| 现象 | 处理 |
|---|---|
is-db migrate 失败 | Postgres 未就绪,重跑初始化 |
| Console 打得开但登录反复跳转 | 用主机局域网 IP 重新部署 |
桥的日志里没有 TTS MQTT connected | 在步骤 8 创建 application 和 API key 后更新 .env 并重建桥容器 |
| stack 容器一起来就被杀 | 检查主机可用内存 |
通过 SSH 部署到网关主机。
运行集中器与本 stack 的那台机器。浏览器和 packet forwarder 都要能访问到它——不能填 127.0.0.1。
piAsia/Shanghai创建管理员账号用的邮箱地址。不会发到任何地方——本 stack 没有配邮件服务。
用于登录 1885 端口的 Console
与 Home Assistant 一起部署的那个 Mosquitto——桥把实体发到这里
1883agrienvagri-env稍后要在 Console 里创建的 application。桥订阅它的上行。
格式:{application-id}@{tenant-id}。自建开源版里各 application 的 tenant 通常是同一个字符串。
有读取 application 流量权限的 API key。在 Console 的「Integrations → MQTT」里创建,只显示一次。首次部署保留默认占位值,待 Console 启动后创建并回填。
7200超过这么久没有上行就在 Home Assistant 里标记为离线
在 ChirpStack 里注册节点、配置 payload decoder,并让节点入网。
| 现象 | 处理 |
|---|---|
| ChirpStack 提示 DevEUI 已存在 | DevEUI 在另一个租户下已存在,从其他网络迁入节点时很常见 |
| 有 join request 但没有 accept | 核对密钥和区域参数 |
| 连 join request 都没有 | 先看网关状态,确认网关能收到节点信号 |
上行到了但没有 object.messages | 在 device profile 里配好对应节点系列的编解码器 |
创建 application、安装 payload formatter、让节点入网。在 Console 生成 API Key 后,在部署目录下回填并重建桥接容器:
sed -i 's/^TTN_MQTT_PASSWORD=.*/TTN_MQTT_PASSWORD="<生成的API_Key>"/' .env
docker compose up -d bridge
Connected。| 现象 | 处理 |
|---|---|
| 有 join request 但没有 join accept | 核对密钥和区域参数 |
| 连 join request 都没有 | 先看网关状态,确认网关收到节点信号 |
上行到了但没有 decoded_payload | 在该 application 上安装 payload formatter |
有 decoded_payload 但没有 messages 数组 | 换成与节点系列对应的 decoder |
打开 Home Assistant 确认节点已出现;无公网部署还要确认断网后照常工作。
| 现象 | 处理 |
|---|---|
设备出现了但实体是 unavailable | 核对上报间隔与离线判定时长 |
| 一断 WAN 实体就停更 | 查看桥的日志和网关的网络页面,找出仍访问外网的环节 |
| 某个实体没有单位 | 把它的 measurementId 加进 assets/config/measurements.yaml |
| 旧的实体 ID 总是回来 | 同时清掉 broker 的 retained 消息和实体注册表 |
从节点到看板的数据都在本地网络内,不依赖云账号。每个入网节点在 Home Assistant 里是一台名为 SenseCAP <DevEUI> 的设备,每个测量项一个实体。
SenseCAP <DevEUI> 的设备,打开一台确认实体带单位(°C、%、dS/m)。assets/homeassistant/agri_env_dashboard.yaml 粘进 Lovelace 原始配置编辑器,把示例 DevEUI 换成自己的。assets/homeassistant/automations.yaml 并入 Home Assistant 的 automations.yaml,重载自动化,按现场设置阈值与 for: 持续时间。看板跑通后做一次: