---
name: add-debug-command
description: 在 GateWay_Debug 模块中添加新的 Debug 调试命令（函数指针表 + 字符串匹配模式）
source: auto-skill
extracted_at: '2026-06-15T08:10:31.194Z'
---

# 添加 Debug 调试命令

本项目的 Debug 命令系统位于 `Project/GateWay/source/Module/GateWay_Debug/DebugCmd.c`，采用**函数指针表 + 字符串匹配**模式。

## 修改步骤

### 1. 编写 handler 函数

在 `DebugCmd.c` 中添加函数，签名固定为 `void FuncName(int argc, char *argv[])`：

```c
static void DebugCmdXxx(int argc, char *argv[])
{
    DBG_LOG("\r\n");
    if(strcmp(argv[1], "?") == 0) {
        DBG_LOG("Debug Cmd: xxx\r\n");
        DBG_LOG("  brief --> 功能描述.\r\n\r\n");
        return;
    }
    // 实际逻辑...
}
```

**必须遵循的模式：**
- 函数体第一行：`DBG_LOG("\r\n");`
- `"?"` 帮助分支：打印命令名和 brief 说明
- 若修改了 `ConfigPara`，调用 `WritePara()` 保存
- 需要被外部引用时声明为 `void`，仅内部使用时声明为 `static void`

### 2. 注册到命令表

在文件末尾的 `DebugFun[]` 常量数组中添加一行：

```c
const DBGFunType DebugFun[DEBUG_CMD_CNT] = {
    // ... 已有命令 ...
    "xxx",              DebugCmdXxx,
};
```

**容量限制：** `DEBUG_CMD_CNT = 30`，添加前检查剩余空位（当前使用 28/30）。若超出需增大该宏。

### 3. 添加到 help 输出

在 `DebugCmdHelp` 函数末尾添加：

```c
len = strlen("xxx ?\r\n");
memcpy(Data, "xxx ?\r\n", len);
DebugAnalyze(GateWay, Data, len);
```

## 可用的关键 API

| 函数 | 头文件 | 用途 |
|---|---|---|
| `CatOneEthSendQueue(data, len)` | CatOneTask.h | 将载荷放入网络发送队列（需 `SvrRegFlag == true`） |
| `CommUintOrgData(GateWay, CUPara, CUData, buf)` | Public.h | 组装通讯单元传感器数据包 |
| `GateWayRegister(TxBuff)` | CatOneTask.h | 组装网关注册包，返回长度 |
| `NetCommOrgData(GateWay, payload, outBuf)` | Public.h | 为载荷添加网络帧头(0x7A)+MAC+CRC |
| `WritePara(data, len)` | (bsp) | 保存配置参数到 Flash |
| `CatOneTriggerRegister()` | CatOneTask.h | 将 Cat1 状态机立即切换到注册状态 |
| `ETHTriggerRegister()` | CatOneTask.h | 将以太网状态机立即切换到注册状态 |

## 可用的全局/extern 变量

| 变量 | 类型 | 来源 |
|---|---|---|
| `GateWay` | `static GateWayPara` | DebugCmd.c 内静态指针，指向网关参数 |
| `SComm1Para` / `SComm2Para` | `SensorCommPara_t` | RS485Task.c 中定义，DebugCmd.c 已 extern |
| `GateWay->SvrRegFlag` | `bool` | 服务器注册状态 |
| `GateWay->ConfigPara` | `GWConfigPara_t` | 网关配置参数 |

## 注意事项

- `CatOne_t CatOne` 和 `CatOneEthTxBuff[]` 均为 CatOneTask.c 中的 **static** 变量，不能直接在 DebugCmd.c 中访问；应使用封装好的接口函数（如 `CatOneTriggerRegister()`、`ETHTriggerRegister()`）来操作状态机
- 重新注册应：清 `GateWay->SvrRegFlag = false`，然后根据通信模式调用 `CatOneTriggerRegister()` 或 `ETHTriggerRegister()` 立即切换状态机到注册状态，而不是仅清标志位等待状态机自动检测
- `CatOneEthSendQueue` 内部检查 `SvrRegFlag`，未注册时返回 `false`
- 命令解析函数 `DebugAnalyze` 按 `" "` 分割参数，去除 `\r`，最多 10 个参数
- `DEBUG_CMD_CNT = 30` 为命令容量上限，添加新命令前需检查当前使用量，若超出需将此宏增大（如改为31）
- 若模块需要保存独立的配置参数（如YOXO1007网络参数），可在DebugCmd.c中定义static变量，并通过Flash读写函数持久化（参考`EthNetPara_t`和`WriteEthNetPara`的实现）