Skip to content

07_API_Guide.md

Latest commit

 

History

History
276 lines (194 loc) · 8.34 KB

07_API_Guide.md

File metadata and controls

276 lines (194 loc) · 8.34 KB
Raw

07 — API 密钥获取与配置指南

⭐ 使用本教程前，请先支持一下这个开源项目：

  1. Star ⭐ — 点击 GitHub 仓库右上角 ⭐ Star，收藏本项目，方便以后找到
  2. Fork 🍴 — 点击 Fork，把项目复制到你的 GitHub 账号下，可以自由修改
  3. Download 📥 — 点击绿色 Code 按钮 → Download ZIP，下载到本地开始复刻

📸 操作示意图：

Star-Fork-Download

MindPaw 使用了两个云端 API 和一个离线语音模块，都需要申请或配置才能使用。本文一步步教你完成所有配置。

目录

1. 心知天气 API（天气查询）

1.1 注册账号

  1. 打开 心知天气官网
  2. 点击右上角 注册
  3. 可用邮箱或 GitHub 账号注册
  4. 注册后登录

1.2 获取 API Key

  1. 登录后进入控制台，点击左侧 产品管理
  2. 找到 天气数据 API，点击 免费版
  3. 免费版每天可调用 1000 次，对个人机器人完全够用
  4. 创建成功后，你会在页面上看到类似这样的密钥：
你的API密钥: S_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  1. 点击 复制，保存到记事本备用

1.3 在代码中的位置

获取的 API Key 不需要写死在代码里，通过网页配置即可（见第四节）。

// main.cpp 第 65 行 — API Key 默认为空，通过网页填写
String weatherapi = ""; // 启动后通过网页填写

2. 火山引擎方舟 API（AI 对话）

MindPaw 通过火山引擎的方舟平台调用豆包大模型，接口完全兼容 OpenAI 格式。

2.1 注册账号

  1. 访问 火山引擎官网
  2. 点击右上角 注册（支持手机号 / 邮箱）
  3. 注册后完成实名认证（AI 服务需要）
  4. 登录控制台

2.2 创建推理接入点

  1. 在控制台顶部搜索框输入 方舟，进入 方舟平台
  2. 左侧菜单选择 推理接入点
  3. 点击 创建接入点，填写：
字段 填写内容
名称 随意，如 MindPaw
模型选择 推荐 Doubao-pro-32k（性价比高）或 Doubao-lite-32k（更快更便宜）
计费方式 按量计费（新用户有免费额度）
  1. 创建完成后，你会得到一个 接入点 ID（Endpoint），格式如：
ep-2025xxxx-xxxxx-xxxxx-xxxx
  1. 复制这个 ID，保存备用

2.3 获取 API Key

  1. 在方舟平台左侧菜单，点击 API Key 管理
  2. 点击 创建 API Key
  3. 填写名称后创建，你会得到：
AK:  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  1. 点击显示完整 Key 并复制（关闭页面后不再显示完整内容）
  2. 将 API Key 和 Endpoint ID 保存到记事本

2.4 （可选）充值

新用户通常有 几十万 Token 免费额度，够用很久。如果后续需要充值：

  1. 方舟平台 → 费用中心
  2. 充值 ¥10 可以用非常久（Doubao-pro 约 0.8元/百万token）

2.5 在代码中的位置

// doubao_config.h 第 10 行 — API 端点（已填好无需修改）
#define DOUBAO_BASE_URL   "https://ark.cn-beijing.volces.com"
#define DOUBAO_API_PATH   "/api/v3/chat/completions"

API Key 和 Endpoint ID 通过网页配置，不写死在代码里。

3. HLK-V20 语音模块配置

HLK-V20（也叫 SU-03T）是离线语音识别模块，无需联网即可识别语音命令。

3.1 下载配置工具

  1. 百度搜索 "SU-03T 配置工具" 或 "HLK-V20 上位机"
  2. 也可以在海凌科官方淘宝店页面找到下载链接
  3. 工具是 Windows 软件，约 200MB

3.2 连接模块到电脑

使用 USB-TTL 模块 连接：

USB-TTL HLK-V20
TX RX
RX TX
GND GND
3.3V VCC

注意：

  • 不要接 5V，HLK-V20 是 3.3V 供电
  • RX/TX 要交叉连接（TX→RX, RX→TX）

3.3 配置语音命令

打开配置工具，按以下步骤操作：

第一步：设置基本参数

参数 推荐值
波特率 9600
唤醒方式 按键触发 / 唤醒词触发（推荐唤醒词）
唤醒词 如 "小狗小狗"（3-5 个字）

第二步：添加命令

点击 添加命令，每一条命令包含：

  • 识别词：用户说的内容（如 "前进"）
  • 输出：模块识别后通过串口发送的字符串（如 CMD1）

按以下表格创建 22 条命令：

# 识别词 输出 作用
1 前进 CMD1 前进
2 后退 CMD2 后退
3 左转 CMD3 左转
4 右转 CMD4 右转
5 停下 CMD5 停止
6 坐下 CMD6 坐下
7 趴下 CMD7 趴下
8 开心 CMD8 开心表情
9 生气 CMD9 生气表情
10 难受 CMD10 难过表情
11 好奇 CMD11 好奇表情
12 喜欢 CMD12 喜爱表情
13 睡觉 CMD13 睡觉姿势
14 自由模式 CMD14 开关自由模式
15 抬左手 CMD15 抬左手
16 抬右手 CMD16 抬右手
17 现在时间 CMD17 显示时间
18 今天天气 CMD18 显示天气
19 显示标志 CMD19 显示 Logo
20 你好 CMD20 打招呼
21 再见 CMD21 告别
22 （不配置） CMD22 保留

第三步：烧录到模块

  1. 点击 烧录 或 生成固件并下载
  2. 等待烧录完成（约 10-30 秒）
  3. 烧录完成后断开 USB-TTL

3.4 验证

烧录后，用 USB-TTL 连接模块：

  1. 打开串口助手（波特率 9600）
  2. 对着模块说话，串口应输出对应的 CMD1、CMD2... 等字符串
  3. 如果没反应，检查麦克风是否正常、识别词是否清晰

4. 在机器狗上配置

4.1 连接 WiFi

  1. 给机器狗上电
  2. 手机/电脑搜索 WiFi 热点 MindPaw
  3. 输入密码 mindpaw1234
  4. 连接成功后，浏览器打开 http://192.168.4.1

4.2 配置天气 API

  1. 在控制台页面，点击 在线功能 → 设置
  2. 找到 天气 API 密钥 输入框
  3. 粘贴从心知天气复制的 API Key
  4. 输入城市名（如 Shanghai、Beijing）
  5. 点击 保存并连接
  6. 返回 在线功能 页面，点击 天气 应能正常显示

4.3 配置 AI Agent

  1. 浏览器打开 http://192.168.4.1/aiconfig.html
  2. 在 API Key 输入框粘贴火山引擎的 API Key
  3. 在 推理端点 ID 输入框粘贴 Endpoint ID
  4. 点击 保存配置
  5. 提示保存成功后，打开 http://192.168.4.1/aichat.html
  6. 输入消息测试，机器狗应通过动作+表情+旋律回复

4.4 验证 HLK-V20

HLK-V20 接好后不需要额外配置，上电即用：

  1. 对着模块说唤醒词（如 "小狗小狗"）
  2. 听到模块发出提示音后，说出命令（如 "前进"）
  3. 观察机器狗是否执行相应动作
  4. 如果没反应，检查接线（见 05_Assembly_Guide.md）

常见问题

天气 API 显示 "Need NET"

  • 机器狗连接 WiFi 了吗？（OLED 显示的是 AP 模式，需要连接外部 WiFi）
  • 在 设置页面 重新填写 WiFi 信息并保存

AI 聊天提示 "AI未配置"

  • 检查 aiconfig.html 是否保存成功
  • 检查 API Key 和 Endpoint ID 是否复制完整（没有多余空格）
  • 火山引擎账号是否完成了实名认证？

HLK-V20 没反应

  • 接线正确吗？RX/TX 是否交叉？
  • 波特率是否设为 9600？
  • 模块里的固件烧录成功了吗？（用 USB-TTL 单独测试输出）
  • 对着模块说话时距离不要太远（推荐 0.5-1 米）

语音命令和实际执行不一致

  • HLK-V20 的识别词和输出字符串对应关系是否正确？
  • 检查 hlkv20.cpp 中的 DEFAULT_MAPPING 表是否与你的输出字符串一致

密钥泄露了怎么办？

  • 心知天气：登录控制台 → 产品管理 → 重置密钥
  • 火山引擎：登录方舟平台 → API Key 管理 → 删除旧 Key → 创建新 Key
  • WiFi 密码：修改 main.cpp 中的 password，重新编译烧录