# 服务控制台示例
[English Version](./README.md)
本示例演示了如何通过控制台运行和测试 ESP Brookesia 的服务框架功能。
本示例提供了一个交互式命令行界面，允许您通过串口控制台与各种系统服务进行交互，包括 NVS（非易失性存储）、WiFi、音频、Agent（智能体）、SNTP（网络时间协议）等服务。
本示例可以作为开发和调试 ESP Brookesia 服务的工具。
## 目录
- [服务控制台示例](#服务控制台示例)
- [目录](#目录)
- [快速入门](#快速入门)
- [准备工作](#准备工作)
- [ESP-IDF 要求](#esp-idf-要求)
- [配置](#配置)
- [如何使用示例](#如何使用示例)
- [编译和烧录示例](#编译和烧录示例)
- [命令说明](#命令说明)
- [基本命令](#基本命令)
- [列出所有服务](#列出所有服务)
- [列出服务函数和事件](#列出服务函数和事件)
- [订阅/取消订阅服务事件](#订阅取消订阅服务事件)
- [停止服务绑定](#停止服务绑定)
- [调用服务函数](#调用服务函数)
- [调试命令](#调试命令)
- [内存分析器](#内存分析器)
- [线程分析器](#线程分析器)
- [时间分析器](#时间分析器)
- [RPC 命令](#rpc-命令)
- [故障排除](#故障排除)
- [常见问题](#常见问题)
- [技术支持与反馈](#技术支持与反馈)
## 快速入门
### 准备工作
本示例支持 ESP32-S3/P4 开发板（如 ESP-BOX-3）。示例通过串口控制台提供交互式命令行界面。
### ESP-IDF 要求
此示例支持以下 ESP-IDF 版本：
- ESP-IDF release/v5.5 最新版本
请参照 [ESP-IDF 编程指南](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/index.html) 设置开发环境。**强烈推荐** 通过 [编译第一个工程](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/index.html#id8) 来熟悉 ESP-IDF，并确保环境设置正确。
### 配置
运行 `idf.py menuconfig` 可以在 `Example Configuration` 菜单中配置以下选项：
- **Console Configuration**：配置控制台相关选项，如是否在 Flash 中存储命令历史、最大命令行长度等
- **Board Manager**：启用板级管理器（可选）
- **Services**：启用或禁用特定服务（NVS、SNTP、WiFi、Audio）
- **Agents**：配置 Agent 服务（Coze、OpenAI），包括 API 密钥、Bot 配置等
> [!WARNING]
> - 请注意，由于 `esp_board_manager` 组件 `v0.5.0` 版本存在依赖问题，请暂时不要启用板级管理器, 否则会导致编译失败，待新版本问题修复后，可启用板级管理器。
> - `Audio` 和 `Agent` 服务需要启用板级管理器才能正常工作，因此暂不支持使用。
## 如何使用示例
### 编译和烧录示例
编译项目并将其烧录到开发板上，运行监视工具可查看串行端口输出（将 `PORT` 替换为所用开发板的串行端口名）：
```bash
idf.py set-target <target>
idf.py -p PORT build flash monitor
```
输入 `Ctrl-]` 可退出串口监视。
有关配置和使用 ESP-IDF 来编译项目的完整步骤，请参阅 [ESP-IDF 快速入门指南](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/index.html) 。
## 命令说明
### 基本命令
本示例提供了管理所有注册服务的基础命令。通过这些命令，您可以查看可用服务、调用服务函数、订阅服务事件等。
#### 列出所有服务
查看所有已注册的服务：
```bash
svc_list
```
#### 列出服务函数和事件
查看指定服务的所有函数：
```bash
svc_funcs <服务名>
```
查看指定服务的所有事件：
```bash
svc_events <服务名>
```
#### 订阅/取消订阅服务事件
订阅服务事件（例如 WiFi 扫描结果更新）：
```bash
svc_subscribe <服务名> <事件名>
```
取消订阅服务事件：
```bash
svc_unsubscribe <服务名> <事件名>
```
#### 停止服务绑定
停止指定服务的绑定：
```bash
svc_stop <服务名>
```
### 调用服务函数
使用 `svc_call` 命令调用服务函数：
```bash
svc_call <服务名> <函数名> [JSON 参数]
```
JSON 参数为 JSON 格式。例如：
```bash
svc_call NVS Set {"KeyValuePairs":{"key1":"value1"}}
```
有关各服务的详细函数说明，请参考对应的服务文档：
- [NVS 服务](./docs/cmd_nvs_cn.md)： 非易失性存储服务
- [WiFi 服务](./docs/cmd_wifi_cn.md)： WiFi 连接和管理服务
- [音频服务](./docs/cmd_audio_cn.md)： 音频播放控制服务
- [Agent 服务](./docs/cmd_agent_cn.md)： AI 代理服务（Coze、OpenAI）
- [SNTP 服务](./docs/cmd_sntp_cn.md)： 网络时间同步服务
### 调试命令
本示例提供了调试命令，用于分析和监控系统性能：
#### 内存分析器
打印内存分析器信息：
```bash
debug_mem
```
#### 线程分析器
打印线程分析器信息：
```bash
debug_thread
```
使用自定义排序和采样持续时间：
```bash
# 设置主排序方式（none|core，默认：core）
debug_thread -p core
# 设置次排序方式（cpu|priority|stack|name，默认：cpu）
debug_thread -s cpu
# 设置采样持续时间（毫秒，默认：1000）
debug_thread -d 2000
# 组合使用
debug_thread -p core -s cpu -d 2000
```
#### 时间分析器
打印时间分析器报告：
```bash
debug_time_report
```
清除所有时间分析器数据：
```bash
debug_time_clear
```
> [!NOTE]
> 时间分析器数据需要代码中显式调用接口（如 `BROOKESIA_TIME_PROFILER_SCOPE()`、`BROOKESIA_TIME_PROFILER_START_EVENT()`、`BROOKESIA_TIME_PROFILER_END_EVENT()`）来采集。
### RPC 命令
除此之外，本示例还提供了 RPC 命令，允许您通过网络调用远程设备上的服务函数，并订阅远程服务事件。
有关 RPC 命令的详细说明，请参考 [RPC 命令](./docs/cmd_rpc_cn.md) 文档。
## 故障排除
### 常见问题
- **命令无法识别**：确保已正确编译和烧录示例，并且串口连接正常。
- **服务未找到**：使用 `svc_list` 命令查看所有可用服务，确保所需服务已启用。
- **RPC 连接失败**：确保设备已连接到同一 WiFi 网络。
- **开启板级管理器后编译失败**：由于 `esp_board_manager` 组件 `v0.5.0` 版本存在依赖问题，请暂时不要启用板级管理器, 待新版本问题修复后，可启用板级管理器。
- **Audio 服务无法使用**：由于 Audio 服务需要通过 `esp_board_manager` 组件初始化硬件资源，因此暂不支持使用。
- **Agent 无法使用**：由于 Agent 服务需要通过 `esp_board_manager` 组件初始化硬件资源，因此暂不支持使用。
## 技术支持与反馈
请通过以下渠道进行反馈：
- 有关技术问题，请访问 [esp32.com](https://esp32.com/viewforum.php?f=52&sid=86e7d3b29eae6d591c965ec885874da6) 论坛。
- 有关功能请求或错误报告，请创建新的 [GitHub 问题](https://github.com/espressif/esp-brookesia/issues)。
我们会尽快回复。
To create a project from this example, run:
idf.py create-project-from-example "espressif/brookesia_service_helper=0.7.1:service_console"