# 螺杆定位 TCP/IP 通信协议文档

## 1. 协议概述

- **传输协议**: TCP/IP
- **数据格式**: JSON（UTF-8编码）
- **服务模式**: 服务端，支持多客户端连接
- **默认端口**: 7800（可配置）

## 2. 消息公共字段

| 字段 | 类型 | 说明 |
|------|------|------|
| MessageType | string | 消息类型 |
| Timestamp | long | 时间戳（毫秒），响应回传请求的 Timestamp |
| Data | object | 数据内容 |

## 3. 螺杆检测（Screw）

**请求：**
```json
{"MessageType": "ScrewRequest", "Timestamp": 1712649600000}
```

**确认响应：**
```json
{"MessageType": "ScrewResponse", "Timestamp": 1712649600000, "Data": {"Status": "Accepted"}}
```

**检测结果：**
```json
{
    "MessageType": "ScrewResult",
    "Timestamp": 1712649600000,
    "Data": {
        "Success": true,
        "ErrorCode": 0,
        "Message": "检测成功",
        "CameraIndex": 1,
        "Count": 2,
        "Screws": [
            {"X": 100.50, "Y": 200.30, "Z": 50.10, "Roll": 15.5, "Pitch": -2.3, "Yaw": 45.0},
            {"X": 120.00, "Y": 210.50, "Z": 48.00, "Roll": -5.0, "Pitch": 1.2, "Yaw": 30.0}
        ]
    }
}
```

## 4. 工具盘检测（Tool）

> 算法接口后续增加，当前返回错误码 -100

**请求：**
```json
{"MessageType": "ToolRequest", "Timestamp": 1712649600000}
```

**确认响应：**
```json
{"MessageType": "ToolResponse", "Timestamp": 1712649600000, "Data": {"Status": "Accepted"}}
```

**检测结果：**
```json
{
    "MessageType": "ToolResult",
    "Timestamp": 1712649600000,
    "Data": {
        "Success": true,
        "ErrorCode": 0,
        "Message": "检测成功",
        "CameraIndex": 1,
        "Count": 1,
        "ToolDisks": [
            {"X": 150.00, "Y": 180.00, "Z": 30.00, "Roll": 0.5, "Pitch": -1.2, "Yaw": 3.0}
        ]
    }
}
```

## 5. 位姿字段说明

| 字段 | 类型 | 单位 | 说明 |
|------|------|------|------|
| X | double | mm | 螺杆顶端/工具盘中心点X坐标（机械臂坐标系） |
| Y | double | mm | 螺杆顶端/工具盘中心点Y坐标（机械臂坐标系） |
| Z | double | mm | 螺杆顶端/工具盘中心点Z坐标（机械臂坐标系） |
| Roll | double | 度 | 绕X轴旋转（螺杆：算法输出的旋转角度） |
| Pitch | double | 度 | 绕Y轴旋转（俯仰角，由轴向方向计算） |
| Yaw | double | 度 | 绕Z轴旋转（偏航角，由轴向方向计算） |

## 6. 错误响应

```json
{
    "MessageType": "Error", "Timestamp": 1712649600000, 
    "Data": {"ErrorCode": -5, "ErrorMessage": "检测启动失败"}
}
```
> ErrorCode 非0标识错误，具体含义以实际最终开发为准