当您使用USB上载模块为NyBoard上传固件时，请先下载并安装USB串口驱动程序：

• macOS: http://www.wch.cn/download/CH341SER_MAC_ZIP.html

• Windows: http://www.wch.cn/download/CH341SER_EXE.html

• Linux: https://www.wch.cn/downloads/CH341SER_LINUX_ZIP.html

为机器人上传固件有以下两种方法：

• 最简单的方法是使用 Petoi 桌面应用程序，因为使用这种方法不涉及编程。 您可以上传一些预设模式。

• 如果您有一定的编程经验，可以使用 Arduino IDE 修改我们的开源代码。

  • 如果您的机器人主板是NyBoard，请参考章节：为NyBoard上传程序

  • 如果您的机器人主板是BiBoard，请参考章节：为BiBoard上传程序

我们人类和许多其他有腿动物都有很多关节。 这些关节让我们能够以多种方式自由行动。 尽管很难在机器人上重现这些复杂的运动，但我们可以将所有这些关节简化为有限数量的执行器。

当控制这么多关节时，首先要做的就是对它们进行索引。 我们可以根据它们与躯干的距离来定义顺序。 例如，肩关节比肘关节更靠近躯干，而让我们环顾四周的关节比让我们点头的关节更靠近躯干。 如果我们有尾巴，那么与肩关节相比，它就会像头部一样接近躯干。

所以我们可以这样对关节进行排序：头部平转、头部倾斜、尾部平转、尾部倾斜、4x 肩部（或臀部）开合、4x 肩部（或臀部）俯仰、4x 肘部（或膝盖）。 对于同一距离组中的关节，如果从后面看身体，我们可以从左前角顺时针索引它们。

当我们将这些关节映射到特定的机器人时，索引变得更加实用。 NyBoard 上关节伺服引脚的排列顺序如下：关节舵机引脚排序规律:

NyBoard

BiBoard

预组装的机器人应该已安装腿部组件，但您可以通过微调关节的校准参数来进一步提高其性能。

校准前请确保您已上传 OpenCat 主功能固件。

*关节校准背后的逻辑是：

1. 在舵机通电和校准之前，您不知道它们上电后会指向哪里。 因此，如果您连接腿，腿将旋转到随机角度，并可能与机器人的身体或其他腿碰撞并被卡住。 如果舵机长时间卡住，则可能会损坏。

2. 该机器人有一种称为“校准”的姿势，所有关节均设置为 0 度。 您可以设置机器人进入校准姿势状态，以便您知道所有关节都应该旋转到零度点（尽管您看不到，因为腿尚未连接到舵机输出轴的齿轮上）。 然后，您可以将身体组件逐个关节地连接到舵机输出轴的齿轮上，尽量保持相互垂直的关系（大腿与躯干垂直，小腿与大腿垂直，颈部安装时尽量保持头部正对正前方），如下图所示。
3. 由于舵机输出轴的齿轮齿是离散的，因此不可能将支腿完美地对齐到直角。 因此，您需要在软件中微调偏移。

Nybble 和 Bittle 的关节校准原理是相同的。

准备进入关节校准状态

进入校准状态需要做好以下几项准备工作： ‌

1. 将所有舵机线连接至主板

2. 将电池连接至主板并开机（长按电池上的按钮可打开/关闭电源）

3. 使用USB 适配器或蓝牙模块连接机器人与电脑或手机。

进入关节校准状态

机器人的腿在启动时可能会指向未知的角度。 当进入校准状态时，关节将转动到零度位置。 您可以看到舵机输出轴上的齿轮旋转然后停止。 然后您可以连接腿部组件并在软件界面中微调关节偏转。 通过使用软件，有3种方式可以进入校准状态并对关节进行微调。

• 使用移动应用 Petoi

• 使用 Petoi 桌面应用程序

• 使用 Arduino IDE

安装螺钉

完成关节校准后，安装中心螺钉，固定所有关节部件和舵机齿轮。

如果您想通过无线连接的方式在 Petoi 桌面应用程序中使用关节校准、技能创作坊，或者在 Mind+中使用编程积木块，您需要首先将主板的蓝牙与电脑进行配对。

连接步骤

BiBoard

1. 通过电池开启主板（将电池插入主板，并长按电池按钮 > 3 秒）；开启后，主板上的蓝色 LED 和黄色 LED 应该亮起。

2. 对于 Windows，打开蓝牙和其他设备设置页面，并按以下步骤开启蓝牙按钮：
3. 添加 BiBoard 蓝牙模块，首次操作如下：

选择名为 Bittle**_BLE 的选项

成功配对后，显示：

检查即将在 Mind+或 Petoi 桌面应用程序的更多蓝牙选项中使用的输出串行端口：

1. 在Mind+中进行测试

NyBoard

请参阅 NyBoard 的蓝牙模块。

** 下载最新版的桌面应用程序 Petoi Desktop App **

Petoi 桌面应用程序为您提供简洁的图形用户界面来配置固件、校准机器人并可以为您的机器人设计自定义动作。 主要功能模块是固件上载、关节校准和技能创作坊。

源代码主要采用 Python3 中的 Tkinker 模块编写，GitHub 代码仓库地址是： https://github.com/PetoiCamp/OpenCat/tree/main/pyUI

其中 UI.py 是所有模块的总入口：

• UI.py 调用：

-> FirmwareUploader.py

-> Calibrator.py

-> SkillComposer.py

translate.py 为 UI 提供多语言支持。 您可以帮助我们将 UI 翻译成您的语言。 在运行应用程序之前，您必须使用随附的 USB 适配器或蓝牙模块连接到 Petoi 机器人。

预编译的可执行程序

您可以使用预编译的可执行程序文件，就不需要使用编程界面了。

下载 Mac 版本后，您必须将其拖到 Application 文件夹中。

如果您看到“Petoi Desktop App”由于无法验证开发者而无法打开的错误消息，您可以右键单击该图标，按住 Shift 键并单击“打开”。

在 Terminal 中运行程序

如果此应用程序在运行时出现兼容性问题，或者您想修改应用程序的源代码并进行测试，您也可以在Terminal 中运行程序。 Terminal 是 Mac 或 Linux 系统中的内置界面，Windows 系统中的等效环境称为命令行工具 (CMD)。 建议您安装 Anaconda 来管理您的 Python 环境，它还可以提供 Powershell 作为旧 Windows 系统中的Terminal 。

根据您现有的 Python 配置，您可能需要升级到 Python3 并安装以下库：

• pyserial

• pillow

您可以通过在Terminal 中输入 pip3 install pyserial pillow 或使用 Anaconda 中的包管理器来安装它们。 运行程序步骤如下：

1. 在终端中，使用 cd 命令导航到 OpenCat/pyUI/ 文件夹， 其间您可以使用 Tab 键自动补充完成路径名

2. 进入 pyUI/ 文件夹后，输入 ls 查看此路径下的所有文件，确保可以看到列出的 UI.py 和其他 python 脚本文件

3. 输入 python3 UI.py 即可开始运行Petoi 桌面应用程序

感谢您选择 Petoi 的机器狗 Bittle 或 机器猫 Nybble。 本操作指南将帮助您设置机器宠物，并提供更简单的 UI 来对机器宠物进行校准、控制和编程。 对于高级用户，我们建议您使用 Github 上的 OpenCat 固件更新机器宠物，以获得最佳兼容性和最新功能。

下载与安装

该应用程序适用于 iOS 和 Android 设备。

• ​iOS 11+​

• ​Android 4.4+​

APK

如果在国内无法访问 Google Play，您可以用下面的 apk文件直接安装。安装前需要解压缩。

如果蓝牙模块在闪烁而 app 中的蓝牙设备扫描列表为空，首先检查是否已打开了App 的蓝牙和位置权限，如果仍搜索不到设备，可以尝试安装前一稳定版本。

连接

您需要将蓝牙模块插入 NyBoard 上的 6 针插座。 注意蓝牙模块的引脚顺序。 长按电池上的按钮，开启机器宠物电源。

蓝牙模块上的 LED 闪烁表示等待连接。 打开应用程序 Petoi 并扫描以连接名称为 Bittle、Petoi 或 OpenCat 的设备。不要在手机系统设置中的蓝牙连接设置界面连接机器人！ 请记住打开蓝牙服务并授予应用程序访问该服务的权限。

请记住打开蓝牙服务并授予应用程序访问该服务的权限。 在某些设备上，您可能还需要允许应用程序的位置服务，尽管我们没有使用任何这些信息。

如果蓝牙已连接，其 LED 将常亮。 机器宠物将演奏三音旋律。 如果稍后机器宠物没有响应或出现故障，请按 NyBoard 上的复位按钮重新启动 NyBoard 上的程序。

该应用程序会自动检测到使用了最新的 OpenCat 固件的 Nybble 或 Bittle。 否则，它将显示出 Nybble 或 Bittle 的选项供用户选择。 当然也可以在控制面板中点击打开右上角菜单，点击“选择宠物”重新访问该选项页面。

以下是用户首次使用App校准时的显示界面。

Nybble

Bittle

进入校准界面，点击“校准”按钮，所有舵机输出轴立即转动到校准位置。

校准时请使用随附的 L 形工具作为参考：

先从“校准”界面图片中选择关节舵机索引号（调整腿部舵机时，先调整大腿，后调整小腿），然后单击 “+” 或 “-” 按钮，将关节微调至直角状态。

您可以通过点击休息、站立、行走按钮来回切换状态，测试校准效果。

校准好后，切记要点击“保存”按钮，保存校准偏移量。 否则，单击左上角的 “<” 放弃校准。

** 下载最新版的桌面应用程序 Petoi Desktop App **

USB上载器正确连接后（连接方法请参考USB上载模块相关章节），或使用蓝牙模块（连接方法请参考双模蓝牙模块相关章节）连接。

打开Petoi Desktop App（Windows：UI.exe / Mac：Petoi Desktop App），选择 产品 和 语言。点击“关节校准”按钮，打开校准界面：

关节校准界面：

1. 点击“校准位”按钮，所有舵机输出轴立即转动到校准位置。

2. 在校准过程中请使用随附的 L 形工具作为参考：

根据界面中间图示中的关节索引号（校准舵机时，先调整大腿，再调整小腿）。 拖动相应的滑块（在索引号下方），或点击滑块轨道的灰色部分将关节微调至直角状态。

您可以通过点击休息、站立、行走按钮来回切换状态，测试校准效果。

校准完成后，记得点击“保存”按钮保存校准偏移量。 否则，单击“放弃”按钮放弃校准数据。 当然您也可以在校准过程中随时保存，以防连接发生中断丢失数据。

** 下载最新版的桌面应用程序 Petoi Desktop App **

从版本 1.2.1 开始，Petoi 桌面应用程序新增了一个功能模块——调试器。此模块提供了方便的调试工具来解决机器人出现的小问题。

重置语音模块

用于重置语音命令模块，简化其调试过程。如果语音模块没有响应您的语音，您可以使用此工具来重置它。使用很简单：先将语言设置为“中文”，然后点击“重置语音模块”按钮。

点击按钮后，请按照消息框中的提示说明操作。

点击“是”按钮后，如果语音指令模块被重置成功，将弹出以下消息提示框：

如果问题仍然存在，请发送电子邮件至 support@petoi.com。

步态

姿势和行为

内置的姿势和行为可以通过按下“默认动作”区域的按钮来触发。 建议不要过于频繁和重复地按下按钮。 给机器宠物一些时间来完成它当前的任务。

自定义命令

长按按钮并拖动，可以改变按钮位置；双击命令按钮可以对它进行编辑；您还可以通过按 “+” 按钮增加自定义的单一命令或者组合命令；

创建单个命令

按下创建命令按钮后，你将看到以下命令编辑界面：

进入编辑状态后，显示一个精简的串口命令控制台（如上图所示），可以用来测试串口命令，控制机器人做各种动作。

您可以在代码文本框中输入以下常用的串口指令：

* 扭头 （旋转脖子舵机角度）

m0 45

* 左右扭动头部（移动 关节1 角度1 关节2 角度2 .... 角度为-127~128）

m0 -70 0 70

* 坐

ksit

* 按顺序依次移动关节

m 0 -70 0 70 8 -30

* 同时移动多个关节

i 0 -45 8 -30 12 -60

以下是关节的索引供您参考。仔细观察排序的模式并试着记住它们。​

* 显示当前关节角度

j

* 长“喵”一声 (Nybble)

u0 1

* 短“喵”三声 (Nybble)

u2 20

* 播放短音（蜂鸣音 持续时间，持续时间为 0~256）

b12 100

* 播放旋律（b音调 1 持续时间 1，音调 2 持续时间 2，音调 3 持续时间 3，.... 仅允许 64 个字符，其中持续时间为数字的倒数，即记谱法中的“几分之一音符”）

b14 4 14 4 21 4 21 4

更详细的命令说明表格请参考文档中心串口协议章节。

将新技能导入为自定义按钮

导入本地创作的技能（技能创作坊）

您可以使用通讯软件（比如微信）或电子邮件将电脑中创作的技能文件发送到您的手机，并使用 Petoi 应用程序在手机上打开该文件。此操作将自动为新技能创建一个按钮， 打开控制面板就可以看到。

导入GitHub技能库中的技能

创建组合命令

按下创建组合命令按钮后，您可以看到以下界面：

您可以在“名字”文本框中为组合命令组命名，并通过单击“指令库”选择框中的命令按钮将命令添加到“组合指令”列表中。 在组合指令列表中，您可以按住单个指令的按钮并拖动来更改单个指令的位置。

单击删除按钮，可以删除此组合指令。

更新和支持

我们会不断改进应用程序，并会在可用时通知您更新。 如果您对该应用程序有任何疑问，请写信至 support@petoi.com。

准备 Mind+

• 从Mind+官网下载最新版本（不低于V1.7.0）https://mindplus.cc/download.html

  • Windows: >= V1.7.0

  • Mac: >= V1.7.3 RC2.0

• 安装教程及如果出现问题可以参考Mind+官方文档： 安装教程

• 安装完成后即可打开Mind+

准备 Petoi 机器人

NyBoard

• 对于使用 NyBoard 的产品：Nybble 和 Bittle。有两种方式来上传Mind+模式固件：

  • • 如果您刚刚下载了此桌面应用程序的新版本。 您应该单击升级固件按钮。 您可以选择“N”来保留原来的舵机校准参数。

    • 如果您在下载此桌面应用程序后已经升级过一次固件，则可以单击只更新模式按钮。 只切换模式而不刷主板配置模式固件可以更加节省时间。

  • 使用 Arduino IDE 请下载GitHub网站最新的程序代码，按照上传程序固件步骤，先进入主板配置模式，再激活 OpenCat.ino 中的以下代码： #define MAIN_SKETCH

    #define GROVE_SERIAL_PASS_THROUGH

    上传主功能程序上电启动机器人。使用数据线及USB上载模块与电脑端进行连接或者使用蓝牙通讯模块与电脑端完成配对。

通讯连接方式

• 有线连接： 套件包含一个USB适配器和一条USB数据线，用于将机器人的主板连接到计算机。

• 无线连接（蓝牙）： 套件包含一个蓝牙模块，用于将机器人的主板连接到计算机。

BiBoard

• 对于使用 BiBoard 的产品：Bittle 和 Bittle X, 不需要修改任何软件代码，默认支持Mind+内所有功能积木块，同时陀螺仪功能处于开启状态，即机器人可以保持自平衡，摔倒后可以自动翻身起立。

通讯连接方式

• 有线连接： 套件包含一条USB Type-C数据线，用于将机器人的主板连接到计算机。

• 无线连接（蓝牙）： 主板内置蓝牙通信模块，可实现机器人主板与计算机之间的蓝牙无线连接。

导入Petoi Mind+扩展库

在导入用户库界面的文本框中粘贴GitHub网址：https://github.com/PetoiCamp/Petoi_MindPlusLib

编写程序并运行

程序运行原理及流程

使用此扩展库编写完成控制机器人的程序代码后，无需编译上传程序代码到机器人主板上。直接点击“运行”按钮即可运行程序代码。如需在程序运行过程中中止程序，可随时点击“停止”按钮。程序运行流程可分为三个步骤：

1. 打开串口

2. 控制机器人

3. 关闭串口

积木块使用说明

打开串口

打开串口有两种方式：

关闭陀螺仪

当开启陀螺仪功能时，机器人可以实时保持自身身体平衡，可能会看到机器人在做预设动作（尤其是执行比较剧烈的动作）时，身体会来回晃动，甚至会发生身体倾翻，这时机器人自动会做复原的动作，这样可能会打乱您预设的执行步骤。

如果上传的固件是Mind+模式程序固件（#define GROVE_SERIAL_PASS_THROUGH 此行代码被激活），机器人启动时默认是关闭陀螺仪功能 (机器人将不能保持自平衡，摔倒后不会自动翻身起立)，就不需要添加此积木块了。

执行固有技能动作

使用此积木块可以让机器人执行烧录到机器人主板中技能动作。其中从“坐下”到“零位”，属于姿势（只包含一个动作帧）；从“拳击”到“闻一闻”，属于行为（包含多个连贯的动作帧，其中一部分连续动作帧可以循环执行多次，但所有动作帧按照顺序只执行一轮）；从“原地踏步”到“向右跑”，属于步态（包含多个连贯的动作帧，这些动作帧按照顺序循环不断重复执行）。配合使用积木块中延时设置，可以控制机器人在做完技能动作延迟预设时间后执行下一个积木块程序。

执行从技能创作坊中最新导出的一个技能

使用此积木块可以让机器人执行从技能创作坊中最新导出的一个技能。配合使用积木块中延时设置，可以控制机器人在做完技能动作延迟预设时间后执行下一个积木块程序。

执行技能文件中的技能

使用此积木块可以让机器人执行技能文件中的技能，技能文件位于以下目录中：

• Windows: C:\Users\{your user name}\.config\Petoi\SkillLibrary\{model}

• MacOS : /Users/{your user name}/.config/Petoi/SkillLibrary/{model}

• Linux: /home/{your user name}/.config/Petoi/SkillLibrary/{model}

目录中文件夹名称 {model} 为 Bittle 或者 Nybble。 从技能创作坊导出技能文件时，程序会自动将技能文件保存到该目录中。

依次旋转关节

使用此积木块可以控制一个关节或多个关节按顺序依次旋转，有以下几种积木块搭配使用方式供参考：

• 控制单个关节旋转到绝对角度值
• 控制单个关节旋转到相对角度值
• 控制多个关节依次旋转到绝对角度值或相对角度值
• 使用关节角度列表来控制多个关节依次旋转到绝对角度

配合使用积木块中延时设置，可以控制机器人在做完动作延迟预设时间后执行下一个积木块程序。

同时旋转关节

使用此积木块可以控制多个关节同时旋转，有以下几种积木块搭配使用方式供参考：

• 控制多个关节同时旋转到绝对角度值或相对角度值
• 使用关节角度列表来控制多个关节同时旋转到绝对角度值

配合使用积木块中延时设置，可以控制机器人在做完动作延迟预设时间后执行下一个积木块程序。

获取关节当前角度值

使用此积木块可以获取到所选关节的当前角度值，建议可以先将其赋值给一个变量，然后可以通过使用变量及逻辑算法，控制其他的关节旋转。

使用示例：

转换到动作帧

使用此积木块可以控制所有关节同时旋转，请与”动作帧“积木块搭配使用。如下图所示：

配合使用积木块中延时设置，可以控制机器人在做完动作延迟预设时间后执行下一个积木块程序。

播放旋律

使用此积木块可以控制主板播放音乐。有以下几种积木块搭配使用方式供参考：

• 使用多个“音符+时值”积木块组成的列表
• 使用音符及时值列表

配合使用积木块中延时设置，可以控制机器人在播放完音乐延迟预设时间后执行下一个积木块程序。

执行串口命令

使用此积木块可以给机器人发送串口命令，这样可以给您提供更多，更灵活的控制方式。比如可以输入“kkcL”（踢左前腿）， “khiR”(举右前腿打招呼)。更多串口命令请参考串口协议。

配合使用积木块中延时设置，可以控制机器人在执行完串口命令延迟预设时间后执行下一个积木块程序。

写模拟值

使用此积木块可以给指定引脚写入模拟值。模拟值范围：0~255

读模拟值

使用此积木块可以读取指定引脚的模拟值。

写数字值

使用此积木块可以给指定引脚写入高低电平值。高电平: 1；低电平：0。

读数字值

使用此积木块可以读取指定引脚的高/低电平值。高电平: 1；低电平：0。

关闭串口

一般在控制程序的结尾，建议使用此积木块关闭串口通讯。

示例程序

在GitHub仓库中(Petoi_MindPlusLib/examples)我们提供了一些相关示例程序，可供您下载参考。

如果您熟悉Petoi编码积木块提供的API接口，可以直接用Python语言来编写程序代码，您可以在Mind+中切换到Code模式，如下图所示：

代码模式其实是一个Python3语言的开发环境。 您可以在其中使用Python3语言编写任意代码，并且可以调用Mind+导入的PetoiRobot库中的所有API接口。

您可以在以下目录中找到PetoiRobot库，其中包含所有与Petoi机器人相关的API接口定义：

• Windows C:\Users\{username}\AppData\Local\DFScratch\extensions\petoi-robot-thirdex\python\libraries\PetoiRobot.py

• MacOS /Users/{username}/Library/DFScratch/extensions/petoi-robot-thirdex/python/libraries/PetoiRobot.py

以下是PetoiRobot库中支持的常用API接口函数。 您可以参考模块模式下自动生成的Python代码来了解其调用格式。

# 用来打印调试信息
def printH(head, value)

# 关闭陀螺仪
def deacGyro()

# 获取当前所有关节的角度值列表
def getAngleList()
    return angleList

# 获取当前某个关节的角度值 
def getCurAng(index)

# 创建一个[关节序号，绝对角度值]组成的列表
def absValList(num1, num2)

# 创建一个[关节序号，符号，相对角度值]组成的列表
# index: 关节序号
# symbol: "+1" 或者 "-1"
# angle: 相对角度值
def relativeValList(index, symbol, angle)

# 依次/同时旋转关节
# token: 'I' 同时旋转, 'M' 依次旋转
# var: absValList(num1, num2) 或者 relativeValList(index, symbol, angle)
def rotateJoints(token, var, delayTime)

# 播放音乐旋律
def play(token, var, delayTime)

# 打开串口
# port: 串口名称
def openPort(port)

# 自动连接并打开串口
def autoConnect()

# 发送技能串口命令
def sendSkillStr(skillStr, delayTime)

# 调用技能文件中的技能
def loadSkill(fileName, delayTime):

# 发送串口指令
def sendCmdStr(cmdStr, delayTime)

# 发送长串口指令
def sendLongCmd(token, var, delayTime)

# 从模拟输入口读值
def readAnalogValue(pin)

# 从数字输入口读值
def readDigitalValue(pin)

# 向模拟输出口写值
def writeAnalogValue(pin, val)
 
# 向数字输出口写值
def writeDigitalValue(pin, val)

# 关闭串口
def closePort()

示例代码：

# 代码从此处开始
from PetoiRobot import *    # 如果使用PetoiRobot库中的API接口，必须使用导入库文件

# 首先连接打开串口
autoConnect()

# 调用API接口控制Petoi机器人
sendSkillStr('ksit', 0.5)
sendCmdStr('T', 0.5)
loadSkill("skillFileName", 0.2)

# 最后关闭串口
closePort()

您也可以在模块模式下的自动生成区域中复制代码，在代码模式下将其粘贴到代码文件中。 然后您可以编辑并运行代码程序。

配置流程

OpenCat 软件可在Petoi机器人上运行，主板是由基于 ATmega328P 的 NyBoard。 更详细的硬件信息请参考 NyBoard V1_0 或 NyBoard V1_1 。

将I2C开关(SW2)拨到“Arduino”

I2C 开关用于改变 I2C 设备（陀螺仪/加速度计、伺服驱动器、外部 EEPROM）的主控。 默认“Arduino”时，NyBoard 使用板载 ATmega328P 作为主控芯片； 拨到“RPi”端时，NyBoard 使用通过I2C 端口（SDA、SCL）连接的外部芯片作为主控芯片。

下载和安装软件环境

使用 NyBoard V1_*主板，您只需选择 Arduino Uno。

连接USB上载器（USB适配器）

具体步骤可参考USB上载模块中连接NyBoard部分。

连接蓝牙上载器（可选）

具体步骤可参考双模蓝牙模块中连接NyBoard部分。

下载OpenCat软件包

• 从GitHub下载最新的OpenCat代码库：https://github.com/PetoiCamp/OpenCat。最好使用GitHub的版本控制功能。否则，请确保您每次都下载全部的OpenCat文件夹。所有代码必须是相同版本时才能一起使用。

• 如果下载代码的Zip文件，则解压缩后将获得一个OpenCat-main文件夹。把它重命名为 OpenCat。

• ModuleTests文件夹中有几个名为testX（X代表功能模块，比如蜂鸣器陀螺仪）.ino的代码。您可以上传它们以分别测试对应模块。打开任何带有前缀“ test”的testX.ino的工程。 （我建议您使用testBuzzer.ino作为第一个测试项目）。

• 打开串行监视器并设置波特率。使用NyBoard V1_ *，将开发板选为Arduino Uno，然后在代码和串口监视器中将波特率设置为115200。

• 编译代码，应该没有错误提示。如果有请根据提示查找问题，一般问题为缺少某些库，根据需要安装即可。随后上传到您的开发板上，您应该看到Tx和Rx LED快速闪烁。一旦它们停止闪烁，消息应出现在串口监视器上。

上传程序固件

代码中配置主板，请按照以下步骤操作：

1. 配置机器人产品类型和主板版本

打开文件 OpenCat.ino，选择您的机器人 产品类型 和 主板版本。 例如：

#define BITTLE    //Petoi 9 DOF robot dog: 1x on head + 8x on leg
//#define NYBBLE  //Petoi 11 DOF robot cat: 2x on head + 1x on tail + 8x on leg

//#define NyBoard_V0_1
//#define NyBoard_V0_2
#define NyBoard_V1_0
//#define NyBoard_V1_1

2.进入主板配置模式

注释此行代码#define MAIN_SKETCH，保存、编译、上传程序固件后，机器人将进入主板配置模式。 上传完成后，请按照串口提示信息继续操作。

// #define MAIN_SKETCH

3. 将 USB 上载器插入您的计算机

如果在 Arduino -> Tools -> Port 下没有找到 USB 端口，请安装驱动程序。

4. 将 USB 上载器插入 NyBoard

具体方法可参考USB上载模块中连接NyBoard部分。

5. 上传主板配置程序

点击 上传 按钮即可上传主板配置程序。

6. 打开串口监视器

您可以在菜单栏 工具 下方或者在主界面的右上角找到按钮。

在输入命令之前，请确保串口监视器设置为 “没有结束符”（No line ending），否则不可见的' \n'或' \r'字符将使解析函数失效。波特率设置为 "115200 波特率" （115200 baud）。

7. 清除校准数据

串口提示内容如下：

Reset joint offsets? (Y/n):

如果要将所有关节的校准数据重置为 0，请输入“Y”并按回车键 (Enter)。 程序将进行重置，然后更新静态内存中的常量和本能技能。

8. 校准IMU

串口提示: 是否校准IMU (Inertial Measurement Unit)？

Calibrate the IMU? (Y/n): 

如果您从未校准过 IMU 或想要重新校准，请输入“Y”并按回车键 (Enter)。 将机器人平放在桌子上，不要触摸它。 机器人会长鸣六声给你足够的时间。 然后它将读取数百个传感器数据并保存偏移量。 校准完成时会发出蜂鸣声。

当串口监视器打印“Ready!”时，您可以关闭串口监视器进行下一步操作。

9. 校准舵机驱动芯片

在校准 IMU后有一步可选的操作来校准舵机驱动：

Optional: Connect PWM 3 -> Grove pin A3 to calibrate PCA9685

您可以通过校准舵机驱动芯片（PCA9685 chip）来让角度控制更加精准。用一根跳线连接 PWM 引脚3（舵机控制脚的信号脚之一 ）和 Grove 引脚 A3，并把线按稳。

您不需要专门的跳线来完成这一步。任何能连通引脚的细金属线都可以，比如拉直的回形针。

程序会测量信号脉宽，在连续三次测量到相同读数后自动校准芯片。校准修正值会被存入控制板并在下次启动时生效。然后您可以继续进行下一步。

10. 上传主要功能程序

此行代码 #define MAIN_SKETCH 取消注释，并保存修改以使其处于激活状态。 编译、上传程序固件后，机器人将运行主要功能的正常程序。

#define MAIN_SKETCH

11. 代码中的模块宏

默认程序是标准模式。如果您有一些扩展模块，可以将这些模块的宏定义语句取消注释。这样会禁用陀螺仪的代码节省出一些编程空间，并激活这些扩展模块的演示代码。

官方模块的代码是在 src/里的单独头文件里定义的。您可以在OpenCat/src/io.h -> readSignal()找到它们对应的函数。 OTHER_MODULES（其他模块）的行为在OpenCat/OpenCat.ino -> otherModule()定义。您可以参考示例代码写出自己的功能。

12. 修改“关节-引脚”映射

在某些情形下，您也许需要更改机器人的“关节-引脚”映射，它可以在OpenCat/src/OpenCat.h中修改。注意要按照 OpenCat.ino 开头的主板版本来修改相应的代码段落。修改后记得保存，并重复从第2步开始的上传步骤。

预组装版本的机器人应该已经正确安装了腿，但没有进行微调校准。

* 校准舵机流程背后的逻辑：

1. 在校准之前，通电前我们不知道舵机将指向哪里。 所以如果躯干连接上腿部部件，腿会旋转到随机角度，并可能与机器人的身体或其他腿碰撞并被堵转。 如果一个舵机堵转了很长时间，它可能会损坏。

Nybble 和 Bittle 的校准原理相同。

进入校准模式需要做好以下准备：

‌1. 全部舵机线路与主板连接好

2. 电池电量充足

如果您使用未组装的套件构建机器人，请在校准之前不要安装头，腿组件。 您还需要安装电池并长按电池上的按钮为机器人供电。

校准分为三个步骤：

1. 进入校准模式，使舵机自由转动到中位；

2. 安装各个肢体到校准位；

3. 通过串口监视器微调关节修正量。

1. 进入校准模式

检查所有舵机接头插入的位置和方向，您必须把舵机和外接电池都插上NyBoard后才可以正确校准。 在我们安装腿部组件之前，舵机的输出轴应该处于零状态（转到中位然后停下）。

在串口监视器输入c来进入校准模式，舵机应该迅速地依次转到中位然后停下，同时齿轮箱会发出一些声响。由于舵机的起始位置各不相同，有些舵机的转角会大一些。在串口监视器会打印出一列表：

第一行是关节序号，第二行是它们的修正量，第三行是刚刚输入的校准指令。

初始的关节修正量是 “-1” 或 “0”，需要测定后修改。

2. 安装舵机关联部件

2.1 坐标系

输入‘c’指令后，所有舵机都转到了中位，就可以安装之前组装好的舵机关联部件了。它们基本上按照相互垂直的角度互相连接，校准姿势如下图所示:

关节角使用本体极坐标系，以逆时针转动为正。从机身左侧看，关节逆时针转动定义为正方向。

2.2 离散的角度间隔

如果我们仔细观察舵机输出轴，可以发现它上面有一定数量的齿，这些齿可以防止输出轴在转动时相对摇臂滑动。在我们的舵机上，输出轴的圆周被分隔成25个齿，每个齿间隔14.4度（偏移 -7.2~7.2 度）。这意味着我们安装关节时不可能绝对垂直，只能尽可能地接近垂直。

3 使用串口监视器对机器人进行精细校准

3.1 关节控制命令

比如:

c8 6表示给8号舵机+6度的修正量。对于每个舵机都需要进行这样的校准以使各部位转动到校准位。

c0 -4 表示给0号舵机-4度的修正量。

找到可以使肢体达到零状态的最佳偏移量。 这是一个反复试验的过程。

校准后，记得要输入s来保存修正量，否则程序重启后它们就失效了。您甚至可以每校准一个舵机就保存一次。

3.2 “L”形关节校准器

实际测量时，我们的观测会由于透视关系而产生偏差，这也是为什么我们在读直尺的刻度时要尽量在尺的上方平视。

在校准机器人的关节时，保持平视也特别重要，所以我提供了“L”形的关节校准器辅助参考。按先调4个肩关节（8~11）后调4个膝关节（12~15）的顺序依次校准，目标是使校准器的三个尖角同时对准舵机螺丝或脚尖孔洞的圆心。在校准每个关节时，要从圆心-尖角的延长线上平视观察，校准器的三角窗口边应该和小腿上的三角窗口边平行。

Nybble

Bittle

3.3 验证校准效果

校准后，可在串口监视器输入d或kbalance验证效果。机器人会在对应的休息和站立姿势间切换，它的四肢应该是前后、左右对称的。

您可能需要进行几轮校准才能达到最佳状态。

3.4 调节重心

试着了解机器从如何在步行过程中保持平衡。如果要向机器人身体上添加新部件，请尽最大努力在脊柱周围对称分布其重量。也可以前后滑动电池座，以找到最佳的平衡位置。由于电池的前半部分较重，必要时您也可以反向插入电池，以使重心更多地向后移动。

请不要强行为机器人增加过重的物品，可能导致舵机扫齿或卡住。

连接USB适配器到主板

您可以在“工具”菜单栏中选择“串口监视器”，或者单击右上角的按钮打开串口监视器窗口，如下图所示：

当使用NyBoard V1_ *主板时，请在串口监视器中设置为“没有结束符”，并将波特率设置为115200。如下图所示：

连接蓝牙模块到主板（可选功能）

然后您可以在 Arduino IDE 的 “工具” -> “端口” 下选择它，使用方法与上述USB适配器相同。

准备工作

1. 安装python 3.6以上版本 （比如Anaconda3-5.2.0-Windows-x86_64.exe）

2. 安装pyserial库(version: 3.5)

运行脚本

使用蓝牙模块时，有两个串口端口号：

打开 Terminal ( 比如Anaconda Prompt)，进入脚本文件所在路径（***\serialMaster）,可以使用以下命令运行脚本，脚本在最开始运行时会自动识别口串口端口号，并完成连接。

方式一：运行 ardSerial.py 脚本程序

当然也您可以不带任何参数运行此脚本

当系统识别有多个串口端口号，脚本在最开始运行时会自动识别出所有与机器人已正常建立连接所有串口端口号（可以同时给多个机器人发送串口命令），并打印出以下提示信息：

程序正式开始运行时，打印出以下提示信息：

您可以键入'quit'或'q'命令退出程序。

接下来，您就可以在 Terminal 中输入串口命令来控制机器人做各种有意思的动作了😃 比如：

方式二：运行自定义脚本程序，比如 example.py

example.py中的列表 testSchedule 用来测试各种串口命令，运行以下脚本代码，可以看到 list 中每条串口命令的执行效果：

您也可以参考列表 stepUpSchedule 的内容（在 ***\serialMaster\demos\stepup.py 中），按照自己的实际需要编写行为列表，实现自己的创意。🤩

注意：运行 ***\serialMaster\demos\ 路径下的脚本程序时，一定要先使用 cd demos 命令进入到脚本程序所在路径（***\serialMaster\demos），再使用 python3 命令运行脚本程序

（比如：python3 stepup.py）

列表 testSchedule 中的串口命令说明：

['kbalance', 2]

• kbalance 控制Bittle正常站立指令

• 2 指令执行完成后的延时时间，单位是秒

['d', 2]

• d 机器人变换到休息姿势并关闭舵机的命令

• 2 指令执行完成后的延时时间，单位是秒

['c', 2]

• c 进入校准模式的命令

• 2 表示执行完命令后延时时间，单位是秒。 运动命令完成后，会延时 2 秒后执行下一条命令。

['c', [0, -9], 2]

• c 进入校准模式的命令

• 0 关节舵机序号

• -9 旋转角度值（此数值表示相对于校准后采用的参考0值），单位是度

• 2 指令执行完成后的延时时间，单位是秒

本例含义：序号为0的关节舵机旋转-9度。 这些运动命令完成后，会延迟 2 秒后执行下一条命令。

使用此格式，可以进入校准模式，校准某个关节舵机的角度。

['m', [0, -20], 1.5]

• m 控制关节舵机转动指令

• 0 关节舵机序号

• -20 旋转角度值（此数值表示相对于校准后采用的参考0值），单位是度

• 1.5 指令执行完成后的延时时间，单位是秒。它可以是一个浮点数。

['m', [0, 45, 0, -45, 0, 45, 0, -45], 2]

使用这种格式，可以一次发出多个关节舵机旋转指令，这些关节舵机旋转指令是顺序执行的，不是同时执行的。 关节角度被视为 ASCII 字符，因此可以直接由人输入。

本例含义：序号为0的关节舵机先旋转到45度位置，再旋转到-45度位置，以此类推。 这些运动命令完成后，会延时 2 秒后执行下一条命令。

['i', [ 8, -15, 9, -20], 2]

使用这种格式，可以一次发出多个关节伺服旋转指令，这些关节伺服旋转指令是同时执行的。 关节角度被视为 ASCII 字符，因此可以直接由人输入。

本例含义：序号为8、9的关节舵机同时旋转到-15、-20度位置。 这些运动命令完成后，会延时 2 秒后执行下一条命令。

['M', [8, 50, 9, 50, 10, 50, 11, 50, 0, 0], 3]

• M 顺序旋转多个关节舵机的命令。 为了提高效率，角度被编码为二进制数。

• 8、9、10、11、0 关节舵机序号

• 50, 50, 50, 50, 0 旋转角度值（这个角度是绝对值，而不是相对值），单位是度

• 3 表示执行完命令后延时时间，单位秒

['l', [20, 0, 0, 0, 0, 0, 0, 0, 45, 45, 45, 45, 36, 36, 36, 36], 5]

• I 控制所有关节舵机同时旋转的命令（目前该命令支持16个自由度，即16个舵机）。 为了提高效率，角度被编码为二进制数。

• 20,0,0,0,0,0,0,0,45,45,45,45,36,36,36,36表示0-15对应的各个关节舵机的旋转角度（这个角度是绝对值，而不是相对值），单位是度

• 5 表示执行完命令后延时时间，单位秒

['b', [10, 2], 2]

• b 控制蜂鸣器发声指令

• 10 音调

• 2 duration的长度，对应 1/duration 秒

• 2 执行完指令后的延时时间，单位是秒

['b',[0, 1, 14, 8, 14, 8, 21, 8, 21, 8, 23, 8, 23, 8, 21, 4, 19, 8, 19, 8, 18, 8, 18, 8, 16, 8, 16, 8, 14, 4],3]

• b 控制蜂鸣器发声指令

• 0、14、14、21…… 音乐的音调

• 1,8,8,8…… duration的长度，对应1/duration秒

• 3 发送指令后延时时间，单位秒

使用这种格式，可以一次发出多个音调的发音命令，播放一段简单的旋律。

本例含义：播放一段简单的旋律，音乐旋律播放后延时3秒。

ck = [

-3, 0, 5, 1,

0, 1, 2,

45, 0, 0, 0, 0, 0, 0, 0, 45, 35, 38, 50, -30, -10, 0, -20, 6, 1, 0, 0,

-45, 0, 0, 0, 0, 0, 0, 0, 35, 45, 50, 38, -10, -30, -20, 0, 6, 1, 0, 0,

0, 0, 0, 0, 0, 0, 0, 0, 30, 30, 30, 30, 30, 30, 30, 30, 5, 0, 0, 0,

]

['K', ck, 1]

• 'K'表示实时发送给机器人的技能数据

• 技能数组被发送到移动中的机器人并在机器人本地执行

• 您可以将技能数组内容以这种格式插入技能库或 InstinctX.h文件中

祝您玩得开心！😍

第一部分：硬件准备

1.1 需要准备的硬件

• NyBoard USB上载模块（CH340C）

• NyBoard WiFi模块

1.2 硬件连接

将WiFi模块插入USB上载器的模块配置接口上，在windows设备管理器找到对应的COM口。

第二部分：软件准备

2.1 下载 Thonny

下载最新版本的Thonny，Thonny是一个开箱即用的Python编辑器，原生提供了MicroPython的支持。

2.2 下载 MicroPython固件

2.3 烧录 MicroPython固件

将MicroPython固件烧录至WiFi模块有两种方法：

• 使用ESPtool下载工具，可以更加精确控制Flash的分区和使用

• 使用Thonny自带工具，比较方便

为了方便我们使用Thonny自带的烧录工具。 具体步骤如下：

1. 打开Thonny软件，主界面如下图。Thonny默认配置使用安装目录下的Python解释器。
2. 打开Tools -> Options（选项），进入选项页面。在第一个General界面，我们可以选择需要的语言 （需要重新启动Thonny）。
3. 打开第二个选项卡Interpreter（解释器），我们将默认的Python3解释器更换为MicroPython(ESP8266)后， 选择对应的端口。
4. 此时我们的WiFi模块还未烧录MicroPython固件，点击上图右下角的Install or update firmware 使用内置的烧录程序更新固件。

5. 选择WiFi模块所在的端口(COMx)，选择下载的MicroPython固件（bin文件）所在的位置。 勾选下载模式（flash mode）为：from image file(keep)（速度会比较慢，但是只需要烧录一次且不容易出错）， 勾选全片擦除（Erase flash before installing）。按下安装(install)键。
6. 界面的左下角会显示进度，先擦除Flash，再写入固件。当出现完成（Done）字样的时候，表示已经烧录完成了。
7. 软件准备工作到此结束，关闭下载界面会出现如下显示。红字乱码是因为ESP8266启动时会打印一串非115200波特率的代码，这段代码无法被MicroPython Shell识别。 当出现Python标志性的>>>符号时，表示固件烧录成功。

NyBoard相当于一块通用的Arduino Uno板，具有丰富的外设。 除了原生 Arduino IDE 之外，您还可以使用 Mind+ 积木块对其进行编程。 但要注意，如果使用此模式，原有的 OpenCat 固件会被覆盖，稍后需要重新上传固件才能恢复默认的机器人功能。

设置编码环境很简单，具体步骤如下：

硬件产品

智能搜索

您可以使用此站点上的查找 (Cmd+K/Ctrl+K) 功能。 它支持 Lens，这是一项基于类似ChatGPT 的服务。

1. 准备

遥控器不需要配对。使用前要拔掉塑料绝缘片，在使用时要把发射端对着机身后部的接收器。如果机器人无响应，您可以通过手机摄像头来检查发射灯。如果按键时灯不闪，您需要更换遥控器电池；如果灯闪，那可能是机器人主机上的程序没有配置好。

2. 按键映射

我们使用的是通用的红外线遥控器，按键发出的信号只与它的位置有关。对应符号有助于记忆，因此在程序代码中我们定义了与位置相关的符号来引用这些键，例如第 1 行第 1 列的 K00，第 4 行和第 3 列的 K32。

使用键定义的缩写可以减少 SRAM 的使用。因为遥控器上的按键有限，您可以更改它们的功能定义来调试新功能。

我们还为未来的批次制作了定制的遥控面板。 以前的用户可以下载设计文件并将其打印在 A4 纸上。

3. 尝试下面的招牌动作

• 休息 关停舵机并使机器人趴下。如果机器人在做一些“怪异”的事，总可以按这个键让它停下。说到“怪异”我是认真的，机器人的头脑甚至连我也说不清；

• 在平衡站立姿势时，您可以从侧面推机器人，或者使它用后腿和尾巴站立，观察它如何试图在摇晃的平面上保持平衡。事实上，平衡算法在大部分姿态都是激活的；

• 前进、左转、右转可以使机器人以当前步态转向；

• 后退可以让机器后退，同时左右转也是可以的；

• 校准可以使机器人进入校准姿势并关闭陀螺仪；

• 踏步使机器人在原点踏步，验证装配和校准的精度；

• 爬、走、小跑是可以切换的不同步态，可以和方向键结合；

• 小跑后的按键是一些预设的姿势或行为；

• 陀螺仪 打开/关闭用于平衡反应的陀螺仪。关闭陀螺仪可加速使原来缓慢的步态更快更稳，但不推荐用于原来就快速的步态（小跑）；

• 拎着机器人脊柱的中间把它悬在半空，这样它的腿可以自由运动。试试遥控器上的所有按钮，看看机器人有什么反应，然后把机器人放到水平的桌上，再试试这些按钮。不同的平面摩擦力可能对机器人的运动造成影响，比如地毯对于机器人的小短腿就好像杂草对于我们的腿一样，这种地形上就比较适合用爬行；

• 您可以下拉电池盒并沿着机器人肚子的中轴线滑动，这样可以调节重心位置，改善某些快速步态的表现；

• 机器人可以在一个小角度（<10度）的坡面上行走。

电脑端桌面应用程序 Petoi Desktop App 适用于 机器人 Nybble 和 Bittle，机器人主板 NyBoard采用Arduino UNO ATmega328P主控芯片， 主板 BiBoard 采用 ESP32 主控芯片。

• NyBoard

NyBoard 主板型号

NyBoard 主板型号（版本信息)，请见主板上的丝印。

• BiBoard

BiBoard 主板型号

BiBoard 主板型号（版本信息)，可参考图示位置：

使用 Petoi Desktop APP 上载固件

对于NyBoard，固件上传主要是调用应用程序 avrdude 来为主板上传固件文件。

对于BiBoard，固件上传主要是调用应用程序 esptool 来为主板上传固件文件。

连接USB上载器

打开 Petoi Desktop App

USB上载器正确连接后，打开 Petoi Desktop App（Windows：UI.exe / Mac：Petoi Desktop App / Linux: Petoi-opencat），选择 产品 和 语言。

Petoi Desktop App中的菜单栏

点击“固件上载”按钮

选择正确的选项

固件上载选项按钮

固件上载流程

单击“上传”按钮后，上传过程立即开始。 底部状态栏会实时显示当前进度，以及关键流程的结果。

参数固件上传成功后，主板开始自动运行配置程序。 会依次弹出一些消息窗口供您确认或取消：

1. 舵机校准参数清零? (Y/N)

选择点击“是(Y)”，程序会将所有舵机校准参数清零，状态栏会实时更新相应的过程和结果。

选择点击“否(N)”，程序将跳过此步骤。

2. 校准 IMU? (Y/N)

选择点击“是(Y)”，程序会校准陀螺仪（IMU），状态栏会实时更新相应的过程和结果。

选择点击“否(N)”，程序将跳过此步骤。

完成所有步骤后，将弹出一个消息窗口，显示“参数初始化完成！” 您需要确认进行第二轮上传主程序固件。

主程序固件上传完成后，状态栏会更新固件上传成功或失败等相应结果。 如果上传成功，则会弹出“固件上传完成！”消息窗口。

如果您有 Arduino IDE 编程经验，可以参考使用 Arduino IDE 上载程序固件。

打开桌面应用程序后，点击“技能创作坊”按钮，即可打开技能创作界面。

界面分为“关节控制器”，“状态开关”，“预设姿态”，“技能编辑器”四个区域：

关节控制器

状态开关

预设姿态

技能编辑器

基本操作

如上图（技能创作界面）所示。

当前动作帧

添加动作帧

编辑动作帧

在添加新的动作帧后，有以下四种方式对该帧动作（当前动作帧）内容进行编辑：

播放动作

删除动作帧

• 如果删除的动作帧为当前动作帧，删除后，之前紧挨在所删动作帧上方的一个动作帧自动激活为当前动作帧

• 如果删除的动作帧不是当前动作帧，删除后，当前动作帧内容保持不变（如果当前动作帧之前在删除的动作帧下方，删除动作帧后，只是当前动作帧的序号会自动减1）

导出动作

导出镜像动作

在导出动作行为时，如果想将动作帧列表中的所有动作按照镜像（动作帧列表中每一帧动作都将按机器人左右对称的方式，左右两边关节动作进行互换）一起导出，可以先点击“镜像导出”按钮（选中后按钮呈现凹陷状态 ），再点击“导出”按钮。如果想取消镜像导出，可以再次点击已选中的“镜像导出”按钮（取消后按钮呈现凸起状态 ）。

导出动作技能后，可以通过以下几种方式来调用：

导入动作

导入动作帧时，有以下两种方式：

• 点击对话框中的“打开文件”按钮，通过选取之前导出保存的文本文件来导入动作行为：选中动作文件，点击“打开”后，对话框中的文本编辑区自动显示动作文件中的内容，如下图所示：

• 按照文本编辑区域中的提示信息，先点击对话框中的“清空”按钮，再从Instinct***.h （***代表Bittle或者Nybble）复制技能数组后, 再粘贴到文本编辑区域中。

确认无误后，点击对话框中的“确认”按钮即可导入动作。如果数组格式有误（比如数组中缺失了一些数值，或者表示循环次数的值不正确等），点击对话框中的“确认”按钮后，程序会弹出一个“格式有误”消息提示框，提示用户更正文本编辑区域中动作数组内容。

导入成功后，机器人会自动简单复现动作帧列表中的第一帧动作。

点击对话框中的“取消”按钮，即取消当前导入操作。

重置动作帧列表

进阶操作

动作帧的继承特性

循环设置

设置运动速度

1，2，4，8，12，16，32，48，最快

设置延时

有17个预设值供您选择： 0，50，100，200，300，400，500，600，700，800，900，1000，2000，3000，4000，5000，6000

当然您也可以在延时文本框中手动输入 0~6000范围内的任意整数值，单位是：毫秒（ms）。

设置触发轴、触发角

• None 表示无触发轴，解发角条件设置

• Pitch 表示正俯仰，机器人身体向前俯下方向旋转

• -Pitch 表示负俯仰，机器人身体向后仰起方向旋转

• Roll 表示正横滚，机器人身体向自身左侧翻滚

• -Roll 表示负横滚，机器人身体向自身右侧翻滚

触发角设置范围是：-125 ~ 125 之间的整数值。

当动作帧中设置了具体的触发轴，触发角时，只有当机器人在完成此帧关节动作后，并按照预设的身体旋转方向旋转越过触发角时，才会触发下一帧动作。如果此动作帧还设置了延时时长，那么机器人在运行此动作帧时，不但要满足触发轴，触发角设置的触发条件，还要达到延时设置时长，才会触发执行下一帧动作。

当创作与机器人身体旋转相关的动作行为（比如后空翻，做单杠运动等）时，尤其是需要在机器人身体转到某个角度时发力，结合触发轴、触发角合理设置，效果可能会更好些。因为在运动过程中，我们可以通过陀螺仪来实时监测机器人身体旋转角度，这样就可以使机器人做到当身体旋转到最理想的角度时来触发关节舵机做动作，从而更高效地做动能势能转换。

标记动作帧

插入动作帧

如果想在动作帧列表的第一帧动作之前插入动作帧列表中的某帧动作，操作会稍微复杂一些：首先将第一帧动作激活为当前动作帧，然后点击第一个动作帧中的“添加”按钮， 这样就在第一个动作帧下方新增一个与该动作帧内容相同的动作帧，然后再将想要插入的动作帧激活为当前动作帧， 然后再次点击第一个动作帧中的“添加”按钮，这样就在第一个动作帧下方插入了想要插入的动作帧，最后点击第一个动作帧中的“删除”按钮，将第一个动作帧删除。

行为、步态选项

在导入动作帧后，程序会按照所导入的动作数组格式，自动识别并变更行为、步态选项。机器人会自动简单复现动作帧列表中的第一帧动作。

舵机状态开关

随机行为状态开关

高阶操作

多机同时操控

如果您在电脑端拔掉一个USB串口（或者在在蓝牙设置界面选择断开此蓝牙模块）， 这时串口下拉列表也会随之实时更新（减少对应的串口名称）。

如果您想让桌面应用程序停止检测串口连接，可以点击“已连接”按钮（按钮中文字变为“连接” ），就会断开所有的串口连接。再次点击“连接”按钮，将恢复串口实时检测功能。

专业用户拓展

您可以修改OpenCat/pyUI/中的技能创作坊的源代码SkillComposer.py来进行二次开发。

ROS 安装包可以供开发人员轻松连接到 ROS 环境。 建议将 ROS 与 Raspberry Pi 一起使用。

在树莓派上使用ROS

目前建议使用docker安装ROS

• 在树莓派上安装 docker (详情参考文档)

sudo apt-get update && sudo apt-get upgrade
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker pi
# test installation
docker run hello-world

• 准备工作环境

mkdir -p workspace/src
cd workspace/src
git clone https://github.com/PetoiCamp/ros_opencat
cd ros_opencat
git submodule init && git submodule update
cd ../../..

• 运行容器

docker run -v path/to/workspace:/workspace \
-it --rm --privileged --network host --name ros ros:noetic-robot

• 源文件和并在容器内构建

cd /workspace
source /opt/ros/noetic/setup.bash
catkin_makbase
source devel/setup.bash

• 运行例程 (更多参考示例)

rosrun opencat_examples opencat_examples_serial

使用ROS实现远程控制

Ros 在设计时考虑了分布式计算。 这是一个关于如何在不同机器上运行节点的简单示例。

• 在主机上（通常比 Raspberry Pi 更强大）

# launch server
roscore

• 在树莓派上运行服务节点

export ROS_MASTER_URI=http://<Host_IP>:11311/
rosrun opencat_server opencat_service_node

• 从主机发送指令

rosrun opencat_examples opencat_examples_client_cpp

例程

• 使用 serial 库

rosrun opencat_examples opencat_examples_serial

• 使用 ROS 服务

# start core
roscore
# start service server
rosrun opencat_server opencat_service_node
# examples using oppencat ros service in C++
rosrun opencat_examples opencat_examples_client_cpp
# examples using opencat ros service in python
rosrun opencat_examples opencat_examples_client_py

1. 阅读快速上手指南

BiBoard 各功能模块具体参数，请根据主板型号，参考相关技术文档。

• BiBoard V0 快速上手指南

• BiBoard V1 用户指南

2. 下载和安装软件环境

2.1 准备ESP32开发环境

详情请参考 BiBoard V0 快速上手指南第3.2.1 章节。

2.2 修改库代码文件

sdkconfig.h

在文档最后追加一行代码：

#define CONFIG_DISABLE_HAL_LOCKS 1

2.3 配置开发板参数

请参考下图中选项列表设置主板的上传速度(Upload Speed)、CPU 频率(CPU Frequency)等参数。 选项中关于 Flash Size 和 Partition Scheme 的设置，请参阅下一节。

2.4 设置硬件分区方案

BiBoard V0 使用带有 16M 闪存的 ESP32。为简化起见，您可以使用默认的 4 MB 分区参数，因为这个配置方案目前已有足够的空间用来上传OpenCatEsp32 固件。

BiBoard V1 使用带有 4M 闪存的 ESP32。

4MB 分区方案

您可以使用默认的带有 spiffs 4MB分区方案。您也可以使用 4 MB 闪存限制下的其他分区方案，例如“无 OTA”或“Huge APP”。

16MB 分区方案

如果您想充分利用 BiBoard 的 16 MB 闪存（这是不必要的，并且需要更长的上传时间）。您可以阅读 Arduino IDE增加硬件分区配置选项。

2.5 下载OpenCatEsp32代码包并安装库文件

1. 从GitHub下载最新的OpenCatEsp32代码包：https://github.com/PetoiCamp/OpenCatEsp32。 建议使用GitHub桌面应用程序进行版本控制。否则，请确保每次下载全部的OpenCatEsp32代码压缩包。所有代码文件必须在同一版本中，才能正常编译使用。

1. 解压缩代码压缩包（zip文件）。 解压缩后将获得一个OpenCatEsp32-main文件夹。您需要在打开OpenCatEsp32.ino之前，将其重命名为OpenCatEsp32（Arduino IDE 要求工程项目代码文件必须放在同名文件夹中）。

• ModuleTests文件夹中有几个名为testX（X代表功能模块，比如蜂鸣器Buzzer，陀螺仪MPU）.ino的代码。您可以上传它们分别测试对应模块的功能。打开任何带有前缀“ test”的testX.ino的工程。 （建议您使用testBuzzer.ino作为第一个测试项目）。

1. 安装库文件 a. 下载 MU Vision Sensor库 并将其加载到您的 Arduino IDE 中

   b. 安装最新版本的ArduinoJson

2.6 使用USB type-C数据线连接电脑与主板

连接成功后，可以在工具菜单下查看串口名称（如下图所示）：

如果连接到电脑后找不到对应的串口名称，可以尝试通过以下几种方式解决问题：

2.7 编译并上传程序

在OpenCatEsp32.ino文件中，根据您所使用的设备类型，修改设备类型宏定义。

#define BITTLE    //Petoi 9 DOF robot dog: 1 on head + 8 on leg
//#define NYBBLE  //Petoi 11 DOF robot cat: 2 on head + 1 on tail + 8 on leg
//#define CUB

根据您所使用的主板的型号，修改主板型号宏定义。

// #define BiBoard_V0_1  //ESP32 Board with 12 channels of built-in PWM for joints
#define BiBoard_V0_2
// #define BiBoard_V1_0

如果机器人带有机械臂（Bittle R），您还应该激活以下宏定义：

 #define ROBOT_ARM                 // for attaching head clip arm 

否则，请注释此行代码。

修改完成后，点击上传按钮（如下图所示）上传程序，代码中的更改部分会自动保存。

2.8 程序初始化

如果当前上传程序代码的版本日期比机器人主板固件的版本日期更新时，程序上传完成后，会自动进入初始化启动模式。

在主板上电启动时，打开串口监视器，您将看到相关的启动信息：

ets Jun  8 2016 00:22:57

rst:0xc (SW_CPU_RESET),boot:0x1b (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:1
load:0x3fff0030,len:1344
load:0x40078000,len:13964
load:0x40080400,len:3600
entry 0x400805f0
k
Flush the serial buffer...

* Start *
Bittle X
Software version: B02_250121
Scanning I2C network...
- I2C device found at address 0x54:	EEPROM
- I2C device found at address 0x5C:	Misc.
- I2C device found at address 0x68:	MPU6050
- I2C device found at address 0x69:	ICM42670
- I2C device found at address 0x7E:	Misc.
- done
GroveVisionQ	0
MuQ	0
Set up the new board...
Unmute and set volume to 5/10
Using constants from I2C EEPROM
- Name the new robot as: Bittle45

接下来您将看到以下提示问题：

Reset the joints' calibration offsets? (Y/n):  // 是否清除所有舵机的校准参数？‌‌

• 发送英文字符“Y”，把所有舵机的修正值归零。

• 发送英文字符“n”, 跳过此步骤。

- Calibrate the Inertial Measurement Unit (IMU)? (Y/n):  // 是否校准IMU（MPU6050）？

• 发送英文字符“Y”，校准 IMU（陀螺仪/加速度计传感器）。

• 发送英文字符“n”, 跳过此步骤。

Run factory quality assurance program? (Y/n)        // 运行工厂质检程序

发送英文字符“n”, 跳过此步骤。或者您什么也不需要做，程序将在 5 秒后自动跳过此步骤。

与提示问题相关的串口打印信息详情如下：

* Start *
Scanning I2C network...
- I2C device found at address 0x54  !
- I2C device found at address 0x68  !
- done
Set up the new board...
// 蓝牙连接时使用的设备名称
- Name the new robot as: BittleED    
Reset the joints' calibration offsets? (Y/n): 
Y
Buzzer volume: 5/10
- Calibrate the Inertial Measurement Unit (IMU)? (Y/n): 
Y

Put the robot FLAT on the table and don't touch it during calibration.

Initializing MPU6050...
OK
If the program stucks, reinstall Arduino ESP32 boards version 2.0.12. Newer version may cause bugs!
- Testing MPU connections...attempt 0
- MPU6050 connection successful
- Initializing DMP...
MPU offsets: 2691	1893	1181	72	-57	0	
Calibrate MPU6050...
>....................>....................
MPU offsets:
//           X Accel  Y Accel  Z Accel   X Gyro   Y Gyro   Z Gyro
//OFFSETS     2759,    1871,    1173,      73,     -56,      -4
- Enabling DMP...
- DMP ready! Waiting for the first interrupt...
BLE:		Bittle45_BLE
Waiting for a BLE client connection to notify...
SSP:		Bittle45_SSP
The SSP device is started, now you can pair it with Bluetooth!
Setup ESP32 PWM servo driver...
Calibrated Zero Position
135	225	135	135	190	80	190	80	190	80	80	190	
Build skill list...88
Run factory quality assurance program? (Y/n)
(Auto skip in 5 seconds)
5...4...3...2...1...n
TaskQ
rest
11
Init voice
Number of customized voice commands on the main board: 
10
Turn on the audio response
Show Petoi Logo color
S,	A,	T,	L,	D,	I,	B,	U,	G,	C,	Q,	
0,	1,	0,	0,	0,	0,	0,	0,	0,	0,	0,	
Ready!
g
rest
d
XAaXAc
Switch English

当看到串口监视器中输出字符串“Ready!”时，程序将进入常规启动模式。

主板在每次上电启动时，通过比对EEPROM 中的BIRTHMARK，判断程序有没有被初始化过。如果程序已被初始化，则不会再次进入初始化启动模式。

2.9 发送串口命令切换工作模式(选做)

程序默认运行语音模式。如果您想切换模式，请打开串口监视器并发送以下串行命令：

2.10 上电开机

• 长按电池上的电源按钮，保持机器人身体侧立开机（如下图所示），主板程序在常规启动模式下会自动进入关节校准状态。 下图是安装好身体各部件后，机器人进入关节校准状态后的身体姿态。

详细的关节校准流程请参考第5章🔌连线 和 第6章📐校准。

• 当机器人上电时，身体正放（背部朝上），主板程序在常规启动模式下，机器人将从“休息”姿势（四肢收缩，并且所有舵机处于释放状态）启动。

3. 使用移动App操控

BiBoard 内置蓝牙，您可以将其与移动App (Petoi) 连接，进行关节校准 与 遥控。

您可以在 ChangeLog.md 中查阅程序更新历史信息。

在完成烧录MicroPython固件后，我们就可以使用它了。

1. 直接运行脚本

我们直接在解释器中输入python语句即可执行。

# 示例代码：
print("Hello MicroPython")

2. 使用.py文件运行程序

NyBoard WiFi模块使用了ESP8266的IO2与一个红色LED连接，用来指示连接状态。这个LED是可编程的。 写一个简单的python blink程序:

from machine import Pin
import time

# GPIO LED IO2
def blink():
    
    led = machine.Pin(2, machine.Pin.OUT)     # Pin 2 ,Output mode
    
    while(True):			# loop
        led.on()			# light on LED
        time.sleep(1)		# delay 1s
        led.off()			# light off LED
        time.sleep(1)		# delay 1s

if __name__ == "__main__":
    blink()

按下工具栏上绿色的开始运行按钮，程序会通过串口发送到WiFi模块上， 由ESP8266内置的MicroPython解释器解释后运行。 因为案例程序是死循环，需要停止时，按下红色的停止键即可完成程序中断和复位。

3. 将.py文件下载到WiFi模块上

我们点击View -> File打开文件工具栏， Thonny左侧显示了文件。上部为本机的目录，下部为MicroPython设备中存储的文件。 默认情况下只有一个boot.py文件，这个文件请不要删除，是MicroPython设备的启动文件。

我们将刚刚的点灯程序保存为blink.py保存在本机后，右键点击文件，选择Upload to / :

在弹出窗口选择MicroPython device：

在设备上就有了一个blink.py的文件。这样文件就保存在设备上。

4. 写一个python程序让机器人顺序执行动作

WiFi模块通过串口向NyBoard发送指令进行控制。我们只需要写一个简单的串口发送程序，向NyBoard发送一系列串口指令， 就可以让机器狗执行序列动作。

from machine import UART
import time

uart = UART(0, baudrate=115200,timeout=5)

# walk
def walk(time_ms):
    print("walk")
    uart.write("kwkF")      # walk cmd
    time.sleep_ms(time_ms)  # keep time
    uart.write("d")         # stop
    time.sleep_ms(1500)
    
# backward
def back(time_ms):
    print("back")
    uart.write("kbk")
    time.sleep_ms(time_ms)
    uart.write("d")
    time.sleep_ms(1500)

# stop
def stop():
    uart.write("d")
    
def initConnection():
    connected = False
    while True:
        uart.write("d")
        for t in range(30):
            uos.dupterm(None, 1)        # disable REPL on UART(0), detach the REPL from UART0
            time.sleep_ms(5)            #delay is a must
            result = uart.read(1)
            uos.dupterm(uart, 1)        # enable REPL on UART(0), reattach REPL

            if result != None:
#                 uart.write(result)    # for debug
                if result == b"d":

                    connected = True
                    break
            time.sleep_ms(10)

        if connected:
            break

    uart.write("b22 4 24 4 26 4")
 

def actSeq():
    initConnection()
    time.sleep_ms(2000)
    walk(3000)
    back(3000)
    uart.write("m0 90")
    time.sleep_ms(3000)
    uart.write("i8 -20 9 -60")
    time.sleep_ms(2000)
    uart.write("b26 4 24 4 20 4")
    time.sleep_ms(1000)
    uart.write("d")
    uos.dupterm(None, 1)        # disable REPL on UART(0), detach the REPL from UART0

    
if __name__ == "__main__":
    actSeq()
    

当我们执行actSeq()函数时，就可以通过串口输出一系列指令。使用串口监视器我们可以进行调试。 使用串口监视器监控输出如下（为了方便阅读我使用了串口调试器的自动断帧，实际上是没有自动换行的）

5. 上电自动运行

当我们调试完序列动作后，将WiFi模块拔下，插上NyBoard后，机器狗没有任何反应，因为actSeq()函数并没有运行。 我们希望上电自动运行程序，有以下2种方法：

1. 请将文件名更改成“main.py”并存到设备（这个是最简单的）

2. 修改boot.py启动文件

我们预先定义了一套串口通信协议，具体指令和参数表如下：

所有的命令都是以单个ASCII字符开头，并区分大小写。通常指令为小写。

您可以在串口监视器中尝试输入以下命令，查看实际效果：

• “ksit”

• “m0 30”

• “m0 -30”

• “kbalance”

• “kwkF”

• “ktrL”

• “d”

src/OpenCat.h 中包含完整的真正有效的指令类型：

更多可用技能命令如下表所示：

实际生效的技能定义在InstinctBittle.h 或 InstinctNybble.h个表：

const char* skillNameWithType[]={"bdFI","bkI","bkLI","crFI","crLI","hlwI","mhFI","mhLI","pcFI","phFI","phLI","trFI","trLI","vtFI","vtLI","wkFI","wkLI","balanceI","buttUpI","calibI","droppedI","liftedI","restI","sitI","strI","zeroN","bfI","ckI","climbCeilI","fdI","ffI","hiI","jyI","pdI","peeI","puI","pu1I","rcI","rlLI","rtI","stpI","tsI",};

可以在所有技能的名称前加“k”并删除后缀来调用。比如，表中有一个"sitI" 的技能。可以发送"ksit" 来调用坐下（sit）。如果一个技能名有 "F" 或 "L" 的后缀，就是一个步态，表示向前或向左走。向右走是向左走的镜像，可以用"kwkR"调用。类似地，还有跑步("tr")、爬行("cr")、踏步("vt")等步态。

您可以在 NyBoard 上焊接一个 2x5 插座以插入 Raspberry Pi。 Pi 3A+ 最适合 NyBoard 的尺寸。

Nybble

Bittle

红色的树莓派卡扣可以3D打印。

如串口协议所示，Arduino IDE的串口监视器支持的命令参数全部编码为AscII码字符串，主机（例如RasPi）支持额外的命令，大多数命令都编码为二进制字符串以进行有效编码。例如，当编码角度为65度时：

• Ascii: 2个字节的char '6' and '5'

• Binary: 一个Byte的char，‘A’

显然，二进制编码比Ascii字符串有效得多。但是，传输的消息将不会直接被人类读取。在OpenCat存储库中，有一个简单的Python脚本ardSerial.py，它可以处理NyBoard和Pi之间的串行通信。

1. 设置树莓派串口

在树莓派的终端输入sudo raspi-config

在Interface选项下找到 Serial，禁用串口登陆，开放串口界面（Disabled the serial login shell and enable the serial interface）：

1. 使用 sudo 权限命令运行 raspi-config：sudo raspi-config

2. 找到 Interface Options-> SerialPort

3. 选项 Would you like a login shell to be accessible over serial? 选择No

4. 选项 Would you like the serial port hardware to be enabled? 选择Yes

5. 退出 raspi-config 并重新启动机器人（关闭、打开电池电源）以使更改生效。

只要把树莓派和NyBoard通过可选的2x5插座相连，它们的串口就自动连接起来了，逻辑电平是3.3V。如果您连接的是其他AI芯片，就要注意Rx和Tx的连接，以及它们的逻辑电平。外接板上的Rx要连接NyBoard的Tx，外接板上的Tx要连接NyBoard的Rx，还需要连接NyBoard的参考电平输入和外接板的逻辑电压。