电台

电台（Radio）

目录

• upsert 模型
• 端点
• 电台对象
• 推送电台状态
  • 集体台操作员
• 删除电台

电台（Radio）资源公开你的 CAT 电台——即 WSJT-X、rigctl 或 GridTracker 等 CAT 客户端推送给 Wavelog 的实时设备状态（频率、模式、功率等）。它是旧版 api/radio 端点的 v2 对应物。

• 基础路径： /api/v2/radio
• 作用域： radio:read、radio:write、radio:delete
• 起始版本： 3.1.0

所有操作都限定在令牌所有者范围内。属于其他用户的电台会被当作未找到处理。

注意

请先阅读 API v2 概览，了解认证、响应封装与错误码。

upsert 模型

与其他资源不同，电台由名称标识，而不是通过 id 创建。CAT 客户端会持续推送当前设备状态的新快照，因此没有 PATCH 或 PUT——每个新快照都只是一个 POST：

• 如果尚不存在属于你的同名电台，则创建它（201 Created）；
• 否则就原地更新已有的电台（200 OK）。

端点

列表端点不分页。

电台对象

频率单位为 Hz。

{
  "id": 3,
  "radio": "FT-950",
  "frequency": 14075000,
  "frequency_rx": null,
  "mode": "SSB",
  "mode_rx": null,
  "power": 100,
  "prop_mode": null,
  "sat_name": null,
  "updated_at": "2026-06-16 17:06:00"
}

空的模式或 non 模式会被规范化为 null。

推送电台状态

POST /api/v2/radio

必填字段： radio（设备名称）。

curl -X POST https://<WAVELOG_URL>/index.php/api/v2/radio \
     -H "Authorization: Bearer wl2_your_token_here" \
     -H "Content-Type: application/json" \
     -d '{
           "radio": "FT-950",
           "frequency": 14075000,
           "mode": "SSB",
           "power": 100
         }'

响应会在 data 中包含已存储的电台对象。新建的电台返回 201 Created 并带有 Location 响应头；更新则返回 200 OK。

卫星 / 异频示例：

curl -X POST https://<WAVELOG_URL>/index.php/api/v2/radio \
     -H "Authorization: Bearer wl2_your_token_here" \
     -H "Content-Type: application/json" \
     -d '{
           "radio": "QO-100 Station",
           "frequency": 2400170000,
           "frequency_rx": 10489670000,
           "mode": "SSB",
           "mode_rx": "SSB",
           "prop_mode": "SAT",
           "sat_name": "QO-100",
           "power": 5
         }'

注意（字段限制）

3.2.0 在存储任何内容之前，请求载荷会按照旧版 api/radio 端点所施加的相同限制进行校验：

• radio：非空字符串，最多 250 个字符
• frequency、frequency_rx、power：整数——小数或非数值会被拒绝，而不是四舍五入
• mode、mode_rx、prop_mode：最多 10 个字符
• sat_name：最多 255 个字符

违反限制会返回 400 validation_error，并在 details.invalid 中列出每一个违规字段，例如 { "invalid": ["frequency", "mode"] }。在此之前，超出长度的值会直接写入数据库。

注意

回调 URL（cat_url）不能通过 API 写入。如果你需要自定义 CAT 回调 URL，请使用旧版 api/radio 端点。

提示

在频率或模式真正发生变化时推送电台状态——不要每秒盲目推送。

集体台操作员

当令牌属于某个集体台成员时（令牌所有者与其创建者不同），电台状态会记录在集体台账户下，并以实际操作的成员作为操作员，这与旧版 radio 端点一致。

因此每名成员在共享的集体台账户内都有自己的一套设备。在低于干事级别时，列出、读取和删除都限定在自己的设备范围内：其他成员的电台会返回 404 not_found。参见集体台。

删除电台

DELETE /api/v2/radio/{id}

curl -X DELETE https://<WAVELOG_URL>/index.php/api/v2/radio/3 \
     -H "Authorization: Bearer wl2_your_token_here"

成功时 API 返回 204 No Content。