protocol-rc-v1.7.0

# 项目版本: RC产品专用协议 v1.7.0
***
## 一、前言

本文档专门针对RC产品（智能租赁柜，产品型号：D2_RC）的协议规范，从主协议v1.6中提取并整理了所有与RC产品相关的通信协议内容。

RC产品采用脱钩锁控制技术，支持8个独立的脱钩锁控制，仅支持开锁操作，不支持锁定操作。同时支持IC卡接触检测功能，可实时监测每个锁位的IC卡接触状态和卡号。

### 1.1. 产品特性
- **产品型号**: RC (D2_RC)
- **主要功能**: 智能租赁柜
- **硬件能力**: 脱钩锁控制 + IC卡检测
- **控制方式**: 脉冲信号控制（仅开锁）
- **锁数量**: 8个独立脱钩锁（编号0-7）
- **状态反馈**: 实时状态检测
- **IC卡功能**: 每个锁位支持IC卡接触检测和卡号识别

### 1.2. 支持的协议
1. MQTT: "硬件终端"作为MQTT客户端
2. TCP Client: "硬件终端"作为TCP客户端  
3. HTTP Server: "硬件终端"作为HTTP服务端

## 二、产品型号说明

| 产品型号 | 完整名称 | 硬件能力 | 主要用途 |
|---------|---------|---------|---------| 
| RC | D2_RC | 脱钩锁控制 + IC卡检测 | 智能租赁柜 |

## 三、设备标识 (device_id)

- 用途：代表终端的唯一编号
- 默认值：设备的主芯片的唯一id

## 四、通信协议

### 4.1. MQTT 协议
#### 4.1.1. MQTT 协议概要
- mqtt 通讯基于2个主题,device_id/device_pub_topic与device_id/device_sub_topic
- "硬件终端"通过device_id/device_pub_topic主题发布数据,"应用终端"通过该主题接收"硬件终端"的数据
- "硬件终端"通过device_id/device_sub_topic主题接收数据,"应用终端"通过该主题发送数据

***node***: mqtt主题由device_id动态构成,修改device_id时,将自动修改这两个主题

#### 4.1.2. MQTT 通讯框图
以下图表,展示了"硬件终端"的"事件上报"与"控制终端"的"应用命令请求"或"参数请求"对应的通讯流程图.

```mermaid
sequenceDiagram
    participant HW_MQTT_Client
    participant MQTT_Server
    participant APP_MQTT_Client

HW_MQTT_Client->>MQTT_Server: 发布消息到 device_pub_topic
    Note right of HW_MQTT_Client: 事件上报

MQTT_Server->>APP_MQTT_Client: 转发消息

APP_MQTT_Client->>MQTT_Server: 发布控制指令到 device_sub_topic
    Note right of APP_MQTT_Client: 控制命令或参数请求

MQTT_Server->>HW_MQTT_Client: 转发指令
    Note right of MQTT_Server: 设备执行指令

HW_MQTT_Client-->>MQTT_Server: 回复确认或失败信息
    MQTT_Server-->>APP_MQTT_Client: 转发应答结果
```

* HW_MQTT_Client: 硬件终端,MQTT客户端
* MQTT_Server: MQTT 服务器端,一般指客户在阿里云,华为云等云平台构建的MQTT服务器终端
* APP_MQTT_Client: 应用终端,也是MQTT客户端,一般由手机小程序充当

### 4.2. TCP Client 协议
#### 4.2.1. TCP Client 协议概要
- TCP Client 代表"硬件终端"作为TCP客户端与"服务器端"进行socket通讯
- "硬件终端"上电联网完成后,会主动与"服务器端"建立socket

#### 4.2.2. TCP Client 通讯框图
以下图表,展示了"硬件终端"的"事件上报"与"应用终端"的"控制命令请求"或"参数请求"对应的通讯流程图.

```mermaid
sequenceDiagram
    participant TCP_Client
    participant TCP_Server

Note over TCP_Server: TCP Server启动并监听端口
    Note over TCP_Client: 硬件终端上电初始化

TCP_Client->>TCP_Server: 建立TCP连接
    TCP_Server-->>TCP_Client: 连接确认

TCP_Client->>TCP_Server: 发送事件上报数据
    TCP_Server-->>TCP_Client: 数据应答

TCP_Server->>TCP_Client: 下发控制指令
    TCP_Client-->>TCP_Server: 控制指令执行应答

```

* TCP_Client: 硬件终端，作为TCP客户端
* TCP_Server: 服务器端，作为TCP服务器
  
### 4.3. HTTP Server 协议
#### 4.3.1. HTTP Server 协议概要
- HTTP Server 代表"硬件终端"启动HTTP服务器，等待其他客户端连接
- 客户端通过HTTP协议发送POST请求到硬件终端
- 硬件终端处理请求并返回HTTP响应

#### 4.3.2. HTTP Server 通讯框图

```mermaid
sequenceDiagram
    participant HTTP_Client
    participant HTTP_Server

Note over HTTP_Server: HTTP Server在硬件终端启动
    Note over HTTP_Client: 应用终端作为客户端

HTTP_Client->>HTTP_Server: 发送HTTP POST请求 (控制指令或参数设置)
    HTTP_Server-->>HTTP_Client: 返回HTTP响应

HTTP_Client->>HTTP_Server: 发送HTTP GET请求 (状态查询或参数获取)
    HTTP_Server-->>HTTP_Client: 返回HTTP响应 (包含设备状态或参数)

```

* HTTP_Client: 应用终端，如手机APP、网页客户端等
* HTTP_Server: 硬件终端，运行HTTP服务器

## 五、报文格式

### 5.1. 控制指令 (RC产品专用)

| 命令 | JSON 格式 | 说明 |
| -------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 开锁单个脱钩锁 | `{"ctrl_cmd":{"unlock_lock_cmd":"x"}}` | 开锁单个脱钩锁,x为锁编号(0-7),如: {"ctrl_cmd":{"unlock_lock_cmd":"0"}} |
| 查询单个锁状态 | `{"ctrl_cmd":{"query_lock_cmd":"x"}}` | 查询单个脱钩锁状态,x为锁编号(0-7),如: {"ctrl_cmd":{"query_lock_cmd":"0"}} |
| 查询单个IC卡 | `{"ctrl_cmd":{"query_card_cmd":"x"}}` | 查询单个IC卡信息,x为锁编号(0-7),如: {"ctrl_cmd":{"query_card_cmd":"0"}} |
| 恢复出厂设置 | `{"ctrl_cmd":{"factory_params_cmd":"xxxx"}}` | 恢复出厂设置,xxxx参数可以为任意字符串 |
| 重启系统 | `{"ctrl_cmd":{"restart_cmd":"xxxx"}}` | 重启系统,xxxx参数可以为任意字符串 |
| OTA 更新 | `{"ctrl_cmd":{"ota_cmd":{"url":"xxxx"}}}` | OTA 升级，url 为固件升级地址 例：`{"ctrl_cmd":{"ota_cmd":{"url":"http://192.168.1.100:8080/firmware.bin"}}}` |

### 5.2. 参数设置&参数获取 (RC产品适用)

| 参数名           | 设置参数                                                                 | 获取参数                                                | 默认值                        | 说明                                                                                                                                                            |
| ------------- | -------------------------------------------------------------------- | --------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 设备 ID         | `{"set_param":{"device_id":"dev001"}}`                              | `{"get_param":{"device_id":{}}}`                    | 使用 ESP32 芯片 ID             |                                                                                                                                                               |
| AP SSID       | `{"set_param":{"ap_ssid":"SmartDevice_AP"}}`                        | `{"get_param":{"ap_ssid":{}}}`                      | "SmartDevice"              |                                                                                                                                                               |
| AP 密码         | `{"set_param":{"ap_pwd":"12345678"}}`                               | `{"get_param":{"ap_pwd":{}}}`                       | "12345678"                 |                                                                                                                                                               |
| 软件版本          | -                                                                    | `{"get_param":{"soft_ver":{}}}`                     | 当前版本                       | 只读参数                                                                                                                                                          |
| 硬件版本          | -                                                                    | `{"get_param":{"hard_ver":{}}}`                     | 当前版本                       | 只读参数                                                                                                                                                          |
| 协议版本          | -                                                                    | `{"get_param":{"protocol_ver":{}}}`                 | 当前版本                       | 只读参数                                                                                                                                                          |
| 参数版本          | -                                                                    | `{"get_param":{"param_ver":{}}}`                    | 当前版本                       | 只读参数                                                                                                                                                          |
| 编译日期时间        | -                                                                    | `{"get_param":{"build_datetime":{}}}`               | 编译时日期时间                    | 只读参数                                                                                                                                                          |
| 完整版本信息        | -                                                                    | `{"get_param":{"full_ver":{}}}`                     | 版本信息                       | 只读参数,包含所有版本信息的组合字符串                                                                                                                                             |
| MQTT 服务器      | `{"set_param":{"mqtt_server":"mqtt.example.com"}}`                  | `{"get_param":{"mqtt_server":{}}}`                  | "192.168.1.45"             |                                                                                                                                                               |
| MQTT 端口       | `{"set_param":{"mqtt_port":1883}}`                                  | `{"get_param":{"mqtt_port":{}}}`                    | 1883                       |                                                                                                                                                               |
| MQTT 用户名      | `{"set_param":{"mqtt_username":"user"}}`                            | `{"get_param":{"mqtt_username":{}}}`                | ""                         |                                                                                                                                                               |
| MQTT 密码       | `{"set_param":{"mqtt_password":"pass"}}`                            | `{"get_param":{"mqtt_password":{}}}`                | ""                         |                                                                                                                                                               |
| MQTT 客户端 ID   | `{"set_param":{"client_id":"client001"}}`                           | `{"get_param":{"client_id":{}}}`                    | 基于 MAC 地址生成               |                                                                                                                                                               |
| 设备订阅主题        | `{"set_param":{"device_sub_topic":"dev001/sub"}}`                   | `{"get_param":{"device_sub_topic":{}}}`             | "dev001/sub"               |                                                                                                                                                               |
| 设备发布主题        | `{"set_param":{"device_pub_topic":"dev001/pub"}}`                   | `{"get_param":{"device_pub_topic":{}}}`             | "dev001/pub"               |                                                                                                                                                               |
| 网络控制台主题       | `{"set_param":{"device_net_console_topic":"dev001/console"}}`       | `{"get_param":{"device_net_console_topic":{}}}`     | "dev001/console"           |                                                                                                                                                               |
| TCP 服务器       | `{"set_param":{"tcp_server":"192.168.1.45"}}`                       | `{"get_param":{"tcp_server":{}}}`                   | "192.168.1.45"             |                                                                                                                                                               |
| TCP 端口        | `{"set_param":{"tcp_port":8080}}`                                   | `{"get_param":{"tcp_port":{}}}`                     | 8080                       |                                                                                                                                                               |
| HTTP 端口       | `{"set_param":{"http_port":80}}`                                    | `{"get_param":{"http_port":{}}}`                    | 80                         |                                                                                                                                                               |
| OTA 标志        | `{"set_param":{"ota_f":true}}`                                      | `{"get_param":{"ota_f":{}}}`                        | true                       | OTA 升级标志位,true:允许 OTA,false:禁止 OTA                                                                                                                            |
| 网络控制台使能       | `{"set_param":{"net_console_en":true}}`                             | `{"get_param":{"net_console_en":{}}}`               | false                      | 启用网络控制台功能,可通过 MQTT 发送调试命令                                                                                                                                      |
| 串口控制台使能       | `{"set_param":{"com_console_en":true}}`                             | `{"get_param":{"com_console_en":{}}}`               | true                       | 启用串口控制台功能,可通过串口发送调试命令                                                                                                                                         |
| Ping 功能使能     | `{"set_param":{"ping_en":true}}`                                    | `{"get_param":{"ping_en":{}}}`                      | true                       | 启用 Ping 主动上报功能                                                                                                                                             |
| Ping 上报间隔     | `{"set_param":{"ping_interval_s":30}}`                              | `{"get_param":{"ping_interval_s":{}}}`              | 60                         | Ping 消息上报间隔,单位:秒                                                                                                                                             |
| WiFi SSID     | `{"set_param":{"wifi_ssid":"xxxx"}}`                                | `{"get_param":{"wifi_ssid":{}}}`                    | "88888888"                 |                                                                                                                                                               |
| WiFi密码        | `{"set_param":{"wifi_pwd":"xxxx"}}`                                 | `{"get_param":{"wifi_pwd":{}}}`                     | "88888888"                 |                                                                                                                                                               |
| 按键锁定          | `{"set_param":{"key_lock":true}}`                                   | `{"get_param":{"key_lock":{}}}`                     | false                      | 设置按键锁定状态(true:锁定 false:解锁)                                                                                                                                   |
| 使用静态 IP       | `{"set_param":{"use_static_ip":true}}`                              | `{"get_param":{"use_static_ip":{}}}`                | true                       | 是否启用静态 IP，true:启用，false:关闭                                                                                                                                   |
| 静态 IP 地址      | `{"set_param":{"static_ip":"192.168.1.100"}}`                       | `{"get_param":{"static_ip":{}}}`                    | 192.168.1.199              | 静态 IP 地址，格式如 "192.168.1.100"                                                                                                                                 |
| 网关 IP 地址      | `{"set_param":{"gateway_ip":"192.168.1.1"}}`                        | `{"get_param":{"gateway_ip":{}}}`                   | 192.168.1.1                | 网关 IP 地址，格式如 "192.168.1.1"                                                                                                                                   |
| 子网掩码          | `{"set_param":{"subnet_mask":"255.255.255.0"}}`                     | `{"get_param":{"subnet_mask":{}}}`                  | 255.255.255.0              | 子网掩码，格式如 "255.255.255.0"                                                                                                                                     |

### 5.3. 状态设置&状态获取 (RC产品专用)

状态(Status)与参数(Param)的区别:
1. 状态是运行时的实时数据, 如当前锁状态、IC卡接触状态等，这些数据断电后不会保存
2. 当设备收到状态获取命令后, 会返回对应的状态值, 具体格式请参考: [[#5.6. 消息应答]]

| 命令 | 设置状态 | 获取状态 | 说明 |
| --------- | --------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
| WiFi信号强度 | - | `{"get_status":{"rssi_abs":{}}}` | 只读参数,WiFi信号强度的绝对值: 50: 非常好 60~70: 好 70~80: 一般 80~90: 差 |
| 脱钩锁状态组 | `{"set_status":{"locks":[true,false,true,false,true,true,true,true]}}` | `{"get_status":{"locks":{}}}` | 设置/获取所有脱钩锁状态数组: 返回格式: [true,false,true,false,true,false,true,false] 数组索引从0开始，对应锁编号0-7 true: 开锁操作/开锁状态, false: 保持当前状态/锁定状态 |
| IC卡接触状态组 | - | `{"get_status":{"card_st":{}}}` | 获取所有IC卡接触状态数组: 返回格式: [true,false,true,false,true,false,true,false] 数组索引从0开始，对应锁编号0-7 true: 有卡接触, false: 无卡接触 |
| IC卡编号状态组 | - | `{"get_status":{"card_id":{}}}` | 获取所有IC卡编号数组: 返回格式: ["1234567890123456","0000000000000000","ABCDEF1234567890",...] 数组索引从0开始，对应锁编号0-7 32字符十六进制字符串，无卡时为空字符串或全零 |

### 5.4. 事件上报 (RC产品专用)

| 事件类型          | JSON 格式                                              | 说明                        |
| ------------- | ---------------------------------------------------- | ------------------------- |
| OTA 更新完成事件    | `{"event":{"ota_end_evt":"更新结果"}}`                   | OTA 升级完成后上报结果             |
| 上电事件          | `{"event":{"powerup_evt":""}}`                       | 设备上电时上报                   |
| 重启事件          | `{"event":{"reboot_evt":""}}`                        | 设备重启时上报                   |
| 恢复出厂设置事件      | `{"event":{"factory_params_evt":""}}`                | 恢复出厂设置时上报                 |
| 系统信息上报事件      | `{"event":{"report_sysinfo_evt":"系统信息"}}`            | 上报系统所有可获取参数               |
| 断电事件          | `{"event":{"powerdown_evt":""}}`                     | 设备断电时上报                   |
| 按键短按          | `{"event":{"key_id":0,"short_click_evt":{}}}`        | 按键0被短按时触发,key_id:按键编号     |
| 按键长按          | `{"event":{"key_id":0,"long_click_evt":{}}}`         | 按键0被长按时触发,key_id:按键编号     |
| 按键超长按         | `{"event":{"key_id":0,"extra_long_click_evt":{}}}`   | 按键0被超长按时触发,key_id:按键编号    |
| 按键双击          | `{"event":{"key_id":0,"double_click_evt":{}}}`       | 按键0被双击时触发,key_id:按键编号     |
| 按键三击          | `{"event":{"key_id":0,"triple_click_evt":{}}}`       | 按键0被三击时触发,key_id:按键编号     |
| 脱钩锁状态变化事件     | `{"event":{"locks":[true,false,true,false,true,false,true,false]}}` | 当任意脱钩锁状态发生变化时，上报所有锁的当前状态    |
| 单个脱钩锁状态变化事件   | `{"event":{"lock_id":0,"lock_state_changed_evt":true}}` | 当特定脱钩锁状态发生变化时上报，lock_id表示锁编号(0-7)，true表示开锁状态，false表示锁定状态 |
| IC卡接触事件       | `{"event":{"card_contact_evt":{"lock_id":0,"card_id":"4263429281","timestamp":135893}}}` | 当IC卡与锁位接触时上报，card_contact_evt包含锁编号(0-7)、IC卡编号和时间戳(ms) |
| IC卡离开事件       | `{"event":{"card_remove_evt":{"lock_id":0,"card_id":"4263429281","timestamp":142893}}}` | 当IC卡从锁位离开时上报，card_remove_evt包含锁编号(0-7)、IC卡编号和时间戳(ms) |
| IC卡更换事件       | `{"event":{"card_change_evt":{"lock_id":0,"old_card_id":"1234567890123456","new_card_id":"ABCDEF1234567890","timestamp":148293}}}` | 当IC卡编号发生变化时上报，适用于台球杆租赁场景中的换位归还情况，card_change_evt包含锁编号(0-7)、旧卡号、新卡号和时间戳(ms) |

注意：
1. 按键事件上报中的数值表示按键索引，从0开始
2. 按键事件的触发时间：
   - 短按：立即触发
   - 双击：两次按键间隔小于300ms
   - 三击：三次按键间隔小于500ms
   - 长按：按住时间超过3秒
   - 超长按：按住时间超过10秒
3. 当按键被锁定时（key_lock=true），所有按键事件将被禁用
4. 对于RC产品：
   - 脱钩锁编号从0开始（锁编号: 0-7）
   - 锁状态: true=开锁状态, false=锁定状态
   - 脱钩锁控制通过脉冲信号实现开锁操作，不支持上锁操作
   - 批量锁状态变化时，上报所有8个锁的状态数组
   - 单个锁状态变化时，上报具体的锁编号和状态
5. 对于IC卡功能：
   - IC卡编号格式：根据实际IC卡而定，长度可变（如示例中的"4263429281"为10字符）
   - 无卡接触时card_st对应位置为false，card_id为空字符串或全零
   - 卡接触和离开事件实时上报，便于应用层及时响应
   - 所有IC卡事件采用嵌套对象格式，事件信息包含在具体的事件对象内
   - 事件对象包含timestamp字段：表示事件发生的时间戳（毫秒）
   - IC卡更换事件：当同一锁位的IC卡编号发生变化时触发，包含旧卡号和新卡号信息
   - 适用场景：台球杆租赁柜中用户归还时可能换位归还，导致同一锁位的IC卡编号改变

### 5.5. 主动上报 (RC产品适用)

"硬件终端"间隔一定的时间,会往"服务器端",上报的报文
该报文是可选,可使用"参数设置"报文开启或关闭
可通过"参数设置"报文,设置上报时间间隔

| 消息类型 | JSON 格式                                                                                    | 说明                   |
| ---- | ------------------------------------------------------------------------------------------ | -------------------- |
| 心跳包  | `{"report":{"ping": { "device_id": "xxxx", "full_ver": "x.x.x", "rssi_abs": "-70 dBm"}}}` | 包含设备基本信息等完整信息 |

### 5.6. 消息应答

终端收到服务器下发的消息后,会根据消息执行结果返回对应的应答帧。
应答帧格式如下:

| 消息类型 | JSON 格式 | 说明 |
| ------ | --------------------------- | -------------------------------------------------------------------------------------- |
| 确认应答 | `{"ask":true}` | 命令执行成功的应答 |
| 否认应答 | `{"ask":false}` | 命令执行失败的应答 |
| 获取参数应答 | {"get_param":{"name":val}} | 举例: 发送`{"get_param":{"device_id":{}}}` 返回 `{"ask_param":{"device_id":"dev001"}}` |
| 获取状态应答 | {"get_status":{"name":val}} | 举例: 脱钩锁状态查询: 发送`{"get_status":{"locks":{}}}` 返回 `{"ask_status":{"locks":[true,false,true,false,true,false,true,false]}}` 单个锁状态查询应答: 发送`{"ctrl_cmd":{"query_lock_cmd":"0"}}` 返回 `{"ask_status":{"lock_0":true}}` 单个IC卡查询应答: 发送`{"ctrl_cmd":{"query_card_cmd":"0"}}` 返回 `{"ask_status":{"card_0":{"card_st":true,"card_id":"1234567890123456"}}}` IC卡状态查询: 发送`{"get_status":{"card_st":{}}}` 返回 `{"ask_status":{"card_st":[true,false,true,false,true,false,true,false]}}` 发送`{"get_status":{"card_id":{}}}` 返回 `{"ask_status":{"card_id":["1234567890123456","","ABCD123456789012","","","","",""]}}` |
| 未知命令 | `{"unknown_cmd":0}` | 收到未知命令时的应答 |

## 六、脱钩锁控制功能说明

### 6.1. 功能概述

脱钩锁控制功能专用于RC产品（智能租赁柜），用于控制多个独立的脱钩锁。该功能通过以下方式工作：
1. 支持8个独立的脱钩锁控制
2. **只提供开锁功能，不提供锁定功能**
3. 通过脉冲信号控制锁的开启
4. 实时监测锁的状态反馈
5. **支持批量操作和单个操作两种模式**

### 6.2. 硬件特性

- **锁数量**: 8个独立脱钩锁
- **控制方式**: 脉冲信号控制（默认100ms脉冲宽度）
- **状态反馈**: 实时状态检测
- **锁编号**: 0-7（对应数组索引0-7）
- **功能限制**: 仅支持开锁操作，不支持上锁操作

### 6.3. 控制方式说明

#### 6.3.1. 批量操作（推荐使用）
通过 `set_status` 指令进行批量锁控制，适合需要同时操作多个锁的场景：
```json
{"set_status":{"locks":[true,false,true,false,true,true,true,true]}}
```
- 数组中 `true` 表示对该位置的锁执行开锁操作
- 数组中 `false` 表示保持该锁当前状态不变
- 数组索引0-7对应锁编号0-7

#### 6.3.2. 单个操作
通过 `ctrl_cmd` 指令进行单个锁控制，适合单独操作某个锁的场景：
```json
{"ctrl_cmd":{"unlock_lock_cmd":"0"}}    // 开锁编号为0的锁
{"ctrl_cmd":{"query_lock_cmd":"0"}}     // 查询编号为0的锁状态
```

### 6.4. 通信流程

#### 6.4.1. 批量脱钩锁控制流程

```mermaid
sequenceDiagram
    participant App as 应用终端
    participant Device as RC设备

App->>Device: 批量设置锁状态 {"set_status":{"locks":[true,false,true,false,true,true,true,true]}}
    Device-->>App: 返回确认帧 {"ask":true}
    Note over Device: 根据数组状态对相应的锁执行开锁操作
    Device->>App: 上报锁状态变化事件 {"event":{"locks":[true,false,true,false,true,true,true,true]}}

App->>Device: 查询所有锁状态 {"get_status":{"locks":{}}}
    Device-->>App: 返回所有锁状态 {"ask_status":{"locks":[true,false,true,false,true,true,true,true]}}

```

#### 6.4.2. 单个脱钩锁控制流程

```mermaid
sequenceDiagram
    participant App as 应用终端
    participant Device as RC设备

App->>Device: 开锁单个脱钩锁 {"ctrl_cmd":{"unlock_lock_cmd":"0"}}
    Device-->>App: 返回确认帧 {"ask":true}
    Note over Device: 对锁0执行开锁操作
    Device->>App: 上报单个锁状态变化 {"event":{"lock_id":0,"lock_state_changed_evt":true}}
    Device->>App: 上报所有锁状态变化 {"event":{"locks":[true,false,true,false,true,false,true,false]}}

App->>Device: 查询单个锁状态 {"ctrl_cmd":{"query_lock_cmd":"0"}}
    Device-->>App: 返回单个锁状态 {"ask_status":{"lock_0":true}}

```

#### 6.4.3. 锁状态查询流程

```mermaid
sequenceDiagram
    participant App as 应用终端
    participant Device as RC设备

App->>Device: 查询所有锁状态 {"get_status":{"locks":{}}}
    Device-->>App: 返回所有锁状态 {"ask_status":{"locks":[true,false,true,false,true,false,true,false]}}

Note over App: 锁编号0-7，true表示开锁状态，false表示锁定状态

```

### 6.5. 相关指令说明

| 类型 | 指令 | 说明 |
| ---- | ----------------------------------------------- | --------------------------- |
| 状态设置 | `{"set_status":{"locks":[true,false,true,false,true,true,true,true]}}` | 批量设置所有锁状态 数组索引0-7对应锁编号0-7 true: 开锁操作, false: 保持当前状态 |
| 状态查询 | `{"get_status":{"locks":{}}}` | 查询所有锁的状态数组 |
| 单个开锁 | `{"ctrl_cmd":{"unlock_lock_cmd":"0"}}` | 开锁单个脱钩锁，参数为锁编号(0-7) |
| 单个查询 | `{"ctrl_cmd":{"query_lock_cmd":"0"}}` | 查询单个脱钩锁状态，参数为锁编号(0-7) |

### 6.6. 事件说明

| 事件类型    | JSON 格式                                         | 说明            |
| ------- | ----------------------------------------------- | ------------- |
| 批量锁状态变化事件 | `{"event":{"locks":[true,false,true,false,true,false,true,false]}}` | 任意锁状态发生变化时上报所有锁状态 |
| 单个锁状态变化事件 | `{"event":{"lock_id":0,"lock_state_changed_evt":true}}` | 特定锁状态变化时上报，包含锁编号和状态 |

### 6.7. 工作原理

1. **脉冲控制机制**：
   - 每个锁通过独立的输出引脚发送控制脉冲
   - 脉冲宽度默认为100ms
   - 脉冲电平可配置（默认高电平有效）
   - 只支持开锁脉冲，不支持上锁脉冲

2. **状态反馈机制**：
   - 每个锁配备独立的状态检测引脚
   - 实时监测锁的开启/锁定状态
   - 状态变化时自动上报事件

3. **批量控制优化**：
   - 支持通过状态设置同时控制多个锁
   - 只有设置为true的锁执行开锁操作
   - 设置为false的锁保持当前状态不变

4. **单个控制支持**：
   - 支持通过控制命令操作单个锁
   - 解决JSON标准语法不支持设置单个数组元素的限制
   - 提供单个锁状态查询功能

5. **安全机制**：
   - 每次操作后自动检测状态
   - 操作失败时上报相应的错误事件
   - 支持重试机制

6. **使用说明**：
   - 锁编号从0开始（0-7），对应数组索引0-7
   - 只能执行开锁操作，不能执行锁定操作
   - 状态数组中true表示开锁状态，false表示锁定状态
   - 批量操作适合多锁同时控制场景
   - 单个操作适合精确控制单个锁场景

## 七、IC卡检测功能说明

### 7.1. 功能概述

IC卡检测功能专用于RC产品（智能租赁柜），用于检测每个锁位的IC卡接触状态和读取卡号。该功能提供：
1. 支持8个锁位的IC卡检测（对应锁编号0-7）
2. 实时检测IC卡接触状态
3. 读取并上报IC卡编号（32字符十六进制格式）
4. IC卡接触和离开事件实时上报

### 7.2. 硬件特性

- **检测位置**: 8个独立IC卡检测位（对应锁编号0-7）
- **卡片格式**: 支持标准IC卡
- **卡号格式**: 32字符十六进制字符串
- **检测方式**: 实时状态监测
- **响应速度**: 毫秒级检测响应

### 7.3. 状态数据说明

#### 7.3.1. IC卡接触状态数组 (card_st)
```json
{"get_status":{"card_st":{}}}
// 返回示例: {"ask_status":{"card_st":[true,false,true,false,false,false,false,false]}}
```
- 数组索引0-7对应锁编号0-7
- `true`: 该位置有IC卡接触
- `false`: 该位置无IC卡接触

#### 7.3.2. IC卡编号数组 (card_id)
```json
{"get_status":{"card_id":{}}}
// 返回示例: {"ask_status":{"card_id":["1234567890123456","","ABCDEF1234567890","","","","",""]}}
```
- 数组索引0-7对应锁编号0-7
- 32字符十六进制字符串格式
- 无卡接触时为空字符串或全零字符串

### 7.4. 事件上报

#### 7.4.1. IC卡接触事件
```json
{"event":{"card_contact_evt":{"lock_id":0,"card_id":"4263429281","timestamp":135893}}}
```
- `card_contact_evt`: IC卡接触事件对象
  - `lock_id`: 锁编号(0-7)，表示哪个锁位检测到卡片
  - `card_id`: 卡号，根据实际IC卡而定（长度可变）
  - `timestamp`: 事件发生的时间戳（毫秒）

#### 7.4.2. IC卡离开事件
```json
{"event":{"card_remove_evt":{"lock_id":0,"card_id":"4263429281","timestamp":142893}}}
```
- `card_remove_evt`: IC卡离开事件对象
  - `lock_id`: 锁编号(0-7)，表示哪个锁位的卡片离开
  - `card_id`: 离开的卡号，根据实际IC卡而定（长度可变）
  - `timestamp`: 事件发生的时间戳（毫秒）

#### 7.4.3. IC卡更换事件
```json
{"event":{"card_change_evt":{"lock_id":0,"old_card_id":"1234567890123456","new_card_id":"ABCDEF1234567890","timestamp":148293}}}
```
- `card_change_evt`: IC卡更换事件对象
  - `lock_id`: 锁编号(0-7)，表示哪个锁位的IC卡发生更换
  - `old_card_id`: 原卡号，根据实际IC卡而定（长度可变）
  - `new_card_id`: 新卡号，根据实际IC卡而定（长度可变）
  - `timestamp`: 事件发生的时间戳（毫秒）

### 7.5. 通信流程

#### 7.5.1. IC卡批量查询流程

```mermaid
sequenceDiagram
    participant App as 应用终端
    participant Device as RC设备

App->>Device: 查询IC卡接触状态 {"get_status":{"card_st":{}}}
    Device-->>App: 返回接触状态数组 {"ask_status":{"card_st":[true,false,true,false,false,false,false,false]}}

App->>Device: 查询IC卡编号 {"get_status":{"card_id":{}}}
    Device-->>App: 返回卡号数组 {"ask_status":{"card_id":["1234567890123456","","ABCDEF1234567890","","","","",""]}}

Note over App: 索引0,2有卡接触，其他位置无卡
```

#### 7.5.2. IC卡单个查询流程

```mermaid
sequenceDiagram
    participant App as 应用终端
    participant Device as RC设备

App->>Device: 查询单个IC卡信息 {"ctrl_cmd":{"query_card_cmd":"0"}}
    Device-->>App: 返回单个卡信息 {"ask_status":{"card_0":{"card_st":true,"card_id":"1234567890123456"}}}

App->>Device: 查询无卡位置 {"ctrl_cmd":{"query_card_cmd":"1"}}
    Device-->>App: 返回无卡状态 {"ask_status":{"card_1":{"card_st":false,"card_id":""}}}

Note over App: 锁位0有卡，锁位1无卡
```

#### 7.5.3. IC卡事件上报流程

```mermaid
sequenceDiagram
    participant Card as IC卡
    participant Device as RC设备
    participant App as 应用终端

Note over Card,Device: 用户将IC卡放置到锁位0
    Card->>Device: 卡片接触检测到
    Device->>App: 上报接触事件 {"event":{"card_contact_evt":{"lock_id":0,"card_id":"4263429281","timestamp":135893}}}

Note over Card,Device: 用户移除IC卡
    Card->>Device: 卡片离开检测到
    Device->>App: 上报离开事件 {"event":{"card_remove_evt":{"lock_id":0,"card_id":"4263429281","timestamp":142893}}}
```

#### 7.5.4. IC卡更换事件上报流程

```mermaid
sequenceDiagram
    participant OldCard as 旧IC卡
    participant NewCard as 新IC卡  
    participant Device as RC设备
    participant App as 应用终端

Note over OldCard,Device: 锁位0原有IC卡"1234567890123456"
    Note over NewCard,Device: 用户归还时将不同IC卡"ABCDEF1234567890"放入锁位0
    
    NewCard->>Device: 检测到卡片更换
    Device->>App: 上报IC卡更换事件 {"event":{"card_change_evt":{"lock_id":0,"old_card_id":"1234567890123456","new_card_id":"ABCDEF1234567890","timestamp":148293}}}
    
    Note over App: 应用层可根据此事件追踪物品换位归还情况
```

### 7.6. 相关指令说明

| 类型   | 指令                                  | 说明                          |
| ---- | ----------------------------------- | --------------------------- |
| 状态查询 | `{"get_status":{"card_st":{}}}`     | 查询所有位置IC卡接触状态数组             |
| 状态查询 | `{"get_status":{"card_id":{}}}`     | 查询所有位置IC卡编号数组               |
| 单个查询 | `{"ctrl_cmd":{"query_card_cmd":"0"}}` | 查询单个IC卡信息，参数为锁编号(0-7)        |

### 7.7. 应用场景

1. **租赁验证**: 用户使用IC卡验证身份后开锁
2. **状态监控**: 实时监控哪些锁位有物品存放（通过IC卡存在判断）
3. **归还检测**: 检测物品归还时的IC卡状态
4. **审计跟踪**: 记录IC卡使用历史和锁位占用情况

### 7.8. 使用说明

1. **卡号格式**: IC卡编号根据实际IC卡而定，长度可变（如示例中的"4263429281"为10字符数字格式）
2. **状态对应**: card_st和card_id数组索引与锁编号一一对应
3. **实时性**: IC卡接触和离开事件实时上报，延迟通常小于100ms
4. **错误处理**: 读卡失败时card_id对应位置为空字符串
5. **兼容性**: 支持多种标准IC卡类型

## 八、协议应用示例

### 8.1. 完整开锁操作示例

#### 批量开锁示例：
```json
// 应用端发送：同时开启锁0、2、4、5、6、7
{"set_status":{"locks":[true,false,true,false,true,true,true,true]}}

// 设备应答：
{"ask":true}

// 设备事件上报：
{"event":{"locks":[true,false,true,false,true,true,true,true]}}
```

#### 单个开锁示例：
```json
// 应用端发送：开启锁0
{"ctrl_cmd":{"unlock_lock_cmd":"0"}}

// 设备应答：
{"ask":true}

// 设备事件上报：
{"event":{"lock_id":0,"lock_state_changed_evt":true}}
{"event":{"locks":[true,false,true,false,true,false,true,false]}}
```

### 8.2. 状态查询示例

#### 查询所有锁状态：
```json
// 应用端发送：
{"get_status":{"locks":{}}}

// 设备应答：
{"ask_status":{"locks":[true,false,true,false,true,false,true,false]}}
```

#### 查询单个锁状态：
```json
// 应用端发送：查询锁0状态
{"ctrl_cmd":{"query_lock_cmd":"0"}}

// 设备应答：
{"ask_status":{"lock_0":true}}
```

### 8.3. IC卡检测示例

#### 查询所有IC卡状态：
```json
// 应用端发送：查询IC卡接触状态
{"get_status":{"card_st":{}}}

// 设备应答：
{"ask_status":{"card_st":[true,false,true,false,false,false,false,false]}}

// 应用端发送：查询IC卡编号
{"get_status":{"card_id":{}}}

// 设备应答：
{"ask_status":{"card_id":["1234567890123456","","ABCDEF1234567890","","","","",""]}}
```

#### 查询单个IC卡状态：
```json
// 应用端发送：查询锁位0的IC卡信息
{"ctrl_cmd":{"query_card_cmd":"0"}}

// 设备应答：
{"ask_status":{"card_0":{"card_st":true,"card_id":"1234567890123456"}}}

// 应用端发送：查询锁位1的IC卡信息（无卡情况）
{"ctrl_cmd":{"query_card_cmd":"1"}}

// 设备应答：
{"ask_status":{"card_1":{"card_st":false,"card_id":""}}}
```

#### IC卡事件上报示例：
```json
// IC卡接触事件：
{"event":{"card_contact_evt":{"lock_id":0,"card_id":"4263429281","timestamp":135893}}}

// IC卡离开事件：
{"event":{"card_remove_evt":{"lock_id":0,"card_id":"4263429281","timestamp":142893}}}

// IC卡更换事件（台球杆租赁场景）：
{"event":{"card_change_evt":{"lock_id":0,"old_card_id":"1234567890123456","new_card_id":"ABCDEF1234567890","timestamp":148293}}}
```

#### IC卡更换事件详细示例：
```json
// 场景：用户租用台球杆时，锁位0绑定了卡号"1234567890123456"
// 用户归还时将另一支台球杆（卡号"ABCDEF1234567890"）放入锁位0

// 设备检测到卡号变化，上报IC卡更换事件：
{
  "event": {
    "card_change_evt": {
      "lock_id": 0,
      "old_card_id": "1234567890123456",
      "new_card_id": "ABCDEF1234567890",
      "timestamp": 148293
    }
  }
}

// 应用层可以根据此事件进行以下处理：
// 1. 记录物品换位归还情况
// 2. 更新库存管理系统
// 3. 追踪台球杆的实际位置
// 4. 发送提醒给管理员进行位置调整
```

### 8.4. 综合使用示例

#### 智能租赁流程：
```json
// 1. 用户放置IC卡到锁位0
// 设备自动上报：
{"event":{"card_contact_evt":{"lock_id":0,"card_id":"4263429281","timestamp":135893}}}

// 2. 应用验证卡片后开锁
// 应用发送：
{"ctrl_cmd":{"unlock_lock_cmd":"0"}}

// 设备应答：
{"ask":true}

// 3. 设备上报锁状态变化
// 设备上报：
{"event":{"lock_id":0,"lock_state_changed_evt":true}}
{"event":{"locks":[true,false,false,false,false,false,false,false]}}

// 4. 用户归还时移除IC卡
// 设备自动上报：
{"event":{"card_remove_evt":{"lock_id":0,"card_id":"4263429281","timestamp":142893}}}
```

#### 台球杆换位归还流程：
```json
// 1. 锁位0原本有台球杆A（卡号"1234567890123456"）
// 2. 用户租走台球杆A后，将台球杆B（卡号"ABCDEF1234567890"）归还到锁位0

// 设备检测到卡号变化，上报IC卡更换事件：
{"event":{"card_change_evt":{"lock_id":0,"old_card_id":"1234567890123456","new_card_id":"ABCDEF1234567890","timestamp":148293}}}

// 应用系统接收到事件后可以：
// - 更新锁位0的物品信息为台球杆B
// - 标记台球杆A为缺失状态
// - 发送管理员提醒进行库存盘点
// - 记录换位归还日志便于后续追踪
```

## 九、版本历史

### v1.7.0 (当前版本)
- **IC卡事件格式优化** (最新更新):
  - **嵌套对象格式**: 将IC卡事件从扁平格式改为嵌套对象格式，提升可读性和扩展性
  - **统一字段命名**: 事件中统一使用card_id字段名，避免混淆
  - **移除冗余字段**: 移除独立的event_type字段，通过事件名称即可识别类型
  - **新格式示例**:
    - IC卡接触: `{"event":{"card_contact_evt":{"lock_id":0,"card_id":"4263429281","timestamp":135893}}}`
    - IC卡离开: `{"event":{"card_remove_evt":{"lock_id":0,"card_id":"4263429281","timestamp":142893}}}`
    - IC卡更换: `{"event":{"card_change_evt":{"lock_id":0,"old_card_id":"1234567890123456","new_card_id":"ABCDEF1234567890","timestamp":148293}}}`
- **IC卡事件格式完善**:
  - 所有IC卡事件增加timestamp字段：表示事件发生的时间戳（毫秒）
  - IC卡编号格式说明：根据实际IC卡而定，长度可变（不再固定32字符格式）
- **IC卡更换事件新增**: 
  - 新增IC卡更换事件（card_change_evt），支持同一锁位IC卡编号变化检测
  - 包含旧卡号（old_card_id）和新卡号（new_card_id）信息
  - 专门针对台球杆租赁柜换位归还场景优化
  - 便于应用层追踪物品换位归还和库存管理
- **通信流程完善**:
  - 新增IC卡更换事件上报流程图
  - 完善台球杆换位归还应用示例
  - 添加详细的事件处理建议和应用场景说明

### v1.6.0
- **IC卡功能新增**: 
  - 新增IC卡接触状态检测（card_st数组）
  - 新增IC卡编号识别（card_id数组）
  - 新增IC卡接触事件（card_contact_evt）
  - 新增IC卡离开事件（card_remove_evt）
  - 支持32字符十六进制卡号格式
- **协议完善**:
  - 更新状态查询接口支持IC卡状态
  - 新增IC卡相关事件上报
  - 完善应用示例和使用说明
  - 新增IC卡检测功能专门章节

### v1.5.0
- **RC产品专用协议提取**: 从主协议v1.5中提取所有RC产品相关内容
- **脱钩锁功能完善**: 
  - 支持单个锁控制命令（unlock_lock_cmd, query_lock_cmd）
  - 支持批量操作（set_status）和单个操作（ctrl_cmd）两种模式
  - 新增单个锁状态变化事件上报
  - 术语统一：使用"脱钩锁"
  - 锁编号从0开始（0-7）
  - 强调仅支持开锁功能
- **协议规范化**:
  - 提取RC产品专用控制指令
  - 整理RC产品相关参数和状态操作
  - 完善事件上报机制
  - 提供完整的通信流程图

### 基于主协议版本
- **v1.6**: IC卡检测功能新增
- **v1.5**: 脱钩锁功能完善
- **v1.4**: 重大功能更正，RC产品实现方式修正
- **v1.3**: 新增RC产品类型支持