1. 光翼智能
  2. 文档中心
  3. 分布式光纤传感
  4. DTS分布式光纤测温主机API文档

DTS分布式光纤测温主机API文档

2024年04月28日 22:25 产品分类： DAS / DVS 分布式光纤振动监测 DTS 分布式光纤测温

本文档供第三方客户端对接 DTS 设备服务使用，说明 HTTP REST 与 WebSocket 的调用方式、参数含义及响应格式。 适合产品：https://www.glgyzn.com/product/164

1. 接入信息

项目 说明
基础地址 http://<host>:8088
WebSocket ws://<host>:8088/ws/stream
数据格式 请求/响应均为 JSON（UTF-8）
Content-Type POST 请求使用 application/json
鉴权 见下文；OPTIONS 预检无需 Token

将 <host> 替换为设备 IP，端口默认为 8088（若设备配置了其他端口，以实际为准）。

1.1 鉴权

所有 HTTP 与 WebSocket 请求需携带 API Token（与设备管理员确认 Token 值，默认常为 glgyzn-dts-token）。

方式 示例
Authorization 头（推荐） Authorization: Bearer glgyzn-dts-token
自定义头 X-DTS-Token: glgyzn-dts-token
WebSocket 查询参数 ws://<host>:8088/ws/stream?token=glgyzn-dts-token

鉴权失败返回 401：

{"ok": false, "error": "unauthorized"}

1.2 通用响应

成功（HTTP 200） — 多数 POST：

{"ok": true, "message": "说明文字"}

失败 — 两种常见格式：

{"ok": false, "error": "错误说明"}
{"ok": false, "message": "错误说明"}

部分 GET 接口直接返回业务 JSON，无 ok 字段。

1.3 推荐调用顺序

1. GET  /api/v1/health
2. POST /api/v1/connect
3. GET  /api/v1/status
4. GET  /api/v1/config          （可选）
5. POST /api/v1/config          （可选）
6. WebSocket /ws/stream          （订阅实时数据）
7. POST /api/v1/acquisition/start
8. 接收 WebSocket frame / alarm 消息
9. POST /api/v1/acquisition/stop （需要时）

说明：

  • 客户端断开 WebSocket 不会停止采集；需显式调用 acquisition/stop。
  • 多个客户端可同时连接，互不影响。
  • POST /connect 已连接时再次调用仍返回成功及当前版本。
  • POST /acquisition/start 已在采集时再次调用仍返回成功。

2. 接口一览

方法 路径 说明
GET /api/v1/health 健康检查
GET /api/v1/status 连接与采集状态
POST /api/v1/connect 连接设备
POST /api/v1/disconnect 断开设备
GET /api/v1/config 读取配置
POST /api/v1/config 更新配置
POST /api/v1/reload-config 重新加载配置
POST /api/v1/acquisition/start 开始采集
POST /api/v1/acquisition/stop 停止采集
GET /api/v1/optical-switch 查询光开关
POST /api/v1/optical-switch 启用/禁用光开关
GET /api/v1/light-source 读取光源参数
POST /api/v1/light-source 设置光源参数
GET /api/v1/alarms 读取告警配置与状态
POST /api/v1/alarms 保存告警配置
POST /api/v1/alarms/acknowledge 确认恢复告警
POST /api/v1/alarms/mute 告警消音
GET /api/v1/relay-linkage 读取继电器联动配置
POST /api/v1/relay-linkage 保存继电器联动配置
GET /api/v1/network/ip 查询主机 IP
POST /api/v1/network/ip 修改主机 IP

3. 接口详情

以下示例中：

  • HOST = 设备 IP，如 192.168.68.4
  • TOKEN = API Token，如 glgyzn-dts-token

GET /api/v1/health

探测服务是否在线。

请求： 无 body

响应：

{"ok": true}

curl：

curl -s "http://HOST:8088/api/v1/health" \
  -H "Authorization: Bearer TOKEN"

GET /api/v1/status

查询设备连接状态与采集参数。

响应：

{
  "connected": true,
  "reading": false,
  "version": "V1.2.3.5",
  "samplePoints": 16384,
  "avgCount": 30000
}
字段 类型 说明
connected bool 是否已连接采集卡
reading bool 是否正在采集
version string 采集卡固件版本
samplePoints number 当前采样点数
avgCount number 当前平均次数

curl：

curl -s "http://HOST:8088/api/v1/status" \
  -H "Authorization: Bearer TOKEN"

POST /api/v1/connect

连接采集卡及外设（光源、光开关等）。首次连接可能耗时较长，建议 HTTP 超时设为 60–90 秒。

请求体： 空对象 {} 或不传 body

响应：

{
  "ok": true,
  "message": "连接成功, 版本: V1.2.3.5"
}
字段 说明
ok 是否成功
message 结果说明；失败时为原因；部分外设失败时也可能 ok=true 并在 message 中说明

curl：

curl -s -X POST "http://HOST:8088/api/v1/connect" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d "{}"

POST /api/v1/disconnect

停止采集并断开设备连接。

请求体：

{}

响应：

{"ok": true}

curl：

curl -s -X POST "http://HOST:8088/api/v1/disconnect" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d "{}"

POST /api/v1/acquisition/start

开始温度采集。采集数据通过 WebSocket 推送。

前置条件： 已成功 connect，且 samplePoints、avgCount 均 > 0。

请求体：

{
  "samplePoints": 16384,
  "avgCount": 30000
}
字段 类型 必填 说明
samplePoints number 否 采样点数；省略则用当前值
avgCount number 否 平均次数；省略则用当前值

响应：

{
  "ok": true,
  "message": "开始采集"
}

curl：

curl -s -X POST "http://HOST:8088/api/v1/acquisition/start" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"samplePoints":16384,"avgCount":30000}'

POST /api/v1/acquisition/stop

停止采集。

请求体：

{}

响应：

{"ok": true}

curl：

curl -s -X POST "http://HOST:8088/api/v1/acquisition/stop" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d "{}"

GET /api/v1/config

读取当前配置。

响应示例：

{
  "samplePoints": 16384,
  "avgCount": 30000,
  "refTemp": 34.3,
  "meterPerPoint": 0.4,
  "attenEnabled": true,
  "attenuations": [
    {"channel": 1, "segStart": 0, "segEnd": 1000, "alphaDiff": 0.001, "offsetK": 0.0}
  ],
  "calibrations": [
    {"channel": 1, "position": 100, "sensitivity": 0.4, "compTemp": 25.0}
  ],
  "channels": [
    {
      "channel": 1,
      "startPos": 0,
      "endPos": 5920,
      "zeroMeter": 0,
      "measureOffsetM": 0.0,
      "meterPerPoint": 0.4,
      "refTemp": 34.3,
      "enabled": true,
      "alias": "通道1"
    }
  ],
  "lightSource": {
    "mode": 1,
    "laserOn": 1,
    "current": 40000,
    "power": 2500,
    "pulseWidth": 10,
    "frequency": 10
  },
  "opticalSwitch": {"enabled": true},
  "forwardTempEnabled": false,
  "forwardTempUrl": "http://127.0.0.1:8080/api/temperature"
}

字段说明见 第 5 节 配置字段。

POST /api/v1/config

更新配置，支持增量更新（只传需要修改的字段）。

注意：

  • 不会写入光源硬件；改光源请用 POST /api/v1/light-source。
  • 正在采集时，samplePoints / avgCount 无法热更新，需先停止采集。

请求体示例（修改通道与标定）：

{
  "refTemp": 34.3,
  "meterPerPoint": 0.4,
  "channels": [
    {
      "channel": 1,
      "startPos": 0,
      "endPos": 5920,
      "zeroMeter": 0,
      "measureOffsetM": 0.0,
      "meterPerPoint": 0.4,
      "refTemp": 34.3,
      "enabled": true,
      "alias": "通道1"
    }
  ],
  "calibrations": [
    {"channel": 1, "position": 100, "sensitivity": 0.4, "compTemp": 25.0}
  ]
}

响应：

{"ok": true, "message": "配置已保存"}

curl：

curl -s -X POST "http://HOST:8088/api/v1/config" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"samplePoints":16384,"avgCount":30000,"refTemp":34.3}'

POST /api/v1/reload-config

从设备重新加载配置文件。

请求体：

{}

响应：

{"ok": true, "message": "配置已加载"}

curl：

curl -s -X POST "http://HOST:8088/api/v1/reload-config" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d "{}"

GET /api/v1/optical-switch

查询光开关状态。

响应：

{
  "ok": true,
  "enabled": true,
  "connected": true,
  "serialPort": "/dev/ttyS1",
  "baudRate": 9600,
  "currentChannel": 2,
  "channelValid": true
}
字段 说明
enabled 是否启用多通道光开关
connected 是否已连接
currentChannel 当前通道号（0=未知）
channelValid currentChannel 是否有效

POST /api/v1/optical-switch

启用或禁用光开关。

请求体：

{
  "enabled": true
}
字段 类型 必填 说明
enabled bool 是 true=启用，false=禁用

响应：

{
  "ok": true,
  "enabled": true,
  "connected": true,
  "currentChannel": 1,
  "channelValid": true,
  "message": "光开关已启用"
}

curl：

curl -s -X POST "http://HOST:8088/api/v1/optical-switch" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

GET /api/v1/light-source

读取光源当前参数。

响应：

{
  "ok": true,
  "connected": true,
  "dataValid": true,
  "laserOn": 1,
  "mode": 1,
  "current": 40000,
  "power": 2500,
  "pulseWidth": 10,
  "frequency": 10,
  "readCurrent": 39500,
  "readPower": 2480,
  "moduleTemp": 34.5
}
字段 说明
laserOn 0=关，1=开
mode 0=ACC，1=APC
current 设置电流
power 设置功率
pulseWidth 脉宽 (ns)
frequency 频率 (kHz)
readCurrent / readPower / moduleTemp 读回值（dataValid=false 时可能缺失）
dataValid 是否成功从硬件读回实时值

POST /api/v1/light-source

写入光源参数到硬件。

请求体：

{
  "laserOn": 1,
  "mode": 1,
  "current": 40000,
  "power": 2500,
  "pulseWidth": 10,
  "frequency": 10
}
字段 类型 必填 说明
laserOn int 否 0=关，1=开
mode int 否 0=ACC，1=APC
current int 否 设置电流
power int 否 设置功率
pulseWidth int 否 脉宽 (ns)
frequency int 否 频率 (kHz)

响应：

{
  "ok": true,
  "message": "光源参数已写入",
  "connected": true,
  "dataValid": true,
  "laserOn": 1,
  "mode": 1,
  "current": 40000,
  "power": 2500,
  "pulseWidth": 10,
  "frequency": 10,
  "readCurrent": 39500,
  "readPower": 2480,
  "moduleTemp": 34.5
}

curl：

curl -s -X POST "http://HOST:8088/api/v1/light-source" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"laserOn":1,"mode":1,"current":40000,"power":2500,"pulseWidth":10,"frequency":10}'

GET /api/v1/alarms

读取温度告警配置及当前告警状态。

响应：

{
  "ok": true,
  "enabled": true,
  "channels": [
    {"channel": 1, "enabled": true},
    {"channel": 2, "enabled": false}
  ],
  "partitions": [
    {
      "channel": 1,
      "partitionId": 1,
      "name": "区段A",
      "startM": 150.0,
      "endM": 4000.0,
      "fixedTempEnabled": true,
      "fixedTempThreshold": 60.0,
      "diffTempEnabled": true,
      "diffTempThreshold": 10.0,
      "diffTempInterval": 3
    }
  ],
  "state": {"active": false}
}
字段 说明
enabled 全局是否启用告警
channels[] 各通道告警开关
partitions[] 告警分区，见 5.2 告警分区
state.active 当前是否处于告警状态

POST /api/v1/alarms

保存告警配置，支持增量更新。state 字段会被忽略。

请求体示例：

{
  "enabled": true,
  "channels": [
    {"channel": 1, "enabled": true}
  ],
  "partitions": [
    {
      "channel": 1,
      "partitionId": 1,
      "name": "区段A",
      "startM": 150.0,
      "endM": 4000.0,
      "fixedTempEnabled": true,
      "fixedTempThreshold": 60.0,
      "diffTempEnabled": true,
      "diffTempThreshold": 10.0,
      "diffTempInterval": 3
    }
  ]
}

响应：

{"ok": true, "message": "告警配置已保存"}

curl：

curl -s -X POST "http://HOST:8088/api/v1/alarms" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"partitions":[{"channel":1,"partitionId":1,"name":"区段A","startM":150,"endM":4000,"fixedTempEnabled":true,"fixedTempThreshold":60,"diffTempEnabled":false,"diffTempThreshold":10,"diffTempInterval":3}]}'

POST /api/v1/alarms/acknowledge

确认恢复告警，清除告警状态；WebSocket 会广播 active: false。

请求体：

{}

响应：

{"ok": true, "message": "告警已恢复"}

curl：

curl -s -X POST "http://HOST:8088/api/v1/alarms/acknowledge" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d "{}"

POST /api/v1/alarms/mute

告警消音（关闭蜂鸣器），告警状态保持不变。

请求体：

{}

响应：

{"ok": true, "message": "告警已消音"}

curl：

curl -s -X POST "http://HOST:8088/api/v1/alarms/mute" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d "{}"

GET /api/v1/relay-linkage

读取继电器联动配置。

响应：

{
  "ok": true,
  "enabled": true,
  "serialPort": "/dev/ttyS0",
  "baudRate": 115200,
  "connected": true,
  "states": [0, 1, 0, 0, 0, 0, 0, 0],
  "rules": [
    {
      "relay": 1,
      "alarmType": "火灾",
      "channel": 1,
      "startM": 0.0,
      "endM": 4000.0
    }
  ]
}
字段 说明
enabled 是否启用继电器联动
connected 继电器板是否已连接
states 8 路继电器状态：0=关，1=开，-1=未知
rules[] 联动规则列表
rules[].relay 继电器编号 1–8
rules[].alarmType 报警类型
rules[].channel 光纤通道号
rules[].startM / endM 有效距离区间 (m)

POST /api/v1/relay-linkage

保存继电器联动配置。connected 字段无需传入。

请求体示例：

{
  "enabled": true,
  "rules": [
    {
      "relay": 1,
      "alarmType": "火灾",
      "channel": 1,
      "startM": 0.0,
      "endM": 4000.0
    }
  ]
}

响应：

{"ok": true, "message": "继电器配置已保存"}

curl：

curl -s -X POST "http://HOST:8088/api/v1/relay-linkage" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"rules":[{"relay":1,"alarmType":"火灾","channel":1,"startM":0,"endM":4000}]}'

GET /api/v1/network/ip

查询设备主机 IP。

响应：

{
  "ok": true,
  "interface": "enp2s0",
  "address": "192.168.68.4/24",
  "gateway": "",
  "available": true
}
字段 说明
interface 网口名称
address IPv4 地址（CIDR 格式）
gateway 网关（可能为空）
available 是否读取成功

POST /api/v1/network/ip

修改设备主机 IP。调用成功后 HTTP 立即返回，网络可能短暂中断，需用新 IP 重连。

请求体：

{
  "address": "192.168.68.4/24",
  "gateway": "192.168.68.1"
}
字段 类型 必填 说明
address string 是 CIDR 格式，如 192.168.68.4/24
gateway string 否 默认网关；省略则不设置

响应：

{
  "ok": true,
  "message": "网络配置已保存..."
}

curl：

curl -s -X POST "http://HOST:8088/api/v1/network/ip" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address":"192.168.68.4/24","gateway":"192.168.68.1"}'

4. WebSocket 实时数据

4.1 连接

ws://HOST:8088/ws/stream?token=TOKEN

或在握手请求头中携带：Authorization: Bearer TOKEN

4.2 温度帧（type = "frame"）

调用 acquisition/start 且采样成功后推送：

{
  "type": "frame",
  "channel": 1,
  "channelIndex": 0,
  "timestamp": "2026-08-20T08:30:15",
  "startPos": 0,
  "meterPerPoint": 0.4,
  "fiberLengthM": 5181.2,
  "temperature": [34.1, 34.2],
  "asCurve": [120.5, 118.3],
  "rawA": [1000, 1002],
  "rawB": [800, 798]
}
字段 说明
channel 通道编号
channelIndex 通道在配置数组中的下标
timestamp 采样时间（ISO8601，无毫秒）
startPos 曲线起始点号
meterPerPoint 每点距离 (m)
fiberLengthM 光缆长度 (m)，失败时为 -1
temperature 温度数组 ℃
asCurve AS 曲线
rawA / rawB Stokes / Anti-Stokes 原始曲线

距离换算：

distanceM = (startPos + i - zeroMeter) * meterPerPoint

zeroMeter、meterPerPoint 来自该通道的 channels[] 配置。

4.3 告警消息（type = "alarm"）

触发：

{
  "type": "alarm",
  "active": true,
  "hits": [
    {
      "channel": 1,
      "partitionId": 1,
      "name": "区段A",
      "distanceM": 320.5,
      "temperature": 62.3,
      "fixedTemp": true,
      "threshold": 60.0
    }
  ]
}

恢复：

{
  "type": "alarm",
  "active": false,
  "hits": []
}
字段 说明
active 是否处于告警状态
hits[].channel 通道号
hits[].partitionId 分区编号
hits[].name 分区名称
hits[].distanceM 告警位置 (m)
hits[].temperature 当前温度 ℃
hits[].fixedTemp true=定温，false=差温
hits[].threshold 触发阈值 ℃

客户端收到 active: true 时更新 UI；用户确认后调用 POST /api/v1/alarms/acknowledge。

5. 配置字段

5.1 channels[] — 通道

字段 类型 说明
channel int 通道号
startPos int 计算起始点号
endPos int 计算结束点号（0=到末尾）
zeroMeter int 0 米标定对应的点号
measureOffsetM number 铠装起点偏移 (m)
meterPerPoint number 每点距离 (m)
refTemp number 参考温度 ℃
enabled bool 多通道模式下是否参与轮询
alias string 通道别名

5.2 partitions[] — 告警分区

字段 类型 说明
channel int 所属通道号
partitionId int 分区编号
name string 分区名称
startM / endM number 报警区间 (m)
fixedTempEnabled bool 是否启用定温报警
fixedTempThreshold number 定温阈值 ℃
diffTempEnabled bool 是否启用差温报警
diffTempThreshold number 差温阈值 ℃
diffTempInterval int 差温比较间隔（连续采样次数）

5.3 其他配置字段

字段 说明
samplePoints 采样点数
avgCount 平均次数
refTemp 全局参考温度 ℃
meterPerPoint 全局每点距离 (m)
attenEnabled 是否启用衰减补偿
attenuations[] 衰减段：channel, segStart, segEnd, alphaDiff, offsetK
calibrations[] 标定点：channel, position, sensitivity, compTemp
forwardTempEnabled 是否向第三方 URL 转发温度
forwardTempUrl 转发目标 URL

6. 接入示例

6.1 完整 curl 流程

HOST="192.168.68.4"
TOKEN="glgyzn-dts-token"

# 1. 健康检查
curl -s "http://${HOST}:8088/api/v1/health" -H "Authorization: Bearer ${TOKEN}"

# 2. 连接
curl -s -X POST "http://${HOST}:8088/api/v1/connect" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" -d "{}"

# 3. 查询状态
curl -s "http://${HOST}:8088/api/v1/status" -H "Authorization: Bearer ${TOKEN}"

# 4. 开始采集
curl -s -X POST "http://${HOST}:8088/api/v1/acquisition/start" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"samplePoints":16384,"avgCount":30000}'

6.2 JavaScript WebSocket

const host = "192.168.68.4";
const token = "glgyzn-dts-token";
const ws = new WebSocket(`ws://${host}:8088/ws/stream?token=${encodeURIComponent(token)}`);

ws.onmessage = (ev) => {
  const msg = JSON.parse(ev.data);
  if (msg.type === "frame") {
    console.log(`通道 ${msg.channel}，温度点数 ${msg.temperature.length}`);
  } else if (msg.type === "alarm") {
    console.log(`告警 active=${msg.active}`, msg.hits);
  }
};

6.3 Python 读取配置

import json, urllib.request

host, token = "192.168.68.4", "glgyzn-dts-token"
req = urllib.request.Request(
    f"http://{host}:8088/api/v1/config",
    headers={"Authorization": f"Bearer {token}"},
)
with urllib.request.urlopen(req) as r:
    cfg = json.load(r)
print(cfg["samplePoints"], cfg["channels"])

7. 常见问题

问题 说明
401 unauthorized Token 不正确或未携带
connect 超时 首次连接较慢，增大 HTTP 超时（建议 60–90s）
404 not found 路径错误或方法不对
修改 IP 后连不上 使用新 IP 重新连接
停止采集后 reading 仍为 true acquisition/stop 异步生效，轮询 GET /status 直到 reading=false

文档版本：2026-08-23


联系电话 13427781756