# 翻转屏通信协议文档

本文档描述了翻转屏设备的通信协议格式。所有通信采用JSON格式，包括从控制端到设备的请求和从设备到控制端的响应。

## 通信基本结构

### 请求格式（控制端 → 设备）
```json
{
    "board_id": 121,       // 设备ID
    "JSON_id": 1,          // 消息唯一标识
    "Flip-screen": {       // 翻转屏指令
        "command_type": {  // 具体命令类型
            // 命令参数
        }
    }
}
```

### 响应格式（设备 → 控制端）
```json
{
    "JSON_id": 1,          // 与请求消息相同的标识
    "Flip-screen": {       // 翻转屏响应
        "command_type": {  // 与请求相同的命令类型
            "status": "success"  // 操作状态: "success" 或 "failed"
        }
    },
    "error_code": 0        // 错误码，0表示成功
}
```

## 功能指令详解

### 1. 平台控制（上升/下降）

#### 请求：
```json
{
    "board_id": 121,
    "JSON_id": 2,
    "Flip-screen": {
        "platform_control": {
            "direction": "up"  // 可选值: "up" 或 "down"
        }
    }
}
```

#### 响应：
```json
{
    "JSON_id": 2,
    "Flip-screen": {
        "platform_control": {
            "status": "success"
        }
    },
    "error_code": 0 
}
```

### 2. 屏幕开关控制

#### 请求：
```json
{
    "board_id": 121,
    "JSON_id": 3,
    "Flip-screen": {
        "screen_control": {
            "power": "on"  // 可选值: "on" 或 "off"
        }
    }
}
```

#### 响应：
```json
{
    "JSON_id": 3,
    "Flip-screen": {
        "screen_control": {
            "status": "success"
        }
    },
    "error_code": 0 
}
```

### 3. 灯模式控制

#### 请求：
```json
{
    "board_id": 121,
    "JSON_id": 4,
    "Flip-screen": {
        "light_mode": {
            "mode": "auto"  // 灯光模式: "auto", "manual", 等
        }
    }
}
```

#### 响应：
```json
{
    "JSON_id": 4,
    "Flip-screen": {
        "light_mode": {
            "status": "success"
        }
    },
    "error_code": 0 
}
```

### 4. 单个灯控制

#### 请求：
```json
{
    "board_id": 121,
    "JSON_id": 5,
    "Flip-screen": {
        "light_control": {
            "light_id": 1,       // 灯ID编号: 1-6
            "state": "on"        // 可选值: "on" 或 "off"
        }
    }
}
```

#### 响应：
```json
{
    "JSON_id": 5,
    "Flip-screen": {
        "light_control": {
            "status": "success"
        }
    },
    "error_code": 0 
}
```

### 5. 亮度调节

#### 请求：
```json
{
    "board_id": 121,
    "JSON_id": 6,
    "Flip-screen": {
        "brightness_control": {
            "value": 70  // 亮度值: 0-100
        }
    }
}
```

#### 响应：
```json
{
    "JSON_id": 6,
    "Flip-screen": {
        "brightness_control": {
            "status": "success"
        }
    },
    "error_code": 0 
}
```

### 6. 节目控制

#### 请求：
```json
{
    "board_id": 121,
    "JSON_id": 7,
    "Flip-screen": {
        "program_control": {
            "program_id": 1  // 节目ID
        }
    }
}
```

#### 响应：
```json
{
    "JSON_id": 7,
    "Flip-screen": {
        "program_control": {
            "status": "success"
        }
    },
    "error_code": 0 
}
```

## 错误处理

当指令执行失败时，设备会返回非零的错误码和错误信息：

```json
{
    "JSON_id": 3,
    "Flip-screen": {
        "screen_control": {
            "status": "failed"
        }
    },
    "error_code": 1001,
    "error_msg": "Device not responding"
}
```

## 错误码说明

| 错误码 | 描述 |
|--------|------|
| 0      | 成功 |
| 1001   | 设备无响应 |
| 1002   | 参数错误 |
| 1003   | 设备忙 |
| 1004   | 操作超时 |
| 1005   | 设备未就绪 |


## 设备状态查询

### 请求：
```json
{
    "board_id": 121,
    "JSON_id": 8,
    "Flip-screen": {
        "status_query": {
            "type": "all"  // 查询类型: "all", "platform", "screen", "lights", "program"
        }
    }
}
```

### 响应：
```json
{
    "JSON_id": 8,
    "Flip-screen": {
        "status": {
            "platform": {
                "position": "up"  // "up" 或 "down"
            },
            "screen": {
                "power": "on",    // "on" 或 "off"
                "brightness": 70  // 0-100
            },
            "lights": [
                {"id": 1, "state": "on", },
                {"id": 2, "state": "off",},
                {"id": 3, "state": "on", },
                {"id": 4, "state": "on", },
                {"id": 5, "state": "off",},
                {"id": 6, "state": "on", }
            ],
            "program": {
                "current_id": 1,
                "available": [1, 2, 3, 4, 5]
            },
            "light_mode": "auto"
        }
    },
    "error_code": 0
}
```