Wavelog 中的 MQTT 集成

Wavelog 中的 MQTT 集成（MQTT Integration in Wavelog）

目录

• 配置
  • 最小示例
  • 完整示例（含认证与自定义前缀）
• 主题
  • 通过界面记录的 QSO
  • 通过 REST API 记录的 QSO
  • CAT（电台控制）状态更新
• 载荷
  • QSO 事件载荷
  • CAT 事件载荷
• 订阅——快速示例
  • mosquitto_sub（命令行）
• 故障排查

每当记录一次 QSO 或 CAT（电台控制）状态发生变化时，Wavelog 都可以向 MQTT 代理（broker）发布实时事件。这样外部应用——仪表盘、家庭自动化系统、显示屏、脚本——无需轮询 Wavelog API 即可对业余无线电活动做出反应。

MQTT 支持是可选的。即使不启用，应用也能正常运行。发布采用 QoS 0 的「即发即忘」方式；如果代理不可达，Wavelog 会记录错误并继续运行，不受影响。

配置

所有 MQTT 设置都位于 application/config/config.php。这些选项默认均不存在——只添加你需要的项。

最小示例

$config['mqtt_server'] = 'broker.example.com';

完整示例（含认证与自定义前缀）

$config['mqtt_server']   = 'broker.example.com';
$config['mqtt_port']     = 1883;
$config['mqtt_username'] = 'wavelog';
$config['mqtt_password'] = 'secret';
$config['mqtt_prefix']   = 'wavelog/';

TLS/SSL： 底层的 phpMQTT 库支持 TLS。默认使用标准明文 TCP。如需使用 TLS，请调整端口（通常为 8883）并相应配置你的代理。

主题

所有主题都带有 mqtt_prefix 的值作为前缀（默认 wavelog/）。因此订阅者看到的完整主题是 {prefix}{topic}。

通过界面记录的 QSO

wavelog/qso/logged/{user_id}

每当通过 Wavelog Web 界面保存一条新通联时发布。

通过 REST API 记录的 QSO

wavelog/qso/logged/api/{user_id}

每当通过 Wavelog REST API 保存一条新通联时发布（例如来自 Log4OM、经桥接的 WSJT-X 等记录软件）。

CAT（电台控制）状态更新

wavelog/cat/{user_id}

每当 Wavelog 从已连接的电台控制应用收到 CAT 更新（频率、模式、功率、卫星数据）时发布。

载荷

所有载荷都是 JSON 编码的 UTF-8 字符串。

QSO 事件载荷

载荷沿用内部使用的 ADIF 字段名。某次 QSO 未设置的字段可能缺省或为 null。

{
  "COL_CALL": "DL1ABC",
  "COL_BAND": "40m",
  "COL_FREQ": "7.074",
  "COL_MODE": "FT8",
  "COL_RST_SENT": "599",
  "COL_RST_RCVD": "599",
  "COL_TIME_ON": "2026-03-14 14:23:00",
  "COL_TIME_OFF": "2026-03-14 14:23:30",
  "COL_NAME": "Hans",
  "COL_COUNTRY": "GERMANY",
  "COL_DXCC": "230",
  "COL_CQZ": "14",
  "COL_ITUZ": "28",
  "COL_PROP_MODE": null,
  "COL_SAT_NAME": null,
  "COL_TX_PWR": "50",
  "COL_ANT_PATH": null,
  "COL_GRIDSQUARE": "JN48",
  "COL_MY_GRIDSQUARE": "JN49",
  "COL_STATION_CALLSIGN": "DK0TU",
  "COL_MY_DXCC": "230",
  "COL_MY_COUNTRY": "GERMANY",
  "COL_MY_CQ_ZONE": "14",
  "COL_MY_ITU_ZONE": "28",
  "COL_COMMENT": "",
  "COL_NOTES": "",
  "user_name": "admin",
  "user_id": "1"
}

记录过程中填充的所有标准 ADIF 字段都会包含在内。两个非 ADIF 的附加字段为：

CAT 事件载荷

{
  "prop_mode": null,
  "sat_name": null,
  "timestamp": "2026-03-14 14:25:00",
  "power": "100",
  "frequency": "14074000",
  "mode": "FT8",
  "frequency_rx": null,
  "mode_rx": null,
  "radio": "IC-7300",
  "user_id": "1",
  "operator": "DK0TU",
  "user_name": "admin"
}

频率格式： CAT 事件中的频率单位为 Hz（整数字符串）。QSO 事件中的频率（COL_FREQ）遵循 ADIF 约定，单位为 MHz（小数字符串，例如 "14.074"）。

订阅——快速示例

mosquitto_sub（命令行）

# All Wavelog events
mosquitto_sub -h broker.example.com -t 'wavelog/#' -v

# Only newly logged QSOs (all users)
mosquitto_sub -h broker.example.com -t 'wavelog/qso/logged/#' -v

# CAT updates for user 1 only
mosquitto_sub -h broker.example.com -t 'wavelog/cat/1' -v

故障排查

启用 CodeIgniter 调试日志即可查看每条已发布的消息：

// application/config/config.php
$config['log_threshold'] = 2;  // 1 = errors only, 2 = errors + debug

已发布的消息显示如下：

DEBUG - published wavelog/qso/logged/1 -> {...} to MQTT broker