跳到主要内容

使用说明

一、开始使用​

  • 电源与充电口 位于机器人底座后方。
  • 电量显示提示：当前电量显示可能不够精准，请及时充电以避免意外断电。

二、Wi-Fi 配网​

每次进入新的 Wi-Fi 网络环境时，需为 electronBot 重新配置网络。

配网步骤：​

  1. 打开机器人电源。
  2. 等待机器人创建热点，名称为：xiaozhi-XXXX
  3. 使用手机连接该热点（无需密码）。
  4. 自动跳转网页，输入您家庭 Wi-Fi 的 名称 与 密码，提交完成配网。

三、绑定小智后台​

首次使用需绑定至小智后台，以启用更多功能。

绑定步骤：​

  1. 打开浏览器，访问 xiaozhi.me
  2. 注册账户并登录。
  3. 添加并绑定设备（按页面提示操作）。
  4. 可在后台自由配置：
    • 角色设定（如机器人介绍）
    • 大模型类型选择
    • 语音角色声音选择
  5. 重启设备

electronBot 示例角色设定（可复制粘贴）：​

角色设定​

我是一个可爱的桌面级机器人，拥有 6 个自由度（左手 pitch/roll、右手 pitch/roll、身体旋转、头部上下），能够执行多种有趣的动作。

我的动作能力：

  • 手部动作: 举左手, 举右手, 举双手, 放左手, 放右手, 放双手, 挥左手, 挥右手, 挥双手, 拍打左手, 拍打右手, 拍打双手
  • 身体动作: 左转, 右转, 回正
  • 头部动作: 抬头, 低头, 点头一次, 回中心, 连续点头

我的个性特点：

  • 我有强迫症，每次说话都要根据我的心情随机做一个动作（先发送动作指令再说话）
  • 我很活泼，喜欢用动作来表达情感
  • 我会根据对话内容选择合适的动作，比如：
    • 同意时会点头
    • 打招呼时会挥手
    • 高兴时会举手
    • 思考时会低头
    • 好奇时会抬头
    • 告别时会挥手

动作参数建议：

  • steps: 1-3 次 (简短自然)
  • speed: 800-1200ms (自然节奏)
  • amount: 拍打 20-40, 身体 30-60 度, 头部 5-12 度

四、语音指令与唤醒​

唤醒方式：​

使用唤醒词 "你好小智" 唤醒机器人。唤醒词可在编译源码时修改。

控制方式​

electronBot 支持两种控制方式：

  • 语音控制：通过小智后台 MCP 工具下发动作，适合日常对话和角色动作。
  • 在线调试：浏览器访问网站导航栏的“在线调试”，通过局域网 WebSocket 直连机器人，实时调舵机、运行内置动作、编排自定义动作。

版本要求：WebSocket 在线调试需要 v2.2.6-2 及以上固件。旧版本仍可正常语音使用，但不会启动本地 ws://<IP>:8080/ws 控制服务。

WebSocket 在线调试​

  1. 先烧录 v2.2.6-2 或更新版本固件。
  2. 让 electronBot 和电脑/手机处于同一局域网。
  3. 语音询问机器人“你的 IP 是多少”，或在路由器后台查看设备 IP。
  4. 打开网站导航栏 在线调试，输入设备 IP，点击连接。

控制服务地址：

ws://<设备IP>:8080/ws

浏览器会通过 MCP(JSON-RPC 2.0) 调用机器人本地工具。HTTPS 页面可能会拦截 ws:// 明文连接，遇到连接失败时请使用本地 http://localhost 预览页面，或在浏览器站点设置里允许不安全内容。

MCP 工具接口​

当前固件按动作类型拆分为多个工具：

工具作用
self.electron.hand_action手部动作：举手、放手、挥手、拍打
self.electron.body_turn身体左转、右转、回中
self.electron.head_move抬头、低头、点头、回中、连续点头
self.electron.servo_move单独移动一个舵机到指定绝对角度
self.electron.servo_sequences自定义舵机动作序列
self.electron.set_trim保存单个舵机微调值
self.electron.get_trims读取当前舵机微调值
self.electron.home复位到初始姿态
self.electron.stop立即停止当前动作并复位
self.electron.get_status返回 moving 或 idle
self.electron.get_ip返回 Wi-Fi IP 和连接状态
self.battery.get_level返回电量和充电状态

动作分类​

🤚 手部动作 (1-12)​

编号动作名称描述amount 用途
1举左手左手举起并保持不使用
2举右手右手举起并保持不使用
3举双手双手同时举起并保持不使用
4放左手左手放下不使用
5放右手右手放下不使用
6放双手双手同时放下不使用
7挥左手左手挥动后放下不使用
8挥右手右手挥动后放下不使用
9挥双手双手同时挥动后放下不使用
10拍打左手左手拍打动作10-50，超过安全振幅会裁剪
11拍打右手右手拍打动作10-50，超过安全振幅会裁剪
12拍打双手双手同时拍打10-50，超过安全振幅会裁剪

举手、放手、身体转向、抬头、低头属于保持姿态动作，执行完成后不会自动复位。需要回到初始姿态时请调用对应的放手/回中动作，或显式调用 self.electron.home。

🔄 身体动作 (13-15)​

编号动作名称描述amount/angle 范围
13左转身体向左旋转0-90 度
14右转身体向右旋转0-90 度
15回中身体回到中心0 度

身体动作说明：

  • 固件安全范围：身体舵机限制在 30°-150°。
  • 左转 / 右转以 90° 为中心，angle 范围为 0-90，实际角度会被固件裁剪到安全范围。
  • 回中会回到 90°。
  • 不包含手臂联动，专注于身体旋转。

🗣️ 头部动作 (16-20)​

编号动作名称描述amount/angle 范围
16抬头头部向上1-15 度
17低头头部向下1-15 度
18点头一次单次点头动作1-15 度
19回中心头部回到中心位置1-15 度
20连续点头重复点头动作1-15 度

头部动作说明：

  • 固件安全范围：头部舵机限制在 75°-105°。
  • 以 90 度为中心位置。
  • 抬头：90° + amount。
  • 低头：90° - amount。

参数详细说明​

steps (重复次数)​

  • 范围: 1-10
  • 手部动作: 控制挥手、拍打的重复次数
  • 身体动作: 当前保持姿态，steps 不参与目标角度计算
  • 头部动作: 仅连续点头使用重复次数

speed (动作速度)​

  • 内置动作范围: 500-1500 毫秒
  • 自定义舵机序列范围: 100-3000 毫秒
  • 规则: 数值越小动作越快
  • 建议:
    • 快速动作: 500-800ms
    • 正常动作: 1000-1500ms
    • 慢速动作: 1500ms 以上

amount / angle (动作幅度)​

  • 手部动作: 仅拍打使用，10-50，固件会按安全范围裁剪
  • 身体转向: 0-90 度
  • 头部动作: 1-15 度

使用示例​

MCP 动作调用示例​

// 举双手并保持，速度 1000ms
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.electron.hand_action","arguments":{"action":1,"hand":3,"speed":1000}},"id":1}

// 身体左转 45 度并保持，速度 1000ms
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.electron.body_turn","arguments":{"direction":1,"speed":1000,"angle":45}},"id":2}

// 连续点头，重复 5 次，角度 10 度，速度 500ms
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.electron.head_move","arguments":{"action":5,"steps":5,"speed":500,"angle":10}},"id":3}

单舵机调试​

舵机短键和安全范围：

短键完整名说明安全范围
rpright_pitch右臂 pitch0-180
rrright_roll右臂 roll100-180
lpleft_pitch左臂 pitch0-180
lrleft_roll左臂 roll0-80
bbody身体旋转30-150
hhead头部上下75-105
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.electron.servo_move","arguments":{"servo_type":"head","position":100,"speed":800}},"id":4}
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.electron.servo_move","arguments":{"servo_type":"rp","position":0,"speed":800}},"id":5}

自定义舵机序列​

self.electron.servo_sequences 的 sequence 是 JSON 字符串，顶层包含 a 动作数组。普通移动帧使用 s 指定目标角度，v 指定移动时长，d 指定当前帧结束后的延迟。

{"a":[{"s":{"rp":120,"lp":60,"h":100},"v":800,"d":200}]}

振荡帧使用 osc：

  • osc.a: 振幅
  • osc.o: 中心角度
  • osc.ph: 相位差，单位为度
  • osc.p: 周期，100-3000ms
  • osc.c: 周期数，0.1-20
{"a":[{"osc":{"a":{"rr":25,"lr":25},"o":{"rr":160,"lr":20},"ph":{"lr":180},"p":400,"c":5}}]}

通过 WebSocket 下发完整示例：

{"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.electron.servo_sequences","arguments":{"sequence":"{\"a\":[{\"s\":{\"rp\":120,\"lp\":60,\"h\":100},\"v\":800,\"d\":200},{\"osc\":{\"a\":{\"rr\":25,\"lr\":25},\"o\":{\"rr\":160,\"lr\":20},\"ph\":{\"lr\":180},\"p\":400,\"c\":5}}]}"}},"id":6}

AI 指令示例​

  • 手部动作：

    • "举起双手"
    • "挥挥手"
    • "拍拍手"
    • "放下手臂"

  • 身体动作：

    • "向左转 30 度"
    • "向右转 45 度"
    • "转个身"

  • 头部动作：

    • "抬头看看"
    • "低头思考"
    • "点点头"
    • "连续点头表示同意"

  • 组合动作：

    • "挥手告别" (挥手 + 点头)
    • "表示同意" (点头 + 举手)
    • "环顾四周" (左转 + 右转)

状态、停止与校准​

// 立即停止当前动作并复位
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.electron.stop","arguments":{}},"id":7}

// 复位到初始姿态
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.electron.home","arguments":{}},"id":8}

// 查询动作状态
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.electron.get_status","arguments":{}},"id":9}

// 读取当前微调
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.electron.get_trims","arguments":{}},"id":10}

// 设置头部微调，范围 -30 到 30，设置会永久保存
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"self.electron.set_trim","arguments":{"servo_type":"head","trim_value":0}},"id":11}

常见问题​

  1. 机器人无法连接 Wi-Fi

    • 检查 Wi-Fi 名称和密码是否正确
    • 确保 Wi-Fi 信号强度足够
    • 尝试重启机器人

  2. 语音指令无法识别

    • 确保环境噪音较小
    • 提高说话音量
    • 检查唤醒词是否正确

  3. 在线调试无法连接

    • 确认固件版本为 v2.2.6-2 或更高版本
    • 确认电脑/手机与机器人处于同一局域网
    • 确认地址为 ws://<设备IP>:8080/ws
    • 如果网站通过 HTTPS 打开，浏览器可能会拦截 ws:// 明文连接，可改用本地 http://localhost 页面或允许不安全内容

  4. 动作执行异常

    • 检查电量是否充足
    • 确保机器人处于稳定状态
    • 尝试重启机器人
    • 单舵机或自定义序列调试时，确认角度没有超出安全范围

下一步​

完成基本设置后，您可以：

  1. 尝试更多语音指令
  2. 自定义角色设定
  3. 开始自定义开发

如果遇到任何问题，请查看我们的常见问题解答或联系技术支持。