1
This commit is contained in:
parent
afda527deb
commit
8a56d80de0
251
云台对接说明.md
Normal file
251
云台对接说明.md
Normal file
@ -0,0 +1,251 @@
|
||||
# 云台(PTZ)通讯对接说明
|
||||
|
||||
> 适用版本:`services.printer`(服务端中转)+ `printServer`(打印/录制电脑客户端)
|
||||
> 最后更新:2026-09-15
|
||||
> 定位:**service.printer 只是中转**,外部(WMS)传入什么就原样推给客户端,不校验执行结果、不做回执、不记状态。
|
||||
|
||||
---
|
||||
|
||||
## 一、整体链路
|
||||
|
||||
```
|
||||
WMS 主服务
|
||||
│ ①HTTP POST /sendToRoom { warehouse, computerId, method, data }
|
||||
▼
|
||||
services.printer :4052 ← 本仓库,仅做中转,零改动
|
||||
│ ②查 Redis 路由表 warehouse:{warehouse}:printer:{computerId}
|
||||
│ ③WS sendTo(uniqueId, { method, data }) 原样透传
|
||||
▼
|
||||
printServer(仓库录制电脑)
|
||||
│ ④按 method 点分路由 → services/camera.ptz.*
|
||||
▼
|
||||
摄像头 / NVR(仓库内网,ISAPI)
|
||||
```
|
||||
|
||||
**关键语义**:HTTP 返回 `status: success` 只代表「消息已写进 WS 房间」,**不代表云台动了**。执行结果只落客户端本地日志,不回传。
|
||||
|
||||
---
|
||||
|
||||
## 二、WMS → services.printer(HTTP)
|
||||
|
||||
复用已有端点(`app/router.js` → `app/controller/home.js#sendToRoom`),**无需新增路由**:
|
||||
|
||||
```
|
||||
POST http://{services.printer 地址}:4052/sendToRoom
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"warehouse": 9, // 必填,仓库 ID
|
||||
"computerId": 12, // 必填,打印电脑 ID(须为录制电脑)
|
||||
"method": "camera.ptz.control", // 必填,见第三节
|
||||
"data": { // 必填,且必须是非空对象
|
||||
"rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",
|
||||
"action": "left",
|
||||
"speed": 4
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 返回
|
||||
|
||||
| 返回 | 含义 |
|
||||
|---|---|
|
||||
| `{ status:'success', message:'消息发送成功', result: 1 }` | 已推送到该电脑的 WS 房间(`result` = 命中房间数) |
|
||||
| `{ status:'fail', message:'缺少必要参数: warehouse, computerId, method, 或 data' }` | 入参不全 |
|
||||
| `{ status:'fail', message:'未找到打印机信息,无法发送消息' }` | 该电脑不在线(Redis 无记录,TTL 300s) |
|
||||
| `{ status:'fail', message:'打印电脑不在线,消息发送失败...' }` | `sendTo` 未命中房间 |
|
||||
|
||||
> 目标电脑怎么定:`wms_print_computer` 里 `warehouse_id = warehouse AND is_recording = 1` 的那台。WMS 侧本来就能查这张表,直接带上 `computerId` 即可。
|
||||
|
||||
---
|
||||
|
||||
## 三、services.printer → 客户端(WS 下发契约)
|
||||
|
||||
服务端把 `method` / `data` **原样** 透传,所以下表就是客户端必须实现的入口。
|
||||
|
||||
| method | 用途 | 是否持续型 |
|
||||
|---|---|---|
|
||||
| `camera.ptz.control` | 开始运动(方向 / 变倍 / 聚焦 / 光圈) | ✅ 必须另发 stop |
|
||||
| `camera.ptz.stop` | 停止运动 | — |
|
||||
| `camera.ptz.presetGoto` | 调用预置点 | ❌ 一次性 |
|
||||
| `camera.ptz.presetSet` | 设置(保存)预置点 | ❌ 一次性 |
|
||||
| `camera.ptz.auto` | 自动巡航(autoPan)开关 | ❌ 开关型 |
|
||||
|
||||
### data 字段
|
||||
|
||||
| 字段 | control | stop | presetGoto | presetSet | auto | 说明 |
|
||||
|---|:--:|:--:|:--:|:--:|:--:|---|
|
||||
| `rtspUrl` | ✔ | ✔ | ✔ | ✔ | ✔ | 设备 RTSP 地址;客户端从中解析 **账号 / 密码 / 主机 / 通道号** |
|
||||
| `action` | ✔ | ✔ | — | — | — | 动作名或 SDK 索引,见下表。**stop 必须与 start 同一个 action** |
|
||||
| `speed` | ○ | — | — | — | — | 1~7,默认 4 |
|
||||
| `presetId` | — | — | ✔ | ✔ | — | 预置点编号(1~256) |
|
||||
| `presetName` | — | — | — | ○ | — | 预置点名称,默认 `Preset{id}` |
|
||||
| `on` | — | — | — | — | ✔ | `true` 开启 / `false` 关闭 |
|
||||
| `channel` | ○ | ○ | ○ | ○ | ○ | 手动覆盖通道号(默认从 rtspUrl 解析) |
|
||||
| `port` | ○ | ○ | ○ | ○ | ○ | 设备 ISAPI 端口,默认 **80** |
|
||||
|
||||
### action 取值
|
||||
|
||||
| action | 同义写法 | SDK 索引 | 效果 |
|
||||
|---|---|:--:|---|
|
||||
| `up` | — | 1 | 上 |
|
||||
| `down` | — | 2 | 下 |
|
||||
| `left` | — | 3 | 左 |
|
||||
| `right` | — | 4 | 右 |
|
||||
| `upLeft` | `up_left` | 5 | 左上 |
|
||||
| `downLeft` | `down_left` | 6 | 左下 |
|
||||
| `upRight` | `up_right` | 7 | 右上 |
|
||||
| `downRight` | `down_right` | 8 | 右下 |
|
||||
| `zoomIn` | `zoom_in` | 10 | 变倍 + |
|
||||
| `zoomOut` | `zoom_out` | 11 | 变倍 − |
|
||||
| `focusIn` | `focus_in` / `focusFar` | 12 | 聚焦 + |
|
||||
| `focusOut` | `focus_out` / `focusNear` | 13 | 聚焦 − |
|
||||
| `irisIn` | `iris_in` | 14 | 光圈 + |
|
||||
| `irisOut` | `iris_out` | 15 | 光圈 − |
|
||||
|
||||
> 索引 9(自动巡航)不在 `control` 里支持,请用 `camera.ptz.auto`。
|
||||
|
||||
### 通道号来源
|
||||
|
||||
客户端从 `rtspUrl` 路径解析,规则:
|
||||
|
||||
| rtspUrl 路径 | 通道号 |
|
||||
|---|---|
|
||||
| `/Streaming/Channels/101` | 1 |
|
||||
| `/Streaming/Channels/601` | 6(末两位是码流号) |
|
||||
| `/Streaming/Channels/1201` | 12 |
|
||||
| `/stream2` | 2 |
|
||||
|
||||
解析不准时用 `channel` 显式覆盖。
|
||||
|
||||
---
|
||||
|
||||
## 四、客户端侧实现(已完成)
|
||||
|
||||
`printServer` 仓库改动清单:
|
||||
|
||||
| 文件 | 改动 |
|
||||
|---|---|
|
||||
| `utils/cameraPtz.js` | **新增**。ISAPI 云台控制,含认证握手、路径回退、路径缓存、文件日志 |
|
||||
| `utils/cameraOsd.js` | 3 处 `export`(`extractRTSPInfo` / `_isapiAuth` / `_isapiRequest`)+ `_isapiRequest`、`_isapiAuth` 各加可选 `port`(默认 80,行为不变) |
|
||||
| `services/camera.js` | 新增 `this.ptz = { control, stop, presetGoto, presetSet, auto }`,与已有 `this.osd` 平级 |
|
||||
|
||||
### ⚠️ 两条硬约束
|
||||
|
||||
1. **这些方法一律不能有返回值。**
|
||||
`core/wsClient.js` 只要拿到非 `undefined` 的返回值,就会回发 `{success:true, method, result}` 给服务端;而服务端 `app/controller/print.js` 会把这条回显**当成一次服务调用**去路由,`services.printer` 里没有 `camera.*` 服务 → 刷一堆 `服务路径 camera 不存在` 的错误。
|
||||
客户端日志里若出现该报错,说明有人给这些方法加了 `return`。
|
||||
|
||||
2. **持续型动作必须由 WMS 补发 stop。**
|
||||
ISAPI `/continuous` 是「一次 PUT 后设备持续运动」。客户端**不做自动停止**,WMS 侧必须在鼠标抬起 / 移出画面 / 窗口失焦 / 关闭时下发 `camera.ptz.stop`(同一个 `action`)。
|
||||
|
||||
### 日志
|
||||
|
||||
| 日志 | 位置 |
|
||||
|---|---|
|
||||
| 云台 | `%ProgramData%\printServer\cameraPtz.log`(同时输出到控制台,前缀 `[CameraPTZ]`) |
|
||||
| OSD | `%ProgramData%\printServer\cameraOsd.log` |
|
||||
|
||||
---
|
||||
|
||||
## 五、动作 ↔ ISAPI 映射(客户端内部实现)
|
||||
|
||||
路径与报文对齐海康官方无插件 SDK(`webVideoCtrl.js`)。每种动作按候选顺序尝试,成功后缓存该设备可用的那一条。
|
||||
|
||||
| 动作 | 首选路径 | 回退路径 |
|
||||
|---|---|---|
|
||||
| 方向 / 变倍 | `/ISAPI/PTZCtrl/channels/{ch}/continuous` | `/ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/continuous` |
|
||||
| 聚焦 | `/ISAPI/Image/channels/{ch}/focus` | `/ISAPI/ContentMgmt/ImageProxy/channels/{ch}/focus` → `/ISAPI/System/Video/inputs/channels/{ch}/focus` |
|
||||
| 光圈 | `/ISAPI/Image/channels/{ch}/iris` | `/ISAPI/ContentMgmt/ImageProxy/channels/{ch}/iris` → `/ISAPI/System/Video/inputs/channels/{ch}/iris` |
|
||||
| 预置点调用 | `/ISAPI/PTZCtrl/channels/{ch}/presets/{id}/goto` | `/ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/presets/{id}/goto` |
|
||||
| 预置点设置 | `/ISAPI/PTZCtrl/channels/{ch}/presets/{id}` | `/ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/presets/{id}` |
|
||||
| 自动巡航 | `/ISAPI/PTZCtrl/channels/{ch}/autoPan` | `/ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/autoPan` |
|
||||
|
||||
全部为 `PUT`;认证自适应 Basic / Digest(401 自动重新握手一次)。
|
||||
|
||||
### 报文与取值
|
||||
|
||||
**速度换算**(与 SDK 一致):`speed < 7 → 15 × speed`,`speed ≥ 7 → 100`;默认 `speed = 4` → `60`。**停止 = 0**。
|
||||
|
||||
```xml
|
||||
<!-- 方向:action=left, speed=4 -->
|
||||
<PTZData><pan>-60</pan><tilt>0</tilt></PTZData>
|
||||
<!-- 方向停止:action=left -->
|
||||
<PTZData><pan>0</pan><tilt>0</tilt></PTZData>
|
||||
<!-- 变倍:action=zoomIn, speed=2 -->
|
||||
<PTZData><zoom>30</zoom></PTZData>
|
||||
<!-- 聚焦:action=focusOut(speed=4) -->
|
||||
<FocusData><focus>-60</focus></FocusData>
|
||||
<!-- 光圈:action=irisIn(speed=4) -->
|
||||
<IrisData><iris>60</iris></IrisData>
|
||||
<!-- 预置点设置:presetId=3, presetName=A点 -->
|
||||
<PTZPreset><id>3</id><presetName>A点</presetName></PTZPreset>
|
||||
<!-- 自动巡航 -->
|
||||
<autoPanData><autoPan>100</autoPan></autoPanData> <!-- 开;关为 0 -->
|
||||
```
|
||||
|
||||
**方向符号**:`pan` 正 = 右、`tilt` 正 = 上。若实机方向相反,改 `utils/cameraPtz.js` 顶部:
|
||||
|
||||
```js
|
||||
const SIGNS = { pan: 1, tilt: 1, zoom: 1, focus: 1, iris: 1 };
|
||||
```
|
||||
|
||||
> 预置点调用按 SDK 行为**不带请求体**。
|
||||
|
||||
---
|
||||
|
||||
## 六、WMS 需要发的完整调用序列
|
||||
|
||||
```jsonc
|
||||
// 1) 按下:向左转
|
||||
POST /sendToRoom
|
||||
{ "warehouse": 9, "computerId": 12, "method": "camera.ptz.control",
|
||||
"data": { "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",
|
||||
"action": "left", "speed": 4 } }
|
||||
|
||||
// 2) 松手:停止(action 必须与上面一致)
|
||||
POST /sendToRoom
|
||||
{ "warehouse": 9, "computerId": 12, "method": "camera.ptz.stop",
|
||||
"data": { "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",
|
||||
"action": "left" } }
|
||||
|
||||
// 3) 转到预置点(一次即可,不用 stop)
|
||||
POST /sendToRoom
|
||||
{ "warehouse": 9, "computerId": 12, "method": "camera.ptz.presetGoto",
|
||||
"data": { "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",
|
||||
"presetId": 3 } }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、排查手册
|
||||
|
||||
| 现象 | 原因 / 处理 |
|
||||
|---|---|
|
||||
| 云台完全不动,服务端返回 success | 客户端 method 路由未命中。看客户端日志 `[WSClient] 方法路由: camera.ptz.control MISSING` → 客户端版本过旧,未包含 `services/camera.js` 的 `ptz` |
|
||||
| 客户端日志 `ISAPI 认证失败` | 设备账号密码不对(来自 `rtspUrl`)或设备不是海康系 |
|
||||
| `全部候选接口失败(最后 HTTP 400/404)` | 路径不匹配:NVR 的 IP 通道、非 80 端口(用 `port`)、或非海康设备 |
|
||||
| 云台转向相反 | 调 `utils/cameraPtz.js` 的 `SIGNS` |
|
||||
| 云台一直转不停 | WMS 没发 `camera.ptz.stop`(或 `action` 与开始不一致) |
|
||||
| 动了但控制错了通道 | 用 `channel` 显式指定通道号 |
|
||||
| 服务端出现 `服务路径 camera 不存在` | 客户端给这些方法加了返回值,触发了回显 → 去掉 `return` |
|
||||
|
||||
---
|
||||
|
||||
## 八、已知限制(按当前口径接受)
|
||||
|
||||
1. **无回执、无状态**:设备写失败、超时,WMS 一律看不到,只能靠客户端本地日志排查。
|
||||
2. **无自动停止**:WMS 侧异常 / 断网 / 忘了发 stop,云台会持续转动。
|
||||
3. **无幂等/防重**:重复下发即重复执行;预置点类幂等,方向类会叠加。
|
||||
4. **可攻击面**:`POST /sendToRoom`、`/camera/setOSD`、`/record/force` 均**未挂鉴权中间件**,端口可达即可调用(`app/middleware/jwtAuth.js` 已存在但未启用)。
|
||||
5. ISAPI 端口默认 80,非 80 设备需显式传 `port`。
|
||||
|
||||
---
|
||||
|
||||
## 九、变更记录
|
||||
|
||||
| 日期 | 内容 |
|
||||
|---|---|
|
||||
| 2026-09-15 | 云台链路定稿:WMS 下发 start/stop,服务端只中转,无回执;客户端新增 `utils/cameraPtz.js` + `services/camera.js#ptz` |
|
||||
Loading…
x
Reference in New Issue
Block a user