# Welcome to Petoi Guide Center for Bittle X V2, Bittle X V2+Arm & Nybble Q

📚➡️🤖

[https://guide.petoi.com](https://guide.petoi.com/) is the Petoi robot product documentation hub for **the latest generation of Petoi robot Bittle X V2, Bittle X V2+Arm, and Nybble Q**. We constantly iterate on our models and code to bring bionic robotic pets to the world. Please read the notes regarding versions carefully before configuring your robot. 

If you need help, please [contact us](https://www.petoi.com/pages/contact-us) or post on [our forum](https://www.petoi.camp/).

<figure><img src="/files/46kqXEdVef7cdQIwsExh" alt=""><figcaption></figcaption></figure>

If you are unsure whether you've received the correct Bittle package, please refer to [this guide](https://www.petoi.com/blogs/blog/how-to-tell-if-you-have-received-the-correct-bittle-bittle-x-robot-dog).

### 🐶 [Bittle X V2 User Manual](/product/bittle-x-v2)

### 🐶 [Bittle X V2+Arm User Manual](/product/bittle-x-v2+arm)

### :cat: [Nybble Q User Manual](/product/nybble-q)

### Check [FAQs](/faq-frequently-asked-questions)

#### Please navigate the sidebar to access all other documentation.  On mobile, you can tap on the menu icon on the top left to access the sidebar.

## If you have legacy Bittle robots, please check [docs.petoi.com](https://docs.petoi.com/):

### 🐶 [Bittle Dog User Manual](https://bittle.petoi.com) - Bittle STEM Kit, Bittle Robotics Kit

### 🐶 [Bittle X User Manual](https://bittle-x.petoi.com/)(not for Bittle X V2)

### 😼 [Nybble Cat User Manual](https://nybble.petoi.com)

## Intelligent Q\&A

You can use the find (Cmd+K/Ctrl+K) feature on this site to ask any questions with a ChatGPT-like service.

<figure><img src="/files/ZMqOaTNKLR44AqhYriwm" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Note that this privacy notice refuses to disappear!

<img src="/files/Kk0lg5Xg07ItAQyYaKpN" alt="" data-size="original">
{% endhint %}


# Outdated - Getting Started Guide

This page gets you started with building/playing/coding with your Petoi robots

Hi, thanks for getting a Petoi robot.

If you have a construction kit, you can follow the following instructions to build it.

* [Bittle](https://bittle.petoi.com/1-tools-and-preparation)
* [Bittle X](https://bittle-x.petoi.com/1-preparation)
* [Bittle X V2](/product/bittle-x-v2)
* [Nybble](https://nybble.petoi.com/chapter1)

{% hint style="warning" %}
Note that the robot is suitable for working on smooth surfaces. When walking on a carpet, the movement may not be smooth.
{% endhint %}

### After you’ve assembled a Petoi robot or have bought a pre-assembled version, the following steps are recommended:

1. [Play with mobile app](https://docs.petoi.com/mobile-app/controller)
   * Play with the default actions
   * Play with [simple joint control](https://docs.petoi.com/mobile-app/controller#move-bittles-head-move-joint-angle)
   * Add [more commands](https://docs.petoi.com/mobile-app/controller#available-commands-to-be-added) to the controller panel
   * Play with [group commands](https://docs.petoi.com/mobile-app/controller#create-a-group-command) to make your robot perform multiple actions in sequence
2. [Play with voice commands](https://docs.petoi.com/extensible-modules/voice-command-module#play-with-the-voice-commands)(for Bittle X or any robot with the voice command module)
   * If the robot doesn’t respond to your voice commands,  please see [the troubleshooting guide](https://docs.petoi.com/extensible-modules/voice-command-module#how-to-debug-if-the-voice-command-doesnt-work).
   * You can [turn off the voice command functionality](https://docs.petoi.com/extensible-modules/voice-command-module#id-2.-turn-on-off-the-voice-command-functionality-audio-response-and-robotics-reaction)(for example: in a public space, or in a classroom setting requiring quiet periods) to avoid accidentally triggering voice responses and robot reactions.
3. If you've bought a Bittle X+Arm, please see [the robotic arm doc](https://app.gitbook.com/o/-M-_eWZUjFA4usjshHcZ/s/-MQ6a951Q6Jn1Zzt5Ajr-887967055/~/diff/~/changes/703/extensible-modules/robot-arm/~/overview).
4. Do some coding
   * Follow [Petoi Coding Blocks curriculum](https://www.petoi.com/pages/free-quadruped-robotics-curriculum-scratch-coding) to [program some Petoi robotics moves](https://www.youtube.com/playlist?list=PLHMFXft_rV6POrzm8O12Nybdy1-FS1ymg)
   * [Visually design](https://www.youtube.com/playlist?list=PLHMFXft_rV6MTs8HMxSOvRAQektoXtaMG) some new robotics skills with [Petoi Skill Composer](https://docs.petoi.com/desktop-app/skill-composer)&#x20;
   * Follow [C++ curriculum](https://www.petoi.com/pages/free-cplusplus-quadruped-robotics-curriculum) to code some Petoi robotics moves in C++
   * For Bittle/Bittle X, you may [3D-print this stand](https://github.com/PetoiCamp/NonCodeFiles/tree/master/stl/BittleStand) to make your robot not run around while you program it.
5. Work on some [quadruped robotics competition projects](https://www.petoi.com/blogs/blog/robot-competitions-with-petoi)

{% hint style="info" %}
Note that all the tutorials work on Bittle/Bittle X robot dogs and Nybble robot cat even though we use one particular robot pet as an example.
{% endhint %}

### FAQ

**Question:** I am confused by the product packaging and unsure if you sent me the right robot.

**Answer:** We reuse the packaging for Bittle and BIttle X.  If you order a Bittle but receive a package with “**Bittle X**” marking, or vice versa,  you can check the text label with the barcode.  That text identifies what’s inside the packaging.

Check [other FAQs](https://www.petoi.com/pages/faq) on our official website or [those](https://docs.petoi.com/technical-support/faq-frequently-asked-questions) in the Petoi Doc Center.<br>


# FAQ(Frequently Asked Questions)

## Bittle vs Bittle X

### The doc seems to refer to Bittle and Bittle X interchangeably.   Why is that?

Bittle and Bittle X are [from the same family](https://www.petoi.com/pages/bittle-smart-robot-dog-model-overview) and share a lot of common things. But Bittle X uses BiBoard, and Bittle uses NyBoard.  So we just refer to Bittle most of the time without specifically mentioning Bittle X.

## The differences in mainboards

The differences in specifications of different mainboards are shown in the figure below:

<figure><img src="/files/lB8a2s6j5oiIeHhUrRQk" alt=""><figcaption></figcaption></figure>

## Sound

### What do different melodies from the board mean?

Please refer to the [**Buzzer beep meaning**](https://bittle.petoi.com/2-open-the-box#buzzer-beep-meaning)**.**

### How to adjust the buzzer volume?

* For NyBoard, please refer to [Mute/Unmute the buzzer beep](https://bittle.petoi.com/2-open-the-box#mute-unmute-the-buzzer-beep).
* For BiBoard, please refer to [Adjust the buzzer volume](https://bittle-x.petoi.com/2-open-the-box#adjust-the-buzzer-volume).

## Software

### BiBoard can not upload firmware on Windows OS.

The following error message appears when uploading firmware:

```
Serial port COM*:
Connecting.............................
COM* failed to connect: Failed to connect to Espressif device： Wrong boot mode detected(0x13)
A fatal error occurred: Could not connect to an Espressif device...
```

Please first check whether the serial port is correct in **Device Manager.** If the serial port is correct,

Especially for **Windows 11** computers with **AMD** CPUs, please try **one** of the following two methods:

* **Connect using a USB hub**<br>

  <figure><img src="/files/hluIRUQgKNg61mqps9B0" alt=""><figcaption></figcaption></figure>

* **Physically "force" into mode**：

  You can intervene manually: Due to potential delays in switching DTR/RTS signals (automatic reset circuit) under Windows, the AMD chipset may experience automatic...

  1. Click the "Download/Flash" command in the terminal or burning software.
  2. When the screen displays "Connecting...:

  · Press and hold the **BOOT** button on the board.

  · Briefly press the **RESET** button and release.

  3. Continue holding the **BOOT** button until you see the progress bar start scrolling (Packet content...), then release.

### When using the mobile app, I found that my Petoi robot was walking very slowly.&#x20;

Try turning off the Gyro in the [mobile app](https://guide.petoi.com/mobile-app/controller#gaits),  as shown in the following picture:

<figure><img src="/files/XJ2aDZx8blxvKQMiGAcf" alt=""><figcaption></figcaption></figure>

### When using the mobile app, my Petoi robot can't self-right after it's upside down.

Try turning on the Gyro in the [mobile app](https://guide.petoi.com/mobile-app/controller#gaits),  as shown in the following picture:

<figure><img src="/files/9pF7ls3jEZ9dkcIxsVyf" alt=""><figcaption></figcaption></figure>

### My Petoi robot doesn't walk very stably.

* Make sure you [calibrate](https://bittle.petoi.com/6-calibration) the joints with the included L-shaped tuner and understand the references
* Remove the rubber toe covers
* [Turning off the Gyro](#when-using-the-smartphone-app-i-found-that-bittle-was-walking-very-slowly.) will make slow gaits more stable
* You may need to use the Petoi Desktop App -> Tools -> calibrate gyroscope to reset the gyroscope.

### When I use the play dead command with the mobile app, my Petoi robot seems to be stuck in a forever loop trying to play dead again and again.

There's a known bug in one of the older firmware.  Please [upgrade to the latest firmware](/desktop-app/firmware-uploader).

### The robot servos don't seem to be working.  How to debug the servos?

<figure><img src="/files/uoxrGjQmjS3E3UCtsZyt" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
\[1]. [Re-upload the firmware](/desktop-app/firmware-uploader)

\[2]. [Calibrate the PWM signal](https://guide.petoi.com/arduino-ide/upload-sketch-for-nyboard#id-9.-calibrate-the-servo-controller-chip-pca9685-on-the-nyboard)

\[3]. [Swap the pin definitions](https://guide.petoi.com/arduino-ide/upload-sketch-for-nyboard#id-12.-modify-the-joint-pin-mapping)
{% endhint %}

### NyBoard can't upload firmware

The error that occurs when uploading the sketch is shown below:

![](/files/mZregacj3hcviwdowg34)

<figure><img src="/files/eUfnhqzxlwb8e4Hb8Ivk" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
\[1]. Do the simple checks as follows:

* Make sure there's no other program using the serial port, If you have opened the Arduino IDE and its serial monitor, it may occupy the serial port.
* Make sure the uploader is connected to the NyBoard [in the right way](https://guide.petoi.com/communication-modules/usb-downloader-ch340c#connect-nyboard).
* Make sure you're using the USB cable that comes with the kit, some USB cables may only have two wires for powering, but no data wires.

\[2]. For this operation, you can use a simple test sketch for convenience.&#x20;

* With the Petoi Desktop App, select the microcontroller type: **NyBoard\_V1\_\***, then you can upgrade the **Standard** firmware.
* With Arduino IDE, select the microcontroller type: **Board-> Arduino AVR Boards-> Arduino Uno**, then you can upload the sketch: **File-> Examples->04.Communication->ASCIITable.**

\[3]. Install [the USB uploader driver](https://guide.petoi.com/communication-modules/usb-downloader-ch340c#the-drivers).

\[4]. [Reset the bootloader](https://guide.petoi.com/technical-support/burn-bootloader-for-nyboard).
{% endhint %}

### Why are there two calibration stages?

There are two calibration steps for different components.

Because the controller board has limited resources, we divide the program into two stages.

In the first stage, we upload the program and large data to the onboard EEPROM (hard disk) and use the remaining programming space to calibrate the IMU, a sensor that measures the body orientation. The board should be leveled and untouched during the (IMU) calibration.

In the second stage, we upload the standard functional code. For the first-time configuration, we need to enter the (joint) calibration state and attach the legs in the right direction.

If you use the Arduino IDE to set up the board, you will handle those stages explicitly. The Petoi Desktop App can finish the two-stage uploading in the background. The mobile app can work only with an already configured board. Its (joint) calibration is only for attaching the legs.

### If I buy the pre-assembled Bittle, does it still need to be calibrated?

If your robot doesn't walk very stably, you may need to use the Petoi Desktop App/Petoi Mobile app/Arduino IDE [to fine-tune the joints](https://bittle.petoi.com/6-calibration).

### If I buy a microcontroller such as NyBoard or BiBoard alone, do I have to buy a separate software program to make it work?

Our microcontrollers are specifically designed for our robots. The open source code is free to use and can be downloaded from [GitHub](https://github.com/PetoiCamp).

### Could Python be used to control any Petoi robot?&#x20;

You can [use Python to control any Petoi robot](https://guide.petoi.com/apis/python-api). The scripts can send commands from your computer to your robot via a wired or Bluetooth connection.&#x20;

### Can your robot (Bittle / Nybble) function on its own? Or does it only work with the commands I give it? Also, can it learn?

It follows your instructions via the mobile app or desktop app. It can also perform random behaviors if you [enable the random mode](https://www.youtube.com/watch?v=nHLkE74Q3k8). Best of all, the program is open source on GitHub, and you can refer to the relevant programming sections in your robot guide to create new skills for your robot.

### When running the Petoi Desktop App in MacOS14.1 (Sonoma), the buttons are not responsive. How to solve this problem?

This is due to the incompatibility of the Python Tk library with MacOS. The temporary solution is that you can press the button and drag the mouse slightly at the same time.

### How to set up Arduino IDE on ChromeOS (for Chromebook)

Please check [this page](/arduino-ide/install-arduino-ide-on-chromebook).

### Unable to find the OpenCat library

If you have downloaded and unzipped the OpenCat folder but see the following error:

```
OpenCat:82:10: fatal error: src/OpenCat.h: No such file or directory 
#include "src/OpenCat.h" 
        ^~~~~~~~~~~~~~~
compilation terminated.
```

You should rename the unzipped **OpenCat-main** folder to **OpenCat** so that the **OpenCat.ino** matches the root name.&#x20;

For more information, please refer to:&#x20;

<https://guide.petoi.com/arduino-ide/upload-sketch-for-nyboard#setup-process>

\
BTW, you can upload [the firmware via the Petoi Desktop App](/desktop-app/firmware-uploader).&#x20;

### I'm on Windows 11 and cannot find the robot in the Bluetooth device list

Try to set "Bluetooth devices discovery" to "Advanced" as follows:

<figure><img src="/files/mMQ0GlY6DLgjlSwR9sUM" alt=""><figcaption></figcaption></figure>

### How to install the CP210x driver on Windows for BiBoard V0?

In the **Device Manager**, if you open the Other devices list, you may see a CP210X device with a triangle exclamation sign. Right-click it to find the "update driver" option, then select the enclosing folder of your [downloaded driver to install](https://guide.petoi.com/technical-support/useful-tools).

<figure><img src="/files/OZ69OZ4b4QMvP4iC5DAu" alt=""><figcaption></figcaption></figure>

### When I use the mobile App to connect to the robot, it indicates "The device doesn't seem to be a Petoi robot".

When connecting, the app will send handshake signals to the robot, and the robot should be running the firmware in standard mode to respond correctly. If the app returns a "not Petoi robot" error, it's probably due to a firmware issue. Please follow this debugging process:

<figure><img src="/files/EK9IzkmM3iE5dTTIjI8g" alt=""><figcaption></figcaption></figure>

\[1]. Please check the version of the app as follows:

<figure><img src="/files/FoTqVVytBF4biXbX28L0" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/IhFmJ71FCrhuedIgosMU" alt=""><figcaption></figcaption></figure>

* App Store

<figure><img src="/files/Bnj01w8am0bOPEOTSOwm" alt=""><figcaption></figcaption></figure>

* Google Play

<figure><img src="/files/8NQPGHLtFPAwEZIKyCQ4" alt=""><figcaption></figcaption></figure>

\[2]. For the startup melody in normal mode, please refer to **00:13** in the video below:

{% embed url="<https://www.youtube.com/watch?v=DrSsbd84ryo>" %}

For how to open the serial monitor and input the serial command, please refer to:

* [BiBoard](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.6-connect-to-biboard-via-usb-type-c-data-cable)
* [NyBoard](https://guide.petoi.com/arduino-ide/upload-sketch-for-nyboard#id-6.-open-the-serial-monitor)

\[3]. You can upgrade the firmware via the [Petoi Desktop App](https://guide.petoi.com/desktop-app/firmware-uploader).

For NyBoard, if the firmware can not be upgraded, please refer to [NyBoard can't upload firmware](https://guide.petoi.com/faq-frequently-asked-questions#nyboard-cant-upload-firmware).

## Hardware

### Does it come with a battery, or do I have to buy a separate battery?

All Petoi robot packages include one rechargeable Li-On battery and a USB data/charging cable.  You can use any regular USB (phone) charger for charging.  You may get more [spare batteries](https://www.petoi.com/products/li-ion-battery-for-petoi-robot-pets).

### My robot battery isn't charging.  What's going on?

The battery charging port is on the battery, NOT on the microcontroller.  Please make sure you connect the USB cable to the right port.  Please check [the battery guide](/technical-support/battery) for more details.

### How can I easily install the springs into the upper legs of Bittle?

### Does it come with a battery, or do I have to buy a separate battery?

All Petoi robot packages include one rechargeable Li-On battery and a USB data/charging cable.  You can use any regular USB (phone) charger for charging.  You may get more [spare batteries](https://www.petoi.com/products/li-ion-battery-for-petoi-robot-pets).

### My robot battery isn't charging.  What's going on?

The battery charging port is on the battery, NOT on the microcontroller.  Please make sure you connect the USB to the right port.  Please check [the battery guide](/technical-support/battery) for more details.

### How can I easily install the springs into the upper legs of Bittle?

Please check out [the forum](https://www.petoi.camp/forum/basic-assembly-and-setup/just-got-my-bittle-kit-can-t-install-springs) post discussing installing springs with various tools.  Or you can [request](https://www.petoi.com/pages/contact-us) Bittle upper legs with pre-installed springs

### I can't find the toe covers. What are the toe covers for?

The toe covers are for special experiments that require more friction. They are not required for regular walking and performance. We have removed them from the standard kit recently, and you may order them as optional accessories.

### Some frame structures are broken. Where can I get replacement parts?

You may [contact us](https://www.petoi.com/pages/contact-us). Show the picture of the broken pieces and explain how they broke. You may find the [3D-printable files](https://github.com/PetoiCamp/NonCodeFiles/tree/master/stl) or get a replacement directly from us.

### Bittle's neck is loose and may fall accidentally. How can I reinforce the connection?

Please refer to Bittle's instructions in [Final Assembly.](https://bittle.petoi.com/7-final-assembly#7.1-head)&#x20;

### Where can I get the bone shown in Bittle's picture?

The little bone is included in the [Intelligent Camera Module](https://guide.petoi.com/extensible-modules/mu-camera) box, and it is not being sold separately. You may download [its 3D-printable file](https://github.com/PetoiCamp/NonCodeFiles/tree/master/stl/Bittle%20%26%20BittleX/Bittle_bone) to print one.

### Does Raspberry Pi require any additional components?

You can solder the 2x5 socket on the NyBoard and then mount the Raspberry Pi on the NyBoard.&#x20;

Read more at:

<https://guide.petoi.com/apis/raspberry-pi-serial-port-as-an-interface>

### Quick fix of the servo motor engagement

In some cases, the motor's output gear may disengage from the gear. It will result in an abnormal buzzing sound inside the servo. You can take off the bottom of the servo and push the motor inward very hard until you hear a clicking sound.&#x20;

<figure><img src="/files/CHHlKstdfQDfXJjyQ6h1" alt=""><figcaption></figcaption></figure>

### The camera module can't work after being connected to the BiBoard extension hat.

Please refer to the FAQ section on [the MU camera](/extensible-modules/mu-camera).

### The serial port can't be found when I use a USB type-C data cable to connect the BiBoard to the computer.&#x20;

Turn off the battery's power to see if the serial port can appear. Please refer to [Connect to BiBoard via USB type-C data cable](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.6-connect-to-biboard-via-usb-type-c-data-cable).

## Resources and links

### Driver for CH340 USB uploader

* Mac: <http://www.wch-ic.com/download/CH341SER_MAC_ZIP.html>
* Windows: <http://www.wch-ic.com/downloads/CH341SER_EXE.html>

### Can I use block-based coding with any Petoi robot?  Do I need to purchase add-on components/modules?

You can use [Petoi Coding blocks](https://guide.petoi.com/block-based-programming/petoi-coding-blocks) to do Scratch-like block-based programming with all of Petoi robots.&#x20;

There's nothing else to purchase.

<figure><img src="/files/66q0PzWr4lMILFgqebdY" alt=""><figcaption></figcaption></figure>


# Bittle X V2

**Bittle X V2** is an open-source, voice-controlled robot dog. It's a new breed of robotics dog for everyone to learn and play with.

<figure><img src="/files/8TL9MEKJq9zfKvGbPhpm" alt=""><figcaption></figcaption></figure>

The small but mighty robot has these amazing features:

* Respond to voice commands, performing over **35 predefined actions** such as sit, push-up, and backflip with high-performance, lifelike movements. You can switch between English and Chinese using simple voice commands.&#x20;
* Can be programmed with **10 more customized voice commands** to perform skills you create. The voice command can be any sound, so it is not necessary to be mapped to any spoken language.&#x20;
* Support  **Petoi** **Coding Blocks and Petoi Web Coding Blocks(block-based Scratch-like), C++, and Python**.
* **Free** [C++](https://www.petoi.com/pages/free-cplusplus-quadruped-robotics-curriculum) and [Petoi Coding Blocks](https://www.petoi.com/pages/free-quadruped-robotics-curriculum-scratch-coding)(block-based Scratch-like) **curriculums**.
* Equipped with BiBoard V1, a high-performance **ESP32** development board supporting additional modules for robotics/AI/IoT applications.
* Support feedback servos for easy robotics skill creations
* Built-in gyroscope and back touch sensor for intuitive human-robot interactions.

If you have questions about “why” rather than “how”, please post on [our forum](https://www.petoi.camp/) or [contact us](https://www.petoi.com/pages/contact-us).

{% hint style="info" %}
There are some [supporting applications and software](https://docs.petoi.com/technical-support/supporting-application-and-software) and [FAQ](https://docs.petoi.com/technical-support/faq-frequently-asked-questions) for your reference.
{% endhint %}

You can support us by shopping at [Petoi Coding Robot Shop](https://www.petoi.com/store).

Our social media (Instagram/Twitter/Facebook/GitHub) account is **@PetoiCamp**.&#x20;

Share your build by tagging **#bittle\_x #petoi #opencat** so that we can repost it for you!&#x20;


# Quick Start Guide

The **Quick Start Guide** section is primarily designed to help you verify that the product is complete after receiving it and to enable you to quickly boot up and use the robot. It includes three parts:&#x20;

1. [**Unboxing**](/product/bittle-x-v2/quick-start-guide/unboxing)
2. [**Assembling (for construction kit version only)**](/product/bittle-x-v2/quick-start-guide/assembling)
3. [**Boot up**](/product/bittle-x-v2/quick-start-guide/boot-up)

**Need help?** Check out our [**FAQ**](/faq-frequently-asked-questions).


# Unboxing

## Check the packaging

Thank you very much for purchasing our product! We highly value your user experience and hope you can begin this enjoyable journey smoontly. To ensure the device was not damaged during transportation and to guarantee all accessories are complete, we recommend that you follow these steps after receiving the package:

1. Please verify the recipient's name, address, order number, and other information on the product packaging to ensure it matches your order. If any information is incorrect, please do not open the box and [contact us](https://www.petoi.com/pages/contact-us) immediately.
2. Please inspect whether the packaging box is intact and undamaged, and whether there are any obvious signs of damage, dampness, deformation, or tampering. If you find any damage to the packaging box, please take photos for evidence and, before confirming the device is intact, avoid signing for or opening the box. As shown in the figure below, the robot kit you receive should have an intact appearance, be free of any damage, and remain clean and tidy.
3. If you are unsure whether you've received the correct package, please refer to [this guide](https://www.petoi.com/blogs/blog/how-to-tell-if-you-have-received-the-correct-bittle-bittle-x-robot-dog).

<figure><img src="/files/caIo0uiFqHJFKArRad6t" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/QM5exwOOEkuHrYQ6aYby" alt=""><figcaption></figcaption></figure>

## Open the box

### Pre-assembled package

<figure><img src="/files/7An606MNDAhMv5SVXmxT" alt=""><figcaption></figcaption></figure>

### Construction package

<figure><img src="/files/Ie50uxn3NXisuI2L6U7o" alt=""><figcaption></figcaption></figure>

## Package Item List

### Pre-assembled version

<table><thead><tr><th width="442.84320068359375">Name</th><th>Quantity</th></tr></thead><tbody><tr><td>Main Unit: Bittle X robotic dog</td><td>1</td></tr><tr><td>Assembly Components: Calibrator part</td><td>1</td></tr><tr><td>Manual: Stickers/Postcard (with voice commands on the back)/Calibrator manual</td><td>1</td></tr><tr><td>Tools: Self-tapping screwdriver/USB cable</td><td>1</td></tr><tr><td>Spare Parts: Spare servo/Raspberry Pi mount/Springs &#x26; screws</td><td>1</td></tr></tbody></table>

#### Install the neck

Align the neck with the matching slots on the body, insert the back end first, then press down the front until you hear a *click*.\
The neck should fit tightly with the body while allowing easy removal if it’s hit. Simply snap it back in place if it becomes detached.

<figure><img src="/files/0AtuDA07XVgtqJR2sg61" alt=""><figcaption><p>Install the neck</p></figcaption></figure>

#### Assemble the Optional Bittle Stand

We have designed a dedicated support stand to ease Bittle family robot debugging and avoid falls. Please assemble the stand as shown in the illustration. Afterward, carefully place the robot onto the stand. Small clasps are present to provide a more secure connection between them.

<figure><img src="/files/7lrmMsIHyfbydDJMahl2" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/0Uc8dALIg55A2PeklJ2C" alt=""><figcaption></figcaption></figure>

#### Battery

When the battery is low (indicated by a red LED on the battery), the battery must be detached from the body.

The battery connects to the body chassis via a latched sliding slot. To detach it, push the battery horizontally along the slot's direction.

<figure><img src="/files/NFwmvZ2QEYcsCVGyi7GL" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Note:&#x20;

Attaching the battery and detaching the battery are reverse processes.

Please ensure that the battery's charging port aligns with the direction of the robot's head to better balance its body during movement.

![](/files/QqzvxEfll2rCzAPOXi8D)
{% endhint %}

#### Back cover

<figure><img src="/files/UbY3Gl9dIdnji8IRNc6h" alt=""><figcaption><p>open the back cover</p></figcaption></figure>

#### The touch sensor inside the back cover

For the Bittle X V2 with BiBoard V1, there is a flexible printed circuit (FPC) attached to the inside of the back cover for touch functionality. Under normal circumstances, there is no need to remove it. If you wish to detach the back cover FPC from the microcontroller completely, please follow these steps:

After opening the back cover, note the relative orientation between the microcontroller (BiBoard V1) and the back cover. There is a flip tab on the connector - lift this tab upward. Once the tab is flipped open, the cable beneath it can be fully detached along with the back cover and microcontroller.

Reconnecting the cable to the mainboard is the reverse process: align the cable, ensuring proper orientation, and press it firmly into place.

<figure><img src="/files/pVHGaiCKrXrRLuIqHzJo" alt=""><figcaption></figcaption></figure>

### Construction version

<table><thead><tr><th width="592.2374267578125">Name</th><th>Quantity</th></tr></thead><tbody><tr><td>Main Frame: Body/Neck/Head/Upper Leg (pre-assembled x4)/Lower Leg Piece (x4)</td><td>1</td></tr><tr><td>Assembly Components: Calibrator part</td><td>1</td></tr><tr><td>Servo: P1S servo with long cable x5/P1S servo with short cable x5</td><td>10</td></tr><tr><td>Electronics: BiBoard V1 (ESP32)/Rechargeable Battery/USB Cable</td><td>1</td></tr><tr><td>Tools: Self-tapping screwdriver/M2*8 screws</td><td>1</td></tr></tbody></table>

After verifying all components listed above, please proceed to the [Assembly Guide](https://guide.petoi.com/product/bittle-x-v2/quick-start-guide/assembling) for detailed assembly instructions. You will learn more about the robot's design and structure through the assembly process.


# Assembling

"The whole is more than the sum of its parts." 🔩

## Item list

### Construction kit

<table><thead><tr><th width="592.2374267578125">Name</th><th>Quantity</th></tr></thead><tbody><tr><td>Main Frame: Body/Neck/Head/Upper Leg (pre-assembled x4)/Lower Leg Piece (x4)</td><td>1</td></tr><tr><td>Assembly Components: Calibrator part</td><td>1</td></tr><tr><td>Servo: P1S servo with long cable x5/P1S servo with short cable x5</td><td>10</td></tr><tr><td>Electronics: BiBoard V1 (ESP32)/Rechargeable Battery/USB Cable</td><td>1</td></tr><tr><td>Tools: Self-tapping screwdriver/M2*8 screws</td><td>1</td></tr></tbody></table>

After verifying all components listed above, please proceed for detailed assembly instructions. You will learn more about the robot's design and structure through the assembly process.

Watch the Bittle [assembly animation ↗](https://youtu.be/G2RDNbek7CQ) for a quick overview.  Then follow the following video to build Bittle X V2 from the construction kit

{% embed url="<https://youtu.be/A2RM1tplOtM>" %}

### Neck

{% hint style="info" %}
Required parts:

* Neck × 1
* Servo arm × 1
* M2x8 sharp-end self-tapping screws × 2

<img src="/files/hUuTtTwsZJn0KPj2hwtJ" alt="" data-size="original">
{% endhint %}

Put the servo arm in the neck part like the figure below. The teeth of the servo arm should face upward.

{% columns %}
{% column %}

<figure><img src="/files/57iJbTmDGgEg1KaCELQ1" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/Vmwou2ZAGexk2F04vcOo" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Screw two M2x8 self-tapping screws beside both sides of the servo arm. Don't over tighten the screws.

{% columns %}
{% column %}

<figure><img src="/files/nUVauUSCy5DAqxuMXDPF" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/o1c0lkcKeG7ylOvzj4m8" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% hint style="success" %}
Your neck assembly should look like this:

![](/files/vOfKel5bNDZwajunVwrU)
{% endhint %}

### Body

{% hint style="info" %}
This part is now fully assembled in the package.

**Includes：**

* Assembled neck × 1
* Chasis × 1
* Front and back plate × 2
* Side shoulder × 2

![](/files/Vap6eJcMKChq4DFMh5cp)
{% endhint %}

Recognize the front and back side of the chassis. The location of the two large holes along the center track makes a difference. In our standard configuration, we define the holes to be shifted towards the tail. You can also find a small mark "A1" in the front of the chassis.

{% columns %}
{% column %}

<figure><img src="/files/ajF0l7VrRPVcEGLxyP7n" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/y4WIHo1gcUbDDIzQiVxG" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Push the back tip of the assembled neck into the slot of the chassis. Then press down the front hook until you hear a snap sound.

{% columns %}
{% column %}

<figure><img src="/files/WYbEu9MrgDfabVWq5irD" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/LwlKpVaRqsERPhTuASI4" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Insert the chassis into one of the side shoulders.

{% columns %}
{% column %}

<figure><img src="/files/E3wOllTOKHJtJ2e0EROI" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/8bLCcvvy5CFYKLaszMno" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Insert the front or back plate into the side shoulder. There are three tenons on each side of the plate. Insert the two front tenons as one group for better alignment.

{% columns %}
{% column %}

<figure><img src="/files/FWmSsM06nUAY1ixFuROR" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/qwPOUroX0CuBojpaBM38" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Insert both the front and back plates. Plug the other side shoulder to complete the body. Again pay attention to the alignment of the tenons of the front and back plates.

{% columns %}
{% column %}

<figure><img src="/files/8TFhET98TaGjTE3mJOJq" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/M4hJJM1NMsS7wC6A6rLR" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% hint style="success" %}
You body assembly should look like this:\
![](/files/Csdy0T1cjBiSRznAYvOa)
{% endhint %}

### Upper leg

{% hint style="info" %}
The upper leg has been pre-assembled in batches after 2022.   We leave it here in case you need to reassemble it.
{% endhint %}

<figure><img src="/files/JpqzkfXuyPY9ri1nyuy5" alt=""><figcaption></figcaption></figure>

This assembly is best demonstrated visually—check the [instruction video at 3:23 ↗](https://youtu.be/oJ2Y9hZgCEY?t=203) for the proper technique. Use finesse, not force! For more tips on installing springs with different tools, check out this [forum post ↗](https://www.petoi.com/forum/basic-assembly-and-setup/just-got-my-bittle-kit-can-t-install-springs).

### Lower leg

{% hint style="warning" %}
There are five servos with long cables and five servos with short cables. The lower legs all need servos with long cables.
{% endhint %}

{% hint style="info" %}
Required parts:

* P1S servo with **long** cable × 4
* Lower leg piece × 4
* M2x8 self-tapping screw × 8

<img src="/files/xYrLRgz5oThzWz4pofFD" alt="" data-size="original">
{% endhint %}

Assemble the right leg. Insert the servo into the window and route the wire through the notch on the internal edge. Refer to the tutorial video for the correct wire folding direction. Secure the servo to the lower leg with two M2×8 screws.

{% columns %}
{% column %}

<figure><img src="/files/nA1hDpAozmoOBhJkIa8O" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/KfcWVyqX9f6CRapBPS3x" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/8yTNIM0zGsBUxiw4hCHj" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

The left and right legs are built as mirror images, but the front and back legs are identical. You'll assemble two mirrored pairs of legs — one pair for the front and one pair for the back.

{% hint style="success" %}
One pair of legs should look like this:

<img src="/files/SxGxvXgp86kBjTOEPQBp" alt="" data-size="original">
{% endhint %}

### Head

If you purchase the head optionally, you can follow these steps:

{% hint style="warning" %}
There are five servos with long cables and five servos with short cables. The head needs a servo with a short cable.
{% endhint %}

{% hint style="info" %}
Required parts:

* P1S servo with **short** cable × 1
* Chin × 1
* Skull × 1
* M2x8 self-tapping screw × 2
  {% endhint %}

Put the servo in the chin as shown in the figure. Pay attention to the direction of the servo's wire. After that, install two M2x8 self-tapping screws.

{% columns %}
{% column width="8.333333333333332%" %}

{% endcolumn %}

{% column width="83.33333333333333%" %}

<figure><img src="/files/7WcJL8HdhKmYaIq4lY5b" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column width="8.333333333333321%" %}

{% endcolumn %}
{% endcolumns %}

Insert the skull into the chin so that it can rotate and bite on small gadgets. It is advisable to apply some lubricant to the contact points.

{% columns %}
{% column width="8.333333333333332%" %}

{% endcolumn %}

{% column width="83.33333333333333%" %}

<figure><img src="/files/j5iUBmOmWwZ7nf66GXN8" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column width="8.33333333333336%" %}

{% endcolumn %}
{% endcolumns %}

{% hint style="success" %}
Your head assembly should look like the figure above.
{% endhint %}

### Shoulder servo

{% hint style="warning" %}
There are five servos with long cables and five servos with short cables. The upper legs all need servos with short cables.
{% endhint %}

{% hint style="info" %}
Required parts:

* P1S servo with **short** cable × 4
* M2x8 self-tapping screws × 8
* Head (assembled)
* Body (assembled)
* Lower leg (assembled) × 4
  {% endhint %}

Put the head, body, servos, and lower legs like the figure below. Insert the short servo wires through the servo slots on the side shoulders. Pay attention to the direction of the servos carefully and place them in the correct configuration.

{% columns %}
{% column %}

<figure><img src="/files/i1slSlp1EmyN1q20Y6fY" alt=""><figcaption><p>Side view </p></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/9MOnK9FDUZvdDyLa1h60" alt=""><figcaption><p>Top view</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

You also need to insert the wire of the head servo into the body.

After confirming all the components ' directions, put the short wire servos into the side shoulders. Pay attention to the directions of the shoulder servos’ output shaft. The long wires of the lower leg servos should be inserted into the opening between the shoulder servo and the shoulder window. Use two M2x8 self-tapping screws to fix each should servo.

Repeat the above assembly for the hip servos.

{% columns %}
{% column width="16.666666666666664%" %}

{% endcolumn %}

{% column width="66.66666666666667%" %}

<figure><img src="/files/gaCNmnJbaZUP7wThkelB" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column width="16.66666666666665%" %}

{% endcolumn %}
{% endcolumns %}

{% hint style="warning" %}
Please note the direction of the shoulder servo:

![](/files/Fqckos38NuUuUsczOV8b)
{% endhint %}

### Connect wires

The connection between the joint servo and the pin is shown in the figure below：

<figure><img src="/files/OB0wIuzWao4IiTIUmkVy" alt=""><figcaption></figcaption></figure>

Please ensure the black wire (or the darkest wire - ground wire) is closest to the board and all the servos are connected to the correct sockets on the circuit board in the proper orientation.

{% embed url="<https://youtu.be/A2RM1tplOtM>" %}
Bittle X with BiBoard V1 assembly and wiring tutorial
{% endembed %}

### Battery

Insert the battery plug into the power socket under the body. Then place the battery in the direction shown in the figure below, aligning with the mounting holes:

{% columns %}
{% column %}

<figure><img src="/files/0VicFSZwbiKjAWJ8tBpO" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/w1QLnJWNQ1cBqfW1WsF9" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

The battery connects to the body chassis via a latched sliding slot. To detach it, push the battery horizontally along the slot's direction.

<figure><img src="/files/NFwmvZ2QEYcsCVGyi7GL" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Note:&#x20;

Attaching the battery and detaching the battery are reverse processes.

Please ensure that the battery's charging port aligns with the direction of the robot's head to better balance its body during movement.

![](/files/QqzvxEfll2rCzAPOXi8D)
{% endhint %}

{% hint style="success" %}
Press and hold the battery button for more than 3 seconds. If the red indicator light is on, charge the battery until the green light turns solid before use.\
Once powered on, the yellow and blue LEDs on the BiBoard will light up simultaneously.

<img src="/files/sojFNmpXxVKelOt4I5T0" alt="" data-size="original">
{% endhint %}

### Calibration required

{% hint style="warning" %}
After completing the assembly, you must calibrate the robot joints before use. Proper calibration ensures accurate movement and prevents damage to the servos.
{% endhint %}

➜ [\[Go to Joint Calibration\]](/quick-reference/joint-calibration)


# Boot up

## The posture before boot up

Drag the curly wire from the knee side to the shoulder side to avoid squeezing when the knee joints rotate. Put the joints into the following posture before turning on the power.

<figure><img src="/files/uxn1ywgOirr1rGixRBtB" alt=""><figcaption></figcaption></figure>

## Power

Long-press the battery button for 3 seconds to turn on/off. You will hear a short melody, and the battery indicator will turn blue. If the indicator is red, please take a look at the [charging method ](/product/bittle-x-v2+arm/quick-start-guide/boot-up#charging)below.

{% hint style="info" %}
After turning on the battery, the robot requires approximately 5 seconds for initialization, after which a melody will play.

The robot's battery charge may decrease during storage and transportation. Please ensure the battery is fully charged when using it for the first time.

It is recommended that the robot be placed on the calibration stand before pressing the button to activate the battery (Optional).

If you use the robot on the floor, please ensure it's upright after activating the battery. Otherwise, upon start-up, it will continuously attempt to flip itself over or perform other corrective motions.

If the robot is placed on its side when powered on, it will automatically initiate the calibration posture.
{% endhint %}

### Battey Indicator

Before you use it, please read the instructions on the bottom of the packaging box carefully to check the battery.  Note that the battery charging port is on the battery, not on the robot's microcontroller.

<figure><img src="/files/fjYJVm8NDbU2KTSSw6ID" alt=""><figcaption><p>            Low Power                                                          Full Power                                                   Intermediate Power</p></figcaption></figure>

\
During charging, the indicator light turns <mark style="color:red;">red</mark>; after charging is complete, it turns <mark style="color:green;">green</mark>.\
Press the blue button briefly to check the battery status:

· When fully charged, short-press the button on the battery, the indicator light is <mark style="color:blue;">blue</mark>.

· When the voltage is low, the indicator light is <mark style="color:red;">red</mark>.

· During battery depletion, the indicator color gradually changes from blue to red.

Note the correct use of battery interfaces: use the Type-C interface for charging, and the 2P 2.54 mm red-black wire terminal interface to connect to BiBoard and power the robot. Please don't mix them up.

If the robot detects a low battery, it will pause its movements and beep. You must detach and charge the battery using a standard 5V USB Type-C interface data cable. The battery will automatically stop supplying power to the robot during charging for safety reasons.

## Buzzer Sound Types

<table><thead><tr><th width="181.00006103515625">Sound</th><th width="246.2000732421875">Trigger Timing</th><th>Indication</th></tr></thead><tbody><tr><td>Short melody [1]</td><td>Power on or restart </td><td>The program startup was successful</td></tr><tr><td>Short beep</td><td>During use</td><td>The Program received a command</td></tr><tr><td>Repetitive melody [2]</td><td>During pauses in use or action</td><td>Low battery or battery not connected</td></tr></tbody></table>

{% hint style="warning" %}
Note: Please **ignore** the microcontroller type used in the video; the buzzer sounds and their interpretations are relevant to all Petoi robot models.
{% endhint %}

{% embed url="<https://youtu.be/DrSsbd84ryo>" %}
Buzzer sounds
{% endembed %}

\[1]. The startup melody in normal mode starts at **00:13** in the video below.

\[2]. The repetitive melody starts at **00:21** in the video below.

## Other Situations

### Charging

The robot's battery socket has limited dimensions, so when the battery is installed on the battery seat, it cannot be directly charged via USB. The battery needs to be detached from the battery socket before charging.

{% hint style="info" %}
Before charging, please turn off the battery (long-press the battery button for 3 seconds). After connecting the charging cable, the battery will automatically shut down (cease external power supply).
{% endhint %}

{% hint style="warning" %}
Please do not confuse the microcontroller's upload port with the battery charging port.
{% endhint %}

### Device Freezing or Unresponsive <a href="#device-freezing-or-unresponsive" id="device-freezing-or-unresponsive"></a>

There are two solutions：

1\. Check the battery indicator light. If the battery level is too low, please charge it immediately.

2\. If the battery level is normal, remove the back cover and press the reset button on the motherboard next to the LED logo to reboot the robot.

<figure><img src="/files/MIfRvJSIAfsxEiYtOZga" alt=""><figcaption></figcaption></figure>


# Control & Programming

### Control

* Voice Command
* [Mobile App](/product/bittle-x-v2/control-and-programming/mobile-app)
* [Optional Joystick Controller with Micro:Bit](/product/bittle-x-v2/control-and-programming/joystick-with-micro-bit)

### Set up & Build Robotics Skill Visually

* [Petoi Desktop App](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-desktop-app)

### Programming

* [Petoi Web Coding Blocks](/petoi-web-coding-blocks/get-started-create-your-first-block-program)
* [Petoi Coding Blocks](/product/bittle-x-v2/control-and-programming/petoi-coding-blocks)
* [Python](/apis/python-api)
* [C++](/apis/c++-api) on [Arduino IDE](/product/bittle-x-v2/control-and-programming/arduino-ide)
* [Play with feedback servos](/apis/serial-protocol/feedback-servos)
* [Sensor & module programming](/extensible-modules/introduction)
* Various application project demos(see the Applications section on the sidebar)
* Various APIs for advanced users(see the APIs section on the sidebar)

### Curricula

Here are [all the free Petoi curricula](https://bit.ly/petoicur) and [some curricula developed by our community](https://www.petoi.com/blogs/blog/tagged/showcase+curriculum).

### Video tutorials

* [Petoi Skill Composer](https://www.youtube.com/playlist?list=PLHMFXft_rV6MTs8HMxSOvRAQektoXtaMG)
* [Desktop block-based coding tutorial](https://www.youtube.com/playlist?list=PLHMFXft_rV6POrzm8O12Nybdy1-FS1ymg)
  * Note that some of the videos may have been developed by older Petoi robots.  So the setup may be different.  But the programming concept can still apply.&#x20;
* [Advanced tutorials](https://www.youtube.com/playlist?list=PLHMFXft_rV6MWNGyofDzRhpatxZuUZMdg)

### Project ideas

* Get inspired by [Petoi user projects](https://www.petoi.com/blogs/blog/tagged/showcase)
* Work on some [quadruped robotics competition projects and ideas](https://www.petoi.com/blogs/blog/robot-competitions-with-petoi)
  * Every fall, we host [Petoi robotics contests](https://www.petoi.com/blogs/blog/tagged/contest-winners). We'd love to see you!


# Mobile App

📱🤖

Thanks for choosing Petoi's robot. This guide will help you set up your robot buddy and provide a simpler UI to calibrate the joints, control the robot, and program it. For advanced users, we recommend you keep the robot updated with the [OpenCat(for NyBoard)](https://github.com/PetoiCamp/OpenCat) / [OpenCatEsp32(for BiBoard)](https://github.com/PetoiCamp/OpenCatEsp32) firmware on GitHub for the best compatibility and the newest features.&#x20;

## Download and installation

The app works on both Android and iOS devices.

* [iOS 11+](https://apps.apple.com/us/app/petoi/id1581548095)
* [Android 4.4+](https://play.google.com/store/apps/details?id=com.petoi.petoiapp)

#### APK

For Android, you can also download the APK and install it on your phone.&#x20;

* The universal version(try this one first)\
  [v1.4.1-40-2-20251022-app-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-release.apk)
* The **v8a** version of the app mainly supports most of the current new mobile phone models\
  [v1.4.1-40-2-20251022-app-arm64-v8a-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-arm64-v8a-release.apk)
* The **v7a** version of the app is compatible with older mobile phone models\
  [v1.4.1-40-2-20251022-app-armeabi-v7a-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-armeabi-v7a-release.apk)
* The **x86\_64** version of the app indicates that the APK is designed for Android devices using Intel or AMD 64-bit processors. This means the APK contains native code libraries optimized for the x86\_64 architecture, designed to improve performance and compatibility.\
  [v1.4.1-40-2-20251022-app-x86\_64-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-x86_64-release.apk)

{% hint style="info" %}
If the connection panel in the App shows a blank Bluetooth connection list, first check whether you have granted the App Bluetooth and location permissions. If it still shows a blank list, try to install the previous stable version. \
[v1.4.0-37-1-app-release-20251006.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.0/v1.4.0-37-1-app-release-20251006.apk)
{% endhint %}

![](/files/G1cSapHMlJK9sDQ53TMN)

## Connect to the robot

For the mainboard BiBoard, the Bluetooth module is already built into the ESP32 module; you just need to power on the robot by long-pressing the button on the battery.

{% hint style="warning" %}
The app will send a greeting to the Bluetooth device and expect a response from the robot. You must upload the OpenCat (for NyBoard) / OpenCatEsp32 (for BiBoard) firmware to your robot before connecting to the app. Otherwise, the app will consider it "not a Petoi device". A pre-assembled robot should already have the firmware installed. Otherwise, you'll need to upload firmware using the [Petoi Desktop app](https://guide.petoi.com/desktop-app/firmware-uploader).&#x20;
{% endhint %}

{% hint style="warning" %}
For BiBoard, please ensure the program enters the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization)**.**
{% endhint %}

Open the app and scan available Bluetooth devices. **Don't connect the robot with the phone's system-wide Bluetooth settings!** Connect the device with the name Bittle, Petoi, or OpenCat.&#x20;

Please remember to enable Bluetooth and give the app access to it. On some devices, you may also need to allow the app's location service, though we are not using any of that information.

{% hint style="info" %}
On some Android OS, you need to activate the location service as follows:![](/files/tu2Vwheh7gELyuRGt2ZJ)
{% endhint %}

![](/files/-MjZWU2EpJOmFcBOEKGH)

The app will open the Control Panel interface when Bluetooth is connected. If the robot doesn't respond or malfunctions later, press the reset button on the mainboard to restart the robot.

The app should automatically detect the supported robot type based on the latest firmware. Otherwise, it will show the selections for the robot type. The above interface can also be revisited by selecting the option "Select a robot" in the control panel.

![](/files/FG3i4k9cmd0KgFjfCaYH)


# Calibrator

## The rationale for calibration

### Understand the zero state and the coordinate system

After the robot [enters the calibration state](#enter-the-calibration-state), with all servos rotated to their zero angles, attach the head, tail, and legs prepared in the previous section to the body. They are generally perpendicular to their linked body frames.&#x20;

<figure><img src="/files/s84JN6ZSNOe6iC01ubet" alt=""><figcaption><p>Bittle's Calibration Mode</p></figcaption></figure>

For the construction kit, please install the servo-related components as shown in the picture (calibration mode) and ensure they are perpendicular to each other (the upper leg is perpendicular to the torso, and the lower leg is perpendicular to the upper leg).

{% hint style="warning" %}
Note: Insert the servo-related components directly into the servo output shaft; do not turn the output shaft during this process.
{% endhint %}

Rotating the limbs counterclockwise from their zero states will be positive (the same as in polar coordinates). Viewed from the left side of the robot's body, the counter-clockwise rotation of the joint is defined as the positive direction.

{% hint style="info" %}
The only exception is the head tilt angle for Nybble. It’s more natural to say head up, while it’s the result of rotating clockwise.&#x20;
{% endhint %}

{% hint style="info" %}
However, from the right side of the robot's body, the rotation directions' positive and negative are just opposite.
{% endhint %}

### Discrete angular intervals

If we look closer at the servo shaft, we can see it has a certain number of teeth. That’s for attaching the servo arms and avoiding sliding in the rotational direction. In our servo sample, the gears divide 360 degrees into 25 sectors, each taking **14.4** degrees(offset of -7.2\~7.2 degrees). That means we cannot always get a perfect perpendicular installation.&#x20;

![](/files/v400iIvlmpXjiobnloRS)

## Calibration Interfaces

{% hint style="info" %}
Bittle, Bittle X, and Bittle X+Arm use the same calibrator interface and process. You can **ignore** the **mainboard type** in the following pictures.
{% endhint %}

The calibrator interface for Bittle is as follows:

![Calibration Interface](/files/-MjZW3to7df6RE8rV5V7)

{% hint style="info" %}
These interfaces will be displayed when you calibrate for the first time. You can also click to open the upper-right menu in the control panel and select **Calibrate** to re-access.

![](/files/JK6QL4MkFti57WTk401r)<br>
{% endhint %}

## Enter the calibration state

After the battery powers on the robot, follow the next steps to enter the calibration mode.&#x20;

* Click the **Start Calibration** button.<br>

  <figure><img src="/files/GwH4B1KbYFIOhQPudrrF" alt=""><figcaption></figcaption></figure>
* Click the **Calibration** button in the calibration interface.<br>

  <figure><img src="/files/FCRxFXfNFSFOIpN7HZWo" alt=""><figcaption></figcaption></figure>

**After** the robot enters the calibration mode, for the construction kit, do the following steps:

{% hint style="info" %}
The pre-assembled robot has already had its joints calibrated, so there is no need to disassemble the joints for further calibration.
{% endhint %}

### Install the neck servo

In the calibration mode, place the head as close to the central axis as possible and insert its servo shaft into the neck's servo arm.

<figure><img src="/files/avQ8YXT0jNhmIiW2oPIy" alt=""><figcaption></figcaption></figure>

Press down on the head so it is firmly attached to the neck.

<figure><img src="/files/Ux0zFualAZghlx3qphHi" alt=""><figcaption></figcaption></figure>

### Install the legs&#x20;

Install the upper leg and lower leg components to the output teeth of the servos when the Bittle is powered on and in the calibration mode. Please keep the torso, upper leg, and lower leg installed vertically as much as possible. Pay attention not to install the lower leg backward (the correct orientation is shown in the picture below).

<figure><img src="/files/5JHkO04jxSvTH1ySJJRy" alt=""><figcaption></figcaption></figure>

### **Use the included L-shaped tool as a reference**

![](/files/hwBOViu4Z8HHD76rSsjT)

![Align the upper leg first](/files/QpS91FEEbFx1kWR8Yofo)

![Pay attention to the reference edges for the lower leg](/files/kuwZZVGFrrkgDo4rhGiH)

<figure><img src="/files/W3TQV4Eo3i9GcMU38nc0" alt=""><figcaption></figcaption></figure>

First, select the index number of the joint servo from the diagram(when adjusting the leg servo, adjust the thigh first, and then adjust the calf).&#x20;

Then, click the "+" or "-" button to fine-tune the joint to the desired angle.&#x20;

{% hint style="info" %}
If the offset is more than ±9 degrees, you need to remove the corresponding part of the servo, reinstall it by rotating one tooth, and then press the "+" or "-" button.

For example, if you need to use -10 as the calibration value, remove the limb, rotate it by one tooth, and then reattach it. The new calibration value should be around 4, i.e.,  they sum up to 14. Avoid rotating the servo shaft during this adjustment.&#x20;
{% endhint %}

## Test the calibration effect

![Bittle](/files/vQv5sjbxiNJmcbZd4v2X)

You can click the skill buttons to switch between **Rest**, **Stand**, and **Walk** to test the calibration effect.&#x20;

If you want to continue calibrating, please click the **Calibration** button, and the robot will return to the calibration mode, with all servos immediately moving to their calibration positions.&#x20;

{% hint style="info" %}
Note:&#x20;

You may need a second round of calibrations to achieve optimal results.
{% endhint %}

After calibration, remember to click the **Save** button to save the calibration offset. Otherwise, click "**<**" in the upper left corner to abandon the calibration.

## Install the screws for the construction kit

For the construction kit, after completing the joint calibration, install the center screws to fix the leg parts and neck servo gears.


# Controller

In the control panel, you can control the robot to perform various postures, behaviors, and gaits.

<figure><img src="/files/DPKqxK3KRMxeLrYG3iPl" alt=""><figcaption></figcaption></figure>

## Gaits

The left panel sets both the robot's gaits and directions and send combined command, such as "walk left" and "trot forward". The robot will only move if an initial gait and direction are selected. The "step" has no direction, and "backward" has left and right directions. The pause button "||" will pause the robot's motion and turn off the servos, so that you can rotate the joints to any angle. The "Turbo" button ( <img src="/files/YQwDEPEj4FqBZvskEzGI" alt="" data-size="line"> ) turns on/off the gyro, a sensor to detect the robot's body orientation. Turning it on will make the robot keep adjusting to body angles, and will know when it's upside down. Turning it off will reduce calculation and make it walk faster and more stable. &#x20;

## Postures and behaviors

The built-in postures and behaviors can be triggered by pressing the buttons. Don't press the button too frequently and repeatedly. Allow some time for the robot to finish its current tasks.&#x20;

## Customized commands

* **Press and hold** the button and drag to change the button position.&#x20;
* **Double-tap** the command button to edit it.&#x20;
* You can also create a customized single command/group command by pressing the "+" button.

<figure><img src="/files/fe7I74M8yoav8RPAbA4q" alt=""><figcaption></figcaption></figure>

### Create a single command

After pressing the **Create Command** button, you can see the following interface:

![](/files/GL2b8zzRrrpBPi28HZvC)

After entering the editing state, there's a serial console to test the command and configure the robot.&#x20;

The joint index of the robot:

<figure><img src="/files/parvvv9mSALj4nWqNRft" alt=""><figcaption></figcaption></figure>

You can try the following useful serial commands in the **Code** text box:

#### \* move robot's head(robot arm)&#x20;

```
m0 45
```

#### \* move head left and right (move joint1 angle1 joint2 angle2 .... The angle is -127\~128)&#x20;

```
m0 -70 0 70
```

#### \* sit&#x20;

```
ksit
```

#### \* move joints one by one&#x20;

```
m 0 -70 0 70 8 -30
```

#### \* move joints simultaneously&#x20;

```
i 0 -45 8 -30 12 -60
```

#### \* show current joint angles&#x20;

```
j
```

#### \* long meow once (Nybble）

```
u0 1
```

#### \* short meow three times (Nybble）

```
u2 20
```

#### \* mute/unmute the buzzer beep

```
b
```

#### **\* adjust the buzzer volume (b\[0-10])**

```
b1
```

#### \* play a short tone (beep tone duration, duration is 0\~256)&#x20;

```
b12 20
```

#### \* play a melody (beep tone1 duration1, tone2 duration2, tone3 duration3, .... only 64 characters are allowed, the actual duration is calculated as 1/duration)&#x20;

```
b14 4 14 4 21 4 21 4
```

#### More common commands to be added

Please see [this list of common commands](https://docs.google.com/spreadsheets/d/1Lr6Cd1T-H9sSdUi_bI-OeMClkVOKjTQM/edit?usp=sharing\&ouid=106975882561093680387\&rtpof=true\&sd=true) that may be added as customized commands.  You can enter the "Voice command" column values as the "Name" values and the "Customized command code for Petoi mobile app" column values as the "Code" values.

A more detailed command table can be found in the [Serial Protocol](https://guide.petoi.com/apis/serial-protocol).&#x20;

### Import new skills as a customized button

#### Import your local customized skill (created by the [Skill Composer](https://guide.petoi.com/desktop-app/skill-composer))

You can send the skill file to your phone via the Messenger app or email, and open it on the phone using the Petoi App. A button for the new skill will be created; you can see it when you open the control panel.

<figure><img src="/files/LvJ0YdTUfEXeg3zLQzpe" alt=""><figcaption></figcaption></figure>

#### Import new skills from the skill library on GitHub

[The SkillLibrary folder](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary) in GitHub contains new skills for the OpenCat robot, which can be used for your reference. You can use your mobile browser to access the GitHub page of the OpenCat project, open the skill file (such as [Bittle\_Fold.md](https://github.com/PetoiCamp/OpenCat/blob/main/SkillLibrary/Bittle/Bittle_Fold.md)), select the "Code" tab, and share it with the [**Petoi Mobile App**](https://guide.petoi.com/mobile-app/introduction)(make sure the mobile app is connected to your Petoi robot first), as shown in the figures below.  Then you can execute this skill by pressing the newly created command button.

{% hint style="warning" %}
On iOS, you cannot share the .md skill file on GitHub in the Chrome browser. You can download the skill file and refer to the method - [Import your local customized skill](#import-your-local-customized-skill-created-by-the-skill-composer) to import it to this smartphone app.
{% endhint %}

<div><figure><img src="/files/HRcf2PQUkNsEsXHf4mTv" alt=""><figcaption></figcaption></figure> <figure><img src="/files/qRBFhbd4S8Dw5vdTCAE4" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="/files/JfZ7DaAzohvSOAZXpjDj" alt=""><figcaption></figcaption></figure> <figure><img src="/files/pVxNWxunKPStuSMfMRWV" alt=""><figcaption></figcaption></figure></div>

<figure><img src="/files/sl0xZZLUmo4SD3gykCmx" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
You are welcome to create your new skills(using the Skill Composer or [modifying the source code](https://guide.petoi.com/applications/skill-creation)) and share them by sending merge requests to [this folder](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary).
{% endhint %}

### Create a group command

The group command feature lets you chain multiple commands together and play them in sequence.

After pressing the **Create Group Command** button, you can see the following interface:

<figure><img src="/files/2a89mNbjVx27MTjDk8ym" alt=""><figcaption></figcaption></figure>

You can name the command group in the **Name** text box and add the command to the **Command Group** list by clicking the command button in the **Command Library** selection box. In the **Command Group** list, you can ***press and hold*** the command button and **drag** to change the command position.&#x20;

Click the **Test** or **Play (**![](/files/ays18QEsFK31wroXlnAC)**)** button to test the function of the command group. Click the **Pause (**![](/files/9ctc9bRh7LUiaV2Cs6qh)**)** button to interrupt the command list execution flow.

Click the **Delete** button to Delete the group command.

### Make your robot act randomly

{% embed url="<https://www.youtube.com/watch?v=nHLkE74Q3k8>" %}

If your robot doesn't have any random behavior, you may need to upgrade your robot to [the latest firmware](/desktop-app/firmware-uploader).&#x20;

## Updates and support

We keep improving the app and will inform you of the updates when available. Please write to  <support@petoi.com> if you have any questions about the app.&#x20;


# Voice Command

## Demo video

{% embed url="<https://youtu.be/aGW8F4mArAs>" %}

## Function introduction

Using this module, you can control the Petoi robot to perform various skills through voice without using wake words. Currently, the module supports 35 fixed voice commands in two languages (English and Chinese) and ten customized commands by recording any sound clips.&#x20;

It is built into the [**BiBoard V1**](https://guide.petoi.com/biboard/biboard-v1-guide) as follows:

<figure><img src="/files/BTXujMNDvdSxFeKDYue9" alt=""><figcaption></figcaption></figure>

## Play with the voice commands

### Common use cases

#### Set the default language

{% hint style="info" %}
This feature is designed for robots using **BiBoard** as their mainboard.
{% endhint %}

When the robot is restarted, the voice module is automatically reset to its default language setting, which is English.

There are two ways to set the default language:

* Using the serial commands
  * Open the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor):
    * To set the default language to **English**, use the command: ***`XAa`***.&#x20;
    * To set it to **Chinese**, use the command: ***`XAb`***.
  * In the [mobile app](https://guide.petoi.com/mobile-app/controller#create-a-single-command):
    * To set the default language to **English**, create a command called **English** and use the code: ***`X65,97`**.*
    * To set it to **Chinese**, create a command called **Chinese** and use the code: ***`X65,98`**.*
* Using the voice commands
  * To set the default language to **English**, you need to say the voice command "**Lizheng**" (phonetic) first and then say "**Bing-Bing**" (phonetic).
  * To set it to **Chinese**, you need to say the voice command "**Attention**" first and then say "**Di-Di**"(phonetic).

#### Switch the language

{% hint style="info" %}
Note: For the **BiBoard**, the language will switch to the default language setting after rebooting the robot. So, if you accidentally switch the language mode, you can restore the default language setting by restarting the robot.
{% endhint %}

* To switch to **English**, you can say "**Bing-Bing**" (phonetic)
* Switch to **Chinese**, you can say "**Di-Di**" (phonetic)

#### Turn on/off the voice command functionality(audio response and robotics reaction)

To turn on

* Speak **Play sound**&#x20;
* Create a command called "**Enable voice**" and use the code: *`X65,99`*

To turn off

* Speak **Be quiet**
* Create a command called **Disable voice** and use the code: *`X65,100`*

#### Use the predefined voice commands

The voice command list for Bittle / Bittle X / Bittle X+Arm

<figure><img src="/files/2oVzDStjdtTsoHe8L2MK" alt=""><figcaption></figcaption></figure>

See [**this doc**](https://docs.google.com/spreadsheets/d/1Lr6Cd1T-H9sSdUi_bI-OeMClkVOKjTQM/edit?usp=sharing\&ouid=106975882561093680387\&rtpof=true\&sd=true) for the latest version.

{% hint style="info" %}
To avoid inadvertently triggering the robot to respond to voice commands, you can say **Be quiet** to the robot to disable the voice module, such as when talking with others.

If the above voice commands don't take effect in **English mode**, try to use the mobile app and create a new button with the code: ***`X65,100`***, or input ***`XAd`*** in the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) to disable the voice module.

<img src="/files/H2dpRnHK6aBYiFVs3Nda" alt="" data-size="original">\
You can say  **Play sound** to the robot to enable the voice module.

Use the mobile app and create a new button with the code: ***`X65,99`***, or input ***`XAc`*** in the [serial monitor](https://docs.petoi.com/arduino-ide/serial-monitor) to enable the voice module.

<img src="/files/ExVu04nKsSn4SfdFdXAQ" alt="" data-size="original">
{% endhint %}

{% hint style="success" %}
The voice command **Climb-up** is a challenge for you. You can [design the behavior](/desktop-app/skill-composer) by yourself. Then, you can post it on the [Petoi Forum Challenge](https://www.petoi.camp/forum/challenge) or email <support@petoi.com>. We may adopt it in our official firmware and send you a gift!

For example, you can share your behavior like this:

{% embed url="<https://www.youtube.com/shorts/RWsQaIZMDqo>" fullWidth="false" %}
{% endhint %}

### How to debug if the voice command doesn't work

In some cases, the voice module may not respond to your voice. Please check the following:

1\. Say **Play sound** to check if the robot responds with **Do-Me-So**. Sometimes, the voice may be accidentally set to muted mode, triggered by **Be Quiet**.

2\. If the module doesn't make any sound with Play sound, say **Bing-Bing** to switch to English mode. You may try different tones and speeds to say **Bing-Bing**. The robot should respond with **Switch English** if not in **English mode**. It won't react with anything if it's already in English.&#x20;

3\. If the voice module still doesn't make any sound, you can try to reset it in our software tools.

* #### Mobile app:

  From version **1.2.0** of the mobile app, you can create a new button with the compound code:&#x20;

  ***`^X65,99;!1000;X65,98;!1000;X65,97`***

  To reset the voice module to English mode. &#x20;

  <figure><img src="/files/lVKQSlzS4IZfH8Bs1no5" alt=""><figcaption></figcaption></figure>

  <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><em><strong><code>X65,99</code></strong></em>, or input <em><strong><code>XAc</code></strong></em> in the <a href="https://guide.petoi.com/arduino-ide/serial-monitor">serial monitor</a> enables the voice module.</p><p><img src="/files/ExVu04nKsSn4SfdFdXAQ" alt="" data-size="original"></p><p><em><strong><code>X65,97</code></strong></em> or input <em><strong><code>XAa</code></strong></em> in the serial monitor is equivalent to saying <strong>Bing-Bing</strong>, but excludes the chance that the voice is not recognized. Then you can try to say <strong>Play sound</strong> again. </p></div>

  <figure><img src="/files/CumkWIADNiXd5ZUXTBf1" alt=""><figcaption></figcaption></figure>
* #### Desktop app:

  From version 1.2.1, you can use the debugger tool to [reset the voice module](https://guide.petoi.com/desktop-app/tools#download-the-latest-version-of-the-petoi-desktop-app).

4. Next, if you say **Hello**, the robot should wave its hand and validate that the complete reaction loop is good. Then, you can try other voice commands.&#x20;
5. Try powering off the mainboard by disconnecting the USB data cable, long-pressing the battery's button, and then re-powering the mainboard.

The above steps validate that the voice module is working. It's powered separately from the motion unit and should work regardless of the robot's status.&#x20;

If the above steps cannot fix the problem, contact <support@petoi.com> for help.

### Record customized voice commands

When the robot works in **English mode**,  you can speak **Start learning** (or input the serial command **XAe** in the serial monitor) into the custom voice command mode and record your voice commands in order.&#x20;

{% hint style="info" %}
If the module is **not** in English mode, you can speak **Bing-Bing** (or input the serial command ***`XAa`*** in the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor)) to switch to **English mode**.
{% endhint %}

You can record up to 10 voice commands, <mark style="color:red;">each with no more than</mark> <mark style="color:red;"></mark><mark style="color:red;">**six**</mark> <mark style="color:red;"></mark><mark style="color:red;">syllables</mark>.

To exit the custom voice command mode in the middle, you can speak **Stop learning** (or input the serial command **XAf** in the serial monitor).&#x20;

After leaving the custom voice command mode, please speak one of the recorded voice commands to trigger the reaction.

Speak **Clear the learning data** to delete all the recordings simultaneously  (you cannot delete a specific recording).

There are **ten** skill strings as custom replies already defined in the `voice.h`:

{% hint style="info" %}
The first 3 commands is standard for all type of petoi robot, which have feedback servos.
{% endhint %}

```cpp
String customizedCmdList[] = {
  "fl",  // learn skill with feedback servos
  "fr",  // replay skill learned with feedback servos
  "fF",  // movement follower demo with feedback servos
#ifdef BITTLE       // also for Bittle X
#ifdef ROBOT_ARM    // for Bittle X+Arm
  "kpickF",                          // pick front 捡起来
  "kputD",                           // put down 放下
  "khuntL",                          // hunt 捕猎
  "kshowOff",                        // show off 展示
  "kputL",                           // put left 收起来
  "ktossL",                          // toss left 左抛
  "klaunchL",                        // launch 发射
  "kclapL",                          // clap 鼓掌
  "ktossF",                          // toss front 前抛
  "qc-2:0>kclap:1000>kpickF:1000>",  // calibrate arm (for QA) 校准(工厂用)
#else
  "kpu1",                                                                  // single-handed pushups
  "m0 80 0 -80 0 0",                                                       // wave head
  "kmw",                                                                   // moonwalk
  "b14,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,\
  21,8,21,8,19,8,19,8,18,8,18,8,16,4,21,8,21,8,19,8,19,8,18,8,18,8,16,4,\
  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",  // twinkle star
  "T",                                                                     // call the last skill data sent by the Skill Composer
  "6th",
  "7th",
  "8th",
  "9th",
  "10th"  // define up to 10 customized commands.
#endif
#elif defined NYBBLE    // also for Nybble Q
  "kluckyL",   // lucky cat 招财猫
  "klkPawsL",  // lick paws 舔爪子
  "qksit:100>i0 20 1 0 8 -70 12 0 15 10:0>o1 0, 0 40 -20 4 0, 1 -30 20 4 30, 8 -70 10 4 60, 12 -10 10 4 0, 15 10 0 4 0:100>m0 0 1 -20 2 0:0>ksit:0",
  // "kwsfL",                                                                 //wash face 洗脸
  "khuntL",                                                                // hunt 捕猎
  "m0 80 0 -80 0 0",                                                       // wave head                                                                //
  "b14,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,\
  21,8,21,8,19,8,19,8,18,8,18,8,16,4,21,8,21,8,19,8,19,8,18,8,18,8,16,4,\
  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",  // twinkle star
  "T",                                                                     // repeat
  "xl",                                                                    // learn a new trick 学习动作
  "xp",                                                                    // play the trick 表演动作
  "10th"                                                                   // define up to 10 customized commands.
#endif
};
```

The response actions (**`kpu1`** means single-handed pushups, **`kmw`** means moonwalk) are already defined in the program.&#x20;

Other serial commands are also supported as responses, such as joint movements(e.g. **`m0 80 0 -80`**  means shaking the head left and right) and playing a melody(e.g. **`b14,8,14,8,21,8,21,8,23,8,23,8,21,4`**)

To use these custom replies above, you need to enter the custom voice command mode, record ten voice commands (such as Single-handed Pushup, Shake Head, Moonwalk, Twinkle Star), and then exit the custom voice command mode.

If you have recorded a voice command and the corresponding custom reply is not a predefined serial command (e.g.,**`6th`**), there is no actual demonstration effect; it only prints a simple message on the serial monitor when you speak the corresponding voice command.

## Advanced usage for developers

### Understand the principle

1. &#x20;Convert the voice command collected by the microphone in the module into a serial command.
2. &#x20;Send the serial command to the mainboard MCU through the soft serial port Serial2.
3. &#x20;After receiving the serial command, the MCU parses it into the corresponding skill command, and finally, the reaction module, according to the skill command, controls the robot to respond accordingly.

Upload the demo sketch **testVoiceCommander.ino**, and you can see every serial command that is sent to MCU(including the custom voice command if you have recorded it)

<figure><img src="/files/B3SFPQ26YbHxxEH4D8i9" alt=""><figcaption></figcaption></figure>

You can open [the serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) to check the raw return values of every voice command.&#x20;

<figure><img src="/files/f8WlQWeFdEp49F3D4A2q" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/2Bjh6ojqNV7qVX4QGNEB" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
After you speak the voice command to the robot, the **Returned value** (**`X A 11`** or **`X A 21 kup`**) is the corresponding serial command sent to the mainboard MCU. The third number(11 or 21) is an invisible character. To understand it, we convert it to a numeric value and print it out.
{% endhint %}

### The test sketch

The test sketch is in the OpenCatEsp32 repository on GitHub (specific path: OpenCatEsp32/ModuleTests/testVoiceCommander). You can visit our GitHub repository <https://github.com/PetoiCamp/OpenCatEsp32> to download the complete code, as shown in the following picture:

<figure><img src="/files/xkAYdahcOoMhWtdwbTNU" alt=""><figcaption></figcaption></figure>

### Serial interface

There are seven related serial commands for configuration; you can input them into the serial monitor.&#x20;

<table><thead><tr><th width="178">Serial Command</th><th width="222">Mobile App Button Code</th><th>Function</th></tr></thead><tbody><tr><td>XAa</td><td>X65,97</td><td>Set the default language to English</td></tr><tr><td>XAb</td><td>X65,98</td><td>Set the default language to Chinese</td></tr><tr><td>XAc</td><td>X65,99</td><td>Turn on the reply tone and enable reaction</td></tr><tr><td>XAd</td><td>X65,100</td><td>Turn off the reply tone and disable reaction</td></tr><tr><td>XAe</td><td>X65,101</td><td>Enter custom voice command mode</td></tr><tr><td>XAf</td><td>X65,102</td><td>Exit custom voice command mode</td></tr><tr><td>XAg</td><td>X65,103</td><td>Delete all the custom voice commands</td></tr></tbody></table>

{% hint style="info" %}
After inputting the command above in the message box, **press Enter** to send the command to the robot.
{% endhint %}

### How to design new reactions

For the robot in Voice mode, to improve the utilization rate of custom voice control commands, you can modify the last **six** skill strings to the skill names with actual action responses.

* Using the task queue to create a sequence of motions, please refer to the source code in the `voice.h` as below:

{% code lineNumbers="true" %}

```cpp
const char *cmd = raw.c_str() + shift;
tQueue->addTask(token, shift > 0 ? cmd : "", 2500);
if (strlen(cmd) > 0) {
  char end = cmd[strlen(cmd) - 1];
  if (!strcmp(cmd, "bk") || !strcmp(cmd, "x") || end >= 'A' && end <= 'Z') {
    tQueue->addTask('k', "up");
  }
}
```

{% endcode %}

{% hint style="info" %}
tQueue is the task queue defined in OpenCat.h; using the method "addTask" of this object, the robot can do some simple skills sequentially as a custom voice command response.&#x20;
{% endhint %}

* Using [the Skill Composer](https://guide.petoi.com/desktop-app/skill-composer) and binding the customized voice command to the new skills

1. &#x20;Use SkillComposer to design new skills and then [export](https://guide.petoi.com/desktop-app/skill-composer#export-the-skill) them to `Instinct***.h`&#x20;
2. &#x20;Modify *voice.h* to bind the customized voice command to the new skills: modify the **`customizedCmdList[]`**（e.g., If you want to bind the sixth customized voice command to the new skill, replace the string "*`6th`*" with **`'k'+the new skill name`**)


# Joystick with Micro:Bit

{% embed url="<https://youtu.be/BRb4nQeWcdQ>" %}

This remote controller is a Micro: Bit-based gamepad. It includes a 4-direction joystick and four undefined buttons. To enhance the gaming experience, it is also paired with a buzzer and vibration motor. It is compact in appearance, comfortable in hand, and can be remotely controlled.

<figure><img src="/files/cWq8AWK04l5QBMYPyAZP" alt=""><figcaption></figcaption></figure>

## Hardware

{% hint style="info" %}
Micro: Bit V1 has a smaller memory. So, the full functionality requires **Micro: Bit V2**.
{% endhint %}

## Software setup

The Joystick's source code is now open-sourced. It can control Bittle X, Bittle X+Arm (Bittle with a robotic arm), and Nybble Q. For more information, please refer to our [GitHub repository](https://github.com/PetoiCamp/ESP32_Microbit_Controller).

You can download the program file([microbit-JoyStick.hex](https://raw.githubusercontent.com/PetoiCamp/ESP32_Microbit_Controller/refs/heads/main/microbit-JoyStick.hex)), then import the program to [the programming platform MakeCode](https://makecode.microbit.org) as follows:

{% hint style="info" %}
We recommend you use a **Chrome** browser.
{% endhint %}

<figure><img src="/files/hFedNL9hJ93oPVbVHOKZ" alt=""><figcaption></figcaption></figure>

Alternatively, you can click "New Project" and drag the program file into the coding window to load it.&#x20;

### Download the program to the Micro: Bit V2

Connect your PC to the Micro: Bit V2 using a USB cable.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/connect-microbit.gif)

After a successful connection, a disk drive named `MICROBIT` is recognized on the computer.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/microbit-drive.png)

Click on the bottom left corner of the ![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-01.png) button， Select `Connect Device`.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-02.png)

Click ![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-03.png) button.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-04.png)

Click![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-05.png)

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-06.png)

Select `BBC micro:bit CMSIS-DAP` in the pop-up window and then select Connect. At this point, our Micro: Bit has connected successfully.

<figure><img src="/files/AYGrUa10XCpIyDScs4KF" alt=""><figcaption></figcaption></figure>

Click to download the program.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-08.png)

## How to use&#x20;

1. [Upload the newest firmware](https://guide.petoi.com/quick-reference/upload-firmware) to the robot (mainboard type: **BiBoard**)
2. Install 2 x #7 AAA batteries and plug in the Micro: Bit V2 to the remote controller. Then, power on the remote controller as follows:\
   ![](/files/4wd4bqBDrhavQ1xEHQuE)
3. Power on the robot. During bootup, it can connect to the controller automatically via Bluetooth.\
   If there are many remote controllers and robots, the connection is one-to-one and first-come, first-served.

{% hint style="info" %}
**Timed lock feature**

This feature limits the play time for each user during exhibitions or science festivals. It is deactivated by default.

After normal startup and Bluetooth connection, you can activate the limited-time usage function for the controller by pressing and holding the middle Logo (touch button) on the Micro:bit while keeping the controller upright (with the left joystick at the bottom). Once activated, the controller will send a rest command to the robot every 20 minutes and no longer respond to subsequent operations. The LED indicator matrix will dynamically display an hourglass pattern, as shown in the figure below:

<img src="/files/9X7ZIZfFs7c3DrOmUZpT" alt="" data-size="original">

You can reset the countdown and reactivate the controller using the same operation described above. The controller will play a prompt tone, and the LED indicator matrix will display an animation of an hourglass reversing.

Once the limited-time feature is activated, it can only be turned off by rebooting the controller. After the controller restarts, you must reset the robot (by clicking the **reset** button on the mainboard) or reboot the robot to reconnect.
{% endhint %}

### To control Bittle X:

<figure><img src="/files/tz2EqwCYXZMTddRVnvsq" alt=""><figcaption></figcaption></figure>

#### Demo

{% hint style="info" %}
Note: This demo shows Bittle X+Arm controlled by joystick. The control method for Bittle X is identical.
{% endhint %}

{% embed url="<https://youtu.be/QLI-x_8qO98>" %}
Bittle X+Arm
{% endembed %}


# Petoi Desktop App

The Petoi Desktop App offers a user-friendly graphical interface for configuring the firmware, calibrating the robot, designing customized motions, and utilizing debugging tools. The major function modules are the [Firmware Uploader](https://guide.petoi.com/desktop-app/firmware-uploader), [Joint Calibrator](https://guide.petoi.com/desktop-app/joint-calibrator), [Skill Composer](https://guide.petoi.com/desktop-app/skill-composer), and [Tools](https://guide.petoi.com/desktop-app/tools).

<figure><img src="/files/TDgmz5IOELYasd0r5kXQ" alt=""><figcaption></figcaption></figure>

## Download & Installation

You can download the [latest version](/desktop-app/introduction#download-the-latest-version-of-the-petoi-desktop-app) of the desktop App and unzip it.

Before running the app, for BiBoard:

* Wired connection: The kit includes a **USB Type-C data cable** connecting the robot's mainboard to the computer.
* Wireless connection (Bluetooth): The motherboard's [**built-in Bluetooth**](https://docs.petoi.com/bluetooth-connection) module allows you to connect the robot's mainboard to the computer wirelessly.

{% hint style="info" %}
For NyBoard, you must use the included USB adapter or the Bluetooth dongle to connect to a Petoi robot.&#x20;
{% endhint %}

You may need to [install drivers](/technical-support/useful-tools/biboard-v1) for the USB connection.

### Windows

Run the UI.exe in the **unzipped** folder.  Do NOT move the UI.exe to another location in Windows.

### Mac

After downloading the Mac version, you must drag it into the **Applications** folder.&#x20;

If you see the error message that **Petoi Desktop App** cannot be opened because the developer cannot be verified, you can right-click the icon, hold the **Shift** key and click **Open**.

![](/files/8358jcqppHBs1YHVE40Z)

{% hint style="warning" %}
The upgraded macOS has introduced some incompatibility with the GUI library. To click/activate an element in the app's interface, press and hold the element, then move your finger slightly and release. Otherwise, the event cannot be recognized.&#x20;

Sorry for the inconvenience. It's been a known issue between macOS and the popular Tkinter library.

<img src="/files/VEUyL4GdnSJyUo1amUuI" alt="" data-size="original">
{% endhint %}

### Linux

Please see the next chapter to run the app from a terminal.

## Run the app from the Terminal for Mac or Linux

In the case of compatibility issues or if you want to modify the source and test, you can also run the code from the Terminal.

The Terminal is a built-in interface on Mac or Linux machines. The equivalent environment on Windows machines is the Command Prompt (CMD). It's recommended that you install [Anaconda](https://www.anaconda.com/) to manage your Python environment (**Python version > 3.7.1)**. It can also provide PowerShell as a Terminal for older Windows machines.

Depending on your existing Python configuration, you may need to upgrade to Python 3 and install the following libraries:

* pyserial
* pillow

You can install them by entering `pip3 install pyserial pillow` in the Terminal or use the package manager in Anaconda.

To run the code:

1. In the Terminal, use the `cd` command to navigate to the `OpenCat/pyUI/` folder. You can use the Tab key to auto-complete the path name.
2. After entering the pyUI/ folder, enter `ls` and ensure you can see the UI.py and other python source codes listed.
3. Enter `python3 UI.py`.

{% hint style="info" %}
For Linux system users,  if you encounter the Python error message "\_tkinter.TclError: no display name and no $DISPLAY environment variable", you can try to install **python3-tk**, **tk-dev**. Taking Debian / Ubuntu as an example, the command is as follows:

`apt install python3-tk`

`apt install tk-dev`

After the installation is complete, reboot the computer.
{% endhint %}

### Check the mainboard version and the USB connector

<figure><img src="/files/47Q1it4Z8bViL993GgH7" alt=""><figcaption></figcaption></figure>

## Robot Connection

Plug in the battery and press the battery button for 3 seconds to power on the robot.

There are two methods to connect to the computer:

* The USB data cable connection must be made directly to **the BiBoard,** not to the battery's charging port. &#x20;
* You can also connect to the computer via [Bluetooth](https://guide.petoi.com/quick-reference/bluetooth-connection).

For BiBoard, please ensure the program enters the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization)**.**

## Open Source Codes

The source code is written in Tkinter using Python 3 and is open-source. The GitHub repository URL is: <https://github.com/PetoiCamp/DesktopAppRelease>

UI.py is the general entry for all the modules in the pyUI file folder:

-> FirmwareUploader.py

-> Calibrator.py

-> SkillComposer.py

-> Debugger.py

-> translate.py provides multi-language support for the UI. You may help to translate the UI into your language.


# Firmware Uploader

Robot's brain is in the firmware.  Robots desire to have the most updated brain!

Please go through to [the introduction](https://guide.petoi.com/desktop-app/introduction) for installing the Petoi Desktop App and connecting the robot to your computer first

## Upload the firmware using Petoi Desktop app

### Open Petoi Desktop App

**After** properly connecting the mainboard with the computer via a USB data cable, open the PetoiDesktopApp (for Windows: UI.exe / for Mac: Petoi Desktop App), and select your **Model** and **Language**.

#### Menu bar in Petoi Desktop APP

<div align="left"><img src="/files/qBCd9Bhez4849Yf780QA" alt="Model"> <img src="/files/gR5eBhARz93cFxxlprzO" alt="Language"> <img src="/files/3sAlQfjLKtep2lBKB4Hg" alt="Help"></div>

### Click the Firmware Uploader button

<div align="center"><img src="/files/bmSa9E1wwzopUOGaqGUS" alt="Main interface"></div>

### Auto Detect the Serial Port&#x20;

If there is **no** serial port or **more than one** serial port is detected by the desktop app:

<figure><img src="/files/zPEK9HCklsSKKfOlij4n" alt=""><figcaption></figcaption></figure>

After clicking the **Firmware Uploader** button,  there will be a message box prompt as follows:

<figure><img src="/files/ii8QC9zLeNtH6vwtQWhP" alt=""><figcaption></figcaption></figure>

Please follow the prompts in the message box. \
After clicking the **Confirm** button, If you complete the prompts within 10 seconds, the desktop app will automatically identify the serial port name connecting the robot to the computer.\
If you complete the operation of unplugging and plugging the USB interface on the computer for more than 10 seconds, the desktop application will enter the manual selection of the serial port name mode：

<figure><img src="/files/kgnSTTD7u6lGHXvrUqz1" alt=""><figcaption></figcaption></figure>

Click the **OK** button in the Warning message box first, then you can refresh the serial port list or select one of them (e.g. **COM3**) and click the **OK** button in the **Manual mode** window to open the Firmware Uploader interface as follows:

<figure><img src="/files/IAPsr99lxuNKhqeN7S3w" alt=""><figcaption></figcaption></figure>

Once the Firmware Uploader interface is opened, you can also unplug and replug the USB cable from the COMPUTER side. The desktop app will automatically identify the serial port name used to connect the robot to the computer.

<figure><img src="/files/4910PiAdo9AGvz9107Rb" alt=""><figcaption></figcaption></figure>

If you unplug the **COM5** and replug it on the computer side, it will be discovered by the desktop app as follows:

<figure><img src="/files/VW5yOQDHLRpfGYUgqW7W" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/QDyj6IxfGOZBglAI9zm9" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/6kaCalAgQlbDT7Ivx4cw" alt=""><figcaption></figcaption></figure>

### Select the correct options to upload the latest firmware.&#x20;

{% hint style="warning" %}
The 1.0 software won't work correctly with the Joint Calibrator, the Skill Composer, and other APIs. Use it only when you want to use the CodeCraft, a graphical coding interface provided by our partner, TinkerGen.&#x20;
{% endhint %}

<table><thead><tr><th width="176">Options</th><th width="293">Values</th><th>Notes</th></tr></thead><tbody><tr><td>Product</td><td><p>Bittle (default)</p><p>Bittle X</p><p>Bittle X+Arm<br>Nybble<br>Nybble Q</p></td><td></td></tr><tr><td>Mode</td><td>Standard (default)<br>RandomMind <br>Voice<br>Mind+<br>Camera <br>Ultrasonic <br>RandomMind_Ultrasonic<br>Light<br>Touch<br>PIR<br>Gesture<br>IR distance</td><td><p>Because <strong>Bittle X running on BiBoard</strong> has more memory space, you only need to upload with the <strong>Standard</strong> mode firmware.  Then you can switch between different modes via serial port commands. [1]</p><p></p><p>For NyBoard, these 12 modes can be selected. All of these modes apply to both <strong>Bittle</strong> and <strong>Nybble</strong>.</p><p></p></td></tr><tr><td>Software version</td><td><p>2.0 (default)</p><p>1.0</p></td><td>The 1.0 version is obsolete.</td></tr><tr><td>Serial port</td><td>Auto detection or by manual selection. </td><td>You can find the correct one through unplug and replug the USB socket on the computer side</td></tr><tr><td>Board version</td><td><p>NyBoard_V1_0 (default<em>)</em><br>NyBoard_V1_1<br>NyBoard_V1_2<br>BiBoard_V0_1</p><p>BiBoard_V0_2<br>BiBoard_V1_0</p></td><td>BiBoard_V0_1 or BiBoard_V0_2  is for <strong>Bittle X.</strong>  <br>BiBoard_V1_0 is for <strong>Bittle X V2</strong> and <strong>Nybble Q</strong>.</td></tr></tbody></table>

{% hint style="info" %}
\[1] You can use the serial commands to [switch modes](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-desktop-app/pages/8ajuxMEplUPiNYi4SRyi#id-2.9-switch-working-mode-via-the-serial-commands-optional) for **BiBoard**:\
For **BiBoard,** Mind+ mode is supported by default, so it doesn't require a serial command to switch on.\
You can learn about the functionw of each module through the [**EXTENSIBLE MODULES**](https://guide.petoi.com/extensible-modules/introduction).
{% endhint %}

{% hint style="warning" %}
There's no correlation between the board (hardware) version and the code (software) version.
{% endhint %}

### Uploading options

* **Factory Reset**\
  After upgrading the firmware, the board will enter the [**initialization startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization) and ask whether to clear the joint calibration parameters and calibrate the IMU.
* **Upgrade the Firmware**\
  It will upgrade the firmware, skip the steps of clearing joint calibration parameters and the IMU calibration(it's equivalent of sending serial command "**n**"), and automatically enter the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization).
* **Update the Mode Only**\
  It has the same function as the **Upgrade the Firmware** at present.

#### **Factory reset** process

After clicking the **Factory Reset** button, the uploading process will start immediately. The board will enter the [**initialization startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization) after uploading the firmware. Some message windows will pop up in sequence for you to confirm or cancel:

1. Reset joint offsets? (Y/N)<br>

   <figure><img src="/files/xp2AMD7ENMG0QPFcJMRr" alt=""><figcaption></figcaption></figure>

Select **Yes**, and the program will reset all servo calibration parameters to zero. The status bar will update the corresponding process and result in real time.

Select **No** to preserve the calibration value(so that you don't need to calibrate again if you have already done so). &#x20;

2. Calibrate IMU? (Y/N)<br>

<figure><img src="/files/kNL86GYJtsuQDf6aOUNE" alt=""><figcaption></figcaption></figure>

Select **Yes**,  and the program will calibrate the gyroscope (IMU) to balance the robot correctly. The status bar will update the corresponding process and result in real time.

Select **No**, and the program will skip this step.

After that, the board will enter the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization)**.**

{% hint style="danger" %}
Note:&#x20;

Ensure the microcontroller is positioned horizontally for IMU calibration before clicking the "Yes" button.&#x20;
{% endhint %}

### Finish uploading the firmware

After the upload, the status bar will update the corresponding result, such as the success or failure of firmware uploading. If the uploading is successful, a message window of "Firmware upload complete!" will pop up simultaneously.

<figure><img src="/files/LoanvpTqxeu9rGHNDzAj" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Note:&#x20;

1. For NyBoard, when you open the software and upload the firmware for the first time, the program will first upload the "**Parameters**" firmware and then the "**Main function**" firmware.&#x20;
2. After uploading the firmware, if the NyBoard or BiBoard V1 is not connected to the battery and powered on, you will hear repetitive descending melodies, indicating that the battery is low or disconnected. You need to connect the battery and turn on its power.&#x20;
   {% endhint %}

### Check the log

From the desktop app version **1.2.7**, the log information will be output in the console box at the bottom of the interface:

<figure><img src="/files/Kusypy1JUioDU1uI0sgi" alt=""><figcaption></figcaption></figure>

You can directly click the **Copy** button to copy all the log information, or you can first select specific key information in the console output box with your mouse, then click the **Copy** button to copy only that portion of the log information, and then paste this information into an email and send it to support.petoi.com for assistance.

{% hint style="info" %}
For the old version of the desktop app, if the upload fails, the following message box will pop up:

<img src="/files/dlpmDOhPH7XgCXMd5IgK" alt="" data-size="original">

the log file is located at:

* For Windows: The log file is in the same directory as **UI.exe**

  ![](https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FNl61Gr6RNtDYEuJek7Gm%252Fimage.png%3Falt%3Dmedia%26token%3D0e0ea071-11e4-48e7-9f80-cbfbca10ccac\&width=768\&dpr=4\&quality=100\&sign=996aee40\&sv=2)
* For macOS: You can check the log file as follows:

  ![](https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FGLeXErV4KpBrfbJQhO3o%252Fimage.png%3Falt%3Dmedia%26token%3Dee485581-cf60-4008-aba7-5c4a91b16ee3\&width=768\&dpr=4\&quality=100\&sign=d6a8daf1\&sv=2)![](https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FL7O8qDstl6NwlwRQ4ZmJ%252Fimage.png%3Falt%3Dmedia%26token%3D972abd2e-b715-4f05-8601-baa99d22ad17\&width=768\&dpr=4\&quality=100\&sign=a61fc3b5\&sv=2)

When you contact our **<support@petoi.com>**, please attach the log file to your email.
{% endhint %}

### Run Firmware Uploader in the terminal

{% hint style="info" %}
There may be some OS platform compatibility issues with different computers.

You can still run the app directly from your terminal:

1. Go to OpenCat/pyUI/ in your terminal.
2. Install **PySerial** and **Pillow** for your Python installation. You may get a clean Anaconda environment and `pip3 install pyserial pillow`
3. Run `python3 UI.py`

For **NyBoard**, the firmware uploader calls the application **avrdude** to upload firmware files to the microcontroller.&#x20;

For **BiBoard**, the firmware uploader calls the application **esptool** to upload firmware files to the microcontroller.&#x20;

**Linux OS**

For Linux system users, in addition to the above steps, you also need to perform the following steps:

1\. Install **avrdude**&#x20;

* Fedora: dnf install avrdude
* CentOS: yum install avrdude
* Debian / Ubuntu: apt install avrdude

2\. Modify the variable **avrdudeconfPath** in FirmwareUploader.py

* Fedora / CentOS : `avrdudeconfPath = '/etc/avrdude/'`
* Debian / Ubuntu : `avrdudeconfPath = '/etc/'`
  {% endhint %}

{% hint style="info" %}
If you have experience with the Arduino IDE, you will see the same log message when uploading.

* For the BiBoard, please review the [Upload Sketch for BiBoard](/arduino-ide/upload-sketch-for-biboard).
* For the NyBoard, please review the [Upload Sketch for NyBoard](/arduino-ide/upload-sketch-for-nyboard).
  {% endhint %}


# Joint Calibrator

Robots can be precisely calibrated using the Petoi Desktop App.

Please go through to [the introduction](https://guide.petoi.com/desktop-app/introduction) for installing the Petoi Desktop App and connecting the robot to your computer first

## The rationale for calibration

### Understand the zero state and the coordinate system

After [entering the calibration state](#enter-the-calibration-state), with all servos rotated to their zero angles, attach the head, tail, and legs prepared in the previous section to the body. They are generally perpendicular to the body frames they are linked to. The calibration pose is shown below:

<figure><img src="/files/s84JN6ZSNOe6iC01ubet" alt=""><figcaption><p>Bittle's Calibration Mode</p></figcaption></figure>

For the construction kit, please install the servo-related components as shown in the picture (calibration mode) and ensure they are perpendicular to each other (the upper leg is perpendicular to the torso, and the lower leg is perpendicular to the upper leg).

{% hint style="warning" %}
Note: Insert the servo-related components directly into the servo output shaft; do not turn the output shaft during this process.
{% endhint %}

Rotating the limbs counterclockwise from their zero states will be positive (the same as in polar coordinates). Viewed from the left side of the robot's body, the counter-clockwise rotation of the joint is defined as the positive direction.

{% hint style="info" %}
The only exception is the head tilt angle for Nybble. It’s more natural to say head up, while it’s the result of rotating clockwise.&#x20;
{% endhint %}

{% hint style="info" %}
However, from the right side of the robot's body, the rotation directions' positive and negative are just opposite.
{% endhint %}

### Discrete angular intervals

If we look closer at the servo shaft, we can see it has a certain number of teeth. That’s for attaching the servo arms and avoiding sliding in the rotational direction. In our servo sample, the gears divide 360 degrees into 25 sectors, each taking **14.4** degrees(offset of -7.2\~7.2 degrees). That means we cannot always get a perfect perpendicular installation.&#x20;

![](/files/v400iIvlmpXjiobnloRS)

## Calibration process

### Enter the calibration state

{% hint style="info" %}
Connect the battery to the mainboard, then long-press the battery button for more than 3 seconds to power on the robot.
{% endhint %}

&#x20;After a battery powers on the robot, there are two methods to enter the calibration mode:

* It will automatically enter calibration mode when you click the **Joint Calibrator** button.<br>

  <figure><img src="/files/CS20IELy2ji3gHVEWbTd" alt=""><figcaption></figcaption></figure>
* Click the **Calibrate** button in the **Joint Calibrator** interface.&#x20;

{% hint style="info" %}
The servo slider is not available in the light yellow background area in the interface.
{% endhint %}

The joint calibration interface for Bittle X V2(BiBoard V1) in the Petoi Desktop App is as follows:

<figure><img src="/files/S2UKlYRBZkIInrXezVWp" alt=""><figcaption><p>For Bittle X V2</p></figcaption></figure>

The joint calibration interface for Bittle X (BiBoard V0) in the Petoi Desktop App is as follows:

<figure><img src="/files/q0I8hNt4XmXz96K13n6O" alt=""><figcaption><p>For Bittle X</p></figcaption></figure>

### Installing and Fine-tuning

{% hint style="warning" %}
Please **disregard** the type of mainboard in the following installation pictures, as all Petoi mainboards have the same size.&#x20;
{% endhint %}

For **the Construction kit**, after entering the calibration state, please install the neck servo and legs as follows:

#### Install the neck servo

In the calibration state, place the head as close to the central axis as possible and insert its servo shaft into the servo arm of the neck.

<figure><img src="/files/avQ8YXT0jNhmIiW2oPIy" alt=""><figcaption></figcaption></figure>

Press down on the head so it is firmly attached to the neck.

<figure><img src="/files/Ux0zFualAZghlx3qphHi" alt=""><figcaption></figcaption></figure>

#### Install the legs

Install the upper leg and lower leg components to the output teeth of the servos after the Bittle is powered on and in the calibrated neutral position. Please keep the torso, upper leg, and lower leg installed vertically as much as possible. Do not install the lower leg backward, as shown in the picture.&#x20;

<figure><img src="/files/5JHkO04jxSvTH1ySJJRy" alt=""><figcaption></figcaption></figure>

#### Fine-tuning

{% hint style="info" %}
The **pre-assembled** robot should already have the components adequately installed. You can do the joint calibration for fine-tuning directly, without needing to uninstall the head and legs.&#x20;
{% endhint %}

Please use the L-shaped calibration tool included in the package as a calibration reference. According to the joint numbers shown in the calibration interface picture, click and drag the corresponding joint sliders or click the blank areas of the slider tracks to fine-tune the joints to a right angle.

Please note that when calibrating the servos, adjust the upper leg first, then change the lower leg.

![](/files/0HXBQK8Fem9hj1AmppKy)

![Align the upper leg first](/files/QpS91FEEbFx1kWR8Yofo)

![Pay attention to the reference edges for the lower leg](/files/kuwZZVGFrrkgDo4rhGiH)

{% hint style="info" %}
If the offset is more than +/-9 degrees, you need to remove the corresponding leg and reinstall it by rotating one tooth and then dragging the corresponding slider. For example, when it is adjusted to +9 and still not right, remove the corresponding leg and shift one tooth when attaching it. Then, you should get a smaller offset in the opposite direction.&#x20;
{% endhint %}

<figure><img src="/files/s84JN6ZSNOe6iC01ubet" alt=""><figcaption><p>Bittle's Calibration Mode</p></figcaption></figure>

For the construction kit, please install the servo-related components as shown in the picture (calibration mode) and ensure they are perpendicular to each other (the upper leg is perpendicular to the torso, and the lower leg is perpendicular to the upper leg).

{% hint style="warning" %}
Note: Insert the servo-related components directly into the servo output shaft; do not turn the output shaft during this process.
{% endhint %}

### Validation and Save data

You can switch between  "**Rest**", "**Stand up**" and "**Walk**" to test the calibration effect.&#x20;

If you want to continue calibrating, please click the **Calibration** button, and the robot will be in the calibration state again (all servos will move to the calibration position immediately).&#x20;

{% hint style="warning" %}
Note: You may need a second round of calibrations to achieve optimal results.
{% endhint %}

After calibration, remember to click the "**Save**" button to save the calibration offset. Otherwise, click the "**Abort**" button to abandon the calibration data. You can save the calibration in the middle in case your connection is interrupted.&#x20;

{% hint style="info" %}
When you close this window, there is a message box shown below:

![](/files/iEbvluamYhzOnshzp9Bn)

To save the calibration data, please click the "**Yes**" button; otherwise, click the "**No**" button. Click the "**Cancel**" button to cancel or quit.
{% endhint %}

### Install the screws for the construction kit

After completing the joint calibration, install the center screws to fix the components and servo gears.


# Skill Composer

Petoi Skill Composer is a robobics skill design too for Petoi robots. Good tools are a prerequisite for job success.

Please go through to [the introduction](https://guide.petoi.com/desktop-app/introduction) for installing the Petoi Desktop App and connecting the robot to your computer first

## A Brief Introduction to the Interface

{% embed url="<https://www.youtube.com/playlist?list=PLHMFXft_rV6MTs8HMxSOvRAQektoXtaMG>" %}

### See [the video tutorials](https://www.youtube.com/playlist?list=PLHMFXft_rV6MTs8HMxSOvRAQektoXtaMG)

## Launch

Open Petoi Desktop App, click the "**Skill Composer**" button, and open the Skill Composer interface.&#x20;

![](/files/4OWjfHFhnNsvmqWomxmj)

## The Skill Composer Interface

{% hint style="info" %}
The servo slider is not available in the light yellow background area in the interface.
{% endhint %}

<figure><img src="/files/ZhIw8pWDnDguLZV60Ko6" alt=""><figcaption><p>For Bittle / Bittle X</p></figcaption></figure>

{% hint style="info" %}
Note: Most of the buttons on the interface have a tooltip when the mouse hovers over.
{% endhint %}

### Menu Options

* Model

  * Nybble
  * Nybble Q
  * Bittle
  * Bittle X
  * Bittle X+Arm

  Nybble cat and Bittle dog have different back leg joint directions. Their skill data are not interchangeable. Select the correct model before operating the Skill Composer. Otherwise, some joints may conflict with the robot's body.
* Language

  Currently, there are English, 中文, and Italian. You may contribute to the [translation script](https://github.com/PetoiCamp/DesktopAppRelease/blob/main/pyUI/translate.py).
* Utility

  We will keep adding small gadgets to the utility tab. We have an eye color picker for the Nybble cat's ultrasonic sensor with built-in LEDs. We also have an entry where you can add your creator credentials to the skills you create.

### Connection and State Dials

<figure><img src="/files/h24YX0YiSDhpIJol5NRJ" alt=""><figcaption><p>Connection and State Dials</p></figcaption></figure>

#### Listening / Connect button

for BiBoard:

* Wired connection: The kit includes a **USB Type-C data cable** connecting the robot's mainboard to the computer.
* Wireless connection (Bluetooth): The motherboard's [**built-in Bluetooth**](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard) module allows you to connect the robot's mainboard to the computer wirelessly.

{% hint style="info" %}
For NyBoard:

You can connect the robot to your computer via the [USB uploader](https://guide.petoi.com/communication-modules/usb-downloader-ch340c#connect-nyboard) or the system [Bluetooth settings](https://guide.petoi.com/communication-modules/dual-mode-bluetooth#connection-with-nyboard), then open up this desktop app.&#x20;
{% endhint %}

It should automatically detect and connect to the robot. The robot's serial port will appear in the following drop-down menu. The button should turn from "<mark style="color:yellow;">**Listening**</mark>" to "<mark style="color:green;">**Connected**</mark>". If the robot fails to connect for the first time, you can click the "<mark style="color:yellow;">**Listening**</mark>" button to disconnect all the ports, then press the "<mark style="color:red;">**Connect**</mark>" button again.

{% hint style="info" %}
Note: The desktop app will keep listening to the serial port and send a handshake signal to the newly added device. If the device responds with a pre-defined signal, it will be recognized as a Petoi device and added to the drop-down menu.
{% endhint %}

#### Servo

The robot's joints will hold position when the force is on. You should **NOT** rotate them by hand. Turning it off can allow you to rotate the robot's joints freely. It's helpful to quickly pose the robot to plan its center of mass for balancing.

#### Gyro

The robot has a gyroscope to detect its body angle and movements. It's used for balancing and roll-recovering. Turning it off can avoid unexpected reactions when rotating the robot.

#### Random

{% hint style="info" %}
For the robot with Nyboard, In certain experimental modes (e.g. [RandomMind mode](https://guide.petoi.com/desktop-app/firmware-uploader#select-the-correct-options-to-upload-the-latest-firmware)), the robot will move randomly. This button can toggle the behavior on/off.
{% endhint %}

### Send a serial command

<div align="left"><figure><img src="/files/jPvAyy2O5upvVQsmYkfx" alt=""><figcaption></figcaption></figure></div>

Like the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor), you can enter a [serial command](https://guide.petoi.com/apis/serial-protocol) in the text box and send it to the robot by pressing the **Enter** key or clicking the **Send** button.

### Preset Postures

![](/files/y1tu9IWMbAZMtwVRjo6F)

A few preset static postures move the robot's joints to specific positions. You can use them as a starting point to build your motion sequence. We usually start with the "balance" posture, with the robot standing on all four legs.

You can switch between different postures and observe how the sliders in the **Joint Controller** area update to reflect the changes in joint angles.

### Joint Controller

<figure><img src="/files/kZ4WhF1yhRzVGvr0393h" alt=""><figcaption></figcaption></figure>

The angle sliders can show the robot's current joint angles. They can reversely rotate the robot's joints if you change their values. You can drag the slider bar for large angle adjustments or click above or below the slider bar for fine adjustments (by 1 degree). Some joints will have smaller accessible ranges than the sliders. Try to use angles between -125 and 125 degrees. Sending larger angles will increase the response time.

The sliders correspond to the robot joints if you look down at the robot's body with its head pointing forward. Joints closer to the body are closer to the center of the panel. The robot's joints can be mapped to your own body and become your avatar.

{% hint style="info" %}
Note: Some sliders with a light yellow background are disabled for joints that don't exist on specific models.
{% endhint %}

You can control multiple joints by clicking the dial "**+**" or "**-**" on each slider. All sliders with their "**+**" pressed will change by the same increments. Sliders with their "**-**" button pressed will change by the negative increments. The button can be toggled on and off. Click the "<mark style="color:red;">Unbind All</mark>" button to disengage all the joints at once.

You can also control the robot's whole body joints with the sliders in the center panel. You can tune these central sliders to adjust the robot's global orientation and translation. The neutral "**balance**" posture can generate better results than other tilted postures.

| Global Orientation and Translation | Effect                          |
| ---------------------------------- | ------------------------------- |
| Pitch                              | Adjust the pitch angle          |
| Roll                               | Adjust the roll angle           |
| Spinal                             | Move in the spinal direction    |
| Height                             | Raise or lower the robot's body |

### Skill Editor

<figure><img src="/files/nDnxRqJy00T1puNCMal1" alt=""><figcaption></figcaption></figure>

The previous functions can modify a single posture. The Skill Editor is a stop-motion animation scheduler. You can add, delete, and insert frames of poses and make the robot perform continuous and smooth motions.

Every frame has a row of buttons and input fields as parameters. The first static row contains the column header to indicate the parameters' names.

## Basic Operation

### The Activated Frame

You can click the "<mark style="color:blue;">**=**</mark>" button (**the 2nd item** of a frame) to activate the corresponding frame and move the robot to the frame's posture. The frame will hold all your new edits on the robot's current posture. The "<mark style="color:blue;">**=**</mark>" symbol will become bold, and the button will become larger. The "=" symbol will become a red "!" mark if the current frame is edited. You can click this button to save your edits. Otherwise, the current edits will be abandoned if you click the "<mark style="color:blue;">**=**</mark>" buttons of the other frames.

### Add a Frame

You can click the "<mark style="color:green;">**v**</mark>" button (**the 9th item** of a frame) to add a frame after the current frame and activate it. The new frame will be identical to the **previous activated frame**.&#x20;

{% hint style="info" %}
Note: The new frame doesn't necessarily copy the "<mark style="color:green;">**v**</mark>" button's frame.
{% endhint %}

### Insert a Frame

You don't always add a new frame after the last frame. You can click the "<mark style="color:green;">**v**</mark>" button (**the 9th item** of a frame) of any intermediate frames to insert a new frame below the "<mark style="color:green;">**v**</mark>" button. The new frame carries information identical to the previously **activated frame**.

### Mirror a frame

You can mirror the activated frame's posture by clicking the "**>|<**" button.

### Delete a Frame

You can click the "<mark style="color:red;">**<**</mark>" button (**the 8th item** of a frame) to delete the current frame holding the button. All the following frames will shift up. If **the activated frame** is deleted, its preceding frame will be activated. If **the activated frame** is the first frame and is deleted, its following frame will be activated.

### Add a Note to a Frame

You may lose track of what each frame holds with multiple edits to the frame list. Switching to individual frames can be time-consuming. We provide a "**Note**" field (**the 7th item** of a frame) where you can add short keywords to identify the frames. By default, a random animal name will be added to a frame when created.

<figure><img src="/files/rKC7CRO4y7yUGvwIASQU" alt=""><figcaption></figcaption></figure>

### Bound joints and passed-through edits

If a joint's angle is the same in the current frame and the next frame, editing and saving its angle will also update the angles in the following frames until the angle differs. For example, if joint 8's angles are 4,4,4,4,6,7 in all the frames, changing the angle in the second frame to 8 will update the sequence to 4,8,8,8,6,7.

### Play the Skill Sequence

Besides manually clicking the "<mark style="color:blue;">**=**</mark>" button (**the 2nd item** of a frame) to view the single posture, you can click the "<mark style="color:green;">**Play**</mark>" button to show the postures in order starting from **the activated frame**. During playing time, the button's text becomes "<mark style="color:red;">**Stop**</mark>" to allow you to stop in the middle.

### Export the skill

After clicking the "<mark style="color:blue;">**Export**</mark>" button, you can choose a location and filename to save the skill (from **the activated frame**. If **the activated frame** is the last action frame, all action frames in the action frame list are exported) as a text file. You can cancel the savings to skip. The desktop app will still send the skill to the robot for real-time performance. And you can call the last exported skill by the serial token "**T**." There are two ways:

* Open [the serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) and input the serial command "**T**."
* Open [the mobile app](https://guide.petoi.com/mobile-app/controller), use the [Create Command](https://guide.petoi.com/mobile-app/controller#create-a-single-command) function, and enter the serial port command "**T**" in the **Code** text box.

{% hint style="info" %}
The last skill exported by the Skill Composer is stored in temporary memory. It can stay after the power is off and rebooted but **will be overwritten by a new export**.&#x20;

From version **1.1.3**, When exporting a skill, the desktop app automatically saves it to /Users/{username}/.config/Petoi/SkillLibrary/. Note the ***.config*** is a hidden directory but can be visited in the terminal or through a specific view setting. Therefore, you can easily manage the skills in [Mind+](https://guide.petoi.com/block-based-programming/petoi-coding-blocks#perform-the-skill-in-the-file).

The [Skill Creation](/applications/skill-creation) chapter focuses on the code and data structure so that you can integrate any number of new skills into the source code. The skill data array in the exported text file (\*.txt or \*.md) content *can be copied and pasted into the Instinct*\*\*.h file to be used as a skill array.
{% endhint %}

* [Export the skill ](/mobile-app/controller#import-new-skills-as-a-customized-button)as a customized button in the mobile app. It can be **permanent** even if you create multiple skills.&#x20;

### Import the Skill

You will see a pop-up window after clicking the <mark style="color:blue;">"Import"</mark> button. It allows you to copy-paste a skill data array in the text editor or import an existing skill file you or other users created. You can find example skill data in OpenCat/src/**InstinctBittle.h** or **InstinctNybble.h**. A complete skill format should include the "**{ }**" pair and the numbers between them. Only **the first one** will be imported if there are multiple skill arrays. The importer will do some simple format checks.

{% hint style="info" %}
[The SkillLibrary folder](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary) in GitHub is a collection of new skills of the OpenCat robot, which can be used for your reference (after downloading, use the import function to save a single skill to the robot's memory, and then use the [play](#play-the-skill-sequence) or [export](#export-the-skill) to view the specific effect).&#x20;

You are welcome to share your new skills by sending merge requests to this folder.
{% endhint %}

### Reset the Skill Editor

You can use the "<mark style="color:red;">**Restart**</mark>" button to clear the Skill Editor panel and start over.

## Advanced operation

### Set up Action Frame Loops

If you need some consecutive action frames in [the action frame list](#skill-editor) to run multiple times in a loop, you can first enter the number of loops in the **Repeat** text box above [the action frame list](#skill-editor) (on the **left side** of the label "**Set**"), and then use the left mouse button to select them in turn, The index numbers (**the 1st item** of a frame) of the **first** and **last** two frames of the continuous action frame that want to achieve cyclic motion (the index number button will appear in a recessed state after selection), as shown in the following figure:

<figure><img src="/files/UJIa23LB49MEBFqt22Il" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you enter **-1** in the **Repeat** text box, the looping action frames will keep looping forever unless you press the reset button on the mainboard of the robot.
{% endhint %}

### Set Movement Speed

In [the action frame list](#skill-editor), you can set the running speed of each frame of action (**the 3rd item** of a frame). There are the following 9 options for you to choose from (speed up the running speed in the order of numerical value):

1，2，4，8，12，16，32，48，max

{% hint style="info" %}
Note:

* In the options box, you can also enter any integer value in the range of 0\~125 (0 means max).
* By clicking the "<mark style="color:green;">**Play**</mark>" button in the "**Skill Editor**" area, you can **NOT** see the real running speed effect of the action; only after clicking the "<mark style="color:blue;">**Export**</mark>" button will you see the real running speed effect.
* Moving at the fastest speed for a long time will cause damage to the servo, so it is generally recommended **NOT** to set it to "**max**".
* When the "<mark style="color:green;">**Gyro**</mark>" button in the "[**State Dials**](#connection-and-state-dials)" area is turned on (the font color is <mark style="color:green;">green</mark>), after adjusting the joint angle value in the action frame or the running speed of the action frame, [<mark style="color:green;">**play**</mark>](#play-the-skill-sequence) it to view the debugging effect, or [<mark style="color:blue;">**export**</mark>](#export-the-skill) the action behavior, the robot It will try to maintain its own body balance in real-time, so it may be seen that when the robot is doing preset actions (especially when running relatively violent actions), its body will shake back and forth or even overturn, and the robot will automatically recover. Action may disrupt your original operation steps. Therefore, it is recommended that you click the "<mark style="color:green;">**Gyro**</mark>" button when designing the action to turn off the gyroscope (the font color changes to <mark style="color:red;">red</mark>), and the robot will not perform balance feedback actions in real-time. When turning on the gyroscope, click the "<mark style="color:red;">**Gyro**</mark>" button again.
  {% endhint %}

### Set Delay

In [the action frame list](#skill-editor), the "**Delay**" option (**the 6th item** of a frame) in each action frame indicates how long the robot delays before doing the next frame of action after the action of this frame is completed.

There are **17** presets for you to choose from: 0，50，100，200，300，400，500，600，700，800，900，1000，2000，3000，4000，5000，6000.

Of course, you can also enter any integer value in the range of 0\~6000 in the "**Delay**" option box. The unit is milliseconds (ms).

### Set Trigger and Angle

<figure><img src="/files/TnxUVWmiNoM5md5KDEyI" alt=""><figcaption></figcaption></figure>

The "**Trigger**" option (**the 4th item** of a frame) in the action frame is used to set the body rotation direction when the robot triggers the next action frame. There are the following **5** setting options:

* **None** means that there is no trigger and the angle condition is set
* **Pitch** means the robot body rotates nose-down
* **-Pitch** means the robot body rotates nose-up
* **Roll** means that the robot body rolls to its left side (counter-clockwise when looking from the tail)
* **-Roll** means the robot body rolls to its right side (clockwise when looking from the tail)

The "**Angle**" option (**the 5th item** of a frame) is defined with reference to the angle of the polar coordinate system. As shown in the figure above, when the body is horizontal, the angle of the polar coordinate axis is 0 degrees. If the polar coordinate axis rotates counterclockwise, the angle is positive and gradually increases. The angle setting range is an integer value between **-125\~125**.

When a specific trigger and angle are set in the action frame, the next frame of action will be triggered only when the robot rotates over the trigger angle in the trigger's direction. If a delay time is also set in this action frame, it will delay an additional time after the trigger condition is met before moving to the next frame.

When creating actions related to the rotation of the robot body (such as backflips, doing high bar exercises, etc.), it's vital to trigger the motion at a certain body angle whose timing can be hard to estimate, and it may also change during the motion. We can use the gyroscope to monitor the rotation angle of the robot body in real-time, so that the robot can trigger the joint servo at the exact time of the trigger event.&#x20;

### Export Mirror Actions

When exporting the action frames, if you want to mirror all the action frames in [the action frame list](#skill-editor) (the robot's left and right side joints will be exchanged, as if seen in a mirror), you can first click the "[<mark style="color:blue;">**MirrorAll**</mark>](#skill-editor)" button, and then click the "[**Export**](#export-the-skill)" button. If you want to cancel the mirrored export, you can deselect the "<mark style="color:blue;">**MirrorAll**</mark>" button.

### Behavior and Gait Options

Before exporting action frames, select the "**Behavior**/**Gait**" options in the "[**Skill Editor**](#skill-editor)" area as "<mark style="color:blue;">**Behavior**</mark>". After clicking the "[<mark style="color:blue;">**Export**</mark>](#export-the-skill)" button, the program will run on the robot and automatically interpolate between these action frames to make the robot move smoothly. All action frames will execute for only one round.

If the "<mark style="color:blue;">**Gait**</mark>" option is selected before you click the "[<mark style="color:blue;">**Export**</mark>](#export-the-skill)" button, the robot will continue to execute in a loop, and each action frame will run at the fastest speed; **NO** interpolation between action frames will be added. The motion can be quite brutal. Therefore, it is recommended that beginners always use the "**Behavior**" option to develop new skills.

When importing some pre-built skill array, the desktop app will automatically select the "**Behavior**/**Gait**" option according to the data format. The frames will be loaded into the frame editor, and the robot will automatically move to the first frame's posture.

{% hint style="info" %}
After sending a command, the desktop app will wait for the robot to return a confirmation token. It may freeze if the robot's program halts or the connection is lost. You don't need to close the desktop app and lose the unsaved action frames but press the "**reset**" button on the robot's main board to break the app's waiting loop. If the program still does not respond, you can click a posture button in the "[**Preset Postures**](#preset-postures)" area or try to reconnect the robot using the "Connect/Listening" button.
{% endhint %}

### Simultaneous Control of Multiple Robots

The desktop app supports connecting multiple robots via their own USB data cables or via [Bluetooth ](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard)to achieve simultaneous control. The desktop app can only recognize a serial port as a robot.&#x20;

{% hint style="info" %}
For the robot with NyBoard:

* [USB data cable](https://guide.petoi.com/communication-modules/usb-downloader-ch340c#connect-nyboard)\
  Connect the USB uploader to the robot's mainboard, then connect the data cable to the computer's USB port.
* [Bluetooth](https://guide.petoi.com/communication-modules/dual-mode-bluetooth#connection-with-nyboard)\
  Plug the Bluetooth module into the robot's mainboard, then pair it with the computer's Bluetooth settings interface.&#x20;
  {% endhint %}

So after the robot is powered on normally, the desktop app will keep detecting if there is a new serial port connection. When multiple serial ports are successfully connected, the serial port option button in the "[**State Dials**](#connection-and-state-dials)" area will change to "<mark style="color:blue;">**All**</mark>." Click the drop-down list to view all serial ports that have been successfully connected. All robots will be synchronized in real-time in this way. You can also select any one of the serial ports to control the corresponding robot.&#x20;

If you unplug a USB serial port on the computer (or disconnect the Bluetooth module in the Bluetooth setting interface), the corresponding serial port will be removed from the drop-down list in real-time.

If you unplug all USB serial ports (disconnect all Bluetooth modules), the serial port option button displays "**None**," and the left button displays "<mark style="color:yellow;">**Listening**</mark>." The desktop app still automatically detects whether there is a serial port connection. When a robot is reconnected to the computer through the serial port, the button on the left side of the drop-down menu will display "<mark style="color:green;">**Connected**</mark>." The corresponding serial port name is displayed in the serial port option button.

If you want the desktop app to stop detecting serial connections, click the "<mark style="color:green;">**Connected**</mark>" / "<mark style="color:yellow;">**Listening**</mark>" button. The text in the button will change to "<mark style="color:red;">**Connect**</mark>," and all serial connections will be disconnected. Click the "<mark style="color:red;">**Connect**</mark>" button again to restart the real-time detection function.

## Professional extensions

You can modify the source code of the Skill Composer in **OpenCat/pyUI/SkillComposer.py**.&#x20;

## Teach by pulling the legs using the feedback servo

{% hint style="warning" %}
This function requires the servos after March 2024, the BiBoard, and the latest firmware.&#x20;
{% endhint %}

We have added the position feedback feature to recent batches of Petoi servos. The servo can reply to a specific PWM pulse (3500µs) with its current position in the form of pulse length. The central controller (BiBoard) can convert the signal to angles for more interaction.

{% embed url="<https://youtu.be/vlHBf_dN4R0>" %}

First, [send the robot a serial command](https://guide.petoi.com/arduino-ide/serial-monitor#set-up-in-the-arduino-ide) "**fl**" to start the learning process. In the demo, it's triggered by our customized voice command. The robot's servo driver will switch to reading mode. Joint jigs can occur during this transition. Organize the robot's legs and then hold it still. Learning begins when no significant movements are detected.

Pull the legs, and the movement will be recorded. Stopping in the middle is okay because identical postures will be skipped. The recording will stop if the maximum frame is reached or if the robot's joints remain stationary for 2 seconds.

The recorded command can be replayed by typing "**fr**". The skill data is also printed to the screen, allowing you to save it and import it into the Skill Composer or other OpenCat interfaces.

The control logic is defined in **OpenCatEsp32/src/reaction.h** and **motion.h**.


# Tools

From the desktop app version **1.2.1**, the Petoi Desktop App includes a new module: **Tools**. This module provides convenient tools to fix your robot's frequent problems.&#x20;

<figure><img src="/files/9H11VrUWgmVvULuTcD1S" alt=""><figcaption></figcaption></figure>

## Reset the voice module <a href="#download-the-latest-version-of-the-petoi-desktop-app" id="download-the-latest-version-of-the-petoi-desktop-app"></a>

It is used to reset the [voice command module](https://guide.petoi.com/extensible-modules/voice-command-module), simplifying its [debugging process](https://guide.petoi.com/extensible-modules/voice-command-module#how-to-debug-if-the-voice-command-doesnt-work).  If the voice module does not respond to your voice, you can use this tool to reset it. It's pretty simple to use: click the **Reset voice module** button.

<figure><img src="/files/K5BT0zg61pnYk911sxII" alt=""><figcaption></figcaption></figure>

Please follow the instructions in the message box.&#x20;

<figure><img src="/files/d6uJBBIu4n5Y4lrtR6Kd" alt=""><figcaption></figcaption></figure>

If the problem persists, please email <support@petoi.com>.

## Calibrate gyroscope

{% hint style="info" %}
From the desktop app version **1.2.4**, the interface has added this new function.
{% endhint %}

It is used to calibrate the gyroscope sensor on the mainboard. If you notice that the robot cannot maintain balance while performing skill movements (such as sitting down) and its body keeps shaking, you need to recalibrate the gyroscope. To calibrate the gyroscope, click the **Calibrate gyroscope** button.

<figure><img src="/files/nPiZL3EettB9GlNynmvq" alt=""><figcaption></figcaption></figure>

Follow the instructions in the message box:

<figure><img src="/files/oK9OXmO0clF6DxNY73Zo" alt=""><figcaption></figcaption></figure>

If the problem persists, please email <support@petoi.com>.

## The Serial monitor

From the desktop app version **1.2.7**, we added the serial monitor feature in this interface.

If the robot and computer are already connected via a USB Type-C cable, the program will automatically enable serial communication after the interface opens. You can then directly enter serial commands in the ***serial command input box*** and press the **Enter** key on your keyboard or click the **Send** button to send the serial commands to the robot.

<figure><img src="/files/aHqWIcppwjKp8MU3WbCU" alt=""><figcaption></figcaption></figure>

If you encounter any problems, you can click the **Copy** button below to copy all the information in the output box, or you can select part of the relevant information in the output box with your mouse and then click the **Copy** button to copy the selected information. Paste the copied the information into your email and send it to support.petoi.com for assistance.


# Petoi Coding Blocks

How to use the extension library specially developed for the Petoi robot in Mind+

## Prepare Mind+

* Download the latest version from the [Mind+ official website](https://mindplus.cc/download-en.html)
  * For Windows: Mind+ version **>= V1.7.0**
  * For macO&#x53;**:** Mind+ version **>= V1.7.3 RC2.0**

{% hint style="warning" %}
If you cannot download the software from Mind+'s official website, you can download a stable version from [the Google Drive folder](https://drive.google.com/drive/folders/1V9WSnNiEOKZznP05W_RPxUD0TqAFFK7T). However, we strongly recommend that you download and use the official latest version.
{% endhint %}

{% hint style="info" %}
**For macOS only:** If you have already installed the old Mind+ version (**<=**&#x56;1.7.2 RC3.0), we recommend that:

1. You uninstall it first
2. Delete this folder /Users/\[vour username]/Documents/mindplus-pv/environment/Python3.6.5.64/ib/python3.6/site-packages/
3. Download and install the latest version of **Mind+**.
   {% endhint %}

* After the installation is complete, you can open Mind+

{% hint style="info" %}
If the default installation language is Chinese, you can switch to **English** as follows:

<img src="/files/y8C9aqhcfz6ItOCnwh25" alt="" data-size="original">
{% endhint %}

## Watch the video tutorials

We provide [a series of video tutorials](https://www.youtube.com/playlist?list=PLHMFXft_rV6POrzm8O12Nybdy1-FS1ymg) on using Petoi Coding Blocks with [the free Scratch-like robotics coding curriculum](https://www.petoi.com/pages/free-quadruped-robotics-curriculum-scratch-coding).   Be sure to click next to go through all the videos.

{% embed url="<https://www.youtube.com/playlist?list=PLHMFXft_rV6POrzm8O12Nybdy1-FS1ymg>" %}

## Prepare Petoi Robot

Please follow the instructions in the subpages to prepare according to the robot's mainboard.

For BiBoard products, such as [**Bittle X**](https://bittle-x.petoi.com/) ([BiBoard V0](https://guide.petoi.com/biboard/biboard-v0)), **Bittle X V2** ([BiBoard V1](https://guide.petoi.com/biboard/biboard-v1-guide)),  **Bittle X+Arm** (BiBoard V1), and **Nybble Q**(BiBoard V1), no software modification is required. By default, all functional blocks in Mind+ are supported.&#x20;

#### Plug the battery socket into the BiBoard, install it in the chassis, and long-press the battery button to power on the robot.

### Connection method

* Wired connection: The kit includes a **USB Type-C data cable** connecting the robot's mainboard to the computer.
* Wireless connection (Bluetooth): The mainboard's [**built-in Bluetooth**](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard) module allows you to connect the robot's mainboard to the computer wirelessly.

## Import Petoi Mind+ extension library

<figure><img src="/files/o27cet8NjxztUuFEzXWi" alt=""><figcaption></figcaption></figure>

Paste the GitHub URL(<https://github.com/PetoiCamp/Petoi_MindPlusLib>) in the text box of the import interface:

<figure><img src="/files/MFD3xnGLRViJZQJzpK10" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/gG9DcmsJsKnHEtxXh3sG" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
For macOS (if the Mind+ version **<= V1.7.2 RC3.0**), you need to download [PetoiRobot.zip](https://github.com/PetoiCamp/Petoi_MindPlusLib/raw/main/PetoiRobot.zip) and copy the extracted folder (PetoiRobot) to /Users/{your username}/Documents/mindplus-py/environment/Python3.6.5-64/lib/python3.6/site-packages/

![](/files/AZu2HURU7HI2m7vqwC2M)
{% endhint %}

{% hint style="info" %}
You can also download the latest extension library file (***\*.mpext***) from the [GitHub repository](https://github.com/PetoiCamp/Petoi_MindPlusLib/tree/main). And then import it  as follows:

![](/files/bwMseGKJ9q0AYBNtK24X)

![](/files/jtuV53VTfGH5H4Z4Whtc)
{% endhint %}

## Programming and Running

<figure><img src="/files/Vvv2cFA7C2IapMsyP6zY" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Petoi Coding Blocks is a user-extended library of Mind+.&#x20;

If you open **Mind+** by double-clicking the icon![](/files/92YALGSXvECxpZe0MY4r), it will not automatically load this extension library, and you need to re-import it manually every time you open the app.&#x20;

If you open Mind+ by double-clicking the code file(suffix **mp** or **sb3**) that uses this extension library or load these code files after opening Mind+, Mind+ will automatically load this extension library.
{% endhint %}

## The principle and process

This extension library can control the robot without compiling and uploading the code to the robot's main board. Click the "Run" button directly to run the program on the Python level and send instructions to the robot's serial port. If you need to stop the program while running, you can click the "Stop" button anytime. The process of the program can be divided into three steps:

1. &#x20;Open the serial port
2. &#x20;Control the robot
3. &#x20;Close the serial port

## The instructions for blocks

### Open the serial port

There are two ways to open the serial port:

* Automatically identify and open the serial port\
  ![](/files/hSINs1yNcWlGsf0u4q7n)
* Enter the name of the serial port to open the serial port\
  ![](/files/S1iOlfySZBn7om16Mdku)

{% hint style="info" %}
If it fails to open the serial port, you can refer to the printed information in the terminal window to replace the name of the serial port:

![](/files/i0bQFkVv43dnbccZ6361)
{% endhint %}

### Perform built-in skills

<div align="left"><figure><img src="/files/7jKeQh2wGwuFwgDAkCLb" alt=""><figcaption></figcaption></figure></div>

Use this block to let the robot perform skills pre-built on the robot's main board. Skills from "**sit**" to "**zero**" are **postures** (containing only one action frame).  Skills from "**boxing**" to "**sniff**" are **behaviors** (containing multiple posture frames and are performed only once).  Skills from "**stepping**" to "**trotRight**" are **gaits** (containing multiple posture frames, and are repeated in periodical loops until stopped).&#x20;

After finishing the current block's task, the program will wait a short time (delay xx seconds) before moving to the next block.&#x20;

### Perform the last skill exported from the Skill Composer

<div align="left"><figure><img src="/files/QZ1G3oIJaRp0PrfyTotm" alt=""><figcaption></figcaption></figure></div>

Use this block to let the robot perform the last skill exported from the [Skill Composer](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-desktop-app/skill-composer#export-the-skill).&#x20;

{% hint style="info" %}
It is equivalent to inputting the serial command 'T' in the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) and then delaying the preset time.
{% endhint %}

### Perform the skill in the file

<div align="left"><figure><img src="/files/N3EGVSD6wBrTkR0YWFCD" alt=""><figcaption></figcaption></figure></div>

Use this block to let the robot perform the skill in the skill files, which are in the following directory:

* **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}

The folder name **{model}** is Bittle or Nybble. When [exporting](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-desktop-app/skill-composer#export-the-skill) a skill file from the **Skill Composer**, it will automatically save the skill file to this directory.

{% hint style="info" %}
Tips: You can also copy & paste the [SkillLibrary](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary) folder from the source code of the OpenCat project on GitHub to the ***.config/Petoi*** directory. Therefore, you can use some sample skills for your Mind+ program, and there is no need to use the export function in the Skill Composer.

![](/files/lIGPo06pBWsggE5hDgwn)
{% endhint %}

{% hint style="info" %}
The folder **.config** is a hidden directory on MacOS/Linux but can be visited in the terminal or through a specific view setting:

* MacOS\
  open the directory /Users/{username} in Finder, then press the “**Command**” + “**Shift**” + “**.**” (period) keys at the same time.<br>

  <figure><img src="/files/Vr4Q0OJZtyFDYhoeCJ9L" alt=""><figcaption></figcaption></figure>

{% endhint %}

### Rotate joints in a sequence.

<div align="left"><figure><img src="/files/l3eF6NwhpeuazKTPEglh" alt=""><figcaption></figcaption></figure></div>

Use this block to control one joint or multiple joints to rotate in sequence. There are several ways to use the blocks for reference:

* Controls individual joint rotations to an absolute angle value.<br>

  <figure><img src="/files/xSXiZEeFCJfTYwtkw0KV" alt=""><figcaption></figcaption></figure>
* Controls individual joint rotations to a relative angle value.<br>

  <figure><img src="/files/yAUrkV4FKyn1Vl0KgfTM" alt=""><figcaption></figcaption></figure>
* Control multiple joints to rotate sequentially to **absolute** angle values or **relative** angle values.<br>

  <figure><img src="/files/G9fc47tePSrHTivPlfKq" alt=""><figcaption></figcaption></figure>
* Use the joint angle list to control multiple joints to rotate to absolute angle values in a sequence.<br>

  <div align="left"><figure><img src="/files/KZDShPYUizPcrOsFR8pd" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}

* <img src="/files/j5rjUZf7qLCmZdG0KBEH" alt="" data-size="original">, <img src="/files/9b6l2VUoNHYuxEhfffBz" alt="" data-size="original">represents a list consisting of a [joint index](https://app.gitbook.com/o/-M-_eWZUjFA4usjshHcZ/s/-MQ6a951Q6Jn1Zzt5Ajr-887967055/~/changes/285/petoi-robot-joint-index) and an angle value. For example, \[Head panning to 30 degrees] represents the list \[0, 30].
* <img src="/files/FyKxGaW0vddwqdYXceTc" alt="" data-size="original">\
  It consists of one or more pairs of[ joint index](https://app.gitbook.com/o/-M-_eWZUjFA4usjshHcZ/s/-MQ6a951Q6Jn1Zzt5Ajr-887967055/~/changes/285/petoi-robot-joint-index) + angle value, and the specific format is as follows: \
  \[joint index, angle value, joint index, angle value...]
  {% endhint %}

### Rotate joints simultaneously&#x20;

<div align="left"><figure><img src="/files/nCFY0sIXcipRPkDrjeRW" alt=""><figcaption></figcaption></figure></div>

Using this block can control multiple joints to rotate at the same time. There are several ways to use the blocks for reference:

* Control multiple joints to rotate to absolute angle values or relative angle values at the same time<br>

  <figure><img src="/files/soKQzuS4ylvcdCHG4L0R" alt=""><figcaption></figcaption></figure>
* Use the joint angle list to control the simultaneous rotation of multiple joints to absolute angle values.<br>

  <div align="left"><figure><img src="/files/Vh2XMoCWbfZ7yWfafXdX" alt=""><figcaption></figcaption></figure></div>

### Get the current angle value of a joint.

<div align="left"><figure><img src="/files/Brc9uT3zfvELerhTX5mN" alt=""><figcaption></figcaption></figure></div>

Use this block to get the current angle value of the selected joint. It is recommended to assign it to a variable first and then use the variable and algorithm to control other joints to rotate.

{% hint style="info" %}
The return value of this block is only an angle value, which cannot be filled in the "Turn sequentially" and "'Turn simultaneously" blocks alone.
{% endhint %}

#### Demo code

<figure><img src="/files/YZuJo0R5UyAWjq4Ea42T" alt=""><figcaption></figcaption></figure>

{% file src="/files/dTxtuiDyT9RbbPkwqO4S" %}

### Transform to frame

<div align="left"><figure><img src="/files/hRZwOu0SW2rvJtJSCgbI" alt=""><figcaption></figcaption></figure></div>

Use this block to control all joints to rotate at the same time. Please use it with the "**Action frame**" block. As shown below:

<div align="left"><figure><img src="/files/9JGREsuYLcSu0SolRpyD" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
The "Action frame" block represents a list of 16 angle values. Each angle value corresponds to the absolute angle value to which the corresponding [joint index](https://app.gitbook.com/o/-M-_eWZUjFA4usjshHcZ/s/-MQ6a951Q6Jn1Zzt5Ajr-887967055/~/changes/285/petoi-robot-joint-index) servo rotates.
{% endhint %}

### Play a melody

![](/files/NqKpHKy7twOf1TuiguBg)

Use this block to control the robot to play music. There are several ways to use  blocks together for reference:

* A list made up of multiple "Tone + Duration" blocks<br>

  <div align="left"><figure><img src="/files/gOG2tmvrP0Xn1zS331B4" alt=""><figcaption></figcaption></figure></div>
* Using a tone duration list<br>

  <div align="left"><figure><img src="/files/3NUr3wQkTxyhf3Qrwd6D" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
![](/files/7KMmq9wgWd8om7CeTaO3)

Consists of one or more pairs of Tone + Duration, the specific format is as follows:

\[tone, duration, tone, duration, tone, duration...]
{% endhint %}

### Execute a serial command

<div align="left"><figure><img src="/files/sPOyyF6TzwjUHvSLaStM" alt=""><figcaption></figcaption></figure></div>

Use this block to send a serial command to the robot, which can provide you with more and more flexible control methods. For example, you can input "**kkcL**" (kick the left front leg), and "**khiR**" (raise the right front leg to say hello). For more serial port commands, please refer to [the serial protocol](https://guide.petoi.com/apis/serial-protocol).&#x20;

### Write analog value

<div align="left"><figure><img src="/files/MqRx61qOySKFFMj7szCw" alt=""><figcaption></figcaption></figure></div>

Use this block to write an analog value to a specified pin. Analog value range: 0\~255

### Read analog value

![](/files/PlKNs3jjcUo0R2kf1M78)

Use this block to read an analog value from a specified pin.

### Write digital value

![](/files/HfD7apmmfLmGvZORMmaG)

Use this block to write a high/low-level value to the specified pin. High-level: 1; Low-level: 0.

### Read digital value

![](/files/WpiPm0lFfejX3m1gjTAA)

Use this block to read the high/low-level value of the specified pin.

### Read Ultrasonic sensor distance

<div align="left"><figure><img src="/files/l6XlAPafftMxUdjVJztQ" alt=""><figcaption></figcaption></figure></div>

Use this block to read the distance value from the ultrasonic sensor.

For the [Petoi RGB Ultrasonic Sensor](https://guide.petoi.com/extensible-modules/ultrasonic-sensor) (or **RUS-04**), you can set the two pins ( Trigger and Echo) like this:

* **NyBoard** (connects to the D6 and D7 pins)<br>

  <div align="left"><figure><img src="/files/Jc2cIVpIGzq7HzwkMLKq" alt=""><figcaption></figcaption></figure></div>
* **BiBoard** (connects to the Rx and Tx pins)<br>

  <div align="left"><figure><img src="/files/Jf90Y6ovj7a9NmRH1eAg" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
For other ultrasonic sensor models (e.g., **HC-SR04** connects to the D6 and D7 pins), you can set the two pins like this:

<img src="/files/wo5NE5VbCl2g8ZYjK0Gr" alt="" data-size="original">
{% endhint %}

#### Demo code

You can download the demo code from the [GitHub repository](https://github.com/PetoiCamp/Petoi_MindPlusLib/tree/main).

* BiBoard\
  examples/BiBoard/avoidObs\_BiBoard.mp
* NyBoard\
  examples/NyBoard/avoidObs\_NyBoard.mp

### Read the target coordinates

<div align="left"><figure><img src="/files/rJOcAU7G0ZR7OLhR10AP" alt="" width="510"><figcaption></figcaption></figure></div>

Use this block to Read the coordinates of the identified target from the camera module([MU camera](/extensible-modules/mu-camera) / [Petoi AI Vision module](/extensible-modules/petoi-ai-vision-module)) which connect to the BiBoard.

#### Demo code

<figure><img src="/files/dUL12wp13goeVxGcAQjY" alt=""><figcaption></figcaption></figure>

You can download this test code ([**testCamera.mp**](https://github.com/PetoiCamp/Petoi_MindPlusLib/raw/refs/heads/main/examples/BiBoard/testCamera.mp)) and run in the Mind+.

### Close the serial port

![](/files/3CNpi9KxnwBBHuT5JaNg)

Generally, at the end of the program, it is recommended to use this block to close the serial port communication.

### Demos

We provide some demos to download for reference in the [GitHub repository](https://github.com/PetoiCamp/Petoi_MindPlusLib) (Petoi\_MindPlusLib/examples).

<figure><img src="/files/T75f4JrnKdj4EfQevufc" alt=""><figcaption></figcaption></figure>

### [Free block coding curriculum for Bittle X](https://drive.google.com/drive/folders/1OU5LT47dbgWb5Av9Z4Qurq1GKlZyxNeD)


# Python coding mode in Mind+

## Switch to the Python coding mode

If you are familiar with the Petoi coding blocks and Python language, you can change to the **Code** mode in Mind+ as follows:

<figure><img src="/files/kDOa6QNU6XJGxyDruHbK" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/kUYqfTeFxjfa4RGYMc9M" alt=""><figcaption></figcaption></figure>

The **Code** mode is a Python 3 development environment. You can write any Python script in it and call all the PetoiRobot library APIs imported by Mind+.&#x20;

You can find the PetoiRobot library in the following directory. There are all the [definitions of API interfaces](/apis/python-api#available-apis) in the **robot.py**

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

Here is a sample code :

```python
# The code starts here
from PetoiRobot import *    # must import the PetoiRobot library

# enter the code below
# auto connect serial ports
autoConnect()

# call the APIs to control the Petoi robot
sendSkillStr('ksit', 0.5)
sendCmdStr('T', 0.5)
loadSkill("skillFileName", 0.2)

# close the serial port
closePort()
```

You can also copy the code in the **Auto-Generate** area in the **Blocks** mode and then paste it into the code file in the **Code** mode. Then you can edit and run the code.


# Install Mind+ on Chromebook

## Configure the Linux environment

You need to [**turn on Linux**](/technical-support/set-up-development-environment-on-chromebook) on the Chromebook to access the Linux environment via the terminal app.

Then, follow the following steps to install Mind+.

## Check the processor architecture

Use the following command to check the processor architecture in the terminal:\
***`uname -m`***\
The output will be similar to "i686", "x86\_64" or "armv7":\
i686 (or similar) - 32-bit Intel/AMD processor (common in older computers).\
x86\_64 (or similar) - 64-bit Intel/AMD processors (modern laptops, desktops, and most Chromebooks).\
armv7 (or higher) - ARM processor. (Mobile phones, tablets, 2nd and 3rd generation Raspberry Pis running Ubuntu Mate, and some Chromebooks. Most are 32-bit now)<br>

## Download package

According to different architectures to download different versions:<https://mindplus.dfrobot.com/linux><br>

## Installation

Use the following command in the terminal to install it (Replace **\*\*\*\*\*** with the file name of the installation package):\
***`sudo dpkg -i *****.deb`***\
***`sudo apt-get -f install`***

After installed, you can start the **Mind+** app in the Chromebook launcher:

<figure><img src="/files/pA5kAwIdHsOfQZobDZjp" alt=""><figcaption></figcaption></figure>

## Run Mind+

Now, you can proceed to the [Mind+ tutorial](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-coding-blocks).

{% hint style="warning" %}
Currently, connection via Bluetooth is not supported.&#x20;
{% endhint %}


# Arduino IDE

This chapter is for Advanced users with programming experience.

## 1. Download and Install

Please follow [the instructions](https://docs.arduino.cc/software/ide-v2/tutorials/getting-started/ide-v2-downloading-and-installing/).

For installation on Chromebook, please check [this guide](/product/bittle-x-v2+arm/control-and-program/arduino-ide/install-arduino-ide-on-chromebook).

## 2. Set up BiBoard&#x20;

For the specific parameters of each functional module of BiBoard, please refer to：

* [BiBoard V1 Guide](https://guide.petoi.com/biboard/biboard-v1-guide)
* [BiBoard V0 Guide](https://guide.petoi.com/biboard/biboard-v0)

### 2.1 Prepare the ESP32 development environment

Open “**Preferences**” in Arduino IDE, add ESP32 development board URL:

`https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json`

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FBeD6sfV1LKR8HOsRvvef%252Fimage.png%3Falt%3Dmedia%26token%3D469f106e-c18c-4e7e-9e36-cac3ea9cdda5&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=75d0ba4e&#x26;sv=2" alt=""><figcaption></figcaption></figure>

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252Fm4kA0SnO0HlaNRggKhTV%252Fimage.png%3Falt%3Dmedia%26token%3D7b4d2178-dc79-402e-886e-bccd277bd1e8&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=f8cdc92a&#x26;sv=2" alt=""><figcaption></figcaption></figure>

Click **OK** to save it and then exit.

Open “**Boards Manager...**” and wait for updates from external board support links. Search “esp32” and install the support package.

{% hint style="warning" %}
Please install the latest available version **2.0.12**. Installing version 2.0.13 and above may cause the motherboard to fail to startup.
{% endhint %}

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FkaI7GwGmYWxJLTksqswt%252Fimage.png%3Falt%3Dmedia%26token%3Ddda85ff5-f77c-4636-ae1d-1c4c49ef6618&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=d474360&#x26;sv=2" alt=""><figcaption></figcaption></figure>

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252Fymh9lMUwgWJEB2eHT2kv%252Fimage.png%3Falt%3Dmedia%26token%3D509f781c-fbbe-47e4-91ec-48e57d7eba8b&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=e4d6c4ea&#x26;sv=2" alt=""><figcaption></figcaption></figure>

After showing “**INSTALLED**”, the BiBoard board support package is finished.

### 2.2 Modify the code file in the package

* #### sdkconfig.h

{% hint style="info" %}

* For Windows:\
  C:\Users\\{username}\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.\*\tools\sdk\esp32\qio\_qspi\include\sdkconfig.h
* For Mac:\
  /Users/{username}/Library/Arduino15/packages/esp32/hardware/esp32/2.0.\*/tools/sdk/esp32/qio\_qspi/include/sdkconfig.h
* For Ubuntu:\
  Arduino root directory/.arduino15 (hidden file)/packages/esp32/hardware/esp32/2.0.12/tools/sdk/esp32/qio\_qspi/include/sdkconfig.h
  {% endhint %}

Append a line of code at the end of the file:

```cpp
#define CONFIG_DISABLE_HAL_LOCKS 1
```

### 2.3 Set up the board options

Please set up the board's upload speed, CPU frequency, etc, as shown in the picture below.&#x20;

There is a setting for the **Flash Size** and **Partition Scheme** among the options. For more information, refer to the next section.&#x20;

<figure><img src="/files/wzC46EwxIGDjVcKwEaSw" alt=""><figcaption></figcaption></figure>

### 2.4 Choose hardware partition

The **BiBoard V0** uses an ESP32 with a **16M** flash. To simplify, you can use the **default** **4 MB** partition map without a problem. There's plenty of programming space for the standard OpenCatEsp32 firmware.&#x20;

The **BiBoard V1** uses an ESP32 with a **4M** flash.

#### 4 MB partition

You can use the **Minimal SPIFFS (1.9MB APP with OTA/190KB SPIFFS)**. You can also use other partition schemes under the 4 MB flash limit, such as "No OTA" or "Huge APP".&#x20;

<figure><img src="/files/ZD0w7RMRATD8ehzC757t" alt=""><figcaption></figcaption></figure>

#### 16 MB partition

Suppose you want to fully utilize the 16 MB flash on **BiBoard V0** (it's unnecessary and takes longer to upload). You can read the user manual for the [Add hardware partition configuration option in Arduino IDE](https://guide.petoi.com/biboard/demo-applications/13.add-hardware-partition-configuration-option-in-arduino-ide).

### 2.5 Download the source code & install the library

{% hint style="info" %}
We keep updating the code as an open-source project. You can star-mark and follow our GitHub repository to get the newest features and bug fixes. You can also share your codes with worldwide OpenCatEsp32 users.&#x20;

You can check the update history information in the [**ChangeLog.md**](https://github.com/PetoiCamp/OpenCatEsp32/blob/main/ChangeLog.md)**.**
{% endhint %}

1. Download the ​OpenCatEsp32 repository from GitHub repository: <https://github.com/PetoiCamp/OpenCatEsp32>\
   We suggest you utilize GitHub’s version control feature. Otherwise, make sure you download the **WHOLE OpenCatEsp32 FOLDER** every time. All the codes have to be the same version to work together.&#x20;

<figure><img src="/files/J1dPxUacMfknKagtEw03" alt=""><figcaption></figcaption></figure>

2. If you download the Zip file of the codes, you will get an **OpenCatEsp32-main** folder after unzipping. Please rename it to **OpenCatEsp32** before opening the **OpenCatEsp32.ino** so that the two names match.&#x20;

{% hint style="warning" %}
No matter where you save the folder, the file structure should be:

![](/files/it5Ae2o7Ot6JhN9Hi28A)&#x20;
{% endhint %}

There are several **test\*\*\*.ino** codes in the **ModuleTests** folder. You can upload them separately to test specific modules (I recommend using **testBuzzer.ino** as your first test sketch).

3. Install the libraries
   * Download and install the [MU Vision Sensor library](https://github.com/mu-opensource/MuVisionSensor3) into the Arduino IDE.<br>

     <figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FrwlwHLV03mwtrtqVazop%252FmuLib.png%3Falt%3Dmedia%26token%3Df7721966-efb2-4388-9563-002c9aa93c3a&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=852f24b1&#x26;sv=2" alt=""><figcaption></figcaption></figure>

     <figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FRN0NyFXOV0ct9IOI0AqU%252FaddZipLib.png%3Falt%3Dmedia%26token%3D4803980c-41cf-406c-907c-3aaff81672ec&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=13cd3321&#x26;sv=2" alt=""><figcaption></figcaption></figure>

   * Install **ArduinoJson** in the Library Manager<br>

     <figure><img src="/files/IRiCEQUFLCVMECjd86bg" alt=""><figcaption></figcaption></figure>

     <figure><img src="/files/chUPMWLsfRiaSkCfylgo" alt=""><figcaption></figcaption></figure>

   * Install **WebSockets** in the Library Manager.<br>

     <figure><img src="/files/kDERHzH9sG2PSYjnqK2e" alt=""><figcaption></figcaption></figure>

### 2.6 [Connect to BiBoard](/quick-reference/upload-firmware#biboard) via USB type-C data cable

Set the serial port in the Arduino IDE:

<figure><img src="/files/i0UrTG4kz2OUwWUj58mb" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you cannot find the serial port after connecting to your computer:

* for BiBoard V0:

  You need to install [the driver](https://guide.petoi.com/technical-support/useful-tools/biboard-v1) for the CP210x chip.&#x20;
* For BiBoard V1:

  You need to install the driver as below:

  * Windows: <https://www.wch-ic.com/downloads/CH343SER_EXE.html>
  * Mac: <https://www.wch-ic.com/downloads/CH34XSER_MAC_ZIP.html>
* If the battery powers on the BiBoard, please long-press the button on the battery >=3s to power off the BiBoard, so that the BiBoard is only powered through the USB cable and only the blue LED is lit up.&#x20;
  {% endhint %}

### 2.7 Compile and upload the sketch

For Bittle or Bittle X:

<pre class="language-cpp"><code class="lang-cpp">#define BITTLE    //Petoi 9 DOF robot dog, also for Bittle X
<strong>//#define NYBBLE  //Petoi 11 DOF robot cat, also for Nybble Q
</strong>//#define CUB
</code></pre>

For Nybble or Nybble Q:

<pre class="language-cpp"><code class="lang-cpp">//#define BITTLE    //Petoi 9 DOF robot dog, also for Bittle X
<strong>#define NYBBLE  //Petoi 11 DOF robot cat, also for Nybble Q
</strong>//#define CUB
</code></pre>

Modify the mainboard model macro definition in OpenCatEsp3&#x32;**.ino** according to the mainboard (BiBoard) version.

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

If the robot(**Bittle X+Arm**) has the robotic arm, you should also activate the macro definition as follows:

<pre class="language-cpp"><code class="lang-cpp"><strong>#define ROBOT_ARM                 // for attaching the head clip arm
</strong></code></pre>

Otherwise, please comment out this line of code.

After the modification is completed, you can click the **Upload** button (as below) to upload the sketch **OpenCatEsp32.ino**, and the changes in the code file will be automatically saved.

<figure><img src="/files/tdpRznaQQrpxXC9osxpY" alt=""><figcaption></figcaption></figure>

### 2.8 Program Initialization

If the **version date** of the currently uploaded sketch is **newer** than the version date of the mainboard firmware, it will automatically enter the **Initialization Startup Mode** after the sketch upload is completed.

{% hint style="warning" %}
Please click the **Serial Monitor** button to open it and set the configuration parameters to **115200** baud rate and **No line ending**.
{% endhint %}

<figure><img src="/files/glEjFxmuYkPy8rRP367h" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/FR7Ns4IvrqMetC1dz3oR" alt=""><figcaption></figcaption></figure>

* You can check the version date of the currently uploaded sketch in the source code file (OpenCatEsp32/src/OpenCat.h):\
  `#define DATE "250218"  // YYMMDD`
* You can send the serial command "**?**" in the serial monitor to check the version date of the mainboard firmware:\
  ![](/files/cjbt1P99Ydx1pEjpJh8m)

When the mainboard is powered on, open the serial monitor and you will see the startup information:

```
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
```

{% hint style="info" %}
If you do not see the startup information after opening the serial monitor, please short press the **Reset** button on the mainboard.
{% endhint %}

Next you will see the following prompt questions:

```cpp
Reset the joints' calibration offsets? (Y/n): 
```

* Send '**Y**' to the question, which means resetting all servo corrections to zero.
* &#x20;Send "**n**" to skip this step.

{% hint style="info" %}
If you want to keep the previous joint calibration data, please send '**n**'.
{% endhint %}

```cpp
- Calibrate the Inertial Measurement Unit (IMU)? (Y/n): 
```

* Send '**Y**' to the question, which means calibrating the IMU, i.e. the gyro/accelerometer sensor.
* &#x20;Send "**n**" to skip this step.

{% hint style="info" %}
If you want to keep the previous IMU calibration data, please send '**n**'.
{% endhint %}

{% hint style="warning" %}
Halts at the connection stage. To restart it, you can close and reopen the serial monitor or press the reset button on BiBoard. Put the BiBoard **FLAT** on the table, and don't touch it during calibration.

Sometimes, the program halts at the connection stage. To restart it, you can close and reopen the serial monitor or press the reset button on BiBoard.&#x20;

The program starts calibration after playing the melody 6 times.
{% endhint %}

```
Run factory quality assurance program? (Y/n)        
```

Input '**n**' and press **Enter** to continue. Or you can do nothing, it will Auto skip in 5 seconds.

The details of serial port printing information are as follows：

```cpp
* 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

```

When the string "<mark style="color:green;">**Ready!**</mark>" is output in the serial monitor, the program will enter the **regular startup mode**.

Every time the mainboard is powered on, it compares the BIRTHMARK in the EEPROM to determine whether the program has been initialized. If the program has already been initialized, it will **not enter** the **initialization startup mode** again.

{% hint style="info" %}
**Note:** When the mainboard is powered on, the music melodies played in the **Regular Startup Mode** and the **initialization startup mode** are entirely different. This is convenient for users (no need to open the serial monitor) and can also identify the startup mode.&#x20;

If you need to clear the calibration parameters of the servo and recalibrate the joint servo, or recalibrate the IMU, you can send the serial command "<mark style="color:red;">**!**</mark>" in the serial monitor, and the program will **re-enter** the **Initialization Startup Mode**.
{% endhint %}

### 2.9 Switch working mode via the serial commands (Optional)

The default code runs the **Standard** mode (including the **Voice command** function). If you want to switch modes, Please open the serial monitor and send the following serial commands:

<table><thead><tr><th width="172">Serial command</th><th>Function</th></tr></thead><tbody><tr><td>XA</td><td>Voice. For <strong>BiBoard V0</strong>, the switch on the extension hat should be dialed to the <strong>Voice command</strong> side （<strong>default mode</strong>）</td></tr><tr><td>XU</td><td>Ultrasonic. For <strong>BiBoard V0</strong>, the switch on the extension hat should be dialed to the <strong>UART2</strong> side; voice control will not work.</td></tr><tr><td>XC</td><td>Camera</td></tr><tr><td>XL</td><td>Light</td></tr><tr><td>XT</td><td>Touch</td></tr><tr><td>XI</td><td>PIR</td></tr><tr><td>XG</td><td>Gesture</td></tr><tr><td>XD</td><td>IR distance</td></tr><tr><td>XQ</td><td>Quick demo</td></tr><tr><td>XS</td><td>Enable the Serial 2(Tx2, Rx2). For <strong>BiBoard V0</strong>, the switch on the extension hat should be dialed to the <strong>Uart2</strong> side; voice control will not work. </td></tr><tr><td>XB</td><td>Enable the back touch funtion. </td></tr><tr><td>X</td><td>Disable all the module functions above.</td></tr><tr><td>z</td><td>RandomMind (On/Off)</td></tr></tbody></table>

{% hint style="info" %}
The behavior of the official modules is defined in separate header files in **OpenCat/src/**. You can find them in **OpenCat/src/io.h** **-> readSignal()**. The behavior of **Quick demo** mode is defined in **OpenCat/OpenCat.ino ->  quickDemo()**. You can study the example code to write your functions.&#x20;

You can learn about the function of each module through the [**EXTENSIBLE MODULES**](https://guide.petoi.com/extensible-modules/introduction).
{% endhint %}

### 2.10 Power on

* Long-press the battery button and boot up the robot with one side up. It will enter the calibration state automatically in the **regular startup mode**. The picture below shows the head, the upper and lower legs installed after the robot enters the calibration state.

![](/files/mzq2t0vK9IyMU6MU2LJG)

Please refer to [Chapter 5 🔌 Connect Wires](https://bittle.petoi.com/5-connect-wires) and [Chapter 6 📐 Calibration](https://bittle.petoi.com/6-calibration) for the complete calibration process.

* If you power on the robot and it is upright (with its back facing up), it will start in the "rest" posture (fold the legs and unlock the servos) in the **regular startup mode**.

### 3. Configuration with App

The BiBoard has built-in Bluetooth, and you can connect it to the [mobile app](https://guide.petoi.com/mobile-app/introduction) for [joint calibration](https://guide.petoi.com/mobile-app/calibrator) and [remote control](https://guide.petoi.com/mobile-app/controller) (for **Bittle X**, which has the mainboard **BiBoard V0**).


# Serial Monitor

## Mainboard connection

* Wired Connection: The kit includes a **USB Type-C data cable** connecting the robot's mainboard to the computer.
* [Wireless Connection(Bluetooth)](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard): The mainboard's built-in Bluetooth module lets you connect the robot's mainboard to your computer wirelessly.

## Set up in the Arduino IDE

1. Select the port in the [Arduino IDE](https://www.arduino.cc/en/software)(recommended version **1.8.19**).

![](/files/HzLGPoEbbiAkP6ySVyut)

{% hint style="info" %}
If you can't determine which port is correct, unplug and re-plug the USB data cable on the computer side and check the difference in the ***Tools*** menu.

You may install the [drivers](https://guide.petoi.com/technical-support/useful-tools) if no new port is shown in the menu list.
{% endhint %}

2. Open the serial monitor.

You can choose the "Serial Monitor" in the ***Tools*** menu bar or click the ![](/files/rFegvOusKIAfaewQ5pHB) Button to open the serial monitor window:

![](/files/3qVD0VPFEtSelxddsD66) ![](/files/NfoeNDc4SxSFe0pPUCuq)

3. Configure the parameters of the serial monitor.

In the serial monitor, set "***No line ending***" and the baud rate to ***115200***.&#x20;

![](/files/HqQm5fVMgFHfBfpSG7WR)

With the USB adapter / Bluetooth module connecting NyBoard and computer, you have the ultimate interface - **Serial Monitor** to communicate with NyBoard and change every byte on it(via sending the serial commands based on the [serial protocol](https://guide.petoi.com/apis/serial-protocol)).


# Calibrate the joints with Arduino IDE

## Prepare to Enter the Calibration Mode

Please refer to the [preparation section](https://guide.petoi.com/quick-reference/joint-calibration#prepare-to-enter-the-calibration-state) in the Joint Calibration.

## The rationale for calibration

### Understand the zero state and the coordinate system

After sending the serial command ‘**c**’ in the serial monitor, the robot will [enter the calibration mode](#enter-the-calibration-mode), with all servos rotated to their zero positions. Then, attach the head, tail, and legs prepared in the previous section to the body. They are generally perpendicular to the body frames they are linked to.

#### Bittle X's Calibration mode

<figure><img src="/files/s84JN6ZSNOe6iC01ubet" alt=""><figcaption><p>Bittle's Calibration Mode</p></figcaption></figure>

For the construction kit, please install the servo-related components as shown in the picture (calibration mode) and ensure they are perpendicular to each other (the upper leg is perpendicular to the torso, and the lower leg is perpendicular to the upper leg).

{% hint style="warning" %}
Note: Insert the servo-related components directly into the servo output shaft; do not turn the output shaft during this process.
{% endhint %}

Rotating the limbs counterclockwise from their zero states will be positive (the same as in polar coordinates). Viewed from the left side of the robot's body, the counter-clockwise rotation of the joint is defined as the positive direction.

{% hint style="info" %}
The only exception is the head tilt angle for Nybble. It’s more natural to say head up, while it’s the result of rotating clockwise.&#x20;
{% endhint %}

{% hint style="info" %}
However, from the right side of the robot's body, the rotation directions' positive and negative are just opposite.
{% endhint %}

### Discrete angular intervals

If we look closer at the servo shaft, we can see it has a certain number of teeth. That’s for attaching the servo arms and avoiding sliding in the rotational direction. In our servo sample, the gears divide 360 degrees into 25 sectors, each taking **14.4** degrees(offset of -7.2\~7.2 degrees). That means we cannot always get a perfect perpendicular installation.&#x20;

![](/files/v400iIvlmpXjiobnloRS)

## Calibration process

### Enter the calibration mode

You must double-check the position and direction of all servos.&#x20;

&#x20;Send the serial command ‘**c**’ in the serial monitor to enter the calibration mode.  Depending on their initial shaft direction, some may travel larger angles until stopping at the middle point.  There will be noise coming from the gear system of the servos. You will see a calibration table like the following:

![](/files/hd4pjWyGSWw4VOVwbSh1)

The first row is the joint indexes; the second row is their calibration offsets:&#x20;

| **Index**  | 0  | 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8  | 9  | 10 | 11 | 12 | 13 | 14 | 15 |
| ---------- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
| **Offset** | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 |

Initial values are “-1” or “0” and should be changed by later calibration.&#x20;

{% hint style="info" %}
The servos use a potentiometer in the feedback loop for position control. When held at a static position, they tend to vibrate around the target angle. A Parkinson 's-like vibration will develop after a short period of use. It won’t affect much during continuous motion. Better servos without these troubles could cost 10 times more, so replacing a failed unit is a more cost-effective solution. &#x20;
{% endhint %}

### Attach body parts to the servos

For the contruction kit, please refer to the subpage of [**Joint Calibrator**](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-desktop-app/joint-calibrator#installing-and-fine-tuning) as abov&#x65;**.**

### Fine-tune the calibration using the serial monitor

#### 1. Joint Control Commands

The command for fine-tuning calibration (refer to the [serial protocol](https://guide.petoi.com/apis/serial-protocol)) is formatted as `cIndex Offset`. Notice that there’s a space between cIndex and Offset.&#x20;

<figure><img src="/files/parvvv9mSALj4nWqNRft" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/6QsnrSmTOVsBl0Y1ZarV" alt=""><figcaption></figcaption></figure>

For example :

* `c8 6` This means giving the 8th servo an offset of 6 degrees.&#x20;
* `c0 -4` This means giving the 0th servo(the head) an offset of -4 degrees.&#x20;

{% hint style="warning" %}
The resolution of the correction amount is 1 degree; do not use decimals.
{% endhint %}

{% hint style="info" %}
If you find the absolute value of offset is more significant than 9, you are not attaching the limb closest to its zero states. That will decrease the servo's reachable range on either side. Please take off the limb and rotate it by one tooth. It will result in an opposite but smaller offset.&#x20;
{% endhint %}

{% hint style="info" %}
For example, if you have to use -9 as the calibration value, remove the limb, rotate it by one tooth, and then attach it back. The new calibration value should be around 5, i.e., the sum of their absolute values is 14. Avoid rotating the servo shaft during this adjustment.&#x20;
{% endhint %}

Find the best offset that can bring the limb to the zero states.  It's a process of trial and error.

{% hint style="info" %}
For the robotic arm, you can use the serial command "**c-2**" to [auto-calibrate](https://docs.petoi.com/extensible-modules/robot-arm#fine-calibration) the robotic claw joint.
{% endhint %}

After calibration, **remember to type ‘s’ to save the offsets**. Otherwise, they will be forgotten when exiting the calibration state. You can even save every time after you’re done with one servo.&#x20;

#### 2. Use ‘L’ shaped joint tuner

When watching something, one's observations will change from different perspectives. When measuring length, one always wants to read directly above a referencing ruler.&#x20;

You must keep a parallel perspective when calibrating the robot. Use the 'L'-shaped joint tuner as a parallel reference to avoid reading errors. Align the tips on the tuner with the center of the screws in the shoulder and knee joints and the little hole on the tip of the foot. Look along the co-axis of the centers. For each leg, calibrate the shoulder servos (index 8\~11) first, then the knee servos(index 12\~15). When calibrating the knee, use the matching triangle windows on both the tuner and shank to ensure parallel alignment.&#x20;

{% hint style="info" %}
The **pre-assembled** robot should already have the components adequately installed. You can do the joint calibration for fine-tuning directly, without needing to uninstall the head and legs.&#x20;
{% endhint %}

Please use the L-shaped calibration tool included in the package as a calibration reference. According to the joint numbers shown in the calibration interface picture, click and drag the corresponding joint sliders or click the blank areas of the slider tracks to fine-tune the joints to a right angle.

Please note that when calibrating the servos, adjust the upper leg first, then change the lower leg.

![](/files/0HXBQK8Fem9hj1AmppKy)

![Align the upper leg first](/files/QpS91FEEbFx1kWR8Yofo)

![Pay attention to the reference edges for the lower leg](/files/kuwZZVGFrrkgDo4rhGiH)

{% hint style="info" %}
If the offset is more than +/-9 degrees, you need to remove the corresponding leg and reinstall it by rotating one tooth and then dragging the corresponding slider. For example, when it is adjusted to +9 and still not right, remove the corresponding leg and shift one tooth when attaching it. Then, you should get a smaller offset in the opposite direction.&#x20;
{% endhint %}

#### 3. Testing and validation

After calibration, send the serial commands: ‘**d**’, ‘**kup**’,  and '**kwkF**' to validate the calibration. This will result in the robot symmetrically moving its limbs between the rest, stand states, and walk gait. &#x20;

{% hint style="warning" %}
You may need to do a few rounds of calibrations to achieve optimal states.
{% endhint %}

#### 4. Install the screws for the construction kit

After completing the joint calibration, install the center screws to fix the components and servo gears.

#### 5. Center of mass

Try to understand how the robot keeps its balance even during walking. If you add new components to the robot, distribute its weight symmetrically about the spine. You may also need to slide the battery holder back and forth to find the best balance spot. Because the battery is heavier at the front, you can insert it in the opposite direction to shift the center of mass farther back.&#x20;

{% hint style="info" %}
You may need to recalibrate if the center of mass changes.&#x20;
{% endhint %}

Please do not force the robot to lift heavy objects, as this may cause the servos to sweep or get stuck.


# Install Arduino IDE on Chromebook

After [**turning on Linux**](/technical-support/set-up-development-environment-on-chromebook) on the Chromebook, you can access the Linux environment via the terminal app.

Please follow the following steps to install the Arduino IDE:

## Check the type of your OS version

<figure><img src="/files/Fy6jFs5A2deqjAWB6ec3" alt=""><figcaption></figcaption></figure>

## Download package

Open the website ([www.arduino.cc/en/software](https://www.arduino.cc/en/software)) and download the corresponding type of Legacy Arduino IDE:

<figure><img src="/files/qZTrJYJpye9JkGlmAy6q" alt=""><figcaption></figcaption></figure>

## Installation

After downloading complete, set the folder ***Downloads*** in the file browser to share with Linux, as mentioned above. Use the following commands to install the **Arduino IDE,** e.g., ***arduino-1.8.19-linux64.tar.xz*** is the downloading file.

```
cd /mnt/chromeos/MyFiles/Downloads/
sudo apt-get install xz-utils
sudo tar -C /opt -xf arduino-1.8.19-linux64.tar.xz
cd /opt
ls
cd arduino-1.8.19/
ls
sudo ./install.sh
```

## Set up the Arduino IDE development environment for the mainboard

You can open the **Arduino IDE** as follows:

<figure><img src="/files/Ek7txzYIkbwUxU8CPp47" alt=""><figcaption></figcaption></figure>

After using the USB data cable to connect the BiBoard and Chromebook, you will see a prompt: Please click ***Connect to Linux*****.**

<figure><img src="/files/Nt2E99Bos1ByKfFL8C23" alt=""><figcaption></figcaption></figure>

and check in the **Settings** interface, and it should be enabled as follows:

<figure><img src="/files/0JzLQ0XvA2qDbjdWiG3M" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/CpjbjAH0VsYoCQZdZkeH" alt=""><figcaption></figcaption></figure>

Use the following commands to install the library pyserial for uploading the sketch for BiBoard

```
sudo apt install python3 pip
python3 -V
pip -V
cd /usr/lib/python3.11/
sudo rm EXTERNALLY-MANAGED
sudo pip3 install pyserial
pip list
```

{% hint style="info" %}
After downloading the project file **OpenCatEsp32-main.zip** from GitHub: <https://github.com/PetoiCamp/OpenCatEsp32>, use the following commands to unzip it to the ***Downloads*** folder.

<pre><code><strong>cd /mnt/chromeos/MyFiles/Downloads/
</strong>sudo apt-get install unzip
unzip OpenCatEsp32-main.zip
</code></pre>

{% endhint %}

For how to upload the sketch, please refer to [Upload Sketch for BiBoard](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard).


# Bittle X V2+Arm

**Bittle X+Arm** is an open-source, voice-controlled robot dog. It's a new breed of robotics dog for everyone to learn and play with.

<figure><img src="/files/O6pbutZBS01v5dU1Nl5d" alt=""><figcaption></figcaption></figure>

The small but mighty robot has these amazing features:

* Respond to voice commands, performing over **35 predefined actions** such as sit, push-up, and backflip with high-performance, lifelike movements. You can switch between English and Chinese using simple voice commands.&#x20;
* Can be programmed with **10 more customized voice commands** to perform skills you create. The voice command can be any sound, so it is not necessary to be mapped to any spoken language.&#x20;
* Support  **Petoi** **Coding Blocks and Petoi Web Coding Blocks(block-based Scratch-like), C++, and Python**.
* **Free** [C++](https://www.petoi.com/pages/free-cplusplus-quadruped-robotics-curriculum) and [Petoi Coding Blocks](https://www.petoi.com/pages/free-quadruped-robotics-curriculum-scratch-coding)(block-based Scratch-like) **curriculums**.
* Equipped with BiBoard V1, a high-performance **ESP32** development board supporting additional modules for robotics/AI/IoT applications.
* Support feedback servos for easy robotics skill creations
* Built-in gyroscope and back touch sensor for intuitive human-robot interactions.

If you have questions about “why” rather than “how”, please post on [our forum](https://www.petoi.camp/) or [contact us](https://www.petoi.com/pages/contact-us).

{% hint style="info" %}
There are some [supporting applications and software](https://docs.petoi.com/technical-support/supporting-application-and-software) and [FAQ](https://docs.petoi.com/technical-support/faq-frequently-asked-questions) for your reference.
{% endhint %}

You can support us by shopping at [Petoi Coding Robot Shop](https://www.petoi.com/store).

Our social media (Instagram/Twitter/Facebook/GitHub) account is **@PetoiCamp**.&#x20;

Share your build by tagging **#bittle\_x+arm #petoi #opencat** so that we can repost it for you!&#x20;

{% hint style="info" %}
Last Updated: 04/22/2025
{% endhint %}


# Quick Start Guide

The **Quick Start Guide** section is primarily designed to help you verify that the product is complete after receiving it and to enable you to quickly boot up and use the robot. It includes three parts:&#x20;

1. [**Unboxing**](/product/bittle-x-v2+arm/quick-start-guide/unboxing)&#x20;
2. [**Assembling (for construction kit version only)**](/product/bittle-x-v2+arm/quick-start-guide/assembling)
3. [**Boot up**](/product/bittle-x-v2+arm/quick-start-guide/boot-up)

**Need help?** Check out our [**FAQ**](/faq-frequently-asked-questions).


# Unboxing

## Check the packaging

Thank you very much for purchasing our product! We highly value your user experience and hope you can begin this enjoyable journey smoontly. To ensure the device was not damaged during transportation and to guarantee all accessories are complete, we recommend that you follow these steps after receiving the package:

1. Please verify the recipient's name, address, order number, and other information on the product packaging to ensure it matches your order. If any information is incorrect, please do not open the box and [contact us](https://www.petoi.com/pages/contact-us) immediately.
2. Please inspect whether the packaging box is intact and undamaged, and whether there are any obvious signs of damage, dampness, deformation, or tampering. If you find any damage to the packaging box, please take photos for evidence and, before confirming the device is intact, avoid signing for or opening the box. As shown in the figure below, the robot kit you receive should have an intact appearance, be free of any damage, and remain clean and tidy.
3. If you are unsure whether you've received the correct package, please refer to [this guide](https://www.petoi.com/blogs/blog/how-to-tell-if-you-have-received-the-correct-bittle-bittle-x-robot-dog).

<figure><img src="/files/caIo0uiFqHJFKArRad6t" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/QM5exwOOEkuHrYQ6aYby" alt=""><figcaption></figcaption></figure>

## Open the box

### Pre-assembled package

<figure><img src="/files/fGqKL7nqjkQI4wCINpl3" alt=""><figcaption></figcaption></figure>

### Construction package

<figure><img src="/files/6dgv65raQiSa5C1pLp9I" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**Construction package?** Start here:[ Assembly Guide](/product/bittle-x-v2+arm/quick-start-guide/assembling).
\
(The steps below are for the pre-assembled version.)
{% endhint %}

## Item list

### Pre-assembled version

<table><thead><tr><th width="487.390625">Name</th><th>Quantity</th></tr></thead><tbody><tr><td>Main Unit: Bittle X+Arm robotic dog</td><td>1</td></tr><tr><td>Assembly Components: Calibrator part</td><td>1</td></tr><tr><td>Manual: Stickers/Postcard (with voice commands on the back)/Calibrator manual</td><td>1</td></tr><tr><td>Tools: Self-tapping screwdriver/USB cable</td><td>1</td></tr><tr><td>Spare Parts: Spare servo/Raspberry Pi mount/Springs &#x26; screws</td><td>1</td></tr></tbody></table>

#### Assemble the robotic arm

This robotic arm is already fully assembled. You need to install the servo with the neck structure in the servo slot with two M2\*5 self-tapping screws.

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252Ft8gnaABbmIwaMjHivgYX%252FNeck.jpeg%3Falt%3Dmedia%26token%3D83a08d4b-db61-4635-ac52-8c7a69d61d06&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=4addb956&#x26;sv=2" alt=""><figcaption><p>Install the robotic arm</p></figcaption></figure>

#### Assemble the Optional Bittle Stand

We have designed a dedicated support stand to ease Bittle family robot debugging and avoid falls. Please assemble the stand as shown in the illustration. Afterward, carefully place the robot onto the stand. Small clasps are present to provide a more secure connection between them.

<figure><img src="/files/7lrmMsIHyfbydDJMahl2" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/0Uc8dALIg55A2PeklJ2C" alt=""><figcaption></figcaption></figure>

#### Battery

When the battery is low (indicated by a red LED on the battery) or during replacement, the battery must be detached from the body.

The battery connects to the body chassis via a latched sliding slot. To detach it, push the battery horizontally along the slot's direction.

<figure><img src="/files/NFwmvZ2QEYcsCVGyi7GL" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Note:&#x20;

Attaching the battery and detaching the battery are reverse processes.

Please ensure that the battery's charging port aligns with the direction of the robot's head to better balance its body during movement.

![](/files/QqzvxEfll2rCzAPOXi8D)
{% endhint %}

{% hint style="warning" %}
Note:&#x20;

Attaching the battery and detaching the battery are reverse processes.

Please ensure that the battery's charging port aligns with the direction of the robot's head to better balance its body during movement.

{Picture of attached battery}
{% endhint %}

#### Back cover

<figure><img src="/files/UbY3Gl9dIdnji8IRNc6h" alt=""><figcaption><p>open the back cover</p></figcaption></figure>

#### The touch sensor inside of the back cover

For the Bittle X V2 with BiBoard V1, there is a flexible printed circuit (FPC) attached to the inside of the back cover for touch functionality. Under normal circumstances, there is no need to remove it. If you wish to detach the back cover FPC from the microcontroller completely, please follow these steps:

After opening the back cover, note the relative orientation between the microcontroller (BiBoard V1) and the back cover. There is a flip tab on the connector - lift this tab upward. Once the tab is flipped open, the cable beneath it can be fully detached along with the back cover and microcontroller.

Reconnecting the cable to the mainboard is the reverse process: align the cable, ensuring proper orientation, and press it firmly into place.

<figure><img src="/files/arOUCLJU5A7RyweljS5f" alt="" width="563"><figcaption><p>Back Cover for Bittle x</p></figcaption></figure>


# Assembling

"The whole is more than the sum of its parts." 🔩

## Item list

### Construction kit

<table><thead><tr><th width="592.2374267578125">Name</th><th>Quantity</th></tr></thead><tbody><tr><td>Main Frame: Body/Neck/Head/Arm/Upper Leg (pre-assembled x4)/Lower Leg Piece (x4)</td><td>1</td></tr><tr><td>Assembly Components: Calibrator part</td><td>1</td></tr><tr><td>Servo: P1S servo with long cable x5/P1S servo with short cable x5</td><td>10</td></tr><tr><td>Electronics: BiBoard (ESP32)/Rechargeable Battery/USB Cable</td><td>1</td></tr><tr><td>Tools: Self-tapping screwdriver/M2*8 screws</td><td>1</td></tr></tbody></table>

After verifying all components listed above, please proceed for detailed assembly instructions. You will learn more about the robot's design and structure through the assembly process.

Watch the Bittle [assembly animation ↗](https://youtu.be/G2RDNbek7CQ) for a quick overview, or follow this detailed [hands-on tutorial ↗ ](https://youtu.be/oJ2Y9hZgCEY)to build Bittle from the construction kit.

### Neck

You must use the neck section with a J-hook (as pictured below) to avoid the neck from falling when using this robot arm.

<figure><img src="/files/t8pKzAzCsZTioctL4P1S" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Required parts:

* Neck × 1
* Servo arm × 1
* M2x8 sharp-end self-tapping screws × 2

<img src="/files/hUuTtTwsZJn0KPj2hwtJ" alt="" data-size="original">
{% endhint %}

Put the servo arm in the neck part like the figure below. The teeth of the servo arm should face upward.

{% columns %}
{% column %}

<figure><img src="/files/57iJbTmDGgEg1KaCELQ1" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/Vmwou2ZAGexk2F04vcOo" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Screw two M2x8 self-tapping screws beside both sides of the servo arm. Don't over tighten the screws.

{% columns %}
{% column %}

<figure><img src="/files/nUVauUSCy5DAqxuMXDPF" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/o1c0lkcKeG7ylOvzj4m8" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% hint style="success" %}
Your neck assembly should look like this:

![](/files/vOfKel5bNDZwajunVwrU)
{% endhint %}

### Body

{% hint style="info" %}
This part is now fully assembled in the package.

**Includes：**

* Assembled neck × 1
* Chasis × 1
* Front and back plate × 2
* Side shoulder × 2

![](/files/Vap6eJcMKChq4DFMh5cp)
{% endhint %}

Recognize the front and back side of the chassis. The location of the two large holes along the center track makes a difference. In our standard configuration, we define the holes to be shifted towards the tail. You can also find a small mark "A1" in the front of the chassis.

{% columns %}
{% column %}

<figure><img src="/files/ajF0l7VrRPVcEGLxyP7n" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/y4WIHo1gcUbDDIzQiVxG" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Push the back tip of the assembled neck into the slot of the chassis. Then press down the front hook until you hear a snap sound.

{% columns %}
{% column %}

<figure><img src="/files/WYbEu9MrgDfabVWq5irD" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/LwlKpVaRqsERPhTuASI4" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Insert the chassis into one of the side shoulders.

{% columns %}
{% column %}

<figure><img src="/files/E3wOllTOKHJtJ2e0EROI" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/8bLCcvvy5CFYKLaszMno" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Insert the front or back plate into the side shoulder. There are three tenons on each side of the plate. Insert the two front tenons as one group for better alignment.

{% columns %}
{% column %}

<figure><img src="/files/FWmSsM06nUAY1ixFuROR" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/qwPOUroX0CuBojpaBM38" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

Insert both the front and back plates. Plug the other side shoulder to complete the body. Again pay attention to the alignment of the tenons of the front and back plates.

{% columns %}
{% column %}

<figure><img src="/files/8TFhET98TaGjTE3mJOJq" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/M4hJJM1NMsS7wC6A6rLR" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

{% hint style="success" %}
You body assembly should look like this:\
![](/files/Csdy0T1cjBiSRznAYvOa)
{% endhint %}

### Upper leg

{% hint style="info" %}
The upper leg has been pre-assembled in batches after 2022.   We leave it here in case you need to reassemble it.
{% endhint %}

<figure><img src="/files/JpqzkfXuyPY9ri1nyuy5" alt=""><figcaption></figcaption></figure>

This assembly is best demonstrated visually—check the [instruction video at 3:23 ↗](https://youtu.be/oJ2Y9hZgCEY?t=203) for the proper technique. Use finesse, not force! For more tips on installing springs with different tools, check out this [forum post ↗](https://www.petoi.com/forum/basic-assembly-and-setup/just-got-my-bittle-kit-can-t-install-springs).

### Lower leg

{% hint style="warning" %}
There are five servos with long cables and five servos with short cables. The lower legs all need servos with long cables.
{% endhint %}

{% hint style="info" %}
Required parts:

* P1S servo with **long** cable × 4
* Lower leg piece × 4
* M2x8 self-tapping screw × 8

<img src="/files/xYrLRgz5oThzWz4pofFD" alt="" data-size="original">
{% endhint %}

Assemble the right leg. Insert the servo into the window and route the wire through the notch on the internal edge. Refer to the tutorial video for the correct wire folding direction. Secure the servo to the lower leg with two M2×8 screws.

{% columns %}
{% column %}

<figure><img src="/files/nA1hDpAozmoOBhJkIa8O" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/KfcWVyqX9f6CRapBPS3x" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/8yTNIM0zGsBUxiw4hCHj" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

The left and right legs are built as mirror images, but the front and back legs are identical. You'll assemble two mirrored pairs of legs — one pair for the front and one pair for the back.

{% hint style="success" %}
One pair of legs should look like this:

<img src="/files/SxGxvXgp86kBjTOEPQBp" alt="" data-size="original">
{% endhint %}

### Robot arm

{% hint style="info" %}
This robot arm is already fully assembled.
{% endhint %}

Use the neck part with a J-hook (shown below) for the robot arm assembly.

<figure><img src="https://guide.petoi.com/~gitbook/image?url=https%3A%2F%2F4130507397-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FXLpFdG7mubqEHWylLK3w%252Fuploads%252FZBkrY6MJfvln4ARxCRZP%252Fimage.png%3Falt%3Dmedia%26token%3D50166897-73d9-4721-a453-02472a8c2b00&#x26;width=300&#x26;dpr=4&#x26;quality=100&#x26;sign=f3e338ee&#x26;sv=2" alt=""><figcaption></figcaption></figure>

Install the servo with the neck structure in the servo slot with two M2\*5 self-tapping screws.

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252Ft8gnaABbmIwaMjHivgYX%252FNeck.jpeg%3Falt%3Dmedia%26token%3D83a08d4b-db61-4635-ac52-8c7a69d61d06&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=4addb956&#x26;sv=2" alt=""><figcaption><p>Install the robotic arm</p></figcaption></figure>

### Head (Optional)

If you purchase the head optionally, you can follow these steps:

{% hint style="warning" %}
There are five servos with long cables and five servos with short cables. The head needs a servo with a short cable.
{% endhint %}

{% hint style="info" %}
Required parts:

* P1S servo with **short** cable × 1
* Chin × 1
* Skull × 1
* M2x8 self-tapping screw × 2
  {% endhint %}

Put the servo in the chin as shown in the figure. Pay attention to the direction of the servo's wire. After that, install two M2x8 self-tapping screws.

{% columns %}
{% column width="8.333333333333332%" %}

{% endcolumn %}

{% column width="83.33333333333333%" %}

<figure><img src="/files/7WcJL8HdhKmYaIq4lY5b" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column width="8.333333333333321%" %}

{% endcolumn %}
{% endcolumns %}

Insert the skull into the chin so that it can rotate and bite on small gadgets. It is advisable to apply some lubricant to the contact points.

{% columns %}
{% column width="8.333333333333332%" %}

{% endcolumn %}

{% column width="83.33333333333333%" %}

<figure><img src="/files/j5iUBmOmWwZ7nf66GXN8" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column width="8.33333333333336%" %}

{% endcolumn %}
{% endcolumns %}

{% hint style="success" %}
Your head assembly should look like the figure above.
{% endhint %}

### Shoulder servo

{% hint style="warning" %}
There are five servos with long cables and five servos with short cables. The upper legs all need servos with short cables.
{% endhint %}

{% hint style="info" %}
Required parts:

* P1S servo with **short** cable × 4
* M2x8 self-tapping screws × 8
* Head (assembled)
* Body (assembled)
* Lower leg (assembled) × 4
  {% endhint %}

Put the head, body, servos, and lower legs like the figure below. Insert the short servo wires through the servo slots on the side shoulders. Pay attention to the direction of the servos carefully and place them in the correct configuration.

{% columns %}
{% column %}

<figure><img src="/files/i1slSlp1EmyN1q20Y6fY" alt=""><figcaption><p>Side view </p></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/9MOnK9FDUZvdDyLa1h60" alt=""><figcaption><p>Top view</p></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

You also need to insert the wire of the head servo into the body.

After confirming all the components ' directions, put the short wire servos into the side shoulders. Pay attention to the directions of the shoulder servos’ output shaft. The long wires of the lower leg servos should be inserted into the opening between the shoulder servo and the shoulder window. Use two M2x8 self-tapping screws to fix each should servo.

Repeat the above assembly for the hip servos.

{% columns %}
{% column width="16.666666666666664%" %}

{% endcolumn %}

{% column width="66.66666666666667%" %}

<figure><img src="/files/gaCNmnJbaZUP7wThkelB" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column width="16.66666666666665%" %}

{% endcolumn %}
{% endcolumns %}

{% hint style="warning" %}
Please note the direction of the shoulder servo:

![](/files/Fqckos38NuUuUsczOV8b)
{% endhint %}

### Connect wires

<figure><img src="/files/TiWGIxbc5wk9DdSYQdYx" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
A servo plug has three wires. Plug it in the right direction, or you may burn the chip. The color of the wires may vary across models. However, the darkest-colored wire (Black or Brown) is always the GND (ground) wire by convention. The GND wire should be plugged closest to the board.&#x20;
{% endhint %}

{% hint style="danger" %}
The index number of the joint servo has **no corresponding relationship** with the PWM pin number on the main board. **You don't even need to read the pin numbers on the PCB board.**&#x20;
{% endhint %}

The wiring between the leg servos and the main board can be found in the Bittle X V2 video tutorial.

{% embed url="<https://youtu.be/A2RM1tplOtM>" %}

### Battery

Insert the battery plug into the power socket under the body. Then place the battery in the direction shown in the figure below, aligning with the mounting holes:

{% columns %}
{% column %}

<figure><img src="/files/0VicFSZwbiKjAWJ8tBpO" alt=""><figcaption></figcaption></figure>
{% endcolumn %}

{% column %}

<figure><img src="/files/w1QLnJWNQ1cBqfW1WsF9" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

The battery connects to the body chassis via a latched sliding slot. To detach it, push the battery horizontally along the slot's direction.

<figure><img src="/files/NFwmvZ2QEYcsCVGyi7GL" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Note:&#x20;

Attaching the battery and detaching the battery are reverse processes.

Please ensure that the battery's charging port aligns with the direction of the robot's head to better balance its body during movement.

![](/files/QqzvxEfll2rCzAPOXi8D)
{% endhint %}

{% hint style="success" %}
Press and hold the battery button for more than 3 seconds. If the red indicator light is on, charge the battery until the green light turns solid before use.\
Once powered on, the yellow and blue LEDs on the BiBoard will light up simultaneously.

<img src="/files/sojFNmpXxVKelOt4I5T0" alt="" data-size="original">
{% endhint %}

### Calibration required

{% hint style="warning" %}
After completing the assembly, you must calibrate the robot joints before use. Proper calibration ensures accurate movement and prevents damage to the servos.
{% endhint %}

➜ [\[Go to Joint Calibration\]](/quick-reference/joint-calibration)


# Boot up

## The posture before boot up

Drag the curly wire from the knee side to the shoulder side to avoid squeezing when the knee joints rotate. Put the joints into the following posture before turning on the power.&#x20;

<figure><img src="/files/MN00wSPP43uKhbSu1ynf" alt=""><figcaption></figcaption></figure>

## Power

Long-press the battery button for 3 seconds to turn on/off. You will hear a short melody, and the battery indicator will turn blue. If the indicator is red, please take a look at the [charging method ](/product/bittle-x-v2+arm/quick-start-guide/boot-up#charging)below.

{% hint style="info" %}
After turning on the battery, the robot requires approximately 5 seconds for initialization, after which a melody will play.

The robot's battery charge may decrease during storage and transportation. Please ensure the battery is fully charged when using it for the first time.

It is recommended that the robot be placed on the calibration stand before pressing the button to activate the battery (Optional).

If you use the robot on the floor, please ensure it's upright after activating the battery. Otherwise, upon start-up, it will continuously attempt to flip itself over or perform other corrective motions.

If the robot is placed on its side when powered on, it will automatically initiate the calibration posture.
{% endhint %}

### Battery Indicator

Before you use it, please read the instructions on the bottom of the packaging box carefully to check the battery.  Note that the battery charging port is on the battery, not on the robot's microcontroller.

<figure><img src="/files/fjYJVm8NDbU2KTSSw6ID" alt=""><figcaption><p>            Low Power                                                          Full Power                                                   Intermediate Power</p></figcaption></figure>

\
During charging, the indicator light turns <mark style="color:red;">red</mark>; after charging is complete, it turns <mark style="color:green;">green</mark>.\
Press the blue button briefly to check the battery status:

· When fully charged, short-press the button on the battery, the indicator light is <mark style="color:blue;">blue</mark>.

· When the voltage is low, the indicator light is <mark style="color:red;">red</mark>.

· During battery depletion, the indicator color gradually changes from blue to red.

Note the correct use of battery interfaces: use the Type-C interface for charging, and the 2P 2.54 mm red-black wire terminal interface to connect to BiBoard and power the robot. Please don't mix them up.

If the robot detects a low battery, it will pause its movements and beep. You must detach and charge the battery using a standard 5V USB Type-C interface data cable. The battery will automatically stop supplying power to the robot during charging for safety reasons.

## Buzzer Sound Types

<table><thead><tr><th width="181.00006103515625">Sound</th><th width="246.2000732421875">Trigger Timing</th><th>Indication</th></tr></thead><tbody><tr><td>Short melody [1]</td><td>Power on or restart </td><td>The program startup was successful</td></tr><tr><td>Short beep</td><td>During use</td><td>The Program received a command</td></tr><tr><td>Repetitive melody [2]</td><td>During pauses in use or action</td><td>Low battery or battery not connected</td></tr></tbody></table>

{% hint style="warning" %}
Note: Please **ignore** the microcontroller type used in the video; the buzzer sounds and their interpretations are relevant to all Petoi robot models.
{% endhint %}

{% embed url="<https://youtu.be/DrSsbd84ryo>" %}
Buzzer sounds
{% endembed %}

\[1]. The startup melody in normal mode starts at **00:13** in the video below.

\[2]. The repetitive melody starts at **00:21** in the video below.

## Other Situations

### Charging

The robot's battery socket has limited dimensions, so when the battery is installed on the battery seat, it cannot be directly charged via USB. The battery needs to be detached from the battery socket before charging.

{% hint style="info" %}
Before charging, please turn off the battery (long-press the battery button for 3 seconds). After connecting the charging cable, the battery will automatically shut down (cease external power supply).
{% endhint %}

{% hint style="warning" %}
Please do not confuse the microcontroller's upload port with the battery charging port.
{% endhint %}

### Device Freezing or Unresponsive <a href="#device-freezing-or-unresponsive" id="device-freezing-or-unresponsive"></a>

There are two solutions：

1\. Check the battery indicator light. If the battery level is too low, please charge it immediately.

2\. If the battery level is normal, remove the back cover and press the reset button on the motherboard next to the LED logo to reboot the robot.

<figure><img src="/files/ZCiUpRxaGlhJjGY3K0wa" alt=""><figcaption></figcaption></figure>


# Control & Program

### Control

* [Voice Command](/product/bittle-x-v2+arm/control-and-program/voice-command)
* [Mobile App](/product/bittle-x-v2+arm/control-and-program/mobile-app)
* [Optional Joystick Controller with Micro:Bit](/product/bittle-x-v2+arm/control-and-program/joystick-with-micro-bit)

### Set up & Build Robotics Skill Visually

* [Petoi Desktop App](/product/bittle-x-v2+arm/control-and-program/petoi-desktop-app)

### Programming

* [Petoi Web Coding Blocks](/petoi-web-coding-blocks/get-started-create-your-first-block-program)
* [Petoi Coding Blocks](/product/bittle-x-v2+arm/control-and-program/petoi-coding-blocks)
* [Python](/apis/python-api)
* [C++](/apis/c++-api) on [Arduino IDE](/product/bittle-x-v2+arm/control-and-program/arduino-ide)
* [Play with feedback servos](/apis/serial-protocol/feedback-servos)
* [Sensor & module programming](/extensible-modules/introduction)
* Various application project demos(see the Applications section on the sidebar)
* Various APIs for advanced users(see the APIs section on the sidebar)

### Curricula

Here are [all the free Petoi curricula](https://bit.ly/petoicur) and [some curricula developed by our community](https://www.petoi.com/blogs/blog/tagged/showcase+curriculum).

### Video tutorials

* [Petoi Skill Composer](https://www.youtube.com/playlist?list=PLHMFXft_rV6MTs8HMxSOvRAQektoXtaMG)
* [Desktop block-based coding tutorial](https://www.youtube.com/playlist?list=PLHMFXft_rV6POrzm8O12Nybdy1-FS1ymg)
  * Note that some of the videos may have been developed by older Petoi robots.  So the setup may be different.  But the programming concept can still apply.&#x20;
* [Advanced tutorials](https://www.youtube.com/playlist?list=PLHMFXft_rV6MWNGyofDzRhpatxZuUZMdg)

### Project ideas

* Get inspired by [Petoi user projects](https://www.petoi.com/blogs/blog/tagged/showcase)
* Work on some [quadruped robotics competition projects and ideas](https://www.petoi.com/blogs/blog/robot-competitions-with-petoi)
  * Every fall, we host [Petoi robotics contests](https://www.petoi.com/blogs/blog/tagged/contest-winners). We'd love to see you!


# Mobile App

📱🤖

Thanks for choosing Petoi's robot. This guide will help you set up your robot buddy and provide a simpler UI to calibrate the joints, control the robot, and program it. For advanced users, we recommend you keep the robot updated with the [OpenCat(for NyBoard)](https://github.com/PetoiCamp/OpenCat) / [OpenCatEsp32(for BiBoard)](https://github.com/PetoiCamp/OpenCatEsp32) firmware on GitHub for the best compatibility and the newest features.&#x20;

## Download and installation

The app works on both Android and iOS devices.

* [iOS 11+](https://apps.apple.com/us/app/petoi/id1581548095)
* [Android 4.4+](https://play.google.com/store/apps/details?id=com.petoi.petoiapp)

#### APK

For Android, you can also download the APK and install it on your phone.&#x20;

* The universal version(try this one first)\
  [v1.4.1-40-2-20251022-app-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-release.apk)
* The **v8a** version of the app mainly supports most of the current new mobile phone models\
  [v1.4.1-40-2-20251022-app-arm64-v8a-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-arm64-v8a-release.apk)
* The **v7a** version of the app is compatible with older mobile phone models\
  [v1.4.1-40-2-20251022-app-armeabi-v7a-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-armeabi-v7a-release.apk)
* The **x86\_64** version of the app indicates that the APK is designed for Android devices using Intel or AMD 64-bit processors. This means the APK contains native code libraries optimized for the x86\_64 architecture, designed to improve performance and compatibility.\
  [v1.4.1-40-2-20251022-app-x86\_64-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-x86_64-release.apk)

{% hint style="info" %}
If the connection panel in the App shows a blank Bluetooth connection list, first check whether you have granted the App Bluetooth and location permissions. If it still shows a blank list, try to install the previous stable version. \
[v1.4.0-37-1-app-release-20251006.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.0/v1.4.0-37-1-app-release-20251006.apk)
{% endhint %}

![](/files/G1cSapHMlJK9sDQ53TMN)

## Connect to the robot

For the mainboard BiBoard, the Bluetooth module is already built into the ESP32 module; you just need to power on the robot by long-pressing the button on the battery.

{% hint style="warning" %}
The app will send a greeting to the Bluetooth device and expect a response from the robot. You must upload the OpenCat (for NyBoard) / OpenCatEsp32 (for BiBoard) firmware to your robot before connecting to the app. Otherwise, the app will consider it "not a Petoi device". A pre-assembled robot should already have the firmware installed. Otherwise, you'll need to upload firmware using the [Petoi Desktop app](https://guide.petoi.com/desktop-app/firmware-uploader).&#x20;
{% endhint %}

{% hint style="warning" %}
For BiBoard, please ensure the program enters the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization)**.**
{% endhint %}

Open the app and scan available Bluetooth devices. **Don't connect the robot with the phone's system-wide Bluetooth settings!** Connect the device with the name Bittle, Petoi, or OpenCat.&#x20;

Please remember to enable Bluetooth and give the app access to it. On some devices, you may also need to allow the app's location service, though we are not using any of that information.

{% hint style="info" %}
On some Android OS, you need to activate the location service as follows:![](/files/tu2Vwheh7gELyuRGt2ZJ)
{% endhint %}

![](/files/-MjZWU2EpJOmFcBOEKGH)

The app will open the Control Panel interface when Bluetooth is connected. If the robot doesn't respond or malfunctions later, press the reset button on the mainboard to restart the robot.

The app should automatically detect the supported robot type based on the latest firmware. Otherwise, it will show the selections for the robot type. The above interface can also be revisited by selecting the option "Select a robot" in the control panel.

![](/files/FG3i4k9cmd0KgFjfCaYH)


# Calibrator

## The rationale for calibration

### Understand the zero state and the coordinate system

After the robot [enters the calibration mode](#enter-the-calibration-state), with all servos rotated to their zero angles, attach the head, tail, and legs prepared in the previous section to the body. They are generally perpendicular to the body frames they are linked to.&#x20;

<figure><img src="/files/jWYfOTCjDsbDKa4oT7BR" alt=""><figcaption></figcaption></figure>

For the construction kit, please install the servo-related components as shown in the picture (calibration mode) and ensure they are perpendicular to each other (the upper leg is perpendicular to the torso, and the lower leg is perpendicular to the upper leg).

{% hint style="warning" %}
Note: Insert the servo-related components directly into the servo output shaft; do not turn the output shaft during this process.
{% endhint %}

Rotating the limbs counterclockwise from their zero states will be positive (the same as in polar coordinates). Viewed from the left side of the robot's body, the counter-clockwise rotation of the joint is defined as the positive direction.

{% hint style="info" %}
The only exception is the head tilt angle for Nybble. It’s more natural to say head up, while it’s the result of rotating clockwise.&#x20;
{% endhint %}

{% hint style="info" %}
However, from the right side of the robot's body, the rotation directions' positive and negative are just opposite.
{% endhint %}

### Discrete angular intervals

If we look closer at the servo shaft, we can see it has a certain number of teeth. That’s for attaching the servo arms and avoiding sliding in the rotational direction. In our servo sample, the gears divide 360 degrees into 25 sectors, each taking **14.4** degrees(offset of -7.2\~7.2 degrees). That means we cannot always get a perfect perpendicular installation.&#x20;

![](/files/v400iIvlmpXjiobnloRS)

## Calibration Interfaces

The calibrator interface for Bittle X V2+Arm is as follows:

<figure><img src="/files/oKCX1udI0zXHlgHyYV3S" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The interfaces above will be displayed when you calibrate for the first time. You can also click to open the upper-right menu in the control panel and select **Calibrate** to re-access.\
![](/files/DNxOLVSoTp3ZZpPwod14)
{% endhint %}

## Enter the calibration mode

After the robot powers on with the battery, follow one of the two methods to enter calibration mode.&#x20;

* Click the **Next step** button.

<figure><img src="/files/SjWUC1Up1waovLPDAhJV" alt=""><figcaption></figcaption></figure>

* Click the **Calibration** button in the calibration interface.<br>

<figure><img src="/files/lsSGdsoaPVfXcWeeJPWV" alt=""><figcaption></figcaption></figure>

**For the** pre-assembled kit, you can directly power on the robot and use the mobile app to fine-tune all joints.

**For the construction kit, after** the robot enters the calibration state, do the following steps:

### Install the neck servo and leg servos

{% hint style="info" %}
Note:

You must use the neck section with a J-hook (as pictured below) to prevent the neck from falling when using this robot arm.

<img src="/files/AoTVJCeFZscPOVGhDd3g" alt="" data-size="original">      ![](/files/t8pKzAzCsZTioctL4P1S)
{% endhint %}

Installing the neck servo is the same as [installing the head](/mobile-app/calibrator/bittle-bittle-x#install-the-head) of Bittle.

Installing the leg servos is the same as [installing the legs](/mobile-app/calibrator/bittle-bittle-x#install-the-legs) of Bittle.

### Install the robot arm

This robot arm is already fully assembled. After finishing calibrating the neck servo and the leg servos, power off the robot and [install](/extensible-modules/robot-arm#installation) the servo slot on the neck servo with two M2\*5 self-tapping screws.

Then, power on the robot, and do the joint calibration for the servos on the robot arm.

{% hint style="info" %}
For the construction kit, after installing the body parts, you do not need to use screws to fix the body parts to the robot trunk for the time being.
{% endhint %}

### **Use the included L-shaped tool as a reference**

![](/files/hwBOViu4Z8HHD76rSsjT)

![Align the upper leg first](/files/QpS91FEEbFx1kWR8Yofo)

![Pay attention to the reference edges for the lower leg](/files/kuwZZVGFrrkgDo4rhGiH)

<figure><img src="/files/ceEPfCFWTu4K0P91pBtV" alt=""><figcaption></figcaption></figure>

First, select the index number of the joint servo from the diagram(when adjusting the leg servo, adjust the thigh first, and then adjust the calf).&#x20;

Then, click the "+" or "-" button to fine-tune the joint to the desired angle.&#x20;

{% hint style="info" %}
If the offset is more than ±9 degrees, you need to remove the corresponding part of the servo, reinstall it by rotating one tooth, and then press the "+" or "-" button.

For example, if you need to use -10 as the calibration value, remove the limb, rotate it by one tooth, and then reattach it. The new calibration value should be around 4, i.e.,  they sum up to 14. Avoid rotating the servo shaft during this adjustment.&#x20;
{% endhint %}

## Test the calibration effect

<figure><img src="/files/jHNumtKNF7h0GatL9xoh" alt=""><figcaption></figcaption></figure>

You can click the skill buttons to switch between **Rest**, **Stand**, and **Walk** to test the calibration effect.&#x20;

If you want to continue calibrating, please click the **Calibration** button, and the robot will return to the calibration mode, with all servos immediately moving to their calibration positions.&#x20;

{% hint style="info" %}
Note:&#x20;

You may need a second round of calibrations to achieve optimal results.
{% endhint %}

After calibration, remember to click the **Save** button to save the calibration offset. Otherwise, click "**<**" in the upper left corner to abandon the calibration.

## Install the screws for the construction kit

For the construction kit, after completing the joint calibration, install the center screws to fix the leg parts and neck servo gears.


# Controller

In the control panel, you can control the robot to perform various postures, behaviors, and gaits.

<figure><img src="/files/DPKqxK3KRMxeLrYG3iPl" alt=""><figcaption></figcaption></figure>

## Gaits

The left panel sets both the robot's gaits and directions and send combined command, such as "walk left" and "trot forward". The robot will only move if an initial gait and direction are selected. The "step" has no direction, and "backward" has left and right directions. The pause button "||" will pause the robot's motion and turn off the servos, so that you can rotate the joints to any angle. The "Turbo" button ( <img src="/files/YQwDEPEj4FqBZvskEzGI" alt="" data-size="line"> ) turns on/off the gyro, a sensor to detect the robot's body orientation. Turning it on will make the robot keep adjusting to body angles, and will know when it's upside down. Turning it off will reduce calculation and make it walk faster and more stable. &#x20;

## Postures and behaviors

The built-in postures and behaviors can be triggered by pressing the buttons. Don't press the button too frequently and repeatedly. Allow some time for the robot to finish its current tasks.&#x20;

## Import commands in batches <a href="#import-commands-in-batches" id="import-commands-in-batches"></a>

You can press the Import commands button in the menu list (as follows) to import the command buttons via a config file (\*.json) .

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252Ft43Bn8Or2mxvChFVgEfz%252Fimage.png%3Falt%3Dmedia%26token%3D509393c0-be63-4ff8-ad6d-bb4eb41d35db&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=6e295d68&#x26;sv=2" alt=""><figcaption></figcaption></figure>

Please install the latest version of the mobile app and download the robotic arm command config file (as below)  and save it on your smartphone:

{% file src="/files/HQ0VslDvIIhPEgoMX1Fc" %}

You can batch import multiple command buttons related to the robotic arm at one time.

## Customized commands

* **Press and hold** the button and drag to change the button position.&#x20;
* **Double-tap** the command button to edit it.&#x20;
* You can also create a customized single command/group command by pressing the "+" button.

<figure><img src="/files/fe7I74M8yoav8RPAbA4q" alt=""><figcaption></figcaption></figure>

### Create a single command

After pressing the **Create Command** button, you can see the following interface:

![](/files/GL2b8zzRrrpBPi28HZvC)

After entering the editing state, there's a serial console to test the command and configure the robot.&#x20;

The joint index of the robot:

<figure><img src="/files/TiWGIxbc5wk9DdSYQdYx" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
A servo plug has three wires. Plug it in the right direction, or you may burn the chip. The color of the wires may vary across models. However, the darkest-colored wire (Black or Brown) is always the GND (ground) wire by convention. The GND wire should be plugged closest to the board.&#x20;
{% endhint %}

{% hint style="danger" %}
The index number of the joint servo has **no corresponding relationship** with the PWM pin number on the main board. **You don't even need to read the pin numbers on the PCB board.**&#x20;
{% endhint %}

You can try the following useful serial commands in the **Code** text box:

#### \* move robot's head(robot arm)&#x20;

```
m0 45
```

#### \* move head left and right (move joint1 angle1 joint2 angle2 .... The angle is -127\~128)&#x20;

```
m0 -70 0 70
```

#### \* sit&#x20;

```
ksit
```

#### \* move joints one by one&#x20;

```
m 0 -70 0 70 8 -30
```

#### \* move joints simultaneously&#x20;

```
i 0 -45 8 -30 12 -60
```

#### \* show current joint angles&#x20;

```
j
```

#### \* long meow once (Nybble）

```
u0 1
```

#### \* short meow three times (Nybble）

```
u2 20
```

#### \* mute/unmute the buzzer beep

```
b
```

#### **\* adjust the buzzer volume (b\[0-10])**

```
b1
```

#### \* play a short tone (beep tone duration, duration is 0\~256)&#x20;

```
b12 20
```

#### \* play a melody (beep tone1 duration1, tone2 duration2, tone3 duration3, .... only 64 characters are allowed, the actual duration is calculated as 1/duration)&#x20;

```
b14 4 14 4 21 4 21 4
```

#### More common commands to be added

Please see [this list of common commands](https://docs.google.com/spreadsheets/d/1Lr6Cd1T-H9sSdUi_bI-OeMClkVOKjTQM/edit?usp=sharing\&ouid=106975882561093680387\&rtpof=true\&sd=true) that may be added as customized commands.  You can enter the "Voice command" column values as the "Name" values and the "Customized command code for Petoi mobile app" column values as the "Code" values.

A more detailed command table can be found in the [Serial Protocol](https://guide.petoi.com/apis/serial-protocol).&#x20;

### Import new skills as a customized button

#### Import your local customized skill (created by the [Skill Composer](https://guide.petoi.com/desktop-app/skill-composer))

You can send the skill file to your phone via the Messenger app or email, and open it on the phone using the Petoi App. A button for the new skill will be created; you can see it when you open the control panel.

<figure><img src="/files/LvJ0YdTUfEXeg3zLQzpe" alt=""><figcaption></figcaption></figure>

#### Import new skills from the skill library on GitHub

[The SkillLibrary folder](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary) in GitHub contains new skills for the OpenCat robot, which can be used for your reference. You can use your mobile browser to access the GitHub page of the OpenCat project, open the skill file (such as [Bittle\_Fold.md](https://github.com/PetoiCamp/OpenCat/blob/main/SkillLibrary/Bittle/Bittle_Fold.md)), select the "Code" tab, and share it with the [**Petoi Mobile App**](https://guide.petoi.com/mobile-app/introduction)(make sure the mobile app is connected to your Petoi robot first), as shown in the figures below.  Then you can execute this skill by pressing the newly created command button.

{% hint style="warning" %}
On iOS, you cannot share the .md skill file on GitHub in the Chrome browser. You can download the skill file and refer to the method - [Import your local customized skill](#import-your-local-customized-skill-created-by-the-skill-composer) to import it to this smartphone app.
{% endhint %}

<div><figure><img src="/files/HRcf2PQUkNsEsXHf4mTv" alt=""><figcaption></figcaption></figure> <figure><img src="/files/qRBFhbd4S8Dw5vdTCAE4" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="/files/JfZ7DaAzohvSOAZXpjDj" alt=""><figcaption></figcaption></figure> <figure><img src="/files/pVxNWxunKPStuSMfMRWV" alt=""><figcaption></figcaption></figure></div>

<figure><img src="/files/sl0xZZLUmo4SD3gykCmx" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
You are welcome to create your new skills(using the Skill Composer or [modifying the source code](https://guide.petoi.com/applications/skill-creation)) and share them by sending merge requests to [this folder](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary).
{% endhint %}

### Create a group command

The group command feature lets you chain multiple commands together and play them in sequence.

After pressing the **Create Group Command** button, you can see the following interface:

<figure><img src="/files/2a89mNbjVx27MTjDk8ym" alt=""><figcaption></figcaption></figure>

You can name the command group in the **Name** text box and add the command to the **Command Group** list by clicking the command button in the **Command Library** selection box. In the **Command Group** list, you can ***press and hold*** the command button and **drag** to change the command position.&#x20;

Click the **Test** or **Play (**![](/files/ays18QEsFK31wroXlnAC)**)** button to test the function of the command group. Click the **Pause (**![](/files/9ctc9bRh7LUiaV2Cs6qh)**)** button to interrupt the command list execution flow.

Click the **Delete** button to Delete the group command.

### Make your robot act randomly

{% embed url="<https://www.youtube.com/watch?v=nHLkE74Q3k8>" %}

If your robot doesn't have any random behavior, you may need to upgrade your robot to [the latest firmware](/desktop-app/firmware-uploader).&#x20;

## Updates and support

We keep improving the app and will inform you of the updates when available. Please write to  <support@petoi.com> if you have any questions about the app.&#x20;


# Voice Command

## Demo video

{% embed url="<https://youtu.be/aGW8F4mArAs>" %}

## Function introduction

Using this module, you can control the Petoi robot to perform various skills through voice without using wake words. Currently, the module supports 35 fixed voice commands in two languages (English and Chinese) and ten customized commands by recording any sound clips.&#x20;

## Hardware setup

It is built into the [**BiBoard V1**](https://guide.petoi.com/biboard/biboard-v1-guide) as follows:

<figure><img src="/files/BTXujMNDvdSxFeKDYue9" alt=""><figcaption></figcaption></figure>

## Software setup

### 1. Upload Firmware

There are two methods to upload the firmware for the robot.

* **use the Petoi Desktop App**
* **use the Arduino IDE**

#### **Petoi Desktop App**

You can use the [Firmware Uploader](https://guide.petoi.com/desktop-app/firmware-uploader#select-the-correct-options-to-upload-the-latest-firmware) within the Petoi Desktop App.

Please select the correct ***Product*** type, ***Board version***, and ***Serial port***. The mode should be **Standard**, so press the **Upgrade the Firmware** button.&#x20;

<figure><img src="/files/l0dmlbcgQbn5jgsq3VzR" alt=""><figcaption></figcaption></figure>

#### **Arduino IDE**

You can use [Arduino IDE](https://www.arduino.cc/en/software) to [upload the sketch](https://docs.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.-set-up-biboard)(***OpenCatEsp32.ino***).&#x20;

For Bittle or Bittle X:

<pre class="language-cpp"><code class="lang-cpp">#define BITTLE    //Petoi 9 DOF robot dog, also for Bittle X
<strong>//#define NYBBLE  //Petoi 11 DOF robot cat, also for Nybble Q
</strong>//#define CUB
</code></pre>

For Nybble or Nybble Q:

<pre class="language-cpp"><code class="lang-cpp">//#define BITTLE    //Petoi 9 DOF robot dog, also for Bittle X
<strong>#define NYBBLE  //Petoi 11 DOF robot cat, also for Nybble Q
</strong>//#define CUB
</code></pre>

Modify the mainboard model macro definition in OpenCatEsp3&#x32;**.ino** according to the mainboard (BiBoard) version.

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

If the robot(**Bittle X+Arm**) has the robotic arm, you should also activate the macro definition as follows:

<pre class="language-cpp"><code class="lang-cpp"><strong>#define ROBOT_ARM                 // for attaching the head clip arm
</strong></code></pre>

Otherwise, please comment out this line of code.

After the modification is completed, you can click the **Upload** button (as below) to upload the sketch **OpenCatEsp32.ino**, and the changes in the code file will be automatically saved.

<figure><img src="/files/tdpRznaQQrpxXC9osxpY" alt=""><figcaption></figcaption></figure>

### 2. Switch mode

After uploading, the program defaults to Voice mode. If it is in another mode and you want to switch to Voice mode, please open the [Serial Monitor](https://guide.petoi.com/arduino-ide/serial-monitor) and send the **`XA`** command.

## Play with the voice commands

### Common use cases

#### Set the default language

{% hint style="info" %}
This feature is designed for robots using **BiBoard** as their mainboard.
{% endhint %}

When the robot is restarted, the voice module is automatically reset to its default language setting, which is English.

There are two ways to set the default language:

* Using the serial commands
  * Open the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor):
    * To set the default language to **English**, use the command: ***`XAa`***.&#x20;
    * To set it to **Chinese**, use the command: ***`XAb`***.
  * In the [mobile app](https://guide.petoi.com/mobile-app/controller#create-a-single-command):
    * To set the default language to **English**, create a command called **English** and use the code: ***`X65,97`**.*
    * To set it to **Chinese**, create a command called **Chinese** and use the code: ***`X65,98`**.*
* Using the voice commands
  * To set the default language to **English**, you need to say the voice command "**Lizheng**" (phonetic) first and then say "**Bing-Bing**" (phonetic).
  * To set it to **Chinese**, you need to say the voice command "**Attention**" first and then say "**Di-Di**"(phonetic).

#### Switch the language

{% hint style="info" %}
Note: For the **BiBoard**, the language will switch to the default language setting after rebooting the robot. So, if you accidentally switch the language mode, you can restore the default language setting by restarting the robot.
{% endhint %}

* To switch to **English**, you can say "**Bing-Bing**" (phonetic)
* Switch to **Chinese**, you can say "**Di-Di**" (phonetic)

#### Turn on/off the voice command functionality(audio response and robotics reaction)

To turn on

* Speak **Play sound**&#x20;
* Create a command called "**Enable voice**" and use the code: *`X65,99`*

To turn off

* Speak **Be quiet**
* Create a command called **Disable voice** and use the code: *`X65,100`*

#### Use the predefined voice commands

The voice command list for Bittle / Bittle X / Bittle X+Arm

<figure><img src="/files/2oVzDStjdtTsoHe8L2MK" alt=""><figcaption></figcaption></figure>

See [**this doc**](https://docs.google.com/spreadsheets/d/1Lr6Cd1T-H9sSdUi_bI-OeMClkVOKjTQM/edit?usp=sharing\&ouid=106975882561093680387\&rtpof=true\&sd=true) for the latest version.

{% hint style="info" %}
To avoid inadvertently triggering the robot to respond to voice commands, you can say **Be quiet** to the robot to disable the voice module, such as when talking with others.

If the above voice commands don't take effect in **English mode**, try to use the mobile app and create a new button with the code: ***`X65,100`***, or input ***`XAd`*** in the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) to disable the voice module.

<img src="/files/H2dpRnHK6aBYiFVs3Nda" alt="" data-size="original">\
You can say  **Play sound** to the robot to enable the voice module.

Use the mobile app and create a new button with the code: ***`X65,99`***, or input ***`XAc`*** in the [serial monitor](https://docs.petoi.com/arduino-ide/serial-monitor) to enable the voice module.

<img src="/files/ExVu04nKsSn4SfdFdXAQ" alt="" data-size="original">
{% endhint %}

{% hint style="success" %}
The voice command **Climb-up** is a challenge for you. You can [design the behavior](/desktop-app/skill-composer) by yourself. Then, you can post it on the [Petoi Forum Challenge](https://www.petoi.camp/forum/challenge) or email <support@petoi.com>. We may adopt it in our official firmware and send you a gift!

For example, you can share your behavior like this:

{% embed url="<https://www.youtube.com/shorts/RWsQaIZMDqo>" fullWidth="false" %}
{% endhint %}

### How to debug if the voice command doesn't work

In some cases, the voice module may not respond to your voice. Please check the following:

1\. Say **Play sound** to check if the robot responds with **Do-Me-So**. Sometimes, the voice may be accidentally set to muted mode, triggered by **Be Quiet**.

2\. If the module doesn't make any sound with Play sound, say **Bing-Bing** to switch to English mode. You may try different tones and speeds to say **Bing-Bing**. The robot should respond with **Switch English** if not in **English mode**. It won't react with anything if it's already in English.&#x20;

3\. If the voice module still doesn't make any sound, you can try to reset it in our software tools.

* #### Mobile app:

  From version **1.2.0** of the mobile app, you can create a new button with the compound code:&#x20;

  ***`^X65,99;!1000;X65,98;!1000;X65,97`***

  To reset the voice module to English mode. &#x20;

  <figure><img src="/files/lVKQSlzS4IZfH8Bs1no5" alt=""><figcaption></figcaption></figure>

  <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><em><strong><code>X65,99</code></strong></em>, or input <em><strong><code>XAc</code></strong></em> in the <a href="https://guide.petoi.com/arduino-ide/serial-monitor">serial monitor</a> enables the voice module.</p><p><img src="/files/ExVu04nKsSn4SfdFdXAQ" alt="" data-size="original"></p><p><em><strong><code>X65,97</code></strong></em> or input <em><strong><code>XAa</code></strong></em> in the serial monitor is equivalent to saying <strong>Bing-Bing</strong>, but excludes the chance that the voice is not recognized. Then you can try to say <strong>Play sound</strong> again. </p></div>

  <figure><img src="/files/CumkWIADNiXd5ZUXTBf1" alt=""><figcaption></figcaption></figure>
* #### Desktop app:

  From version 1.2.1, you can use the debugger tool to [reset the voice module](https://guide.petoi.com/desktop-app/tools#download-the-latest-version-of-the-petoi-desktop-app).

4. Next, if you say **Hello**, the robot should wave its hand and validate that the complete reaction loop is good. Then, you can try other voice commands.&#x20;
5. Try powering off the mainboard by disconnecting the USB data cable, long-pressing the battery's button, and then re-powering the mainboard.

The above steps validate that the voice module is working. It's powered separately from the motion unit and should work regardless of the robot's status.&#x20;

If the above steps cannot fix the problem, contact <support@petoi.com> for help.

### Record customized voice commands

When the robot works in **English mode**,  you can speak **Start learning** (or input the serial command **XAe** in the serial monitor) into the custom voice command mode and record your voice commands in order.&#x20;

{% hint style="info" %}
If the module is **not** in English mode, you can speak **Bing-Bing** (or input the serial command ***`XAa`*** in the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor)) to switch to **English mode**.
{% endhint %}

You can record up to 10 voice commands, <mark style="color:red;">each with no more than</mark> <mark style="color:red;"></mark><mark style="color:red;">**six**</mark> <mark style="color:red;"></mark><mark style="color:red;">syllables</mark>.

To exit the custom voice command mode in the middle, you can speak **Stop learning** (or input the serial command **XAf** in the serial monitor).&#x20;

After leaving the custom voice command mode, please speak one of the recorded voice commands to trigger the reaction.

Speak **Clear the learning data** to delete all the recordings simultaneously  (you cannot delete a specific recording).

There are **ten** skill strings as custom replies already defined in the `voice.h`:

{% hint style="info" %}
The first 3 commands is standard for all type of petoi robot, which have feedback servos.
{% endhint %}

```cpp
String customizedCmdList[] = {
  "fl",  // learn skill with feedback servos
  "fr",  // replay skill learned with feedback servos
  "fF",  // movement follower demo with feedback servos
#ifdef BITTLE       // also for Bittle X
#ifdef ROBOT_ARM    // for Bittle X+Arm
  "kpickF",                          // pick front 捡起来
  "kputD",                           // put down 放下
  "khuntL",                          // hunt 捕猎
  "kshowOff",                        // show off 展示
  "kputL",                           // put left 收起来
  "ktossL",                          // toss left 左抛
  "klaunchL",                        // launch 发射
  "kclapL",                          // clap 鼓掌
  "ktossF",                          // toss front 前抛
  "qc-2:0>kclap:1000>kpickF:1000>",  // calibrate arm (for QA) 校准(工厂用)
#else
  "kpu1",                                                                  // single-handed pushups
  "m0 80 0 -80 0 0",                                                       // wave head
  "kmw",                                                                   // moonwalk
  "b14,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,\
  21,8,21,8,19,8,19,8,18,8,18,8,16,4,21,8,21,8,19,8,19,8,18,8,18,8,16,4,\
  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",  // twinkle star
  "T",                                                                     // call the last skill data sent by the Skill Composer
  "6th",
  "7th",
  "8th",
  "9th",
  "10th"  // define up to 10 customized commands.
#endif
#elif defined NYBBLE    // also for Nybble Q
  "kluckyL",   // lucky cat 招财猫
  "klkPawsL",  // lick paws 舔爪子
  "qksit:100>i0 20 1 0 8 -70 12 0 15 10:0>o1 0, 0 40 -20 4 0, 1 -30 20 4 30, 8 -70 10 4 60, 12 -10 10 4 0, 15 10 0 4 0:100>m0 0 1 -20 2 0:0>ksit:0",
  // "kwsfL",                                                                 //wash face 洗脸
  "khuntL",                                                                // hunt 捕猎
  "m0 80 0 -80 0 0",                                                       // wave head                                                                //
  "b14,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,\
  21,8,21,8,19,8,19,8,18,8,18,8,16,4,21,8,21,8,19,8,19,8,18,8,18,8,16,4,\
  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",  // twinkle star
  "T",                                                                     // repeat
  "xl",                                                                    // learn a new trick 学习动作
  "xp",                                                                    // play the trick 表演动作
  "10th"                                                                   // define up to 10 customized commands.
#endif
};
```

The response actions (**`kpu1`** means single-handed pushups, **`kmw`** means moonwalk) are already defined in the program.&#x20;

Other serial commands are also supported as responses, such as joint movements(e.g. **`m0 80 0 -80`**  means shaking the head left and right) and playing a melody(e.g. **`b14,8,14,8,21,8,21,8,23,8,23,8,21,4`**)

To use these custom replies above, you need to enter the custom voice command mode, record ten voice commands (such as Single-handed Pushup, Shake Head, Moonwalk, Twinkle Star), and then exit the custom voice command mode.

If you have recorded a voice command and the corresponding custom reply is not a predefined serial command (e.g.,**`6th`**), there is no actual demonstration effect; it only prints a simple message on the serial monitor when you speak the corresponding voice command.

## Advanced usage for developers

### Understand the principle

1. &#x20;Convert the voice command collected by the microphone in the module into a serial command.
2. &#x20;Send the serial command to the mainboard MCU through the soft serial port Serial2.
3. &#x20;After receiving the serial command, the MCU parses it into the corresponding skill command, and finally, the reaction module, according to the skill command, controls the robot to respond accordingly.

Upload the demo sketch **testVoiceCommander.ino**, and you can see every serial command that is sent to MCU(including the custom voice command if you have recorded it)

<figure><img src="/files/B3SFPQ26YbHxxEH4D8i9" alt=""><figcaption></figcaption></figure>

You can open [the serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) to check the raw return values of every voice command.&#x20;

<figure><img src="/files/f8WlQWeFdEp49F3D4A2q" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/2Bjh6ojqNV7qVX4QGNEB" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
After you speak the voice command to the robot, the **Returned value** (**`X A 11`** or **`X A 21 kup`**) is the corresponding serial command sent to the mainboard MCU. The third number(11 or 21) is an invisible character. To understand it, we convert it to a numeric value and print it out.
{% endhint %}

### The test sketch

The test sketch is in the OpenCatEsp32 repository on GitHub (specific path: OpenCatEsp32/ModuleTests/testVoiceCommander). You can visit our GitHub repository <https://github.com/PetoiCamp/OpenCatEsp32> to download the complete code, as shown in the following picture:

<figure><img src="/files/xkAYdahcOoMhWtdwbTNU" alt=""><figcaption></figcaption></figure>

### Serial interface

There are seven related serial commands for configuration; you can input them into the serial monitor.&#x20;

<table><thead><tr><th width="178">Serial Command</th><th width="222">Mobile App Button Code</th><th>Function</th></tr></thead><tbody><tr><td>XAa</td><td>X65,97</td><td>Set the default language to English</td></tr><tr><td>XAb</td><td>X65,98</td><td>Set the default language to Chinese</td></tr><tr><td>XAc</td><td>X65,99</td><td>Turn on the reply tone and enable reaction</td></tr><tr><td>XAd</td><td>X65,100</td><td>Turn off the reply tone and disable reaction</td></tr><tr><td>XAe</td><td>X65,101</td><td>Enter custom voice command mode</td></tr><tr><td>XAf</td><td>X65,102</td><td>Exit custom voice command mode</td></tr><tr><td>XAg</td><td>X65,103</td><td>Delete all the custom voice commands</td></tr></tbody></table>

{% hint style="info" %}
After inputting the command above in the message box, **press Enter** to send the command to the robot.
{% endhint %}

### How to design new reactions

For the robot in Voice mode, to improve the utilization rate of custom voice control commands, you can modify the last **six** skill strings to the skill names with actual action responses.

* Using the task queue to create a sequence of motions, please refer to the source code in the `voice.h` as below:

{% code lineNumbers="true" %}

```cpp
const char *cmd = raw.c_str() + shift;
tQueue->addTask(token, shift > 0 ? cmd : "", 2500);
if (strlen(cmd) > 0) {
  char end = cmd[strlen(cmd) - 1];
  if (!strcmp(cmd, "bk") || !strcmp(cmd, "x") || end >= 'A' && end <= 'Z') {
    tQueue->addTask('k', "up");
  }
}
```

{% endcode %}

{% hint style="info" %}
tQueue is the task queue defined in OpenCat.h; using the method "addTask" of this object, the robot can do some simple skills sequentially as a custom voice command response.&#x20;
{% endhint %}

* Using [the Skill Composer](https://guide.petoi.com/desktop-app/skill-composer) and binding the customized voice command to the new skills

1. &#x20;Use SkillComposer to design new skills and then [export](https://guide.petoi.com/desktop-app/skill-composer#export-the-skill) them to `Instinct***.h`&#x20;
2. &#x20;Modify *voice.h* to bind the customized voice command to the new skills: modify the **`customizedCmdList[]`**（e.g., If you want to bind the sixth customized voice command to the new skill, replace the string "*`6th`*" with **`'k'+the new skill name`**)


# Joystick with Micro:Bit

{% embed url="<https://youtu.be/BRb4nQeWcdQ>" %}

This remote controller is a Micro: Bit-based gamepad. It includes a 4-direction joystick and four undefined buttons. To enhance the gaming experience, it is also paired with a buzzer and vibration motor. It is compact in appearance, comfortable in hand, and can be remotely controlled.

<figure><img src="/files/cWq8AWK04l5QBMYPyAZP" alt=""><figcaption></figcaption></figure>

## Hardware

{% hint style="info" %}
Micro: Bit V1 has a smaller memory. So, the full functionality requires **Micro: Bit V2**.
{% endhint %}

## Software setup

The Joystick's source code is now open-sourced. It can control Bittle X, Bittle X+Arm (Bittle with a robotic arm), and Nybble Q. For more information, please refer to our [GitHub repository](https://github.com/PetoiCamp/ESP32_Microbit_Controller).

You can download the program file([microbit-JoyStick.hex](https://raw.githubusercontent.com/PetoiCamp/ESP32_Microbit_Controller/refs/heads/main/microbit-JoyStick.hex)), then import the program to [the programming platform MakeCode](https://makecode.microbit.org) as follows:

{% hint style="info" %}
We recommend you use a **Chrome** browser.
{% endhint %}

<figure><img src="/files/hFedNL9hJ93oPVbVHOKZ" alt=""><figcaption></figcaption></figure>

Alternatively, you can click "New Project" and drag the program file into the coding window to load it.&#x20;

### Download the program to the Micro: Bit V2

Connect your PC to the Micro: Bit V2 using a USB cable.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/connect-microbit.gif)

After a successful connection, a disk drive named `MICROBIT` is recognized on the computer.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/microbit-drive.png)

Click on the bottom left corner of the ![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-01.png) button， Select `Connect Device`.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-02.png)

Click ![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-03.png) button.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-04.png)

Click![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-05.png)

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-06.png)

Select `BBC micro:bit CMSIS-DAP` in the pop-up window and then select Connect. At this point, our Micro: Bit has connected successfully.

<figure><img src="/files/AYGrUa10XCpIyDScs4KF" alt=""><figcaption></figcaption></figure>

Click to download the program.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-08.png)

## How to use&#x20;

1. [Upload the newest firmware](https://guide.petoi.com/quick-reference/upload-firmware) to the robot (mainboard type: **BiBoard**)
2. Install 2 x #7 AAA batteries and plug in the Micro: Bit V2 to the remote controller. Then, power on the remote controller as follows:\
   ![](/files/4wd4bqBDrhavQ1xEHQuE)
3. Power on the robot. During bootup, it can connect to the controller automatically via Bluetooth.\
   If there are many remote controllers and robots, the connection is one-to-one and first-come, first-served.

{% hint style="info" %}
**Timed lock feature**

This feature limits the play time for each user during exhibitions or science festivals. It is deactivated by default.

After normal startup and Bluetooth connection, you can activate the limited-time usage function for the controller by pressing and holding the middle Logo (touch button) on the Micro:bit while keeping the controller upright (with the left joystick at the bottom). Once activated, the controller will send a rest command to the robot every 20 minutes and no longer respond to subsequent operations. The LED indicator matrix will dynamically display an hourglass pattern, as shown in the figure below:

<img src="/files/9X7ZIZfFs7c3DrOmUZpT" alt="" data-size="original">

You can reset the countdown and reactivate the controller using the same operation described above. The controller will play a prompt tone, and the LED indicator matrix will display an animation of an hourglass reversing.

Once the limited-time feature is activated, it can only be turned off by rebooting the controller. After the controller restarts, you must reset the robot (by clicking the **reset** button on the mainboard) or reboot the robot to reconnect.
{% endhint %}

### To control Bittle X+Arm (with robotic arm):

<figure><img src="/files/9HkosP4fl2JDcuW3nnuO" alt=""><figcaption></figcaption></figure>

#### Demo

{% embed url="<https://youtu.be/QLI-x_8qO98>" %}
Bittle X+Arm
{% endembed %}


# Petoi Desktop App

The Petoi Desktop App offers a user-friendly graphical interface for configuring the firmware, calibrating the robot, designing customized motions, and utilizing debugging tools. The major function modules are the [Firmware Uploader](https://guide.petoi.com/desktop-app/firmware-uploader), [Joint Calibrator](https://guide.petoi.com/desktop-app/joint-calibrator), [Skill Composer](https://guide.petoi.com/desktop-app/skill-composer), and [Tools](https://guide.petoi.com/desktop-app/tools).

<figure><img src="/files/TDgmz5IOELYasd0r5kXQ" alt=""><figcaption></figcaption></figure>

## Download & Installation

You can download the [latest version](/desktop-app/introduction#download-the-latest-version-of-the-petoi-desktop-app) of the desktop App and unzip it.

Before running the app, you must use the included USB adapter or the Bluetooth dongle to connect to a Petoi robot. You may need to [install driver](https://guide.petoi.com/technical-support/useful-tools#usb-driver) for USB connection.

### Windows

Run the UI.exe in the **unzipped** folder.  Do NOT move the UI.exe to another location in Windows.

### Mac

After downloading the Mac version, you must drag it into the **Applications** folder.&#x20;

If you see the error message that **Petoi Desktop App** cannot be opened because the developer cannot be verified, you can right-click the icon, hold the **Shift** key and click **Open**.

![](/files/8358jcqppHBs1YHVE40Z)

{% hint style="warning" %}
The upgraded macOS has introduced some incompatibility with the GUI library. To click/activate an element in the app's interface, press and hold the element, then move your finger slightly and release. Otherwise, the event cannot be recognized.&#x20;

Sorry for the inconvenience. It's been a known issue between macOS and the popular Tkinter library.

<img src="/files/VEUyL4GdnSJyUo1amUuI" alt="" data-size="original">
{% endhint %}

### Linux

Please see the next chapter to run the app from a terminal.

## Run the app from the Terminal for Mac or Linux

In the case of compatibility issues or if you want to modify the source and test, you can also run the code from the Terminal.

The Terminal is a built-in interface on Mac or Linux machines. The equivalent environment on Windows machines is the Command Prompt (CMD). It's recommended that you install [Anaconda](https://www.anaconda.com/) to manage your Python environment (**Python version > 3.7.1)**. It can also provide PowerShell as a Terminal for older Windows machines.

Depending on your existing Python configuration, you may need to upgrade to Python 3 and install the following libraries:

* pyserial
* pillow

You can install them by entering `pip3 install pyserial pillow` in the Terminal or use the package manager in Anaconda.

To run the code:

1. In the Terminal, use the `cd` command to navigate to the `OpenCat/pyUI/` folder. You can use the Tab key to auto-complete the path name.
2. After entering the pyUI/ folder, enter `ls` and ensure you can see the UI.py and other python source codes listed.
3. Enter `python3 UI.py`.

{% hint style="info" %}
For Linux system users,  if you encounter the Python error message "\_tkinter.TclError: no display name and no $DISPLAY environment variable", you can try to install **python3-tk**, **tk-dev**. Taking Debian / Ubuntu as an example, the command is as follows:

`apt install python3-tk`

`apt install tk-dev`

After the installation is complete, reboot the computer.
{% endhint %}

### Check the mainboard version and the USB connector

<figure><img src="/files/47Q1it4Z8bViL993GgH7" alt=""><figcaption></figcaption></figure>

## Robot Connection

Plug in the battery and press the battery button for 3 seconds to power on the robot.

There are two methods to connect to the computer:

* The USB data cable connection must be made directly to **the BiBoard,** not to the battery's charging port. &#x20;
* You can also connect to the computer via [Bluetooth](https://guide.petoi.com/quick-reference/bluetooth-connection).

For BiBoard, please ensure the program enters the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization)**.**

## Open Source Codes

The source code is written in Tkinter using Python 3 and is open-source. The GitHub repository URL is: <https://github.com/PetoiCamp/DesktopAppRelease>

UI.py is the general entry for all the modules in the pyUI file folder:

-> FirmwareUploader.py

-> Calibrator.py

-> SkillComposer.py

-> Debugger.py

-> translate.py provides multi-language support for the UI. You may help to translate the UI into your language.


# Firmware Uploader

Robot's brain is in the firmware.  Robots desire to have the most updated brain!

Please refer to [the introduction](/product/bittle-x-v2+arm/control-and-program/petoi-desktop-app) for installing the Petoi Desktop App and connecting the robot to your computer.

## Upload the firmware using Petoi Desktop app

### Open Petoi Desktop App

**After** properly connecting the mainboard with the computer via a USB data cable, open the PetoiDesktopApp (for Windows: UI.exe / for Mac: Petoi Desktop App), and select your **Model** and **Language**.

#### Menu bar in Petoi Desktop APP

<div align="left"><img src="/files/qBCd9Bhez4849Yf780QA" alt="Model"> <img src="/files/gR5eBhARz93cFxxlprzO" alt="Language"> <img src="/files/3sAlQfjLKtep2lBKB4Hg" alt="Help"></div>

### Click the Firmware Uploader button

<div align="center"><img src="/files/bmSa9E1wwzopUOGaqGUS" alt="Main interface"></div>

### Auto Detect the Serial Port&#x20;

If there is **no** serial port or **more than one** serial port is detected by the desktop app:

<figure><img src="/files/zPEK9HCklsSKKfOlij4n" alt=""><figcaption></figcaption></figure>

After clicking the **Firmware Uploader** button,  there will be a message box prompt as follows:

<figure><img src="/files/ii8QC9zLeNtH6vwtQWhP" alt=""><figcaption></figcaption></figure>

Please follow the prompts in the message box. \
After clicking the **Confirm** button, If you complete the prompts within 10 seconds, the desktop app will automatically identify the serial port name connecting the robot to the computer.\
If you complete the operation of unplugging and plugging the USB interface on the computer for more than 10 seconds, the desktop application will enter the manual selection of the serial port name mode：

<figure><img src="/files/kgnSTTD7u6lGHXvrUqz1" alt=""><figcaption></figcaption></figure>

Click the **OK** button in the Warning message box first, then you can refresh the serial port list or select one of them (e.g. **COM3**) and click the **OK** button in the **Manual mode** window to open the Firmware Uploader interface as follows:

<figure><img src="/files/IAPsr99lxuNKhqeN7S3w" alt=""><figcaption></figcaption></figure>

Once the Firmware Uploader interface is opened, you can also unplug and replug the USB cable from the COMPUTER side. The desktop app will automatically identify the serial port name used to connect the robot to the computer.

<figure><img src="/files/4910PiAdo9AGvz9107Rb" alt=""><figcaption></figcaption></figure>

If you unplug the **COM5** and replug it on the computer side, it will be discovered by the desktop app as follows:

<figure><img src="/files/VW5yOQDHLRpfGYUgqW7W" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/QDyj6IxfGOZBglAI9zm9" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/6kaCalAgQlbDT7Ivx4cw" alt=""><figcaption></figcaption></figure>

### Select the correct options to upload the latest firmware.&#x20;

{% hint style="warning" %}
The 1.0 software won't work correctly with the Joint Calibrator, the Skill Composer, and other APIs. Use it only when you want to use the CodeCraft, a graphical coding interface provided by our partner, TinkerGen.&#x20;
{% endhint %}

<table><thead><tr><th width="176">Options</th><th width="293">Values</th><th>Notes</th></tr></thead><tbody><tr><td>Product</td><td><p>Bittle (default)</p><p>Bittle X</p><p>Bittle X+Arm<br>Nybble<br>Nybble Q</p></td><td></td></tr><tr><td>Mode</td><td>Standard (default)<br>RandomMind <br>Voice<br>Mind+<br>Camera <br>Ultrasonic <br>RandomMind_Ultrasonic<br>Light<br>Touch<br>PIR<br>Gesture<br>IR distance</td><td><p>Because <strong>Bittle X running on BiBoard</strong> has more memory space, you only need to upload with the <strong>Standard</strong> mode firmware.  Then you can switch between different modes via serial port commands. [1]</p><p></p><p>For NyBoard, these 12 modes can be selected. All of these modes apply to both <strong>Bittle</strong> and <strong>Nybble</strong>.</p><p></p></td></tr><tr><td>Software version</td><td><p>2.0 (default)</p><p>1.0</p></td><td>The 1.0 version is obsolete.</td></tr><tr><td>Serial port</td><td>Auto detection or by manual selection. </td><td>You can find the correct one through unplug and replug the USB socket on the computer side</td></tr><tr><td>Board version</td><td><p>NyBoard_V1_0 (default<em>)</em><br>NyBoard_V1_1<br>NyBoard_V1_2<br>BiBoard_V0_1</p><p>BiBoard_V0_2<br>BiBoard_V1_0</p></td><td>BiBoard_V0_1 or BiBoard_V0_2  is for <strong>Bittle X.</strong>  <br>BiBoard_V1_0 is for <strong>Bittle X V2</strong> and <strong>Nybble Q</strong>.</td></tr></tbody></table>

{% hint style="info" %}
\[1] You can use the serial commands to [switch modes](https://guide.petoi.com/product/bittle-x-v2+arm/control-and-program/petoi-desktop-app/pages/8ajuxMEplUPiNYi4SRyi#id-2.9-switch-working-mode-via-the-serial-commands-optional) for **BiBoard**:\
For **BiBoard,** Mind+ mode is supported by default, so it doesn't require a serial command to switch on.\
You can learn about the functionw of each module through the [**EXTENSIBLE MODULES**](https://guide.petoi.com/extensible-modules/introduction).
{% endhint %}

{% hint style="warning" %}
There's no correlation between the board (hardware) version and the code (software) version.
{% endhint %}

### Uploading options

* **Factory Reset**\
  After upgrading the firmware, the board will enter the [**initialization startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization) and ask whether to clear the joint calibration parameters and calibrate the IMU.
* **Upgrade the Firmware**\
  It will upgrade the firmware, skip the steps of clearing joint calibration parameters and the IMU calibration(it's equivalent of sending serial command "**n**"), and automatically enter the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization).
* **Update the Mode Only**\
  It has the same function as the **Upgrade the Firmware** at present.

#### **Factory reset** process

After clicking the **Factory Reset** button, the uploading process will start immediately. The board will enter the [**initialization startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization) after uploading the firmware. Some message windows will pop up in sequence for you to confirm or cancel:

1. Reset joint offsets? (Y/N)<br>

   <figure><img src="/files/xp2AMD7ENMG0QPFcJMRr" alt=""><figcaption></figcaption></figure>

Select **Yes**, and the program will reset all servo calibration parameters to zero. The status bar will update the corresponding process and result in real time.

Select **No** to preserve the calibration value(so that you don't need to calibrate again if you have already done so). &#x20;

2. Calibrate IMU? (Y/N)<br>

<figure><img src="/files/kNL86GYJtsuQDf6aOUNE" alt=""><figcaption></figcaption></figure>

Select **Yes**,  and the program will calibrate the gyroscope (IMU) to balance the robot correctly. The status bar will update the corresponding process and result in real time.

Select **No**, and the program will skip this step.

After that, the board will enter the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization)**.**

{% hint style="danger" %}
Note:&#x20;

Ensure the microcontroller is positioned horizontally for IMU calibration before clicking the "Yes" button.&#x20;
{% endhint %}

### Finish uploading the firmware

After the upload, the status bar will update the corresponding result, such as the success or failure of firmware uploading. If the uploading is successful, a message window of "Firmware upload complete!" will pop up simultaneously.

<figure><img src="/files/LoanvpTqxeu9rGHNDzAj" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Note:&#x20;

1. For NyBoard, when you open the software and upload the firmware for the first time, the program will first upload the "**Parameters**" firmware and then the "**Main function**" firmware.&#x20;
2. After uploading the firmware, if the NyBoard or BiBoard V1 is not connected to the battery and powered on, you will hear repetitive descending melodies, indicating that the battery is low or disconnected. You need to connect the battery and turn on its power.&#x20;
   {% endhint %}

### Check the log file

From the desktop app version **1.2.7**, the log information will be output in the console box at the bottom of the interface:

<figure><img src="/files/Kusypy1JUioDU1uI0sgi" alt=""><figcaption></figcaption></figure>

You can directly click the **Copy** button to copy all the log information, or you can first select specific key information in the console output box with your mouse, then click the **Copy** button to copy only that portion of the log information, and then paste this information into an email and send it to support.petoi.com for assistance.

{% hint style="info" %}
For the old version of the desktop app, if the upload fails, the following message box will pop up:

<img src="/files/dlpmDOhPH7XgCXMd5IgK" alt="" data-size="original">

the log file is located at:

* For Windows: The log file is in the same directory as **UI.exe**

  ![](https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FNl61Gr6RNtDYEuJek7Gm%252Fimage.png%3Falt%3Dmedia%26token%3D0e0ea071-11e4-48e7-9f80-cbfbca10ccac\&width=768\&dpr=4\&quality=100\&sign=996aee40\&sv=2)
* For macOS: You can check the log file as follows:

  ![](https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FGLeXErV4KpBrfbJQhO3o%252Fimage.png%3Falt%3Dmedia%26token%3Dee485581-cf60-4008-aba7-5c4a91b16ee3\&width=768\&dpr=4\&quality=100\&sign=d6a8daf1\&sv=2)![](https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FL7O8qDstl6NwlwRQ4ZmJ%252Fimage.png%3Falt%3Dmedia%26token%3D972abd2e-b715-4f05-8601-baa99d22ad17\&width=768\&dpr=4\&quality=100\&sign=a61fc3b5\&sv=2)

When you contact our **<support@petoi.com>**, please attach the log file to your email.
{% endhint %}

### Run Firmware Uploader in the terminal

{% hint style="info" %}
There may be some OS platform compatibility issues with different computers.

You can still run the app directly from your terminal:

1. Go to OpenCat/pyUI/ in your terminal.
2. Install **PySerial** and **Pillow** for your Python installation. You may get a clean Anaconda environment and `pip3 install pyserial pillow`
3. Run `python3 UI.py`

For **NyBoard**, the firmware uploader calls the application **avrdude** to upload firmware files to the microcontroller.&#x20;

For **BiBoard**, the firmware uploader calls the application **esptool** to upload firmware files to the microcontroller.&#x20;

**Linux OS**

For Linux system users, in addition to the above steps, you also need to perform the following steps:

1\. Install **avrdude**&#x20;

* Fedora: dnf install avrdude
* CentOS: yum install avrdude
* Debian / Ubuntu: apt install avrdude

2\. Modify the variable **avrdudeconfPath** in FirmwareUploader.py

* Fedora / CentOS : `avrdudeconfPath = '/etc/avrdude/'`
* Debian / Ubuntu : `avrdudeconfPath = '/etc/'`
  {% endhint %}

{% hint style="info" %}
If you have experience with the Arduino IDE, you will see the same log message when uploading.

* For the BiBoard, please review the [Upload Sketch for BiBoard](/arduino-ide/upload-sketch-for-biboard).
* For the NyBoard, please review the [Upload Sketch for NyBoard](/arduino-ide/upload-sketch-for-nyboard).
  {% endhint %}


# Joint Calibrator

Robots can be precisely calibrated using the Petoi Desktop App.

Please refer to [the introduction](/product/bittle-x-v2+arm/control-and-program/petoi-desktop-app) for installing the Petoi Desktop App and connecting the robot to your computer.

## Prepare for calibration

This robotic arm is already fully assembled.

For the **pre-assembled** kit, install the neck servo in the servo slot using two M2 x 5 self-tapping screws. Then you can do the fine-tuning.

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252Ft8gnaABbmIwaMjHivgYX%252FNeck.jpeg%3Falt%3Dmedia%26token%3D83a08d4b-db61-4635-ac52-8c7a69d61d06&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=4addb956&#x26;sv=2" alt=""><figcaption><p>Install the robotic arm</p></figcaption></figure>

## The rationale for calibration

### Understand the zero state and the coordinate system

After [entering the calibration mode](#enter-the-calibration-state), with all servos rotated to their zero angles, attach the head, tail, and legs prepared in the previous section to the body. They are generally perpendicular to their linked body frames. The calibration pose is shown below:

<figure><img src="/files/jWYfOTCjDsbDKa4oT7BR" alt=""><figcaption></figcaption></figure>

For the construction kit, please install the servo-related components as shown in the picture (calibration mode) and ensure they are perpendicular to each other (the upper leg is perpendicular to the torso, and the lower leg is perpendicular to the upper leg).

{% hint style="warning" %}
Note: Insert the servo-related components directly into the servo output shaft; do not turn the output shaft during this process.
{% endhint %}

Rotating the limbs counterclockwise from their zero states will be positive (the same as in polar coordinates). Viewed from the left side of the robot's body, the counter-clockwise rotation of the joint is defined as the positive direction.

{% hint style="info" %}
The only exception is the head tilt angle for Nybble. It’s more natural to say head up, while it’s the result of rotating clockwise.&#x20;
{% endhint %}

{% hint style="info" %}
However, from the right side of the robot's body, the rotation directions' positive and negative are just opposite.
{% endhint %}

### Discrete angular intervals

If we look closer at the servo shaft, we can see it has a certain number of teeth. That’s for attaching the servo arms and avoiding sliding in the rotational direction. In our servo sample, the gears divide 360 degrees into 25 sectors, each taking **14.4** degrees(offset of -7.2\~7.2 degrees). That means we cannot always get a perfect perpendicular installation.&#x20;

![](/files/v400iIvlmpXjiobnloRS)

## Calibration process

### Enter the calibration mode

{% hint style="info" %}
Connect the battery to the mainboard, then long-press the battery button for more than 3 seconds to power on the robot.
{% endhint %}

&#x20;After a battery powers on the robot, there are two methods to enter the calibration mode:

* It will automatically enter calibration mode when you click the **Joint Calibrator** button.<br>

  <figure><img src="/files/CS20IELy2ji3gHVEWbTd" alt=""><figcaption></figcaption></figure>
* Click the **Calibrate** button in the **Joint Calibrator** interface.&#x20;

{% hint style="info" %}
The servo slider is not available in the light yellow background area in the interface.
{% endhint %}

The joint calibration interface for Bittle X+Arm, which uses **BiBoard V1** in the Petoi Desktop App, is as follows:

<figure><img src="/files/c2xhtXbVZNXlLGgRgtCT" alt=""><figcaption><p>For Bittle X+Arm with BiBoard V1</p></figcaption></figure>

Some customers already have **Bittle X** (BiBoard V0), which can also be equipped with a robotic arm. The joint calibrator interface is as follows. Please **note** the wiring of the servo:

<figure><img src="/files/0Rvk6j7dol4SFp5hx3Gg" alt=""><figcaption><p>For Bittle X+Arm with BiBoard V0</p></figcaption></figure>

### Installing and Fine-tuning

{% hint style="warning" %}
Please **disregard** the type of mainboard in the following installation pictures, as all Petoi mainboards have the same size.&#x20;
{% endhint %}

For **the Construction kit**, after entering the calibration state, please install the neck servo and legs as follows:

### Install the neck servo and leg servos

{% hint style="info" %}
Note:

You must use the neck section with a J-hook (as pictured below) to prevent the neck from falling when using this robot arm.

<img src="/files/AoTVJCeFZscPOVGhDd3g" alt="" data-size="original">      ![](/files/t8pKzAzCsZTioctL4P1S)
{% endhint %}

Installing the neck servo is the same as [installing the head](/mobile-app/calibrator/bittle-bittle-x#install-the-head) of Bittle.

Installing the leg servos is the same as [installing the legs](/mobile-app/calibrator/bittle-bittle-x#install-the-legs) of Bittle.

### Install the robot arm

This robot arm is already fully assembled. After finishing calibrating the neck servo and the leg servos, power off the robot and [install](/extensible-modules/robot-arm#installation) the servo slot on the neck servo with two M2\*5 self-tapping screws.

Then, power on the robot, and do the joint calibration for the servos on the robot arm.

#### Fine-tuning

{% hint style="info" %}
The **pre-assembled** robot should already have the components adequately installed. You can do the joint calibration for fine-tuning directly, without needing to uninstall the head and legs.&#x20;
{% endhint %}

Please use the L-shaped calibration tool included in the package as a calibration reference. According to the joint numbers shown in the calibration interface picture, click and drag the corresponding joint sliders or click the blank areas of the slider tracks to fine-tune the joints to a right angle.

Please note that when calibrating the servos, adjust the upper leg first, then change the lower leg.

![](/files/0HXBQK8Fem9hj1AmppKy)

![Align the upper leg first](/files/QpS91FEEbFx1kWR8Yofo)

![Pay attention to the reference edges for the lower leg](/files/kuwZZVGFrrkgDo4rhGiH)

{% hint style="info" %}
If the offset is more than +/-9 degrees, you need to remove the corresponding leg and reinstall it by rotating one tooth and then dragging the corresponding slider. For example, when it is adjusted to +9 and still not right, remove the corresponding leg and shift one tooth when attaching it. Then, you should get a smaller offset in the opposite direction.&#x20;
{% endhint %}

The process of fine-tuning the legs and the neck servo (**joint index 0**)  is the same as that of [Bittle / Bittle X's](https://guide.petoi.com/desktop-app/joint-calibrator/bittle-bittle-x#fine-tuning) (as above).&#x20;

Please click the blank part of the slider track and follow the calibration posture below to fine-tune **Servo 1** (**joint index 1**) on the robotic arm.

Please click the **Auto** button to fine-tune the claw servo (**joint index 2**) on the robotic arm.

You can also manually click the blank part of the corresponding slider track and adjust the gear on the servo output shaft to the position shown in the figure above.

### Validation and Save data

<figure><img src="/files/jHNumtKNF7h0GatL9xoh" alt=""><figcaption></figcaption></figure>

You can switch between  "**Rest**", "**Stand up**" and "**Walk**" to test the calibration effect.&#x20;

If you want to continue calibrating, please click the **Calibration** button, and the robot will be in the calibration state again (all servos will move to the calibration position immediately).&#x20;

{% hint style="warning" %}
Note: You may need a second round of calibrations to achieve optimal results.
{% endhint %}

After calibration, remember to click the "**Save**" button to save the calibration offset. Otherwise, click the "**Abort**" button to abandon the calibration data. You can save the calibration in the middle in case your connection is interrupted.&#x20;

{% hint style="info" %}
When you close this window, there is a message box shown below:

![](/files/iEbvluamYhzOnshzp9Bn)

To save the calibration data, please click the "**Yes**" button; otherwise, click the "**No**" button. Click the "**Cancel**" button to cancel or quit.
{% endhint %}

### Install the screws for the construction kit

After completing the joint calibration, install the center screws to fix the components and servo gears.


# Skill Composer

Petoi Skill Composer is a robobics skill design too for Petoi robots. Good tools are a prerequisite for job success.

Please refer to [the introduction](/product/bittle-x-v2+arm/control-and-program/petoi-desktop-app) for installing the Petoi Desktop App and connecting the robot to your computer.

## A Brief Introduction to the Interface

{% embed url="<https://www.youtube.com/playlist?list=PLHMFXft_rV6MTs8HMxSOvRAQektoXtaMG>" %}

### See [the video tutorials](https://www.youtube.com/playlist?list=PLHMFXft_rV6MTs8HMxSOvRAQektoXtaMG)

Open Petoi Desktop App, click the "**Skill Composer**" button, and open the Skill Composer interface.&#x20;

![](/files/4OWjfHFhnNsvmqWomxmj)

## The Skill Composer Interface

{% hint style="info" %}
The servo slider is not available in the light yellow background area in the interface.
{% endhint %}

<figure><img src="/files/CJbt5Oo3ZHnWPF6sTvCK" alt=""><figcaption><p>For Bittle X+Arm</p></figcaption></figure>

{% hint style="info" %}
Note: Most of the buttons on the interface have a tooltip when the mouse hovers over.
{% endhint %}

### Menu Options

* Model

  * Nybble
  * Nybble Q
  * Bittle
  * Bittle X
  * Bittle X+Arm

  Nybble cat and Bittle dog have different back leg joint directions. Their skill data are not interchangeable. Select the correct model before operating the Skill Composer. Otherwise, some joints may conflict with the robot's body.
* Language

  Currently, there are English, 中文, and Italian. You may contribute to the [translation script](https://github.com/PetoiCamp/DesktopAppRelease/blob/main/pyUI/translate.py).
* Utility

  We will keep adding small gadgets to the utility tab. We have an eye color picker for the Nybble cat's ultrasonic sensor with built-in LEDs. We also have an entry where you can add your creator credentials to the skills you create.

### Connection and State Dials

<figure><img src="/files/h24YX0YiSDhpIJol5NRJ" alt=""><figcaption><p>Connection and State Dials</p></figcaption></figure>

#### Listening / Connect button

for BiBoard:

* Wired connection: The kit includes a **USB Type-C data cable** connecting the robot's mainboard to the computer.
* Wireless connection (Bluetooth): The motherboard's [**built-in Bluetooth**](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard) module allows you to connect the robot's mainboard to the computer wirelessly.

{% hint style="info" %}
For NyBoard:

You can connect the robot to your computer via the [USB uploader](https://guide.petoi.com/communication-modules/usb-downloader-ch340c#connect-nyboard) or the system [Bluetooth settings](https://guide.petoi.com/communication-modules/dual-mode-bluetooth#connection-with-nyboard), then open up this desktop app.&#x20;
{% endhint %}

It should automatically detect and connect to the robot. The robot's serial port will appear in the following drop-down menu. The button should turn from "<mark style="color:yellow;">**Listening**</mark>" to "<mark style="color:green;">**Connected**</mark>". If the robot fails to connect for the first time, you can click the "<mark style="color:yellow;">**Listening**</mark>" button to disconnect all the ports, then press the "<mark style="color:red;">**Connect**</mark>" button again.

{% hint style="info" %}
Note: The desktop app will keep listening to the serial port and send a handshake signal to the newly added device. If the device responds with a pre-defined signal, it will be recognized as a Petoi device and added to the drop-down menu.
{% endhint %}

#### Servo

The robot's joints will hold position when the force is on. You should **NOT** rotate them by hand. Turning it off can allow you to rotate the robot's joints freely. It's helpful to quickly pose the robot to plan its center of mass for balancing.

#### Gyro

The robot has a gyroscope to detect its body angle and movements. It's used for balancing and roll-recovering. Turning it off can avoid unexpected reactions when rotating the robot.

#### Random

{% hint style="info" %}
For the robot with Nyboard, In certain experimental modes (e.g. [RandomMind mode](https://guide.petoi.com/desktop-app/firmware-uploader#select-the-correct-options-to-upload-the-latest-firmware)), the robot will move randomly. This button can toggle the behavior on/off.
{% endhint %}

### Send a serial command

<div align="left"><figure><img src="/files/jPvAyy2O5upvVQsmYkfx" alt=""><figcaption></figcaption></figure></div>

Like the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor), you can enter a [serial command](https://guide.petoi.com/apis/serial-protocol) in the text box and send it to the robot by pressing the **Enter** key or clicking the **Send** button.

### Preset Postures

![](/files/y1tu9IWMbAZMtwVRjo6F)

A few preset static postures move the robot's joints to specific positions. You can use them as a starting point to build your motion sequence. We usually start with the "balance" posture, with the robot standing on all four legs.

You can switch between different postures and observe how the sliders in the **Joint Controller** area update to reflect the changes in joint angles.

### Joint Controller

<figure><img src="/files/S8nWFhunvucGI8UYqJ63" alt=""><figcaption></figcaption></figure>

The angle sliders can show the robot's current joint angles. They can reversely rotate the robot's joints if you change their values. You can drag the slider bar for large angle adjustments or click above or below the slider bar for fine adjustments (by 1 degree). Some joints will have smaller accessible ranges than the sliders. Try to use angles between -125 and 125 degrees. Sending larger angles will increase the response time.

The sliders correspond to the robot joints if you look down at the robot's body with its head pointing forward. Joints closer to the body are closer to the center of the panel. The robot's joints can be mapped to your own body and become your avatar.

{% hint style="info" %}
Note: Some sliders with a light yellow background are disabled for joints that don't exist on specific models.
{% endhint %}

You can control multiple joints by clicking the dial "**+**" or "**-**" on each slider. All sliders with their "**+**" pressed will change by the same increments. Sliders with their "**-**" button pressed will change by the negative increments. The button can be toggled on and off. Click the "<mark style="color:red;">Unbind All</mark>" button to disengage all the joints at once.

You can also control the robot's whole body joints with the sliders in the center panel. You can tune these central sliders to adjust the robot's global orientation and translation. The neutral "**balance**" posture can generate better results than other tilted postures.

| Global Orientation and Translation | Effect                          |
| ---------------------------------- | ------------------------------- |
| Pitch                              | Adjust the pitch angle          |
| Roll                               | Adjust the roll angle           |
| Spinal                             | Move in the spinal direction    |
| Height                             | Raise or lower the robot's body |

### Skill Editor

<figure><img src="/files/nDnxRqJy00T1puNCMal1" alt=""><figcaption></figcaption></figure>

The previous functions can modify a single posture. The Skill Editor is a stop-motion animation scheduler. You can add, delete, and insert frames of poses and make the robot perform continuous and smooth motions.

Every frame has a row of buttons and input fields as parameters. The first static row contains the column header to indicate the parameters' names.

## Basic Operation

### The Activated Frame

You can click the "<mark style="color:blue;">**=**</mark>" button (**the 2nd item** of a frame) to activate the corresponding frame and move the robot to the frame's posture. The frame will hold all your new edits on the robot's current posture. The "<mark style="color:blue;">**=**</mark>" symbol will become bold, and the button will become larger. The "=" symbol will become a red "!" mark if the current frame is edited. You can click this button to save your edits. Otherwise, the current edits will be abandoned if you click the "<mark style="color:blue;">**=**</mark>" buttons of the other frames.

### Add a Frame

You can click the "<mark style="color:green;">**v**</mark>" button (**the 9th item** of a frame) to add a frame after the current frame and activate it. The new frame will be identical to the **previous activated frame**.&#x20;

{% hint style="info" %}
Note: The new frame doesn't necessarily copy the "<mark style="color:green;">**v**</mark>" button's frame.
{% endhint %}

### Insert a Frame

You don't always add a new frame after the last frame. You can click the "<mark style="color:green;">**v**</mark>" button (**the 9th item** of a frame) of any intermediate frames to insert a new frame below the "<mark style="color:green;">**v**</mark>" button. The new frame carries information identical to the previously **activated frame**.

### Mirror a frame

You can mirror the activated frame's posture by clicking the "**>|<**" button.

### Delete a Frame

You can click the "<mark style="color:red;">**<**</mark>" button (**the 8th item** of a frame) to delete the current frame holding the button. All the following frames will shift up. If **the activated frame** is deleted, its preceding frame will be activated. If **the activated frame** is the first frame and is deleted, its following frame will be activated.

### Add a Note to a Frame

You may lose track of what each frame holds with multiple edits to the frame list. Switching to individual frames can be time-consuming. We provide a "**Note**" field (**the 7th item** of a frame) where you can add short keywords to identify the frames. By default, a random animal name will be added to a frame when created.

<figure><img src="/files/rKC7CRO4y7yUGvwIASQU" alt=""><figcaption></figcaption></figure>

### Bound joints and passed-through edits

If a joint's angle is the same in the current frame and the next frame, editing and saving its angle will also update the angles in the following frames until the angle differs. For example, if joint 8's angles are 4,4,4,4,6,7 in all the frames, changing the angle in the second frame to 8 will update the sequence to 4,8,8,8,6,7.

### Play the Skill Sequence

Besides manually clicking the "<mark style="color:blue;">**=**</mark>" button (**the 2nd item** of a frame) to view the single posture, you can click the "<mark style="color:green;">**Play**</mark>" button to show the postures in order starting from **the activated frame**. During playing time, the button's text becomes "<mark style="color:red;">**Stop**</mark>" to allow you to stop in the middle.

### Export the skill

After clicking the "<mark style="color:blue;">**Export**</mark>" button, you can choose a location and filename to save the skill (from **the activated frame**. If **the activated frame** is the last action frame, all action frames in the action frame list are exported) as a text file. You can cancel the savings to skip. The desktop app will still send the skill to the robot for real-time performance. And you can call the last exported skill by the serial token "**T**." There are two ways:

* Open [the serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) and input the serial command "**T**."
* Open [the mobile app](https://guide.petoi.com/mobile-app/controller), use the [Create Command](https://guide.petoi.com/mobile-app/controller#create-a-single-command) function, and enter the serial port command "**T**" in the **Code** text box.

{% hint style="info" %}
The last skill exported by the Skill Composer is stored in temporary memory. It can stay after the power is off and rebooted but **will be overwritten by a new export**.&#x20;

From version **1.1.3**, When exporting a skill, the desktop app automatically saves it to /Users/{username}/.config/Petoi/SkillLibrary/. Note the ***.config*** is a hidden directory but can be visited in the terminal or through a specific view setting. Therefore, you can easily manage the skills in [Mind+](https://guide.petoi.com/block-based-programming/petoi-coding-blocks#perform-the-skill-in-the-file).

The [Skill Creation](/applications/skill-creation) chapter focuses on the code and data structure so that you can integrate any number of new skills into the source code. The skill data array in the exported text file (\*.txt or \*.md) content *can be copied and pasted into the Instinct*\*\*.h file to be used as a skill array.
{% endhint %}

* [Export the skill ](/mobile-app/controller#import-new-skills-as-a-customized-button)as a customized button in the mobile app. It can be **permanent** even if you create multiple skills.&#x20;

### Import the Skill

You will see a pop-up window after clicking the <mark style="color:blue;">"Import"</mark> button. It allows you to copy-paste a skill data array in the text editor or import an existing skill file you or other users created. You can find example skill data in OpenCat/src/**InstinctBittle.h** or **InstinctNybble.h**. A complete skill format should include the "**{ }**" pair and the numbers between them. Only **the first one** will be imported if there are multiple skill arrays. The importer will do some simple format checks.

{% hint style="info" %}
[The SkillLibrary folder](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary) in GitHub is a collection of new skills of the OpenCat robot, which can be used for your reference (after downloading, use the import function to save a single skill to the robot's memory, and then use the [play](#play-the-skill-sequence) or [export](#export-the-skill) to view the specific effect).&#x20;

You are welcome to share your new skills by sending merge requests to this folder.
{% endhint %}

### Reset the Skill Editor

You can use the "<mark style="color:red;">**Restart**</mark>" button to clear the Skill Editor panel and start over.

## Advanced operation

### Set up Action Frame Loops

If you need some consecutive action frames in [the action frame list](#skill-editor) to run multiple times in a loop, you can first enter the number of loops in the **Repeat** text box above [the action frame list](#skill-editor) (on the **left side** of the label "**Set**"), and then use the left mouse button to select them in turn, The index numbers (**the 1st item** of a frame) of the **first** and **last** two frames of the continuous action frame that want to achieve cyclic motion (the index number button will appear in a recessed state after selection), as shown in the following figure:

<figure><img src="/files/UJIa23LB49MEBFqt22Il" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you enter **-1** in the **Repeat** text box, the looping action frames will keep looping forever unless you press the reset button on the mainboard of the robot.
{% endhint %}

### Set Movement Speed

In [the action frame list](#skill-editor), you can set the running speed of each frame of action (**the 3rd item** of a frame). There are the following 9 options for you to choose from (speed up the running speed in the order of numerical value):

1，2，4，8，12，16，32，48，max

{% hint style="info" %}
Note:

* In the options box, you can also enter any integer value in the range of 0\~125 (0 means max).
* By clicking the "<mark style="color:green;">**Play**</mark>" button in the "**Skill Editor**" area, you can **NOT** see the real running speed effect of the action; only after clicking the "<mark style="color:blue;">**Export**</mark>" button will you see the real running speed effect.
* Moving at the fastest speed for a long time will cause damage to the servo, so it is generally recommended **NOT** to set it to "**max**".
* When the "<mark style="color:green;">**Gyro**</mark>" button in the "[**State Dials**](#connection-and-state-dials)" area is turned on (the font color is <mark style="color:green;">green</mark>), after adjusting the joint angle value in the action frame or the running speed of the action frame, [<mark style="color:green;">**play**</mark>](#play-the-skill-sequence) it to view the debugging effect, or [<mark style="color:blue;">**export**</mark>](#export-the-skill) the action behavior, the robot It will try to maintain its own body balance in real-time, so it may be seen that when the robot is doing preset actions (especially when running relatively violent actions), its body will shake back and forth or even overturn, and the robot will automatically recover. Action may disrupt your original operation steps. Therefore, it is recommended that you click the "<mark style="color:green;">**Gyro**</mark>" button when designing the action to turn off the gyroscope (the font color changes to <mark style="color:red;">red</mark>), and the robot will not perform balance feedback actions in real-time. When turning on the gyroscope, click the "<mark style="color:red;">**Gyro**</mark>" button again.
  {% endhint %}

### Set Delay

In [the action frame list](#skill-editor), the "**Delay**" option (**the 6th item** of a frame) in each action frame indicates how long the robot delays before doing the next frame of action after the action of this frame is completed.

There are **17** presets for you to choose from: 0，50，100，200，300，400，500，600，700，800，900，1000，2000，3000，4000，5000，6000.

Of course, you can also enter any integer value in the range of 0\~6000 in the "**Delay**" option box. The unit is milliseconds (ms).

### Set Trigger and Angle

<figure><img src="/files/TnxUVWmiNoM5md5KDEyI" alt=""><figcaption></figcaption></figure>

The "**Trigger**" option (**the 4th item** of a frame) in the action frame is used to set the body rotation direction when the robot triggers the next action frame. There are the following **5** setting options:

* **None** means that there is no trigger and the angle condition is set
* **Pitch** means the robot body rotates nose-down
* **-Pitch** means the robot body rotates nose-up
* **Roll** means that the robot body rolls to its left side (counter-clockwise when looking from the tail)
* **-Roll** means the robot body rolls to its right side (clockwise when looking from the tail)

The "**Angle**" option (**the 5th item** of a frame) is defined with reference to the angle of the polar coordinate system. As shown in the figure above, when the body is horizontal, the angle of the polar coordinate axis is 0 degrees. If the polar coordinate axis rotates counterclockwise, the angle is positive and gradually increases. The angle setting range is an integer value between **-125\~125**.

When a specific trigger and angle are set in the action frame, the next frame of action will be triggered only when the robot rotates over the trigger angle in the trigger's direction. If a delay time is also set in this action frame, it will delay an additional time after the trigger condition is met before moving to the next frame.

When creating actions related to the rotation of the robot body (such as backflips, doing high bar exercises, etc.), it's vital to trigger the motion at a certain body angle whose timing can be hard to estimate, and it may also change during the motion. We can use the gyroscope to monitor the rotation angle of the robot body in real-time, so that the robot can trigger the joint servo at the exact time of the trigger event.&#x20;

### Export Mirror Actions

When exporting the action frames, if you want to mirror all the action frames in [the action frame list](#skill-editor) (the robot's left and right side joints will be exchanged, as if seen in a mirror), you can first click the "[<mark style="color:blue;">**MirrorAll**</mark>](#skill-editor)" button, and then click the "[**Export**](#export-the-skill)" button. If you want to cancel the mirrored export, you can deselect the "<mark style="color:blue;">**MirrorAll**</mark>" button.

### Behavior and Gait Options

Before exporting action frames, select the "**Behavior**/**Gait**" options in the "[**Skill Editor**](#skill-editor)" area as "<mark style="color:blue;">**Behavior**</mark>". After clicking the "[<mark style="color:blue;">**Export**</mark>](#export-the-skill)" button, the program will run on the robot and automatically interpolate between these action frames to make the robot move smoothly. All action frames will execute for only one round.

If the "<mark style="color:blue;">**Gait**</mark>" option is selected before you click the "[<mark style="color:blue;">**Export**</mark>](#export-the-skill)" button, the robot will continue to execute in a loop, and each action frame will run at the fastest speed; **NO** interpolation between action frames will be added. The motion can be quite brutal. Therefore, it is recommended that beginners always use the "**Behavior**" option to develop new skills.

When importing some pre-built skill array, the desktop app will automatically select the "**Behavior**/**Gait**" option according to the data format. The frames will be loaded into the frame editor, and the robot will automatically move to the first frame's posture.

{% hint style="info" %}
After sending a command, the desktop app will wait for the robot to return a confirmation token. It may freeze if the robot's program halts or the connection is lost. You don't need to close the desktop app and lose the unsaved action frames but press the "**reset**" button on the robot's main board to break the app's waiting loop. If the program still does not respond, you can click a posture button in the "[**Preset Postures**](#preset-postures)" area or try to reconnect the robot using the "Connect/Listening" button.
{% endhint %}

### Simultaneous Control of Multiple Robots

The desktop app supports connecting multiple robots via their own USB data cables or via [Bluetooth ](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard)to achieve simultaneous control. The desktop app can only recognize a serial port as a robot.&#x20;

{% hint style="info" %}
For the robot with NyBoard:

* [USB data cable](https://guide.petoi.com/communication-modules/usb-downloader-ch340c#connect-nyboard)\
  Connect the USB uploader to the robot's mainboard, then connect the data cable to the computer's USB port.
* [Bluetooth](https://guide.petoi.com/communication-modules/dual-mode-bluetooth#connection-with-nyboard)\
  Plug the Bluetooth module into the robot's mainboard, then pair it with the computer's Bluetooth settings interface.&#x20;
  {% endhint %}

So after the robot is powered on normally, the desktop app will keep detecting if there is a new serial port connection. When multiple serial ports are successfully connected, the serial port option button in the "[**State Dials**](#connection-and-state-dials)" area will change to "<mark style="color:blue;">**All**</mark>." Click the drop-down list to view all serial ports that have been successfully connected. All robots will be synchronized in real-time in this way. You can also select any one of the serial ports to control the corresponding robot.&#x20;

If you unplug a USB serial port on the computer (or disconnect the Bluetooth module in the Bluetooth setting interface), the corresponding serial port will be removed from the drop-down list in real-time.

If you unplug all USB serial ports (disconnect all Bluetooth modules), the serial port option button displays "**None**," and the left button displays "<mark style="color:yellow;">**Listening**</mark>." The desktop app still automatically detects whether there is a serial port connection. When a robot is reconnected to the computer through the serial port, the button on the left side of the drop-down menu will display "<mark style="color:green;">**Connected**</mark>." The corresponding serial port name is displayed in the serial port option button.

If you want the desktop app to stop detecting serial connections, click the "<mark style="color:green;">**Connected**</mark>" / "<mark style="color:yellow;">**Listening**</mark>" button. The text in the button will change to "<mark style="color:red;">**Connect**</mark>," and all serial connections will be disconnected. Click the "<mark style="color:red;">**Connect**</mark>" button again to restart the real-time detection function.

## Professional extensions

You can modify the source code of the Skill Composer in **OpenCat/pyUI/SkillComposer.py**.&#x20;

## Teach by pulling the legs using the feedback servo

{% hint style="warning" %}
This function requires the servos after March 2024, the BiBoard, and the latest firmware.&#x20;
{% endhint %}

We have added the position feedback feature to recent batches of Petoi servos. The servo can reply to a specific PWM pulse (3500µs) with its current position in the form of pulse length. The central controller (BiBoard) can convert the signal to angles for more interaction.

{% embed url="<https://youtu.be/vlHBf_dN4R0>" %}

First, [send the robot a serial command](https://guide.petoi.com/arduino-ide/serial-monitor#set-up-in-the-arduino-ide) "**fl**" to start the learning process. In the demo, it's triggered by our customized voice command. The robot's servo driver will switch to reading mode. Joint jigs can occur during this transition. Organize the robot's legs and then hold it still. Learning begins when no significant movements are detected.

Pull the legs, and the movement will be recorded. Stopping in the middle is okay because identical postures will be skipped. The recording will stop if the maximum frame is reached or if the robot's joints remain stationary for 2 seconds.

The recorded command can be replayed by typing "**fr**". The skill data is also printed to the screen, allowing you to save it and import it into the Skill Composer or other OpenCat interfaces.

The control logic is defined in **OpenCatEsp32/src/reaction.h** and **motion.h**.


# Tools

From the desktop app version **1.2.1**, the Petoi Desktop App includes a new module: **Tools**. This module provides convenient tools to fix your robot's frequent problems.&#x20;

<figure><img src="/files/9H11VrUWgmVvULuTcD1S" alt=""><figcaption></figcaption></figure>

## Reset voice module <a href="#download-the-latest-version-of-the-petoi-desktop-app" id="download-the-latest-version-of-the-petoi-desktop-app"></a>

It is used to reset the [voice command module](https://guide.petoi.com/extensible-modules/voice-command-module), simplifying its [debugging process](https://guide.petoi.com/extensible-modules/voice-command-module#how-to-debug-if-the-voice-command-doesnt-work).  If the voice module does not respond to your voice, you can use this tool to reset it. It's pretty simple to use: click the **Reset voice module** button.

<figure><img src="/files/K5BT0zg61pnYk911sxII" alt=""><figcaption></figcaption></figure>

Please follow the instructions in the message box.&#x20;

<figure><img src="/files/d6uJBBIu4n5Y4lrtR6Kd" alt=""><figcaption></figcaption></figure>

If the problem persists, please email <support@petoi.com>.

## Calibrate gyroscope

{% hint style="info" %}
From the desktop app version **1.2.4**, the interface has added this new function.
{% endhint %}

It is used to calibrate the gyroscope sensor on the mainboard. If you notice that the robot cannot maintain balance while performing skill movements (such as sitting down) and its body keeps shaking, you need to recalibrate the gyroscope. To calibrate the gyroscope, click the **Calibrate gyroscope** button.

<figure><img src="/files/nPiZL3EettB9GlNynmvq" alt=""><figcaption></figcaption></figure>

Follow the instructions in the message box:

<figure><img src="/files/oK9OXmO0clF6DxNY73Zo" alt=""><figcaption></figcaption></figure>

If the problem persists, please email <support@petoi.com>.

## The Serial monitor

From the desktop app version **1.2.7**, we added the serial monitor feature in this interface.

If the robot and computer are already connected via a USB Type-C cable, the program will automatically enable serial communication after the interface opens. You can then directly enter serial commands in the ***serial command input box*** and press the **Enter** key on your keyboard or click the **Send** button to send the serial commands to the robot.

<figure><img src="/files/aHqWIcppwjKp8MU3WbCU" alt=""><figcaption></figcaption></figure>

If you encounter any problems, you can click the **Copy** button below to copy all the information in the output box, or you can select part of the relevant information in the output box with your mouse and then click the **Copy** button to copy the selected information. Paste the copied the information into your email and send it to support.petoi.com for assistance.


# Petoi Coding Blocks

How to use the extension library specially developed for the Petoi robot in Mind+

## Prepare Mind+

* Download the latest version from the [Mind+ official website](https://mindplus.cc/download-en.html)
  * For Windows: Mind+ version **>= V1.7.0**
  * For macO&#x53;**:** Mind+ version **>= V1.7.3 RC2.0**

{% hint style="warning" %}
If you cannot download the software from Mind+'s official website, you can download a stable version from [the Google Drive folder](https://drive.google.com/drive/folders/1V9WSnNiEOKZznP05W_RPxUD0TqAFFK7T). However, we strongly recommend that you download and use the official latest version.
{% endhint %}

{% hint style="info" %}
**For macOS only:** If you have already installed the old Mind+ version (**<=**&#x56;1.7.2 RC3.0), we recommend that:

1. You uninstall it first
2. Delete this folder /Users/\[vour username]/Documents/mindplus-pv/environment/Python3.6.5.64/ib/python3.6/site-packages/
3. Download and install the latest version of **Mind+**.
   {% endhint %}

* After the installation is complete, you can open Mind+

{% hint style="info" %}
If the default installation language is Chinese, you can switch to **English** as follows:

<img src="/files/y8C9aqhcfz6ItOCnwh25" alt="" data-size="original">
{% endhint %}

## Watch the video tutorials

We provide [a series of video tutorials](https://www.youtube.com/playlist?list=PLHMFXft_rV6POrzm8O12Nybdy1-FS1ymg) on using Petoi Coding Blocks with [the free Scratch-like robotics coding curriculum](https://www.petoi.com/pages/free-quadruped-robotics-curriculum-scratch-coding).   Be sure to click next to go through all the videos.

{% embed url="<https://www.youtube.com/playlist?list=PLHMFXft_rV6POrzm8O12Nybdy1-FS1ymg>" %}

## Prepare Petoi Robot

Please follow the instructions in the subpages to prepare according to the robot's mainboard.

For BiBoard products, such as [**Bittle X**](https://bittle-x.petoi.com/) ([BiBoard V0](https://guide.petoi.com/biboard/biboard-v0)), **Bittle X V2** ([BiBoard V1](https://guide.petoi.com/biboard/biboard-v1-guide)),  **Bittle X+Arm** (BiBoard V1), and **Nybble Q**(BiBoard V1), no software modification is required. By default, all functional blocks in Mind+ are supported.&#x20;

#### Plug the battery socket into the BiBoard, install it in the chassis, and long-press the battery button to power on the robot.

### Connection method

* Wired connection: The kit includes a **USB Type-C data cable** connecting the robot's mainboard to the computer.
* Wireless connection (Bluetooth): The mainboard's [**built-in Bluetooth**](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard) module allows you to connect the robot's mainboard to the computer wirelessly.

## Import Petoi Mind+ extension library

<figure><img src="/files/o27cet8NjxztUuFEzXWi" alt=""><figcaption></figcaption></figure>

Paste the GitHub URL(<https://github.com/PetoiCamp/Petoi_MindPlusLib>) in the text box of the import interface:

<figure><img src="/files/MFD3xnGLRViJZQJzpK10" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/gG9DcmsJsKnHEtxXh3sG" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
For macOS (if the Mind+ version **<= V1.7.2 RC3.0**), you need to download [PetoiRobot.zip](https://github.com/PetoiCamp/Petoi_MindPlusLib/raw/main/PetoiRobot.zip) and copy the extracted folder (PetoiRobot) to /Users/{your username}/Documents/mindplus-py/environment/Python3.6.5-64/lib/python3.6/site-packages/

![](/files/AZu2HURU7HI2m7vqwC2M)
{% endhint %}

{% hint style="info" %}
You can also download the latest extension library file (***\*.mpext***) from the [GitHub repository](https://github.com/PetoiCamp/Petoi_MindPlusLib/tree/main). And then import it  as follows:

![](/files/bwMseGKJ9q0AYBNtK24X)

![](/files/jtuV53VTfGH5H4Z4Whtc)
{% endhint %}

## Programming and Running

<figure><img src="/files/Vvv2cFA7C2IapMsyP6zY" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Petoi Coding Blocks is a user-extended library of Mind+.&#x20;

If you open **Mind+** by double-clicking the icon![](/files/92YALGSXvECxpZe0MY4r), it will not automatically load this extension library, and you need to re-import it manually every time you open the app.&#x20;

If you open Mind+ by double-clicking the code file(suffix **mp** or **sb3**) that uses this extension library or load these code files after opening Mind+, Mind+ will automatically load this extension library.
{% endhint %}

## The principle and process

This extension library can control the robot without compiling and uploading the code to the robot's main board. Click the "Run" button directly to run the program on the Python level and send instructions to the robot's serial port. If you need to stop the program while running, you can click the "Stop" button anytime. The process of the program can be divided into three steps:

1. &#x20;Open the serial port
2. &#x20;Control the robot
3. &#x20;Close the serial port

## The instructions for blocks

### Open the serial port

There are two ways to open the serial port:

* Automatically identify and open the serial port\
  ![](/files/hSINs1yNcWlGsf0u4q7n)
* Enter the name of the serial port to open the serial port\
  ![](/files/S1iOlfySZBn7om16Mdku)

{% hint style="info" %}
If it fails to open the serial port, you can refer to the printed information in the terminal window to replace the name of the serial port:

![](/files/i0bQFkVv43dnbccZ6361)
{% endhint %}

### Perform built-in skills

<div align="left"><figure><img src="/files/7jKeQh2wGwuFwgDAkCLb" alt=""><figcaption></figcaption></figure></div>

Use this block to let the robot perform skills pre-built on the robot's main board. Skills from "**sit**" to "**zero**" are **postures** (containing only one action frame).  Skills from "**boxing**" to "**sniff**" are **behaviors** (containing multiple posture frames and are performed only once).  Skills from "**stepping**" to "**trotRight**" are **gaits** (containing multiple posture frames, and are repeated in periodical loops until stopped).&#x20;

After finishing the current block's task, the program will wait a short time (delay xx seconds) before moving to the next block.&#x20;

### Perform the last skill exported from the Skill Composer

<div align="left"><figure><img src="/files/QZ1G3oIJaRp0PrfyTotm" alt=""><figcaption></figcaption></figure></div>

Use this block to let the robot perform the last skill exported from the [Skill Composer](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-desktop-app/skill-composer#export-the-skill).&#x20;

{% hint style="info" %}
It is equivalent to inputting the serial command 'T' in the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) and then delaying the preset time.
{% endhint %}

### Perform the skill in the file

<div align="left"><figure><img src="/files/N3EGVSD6wBrTkR0YWFCD" alt=""><figcaption></figcaption></figure></div>

Use this block to let the robot perform the skill in the skill files, which are in the following directory:

* **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}

The folder name **{model}** is Bittle or Nybble. When [exporting](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-desktop-app/skill-composer#export-the-skill) a skill file from the **Skill Composer**, it will automatically save the skill file to this directory.

{% hint style="info" %}
Tips: You can also copy & paste the [SkillLibrary](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary) folder from the source code of the OpenCat project on GitHub to the ***.config/Petoi*** directory. Therefore, you can use some sample skills for your Mind+ program, and there is no need to use the export function in the Skill Composer.

![](/files/lIGPo06pBWsggE5hDgwn)
{% endhint %}

{% hint style="info" %}
The folder **.config** is a hidden directory on MacOS/Linux but can be visited in the terminal or through a specific view setting:

* MacOS\
  open the directory /Users/{username} in Finder, then press the “**Command**” + “**Shift**” + “**.**” (period) keys at the same time.<br>

  <figure><img src="/files/Vr4Q0OJZtyFDYhoeCJ9L" alt=""><figcaption></figcaption></figure>

{% endhint %}

### Rotate joints in a sequence.

<div align="left"><figure><img src="/files/l3eF6NwhpeuazKTPEglh" alt=""><figcaption></figcaption></figure></div>

Use this block to control one joint or multiple joints to rotate in sequence. There are several ways to use the blocks for reference:

* Controls individual joint rotations to an absolute angle value.<br>

  <figure><img src="/files/xSXiZEeFCJfTYwtkw0KV" alt=""><figcaption></figcaption></figure>
* Controls individual joint rotations to a relative angle value.<br>

  <figure><img src="/files/yAUrkV4FKyn1Vl0KgfTM" alt=""><figcaption></figcaption></figure>
* Control multiple joints to rotate sequentially to **absolute** angle values or **relative** angle values.<br>

  <figure><img src="/files/G9fc47tePSrHTivPlfKq" alt=""><figcaption></figcaption></figure>
* Use the joint angle list to control multiple joints to rotate to absolute angle values in a sequence.<br>

  <div align="left"><figure><img src="/files/KZDShPYUizPcrOsFR8pd" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}

* <img src="/files/j5rjUZf7qLCmZdG0KBEH" alt="" data-size="original">, <img src="/files/9b6l2VUoNHYuxEhfffBz" alt="" data-size="original">represents a list consisting of a [joint index](https://app.gitbook.com/o/-M-_eWZUjFA4usjshHcZ/s/-MQ6a951Q6Jn1Zzt5Ajr-887967055/~/changes/285/petoi-robot-joint-index) and an angle value. For example, \[Head panning to 30 degrees] represents the list \[0, 30].
* <img src="/files/FyKxGaW0vddwqdYXceTc" alt="" data-size="original">\
  It consists of one or more pairs of[ joint index](https://app.gitbook.com/o/-M-_eWZUjFA4usjshHcZ/s/-MQ6a951Q6Jn1Zzt5Ajr-887967055/~/changes/285/petoi-robot-joint-index) + angle value, and the specific format is as follows: \
  \[joint index, angle value, joint index, angle value...]
  {% endhint %}

### Rotate joints simultaneously&#x20;

<div align="left"><figure><img src="/files/nCFY0sIXcipRPkDrjeRW" alt=""><figcaption></figcaption></figure></div>

Using this block can control multiple joints to rotate at the same time. There are several ways to use the blocks for reference:

* Control multiple joints to rotate to absolute angle values or relative angle values at the same time<br>

  <figure><img src="/files/soKQzuS4ylvcdCHG4L0R" alt=""><figcaption></figcaption></figure>
* Use the joint angle list to control the simultaneous rotation of multiple joints to absolute angle values.<br>

  <div align="left"><figure><img src="/files/Vh2XMoCWbfZ7yWfafXdX" alt=""><figcaption></figcaption></figure></div>

### Get the current angle value of a joint.

<div align="left"><figure><img src="/files/Brc9uT3zfvELerhTX5mN" alt=""><figcaption></figcaption></figure></div>

Use this block to get the current angle value of the selected joint. It is recommended to assign it to a variable first and then use the variable and algorithm to control other joints to rotate.

{% hint style="info" %}
The return value of this block is only an angle value, which cannot be filled in the "Turn sequentially" and "'Turn simultaneously" blocks alone.
{% endhint %}

#### Demo code

<figure><img src="/files/YZuJo0R5UyAWjq4Ea42T" alt=""><figcaption></figcaption></figure>

{% file src="/files/dTxtuiDyT9RbbPkwqO4S" %}

### Transform to frame

<div align="left"><figure><img src="/files/hRZwOu0SW2rvJtJSCgbI" alt=""><figcaption></figcaption></figure></div>

Use this block to control all joints to rotate at the same time. Please use it with the "**Action frame**" block. As shown below:

<div align="left"><figure><img src="/files/9JGREsuYLcSu0SolRpyD" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
The "Action frame" block represents a list of 16 angle values. Each angle value corresponds to the absolute angle value to which the corresponding [joint index](https://app.gitbook.com/o/-M-_eWZUjFA4usjshHcZ/s/-MQ6a951Q6Jn1Zzt5Ajr-887967055/~/changes/285/petoi-robot-joint-index) servo rotates.
{% endhint %}

### Play a melody

![](/files/NqKpHKy7twOf1TuiguBg)

Use this block to control the robot to play music. There are several ways to use  blocks together for reference:

* A list made up of multiple "Tone + Duration" blocks<br>

  <div align="left"><figure><img src="/files/gOG2tmvrP0Xn1zS331B4" alt=""><figcaption></figcaption></figure></div>
* Using a tone duration list<br>

  <div align="left"><figure><img src="/files/3NUr3wQkTxyhf3Qrwd6D" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
![](/files/7KMmq9wgWd8om7CeTaO3)

Consists of one or more pairs of Tone + Duration, the specific format is as follows:

\[tone, duration, tone, duration, tone, duration...]
{% endhint %}

### Execute a serial command

<div align="left"><figure><img src="/files/sPOyyF6TzwjUHvSLaStM" alt=""><figcaption></figcaption></figure></div>

Use this block to send a serial command to the robot, which can provide you with more and more flexible control methods. For example, you can input "**kkcL**" (kick the left front leg), and "**khiR**" (raise the right front leg to say hello). For more serial port commands, please refer to [the serial protocol](https://guide.petoi.com/apis/serial-protocol).&#x20;

### Write analog value

<div align="left"><figure><img src="/files/MqRx61qOySKFFMj7szCw" alt=""><figcaption></figcaption></figure></div>

Use this block to write an analog value to a specified pin. Analog value range: 0\~255

### Read analog value

![](/files/PlKNs3jjcUo0R2kf1M78)

Use this block to read an analog value from a specified pin.

### Write digital value

![](/files/HfD7apmmfLmGvZORMmaG)

Use this block to write a high/low-level value to the specified pin. High-level: 1; Low-level: 0.

### Read digital value

![](/files/WpiPm0lFfejX3m1gjTAA)

Use this block to read the high/low-level value of the specified pin.

### Read Ultrasonic sensor distance

<div align="left"><figure><img src="/files/l6XlAPafftMxUdjVJztQ" alt=""><figcaption></figcaption></figure></div>

Use this block to read the distance value from the ultrasonic sensor.

For the [Petoi RGB Ultrasonic Sensor](https://guide.petoi.com/extensible-modules/ultrasonic-sensor) (or **RUS-04**), you can set the two pins ( Trigger and Echo) like this:

* **NyBoard** (connects to the D6 and D7 pins)<br>

  <div align="left"><figure><img src="/files/Jc2cIVpIGzq7HzwkMLKq" alt=""><figcaption></figcaption></figure></div>
* **BiBoard** (connects to the Rx and Tx pins)<br>

  <div align="left"><figure><img src="/files/Jf90Y6ovj7a9NmRH1eAg" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
For other ultrasonic sensor models (e.g., **HC-SR04** connects to the D6 and D7 pins), you can set the two pins like this:

<img src="/files/wo5NE5VbCl2g8ZYjK0Gr" alt="" data-size="original">
{% endhint %}

#### Demo code

You can download the demo code from the [GitHub repository](https://github.com/PetoiCamp/Petoi_MindPlusLib/tree/main).

* BiBoard\
  examples/BiBoard/avoidObs\_BiBoard.mp
* NyBoard\
  examples/NyBoard/avoidObs\_NyBoard.mp

### Read the target coordinates

<div align="left"><figure><img src="/files/rJOcAU7G0ZR7OLhR10AP" alt="" width="510"><figcaption></figcaption></figure></div>

Use this block to Read the coordinates of the identified target from the camera module([MU camera](/extensible-modules/mu-camera) / [Petoi AI Vision module](/extensible-modules/petoi-ai-vision-module)) which connect to the BiBoard.

#### Demo code

<figure><img src="/files/dUL12wp13goeVxGcAQjY" alt=""><figcaption></figcaption></figure>

You can download this test code ([**testCamera.mp**](https://github.com/PetoiCamp/Petoi_MindPlusLib/raw/refs/heads/main/examples/BiBoard/testCamera.mp)) and run in the Mind+.

### Close the serial port

![](/files/3CNpi9KxnwBBHuT5JaNg)

Generally, at the end of the program, it is recommended to use this block to close the serial port communication.

### Demos

We provide some demos to download for reference in the [GitHub repository](https://github.com/PetoiCamp/Petoi_MindPlusLib) (Petoi\_MindPlusLib/examples).

<figure><img src="/files/T75f4JrnKdj4EfQevufc" alt=""><figcaption></figcaption></figure>

### [Free block coding curriculum for Bittle X](https://drive.google.com/drive/folders/1OU5LT47dbgWb5Av9Z4Qurq1GKlZyxNeD)


# Python coding mode in Mind+

## Switch to the Python coding mode

If you are familiar with the Petoi coding blocks and Python language, you can change to the **Code** mode in Mind+ as follows:

<figure><img src="/files/kDOa6QNU6XJGxyDruHbK" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/kUYqfTeFxjfa4RGYMc9M" alt=""><figcaption></figcaption></figure>

The **Code** mode is a Python 3 development environment. You can write any Python script in it and call all the PetoiRobot library APIs imported by Mind+.&#x20;

You can find the PetoiRobot library in the following directory. There are all the [definitions of API interfaces](/apis/python-api#available-apis) in the **robot.py**

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

Here is a sample code :

```python
# The code starts here
from PetoiRobot import *    # must import the PetoiRobot library

# enter the code below
# auto connect serial ports
autoConnect()

# call the APIs to control the Petoi robot
sendSkillStr('ksit', 0.5)
sendCmdStr('T', 0.5)
loadSkill("skillFileName", 0.2)

# close the serial port
closePort()
```

You can also copy the code in the **Auto-Generate** area in the **Blocks** mode and then paste it into the code file in the **Code** mode. Then you can edit and run the code.


# Install Mind+ on Chromebook

## Configure the Linux environment

You need to [**turn on Linux**](/technical-support/set-up-development-environment-on-chromebook) on the Chromebook to access the Linux environment via the terminal app.

Then, follow the following steps to install Mind+.

## Check the processor architecture

Use the following command to check the processor architecture in the terminal:\
***`uname -m`***\
The output will be similar to "i686", "x86\_64" or "armv7":\
i686 (or similar) - 32-bit Intel/AMD processor (common in older computers).\
x86\_64 (or similar) - 64-bit Intel/AMD processors (modern laptops, desktops, and most Chromebooks).\
armv7 (or higher) - ARM processor. (Mobile phones, tablets, 2nd and 3rd generation Raspberry Pis running Ubuntu Mate, and some Chromebooks. Most are 32-bit now)<br>

## Download package

According to different architectures to download different versions:<https://mindplus.dfrobot.com/linux><br>

## Installation

Use the following command in the terminal to install it (Replace **\*\*\*\*\*** with the file name of the installation package):\
***`sudo dpkg -i *****.deb`***\
***`sudo apt-get -f install`***

After installed, you can start the **Mind+** app in the Chromebook launcher:

<figure><img src="/files/pA5kAwIdHsOfQZobDZjp" alt=""><figcaption></figcaption></figure>

## Run Mind+

Now, you can proceed to the [Mind+ tutorial](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-coding-blocks).

{% hint style="warning" %}
Currently, connection via Bluetooth is not supported.&#x20;
{% endhint %}


# Arduino IDE

This chapter is for Advanced users with programming experience.

## 1. Download and Install

Please follow [the instructions](https://docs.arduino.cc/software/ide-v2/tutorials/getting-started/ide-v2-downloading-and-installing/).

For installation on Chromebook, please check [this guide](/product/bittle-x-v2+arm/control-and-program/arduino-ide/install-arduino-ide-on-chromebook).

## 2. Set up BiBoard&#x20;

For the specific parameters of each functional module of BiBoard, please refer to：

* [BiBoard V1 Guide](https://guide.petoi.com/biboard/biboard-v1-guide)
* [BiBoard V0 Guide](https://guide.petoi.com/biboard/biboard-v0)

### 2.1 Prepare the ESP32 development environment

Open “**Preferences**” in Arduino IDE, add ESP32 development board URL:

`https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json`

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FBeD6sfV1LKR8HOsRvvef%252Fimage.png%3Falt%3Dmedia%26token%3D469f106e-c18c-4e7e-9e36-cac3ea9cdda5&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=75d0ba4e&#x26;sv=2" alt=""><figcaption></figcaption></figure>

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252Fm4kA0SnO0HlaNRggKhTV%252Fimage.png%3Falt%3Dmedia%26token%3D7b4d2178-dc79-402e-886e-bccd277bd1e8&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=f8cdc92a&#x26;sv=2" alt=""><figcaption></figcaption></figure>

Click **OK** to save it and then exit.

Open “**Boards Manager...**” and wait for updates from external board support links. Search “esp32” and install the support package.

{% hint style="warning" %}
Please install the latest available version **2.0.12**. Installing version 2.0.13 and above may cause the motherboard to fail to startup.
{% endhint %}

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FkaI7GwGmYWxJLTksqswt%252Fimage.png%3Falt%3Dmedia%26token%3Ddda85ff5-f77c-4636-ae1d-1c4c49ef6618&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=d474360&#x26;sv=2" alt=""><figcaption></figcaption></figure>

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252Fymh9lMUwgWJEB2eHT2kv%252Fimage.png%3Falt%3Dmedia%26token%3D509f781c-fbbe-47e4-91ec-48e57d7eba8b&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=e4d6c4ea&#x26;sv=2" alt=""><figcaption></figcaption></figure>

After showing “**INSTALLED**”, the BiBoard board support package is finished.

### 2.2 Modify the code file in the package

* #### sdkconfig.h

{% hint style="info" %}

* For Windows:\
  C:\Users\\{username}\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.\*\tools\sdk\esp32\qio\_qspi\include\sdkconfig.h
* For Mac:\
  /Users/{username}/Library/Arduino15/packages/esp32/hardware/esp32/2.0.\*/tools/sdk/esp32/qio\_qspi/include/sdkconfig.h
* For Ubuntu:\
  Arduino root directory/.arduino15 (hidden file)/packages/esp32/hardware/esp32/2.0.12/tools/sdk/esp32/qio\_qspi/include/sdkconfig.h
  {% endhint %}

Append a line of code at the end of the file:

```cpp
#define CONFIG_DISABLE_HAL_LOCKS 1
```

### 2.3 Set up the board options

Please set up the board's upload speed, CPU frequency, etc, as shown in the picture below.&#x20;

There is a setting for the **Flash Size** and **Partition Scheme** among the options. For more information, refer to the next section.&#x20;

<figure><img src="/files/wzC46EwxIGDjVcKwEaSw" alt=""><figcaption></figcaption></figure>

### 2.4 Choose hardware partition

The **BiBoard V0** uses an ESP32 with a **16M** flash. To simplify, you can use the **default** **4 MB** partition map without a problem. There's plenty of programming space for the standard OpenCatEsp32 firmware.&#x20;

The **BiBoard V1** uses an ESP32 with a **4M** flash.

#### 4 MB partition

You can use the **Minimal SPIFFS (1.9MB APP with OTA/190KB SPIFFS)**. You can also use other partition schemes under the 4 MB flash limit, such as "No OTA" or "Huge APP".&#x20;

<figure><img src="/files/ZD0w7RMRATD8ehzC757t" alt=""><figcaption></figcaption></figure>

#### 16 MB partition

Suppose you want to fully utilize the 16 MB flash on **BiBoard V0** (it's unnecessary and takes longer to upload). You can read the user manual for the [Add hardware partition configuration option in Arduino IDE](https://guide.petoi.com/biboard/demo-applications/13.add-hardware-partition-configuration-option-in-arduino-ide).

### 2.5 Download the source code & install the library

{% hint style="info" %}
We keep updating the code as an open-source project. You can star-mark and follow our GitHub repository to get the newest features and bug fixes. You can also share your codes with worldwide OpenCatEsp32 users.&#x20;

You can check the update history information in the [**ChangeLog.md**](https://github.com/PetoiCamp/OpenCatEsp32/blob/main/ChangeLog.md)**.**
{% endhint %}

1. Download the ​OpenCatEsp32 repository from GitHub repository: <https://github.com/PetoiCamp/OpenCatEsp32>\
   We suggest you utilize GitHub’s version control feature. Otherwise, make sure you download the **WHOLE OpenCatEsp32 FOLDER** every time. All the codes have to be the same version to work together.&#x20;

<figure><img src="/files/J1dPxUacMfknKagtEw03" alt=""><figcaption></figcaption></figure>

2. If you download the Zip file of the codes, you will get an **OpenCatEsp32-main** folder after unzipping. Please rename it to **OpenCatEsp32** before opening the **OpenCatEsp32.ino** so that the two names match.&#x20;

{% hint style="warning" %}
No matter where you save the folder, the file structure should be:

![](/files/it5Ae2o7Ot6JhN9Hi28A)&#x20;
{% endhint %}

There are several **test\*\*\*.ino** codes in the **ModuleTests** folder. You can upload them separately to test specific modules (I recommend using **testBuzzer.ino** as your first test sketch).

3. Install the libraries
   * Download and install the [MU Vision Sensor library](https://github.com/mu-opensource/MuVisionSensor3) into the Arduino IDE.<br>

     <figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FrwlwHLV03mwtrtqVazop%252FmuLib.png%3Falt%3Dmedia%26token%3Df7721966-efb2-4388-9563-002c9aa93c3a&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=852f24b1&#x26;sv=2" alt=""><figcaption></figcaption></figure>

     <figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FRN0NyFXOV0ct9IOI0AqU%252FaddZipLib.png%3Falt%3Dmedia%26token%3D4803980c-41cf-406c-907c-3aaff81672ec&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=13cd3321&#x26;sv=2" alt=""><figcaption></figcaption></figure>

   * Install **ArduinoJson** in the Library Manager<br>

     <figure><img src="/files/IRiCEQUFLCVMECjd86bg" alt=""><figcaption></figcaption></figure>

     <figure><img src="/files/chUPMWLsfRiaSkCfylgo" alt=""><figcaption></figcaption></figure>

   * Install **WebSockets** in the Library Manager.<br>

     <figure><img src="/files/kDERHzH9sG2PSYjnqK2e" alt=""><figcaption></figcaption></figure>

### 2.6 [Connect to BiBoard](/quick-reference/upload-firmware#biboard) via USB type-C data cable

Set the serial port in the Arduino IDE:

<figure><img src="/files/i0UrTG4kz2OUwWUj58mb" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you cannot find the serial port after connecting to your computer:

* for BiBoard V0:

  You need to install [the driver](https://guide.petoi.com/technical-support/useful-tools/biboard-v1) for the CP210x chip.&#x20;
* For BiBoard V1:

  You need to install the driver as below:

  * Windows: <https://www.wch-ic.com/downloads/CH343SER_EXE.html>
  * Mac: <https://www.wch-ic.com/downloads/CH34XSER_MAC_ZIP.html>
* If the battery powers on the BiBoard, please long-press the button on the battery >=3s to power off the BiBoard, so that the BiBoard is only powered through the USB cable and only the blue LED is lit up.&#x20;
  {% endhint %}

### 2.7 Compile and upload the sketch

For Bittle or Bittle X:

<pre class="language-cpp"><code class="lang-cpp">#define BITTLE    //Petoi 9 DOF robot dog, also for Bittle X
<strong>//#define NYBBLE  //Petoi 11 DOF robot cat, also for Nybble Q
</strong>//#define CUB
</code></pre>

For Nybble or Nybble Q:

<pre class="language-cpp"><code class="lang-cpp">//#define BITTLE    //Petoi 9 DOF robot dog, also for Bittle X
<strong>#define NYBBLE  //Petoi 11 DOF robot cat, also for Nybble Q
</strong>//#define CUB
</code></pre>

Modify the mainboard model macro definition in OpenCatEsp3&#x32;**.ino** according to the mainboard (BiBoard) version.

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

If the robot(**Bittle X+Arm**) has the robotic arm, you should also activate the macro definition as follows:

<pre class="language-cpp"><code class="lang-cpp"><strong>#define ROBOT_ARM                 // for attaching the head clip arm
</strong></code></pre>

Otherwise, please comment out this line of code.

After the modification is completed, you can click the **Upload** button (as below) to upload the sketch **OpenCatEsp32.ino**, and the changes in the code file will be automatically saved.

<figure><img src="/files/tdpRznaQQrpxXC9osxpY" alt=""><figcaption></figcaption></figure>

### 2.8 Program Initialization

If the **version date** of the currently uploaded sketch is **newer** than the version date of the mainboard firmware, it will automatically enter the **Initialization Startup Mode** after the sketch upload is completed.

{% hint style="warning" %}
Please click the **Serial Monitor** button to open it and set the configuration parameters to **115200** baud rate and **No line ending**.
{% endhint %}

<figure><img src="/files/glEjFxmuYkPy8rRP367h" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/FR7Ns4IvrqMetC1dz3oR" alt=""><figcaption></figcaption></figure>

* You can check the version date of the currently uploaded sketch in the source code file (OpenCatEsp32/src/OpenCat.h):\
  `#define DATE "250218"  // YYMMDD`
* You can send the serial command "**?**" in the serial monitor to check the version date of the mainboard firmware:\
  ![](/files/cjbt1P99Ydx1pEjpJh8m)

When the mainboard is powered on, open the serial monitor and you will see the startup information:

```
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
```

{% hint style="info" %}
If you do not see the startup information after opening the serial monitor, please short press the **Reset** button on the mainboard.
{% endhint %}

Next you will see the following prompt questions:

```cpp
Reset the joints' calibration offsets? (Y/n): 
```

* Send '**Y**' to the question, which means resetting all servo corrections to zero.
* &#x20;Send "**n**" to skip this step.

{% hint style="info" %}
If you want to keep the previous joint calibration data, please send '**n**'.
{% endhint %}

```cpp
- Calibrate the Inertial Measurement Unit (IMU)? (Y/n): 
```

* Send '**Y**' to the question, which means calibrating the IMU, i.e. the gyro/accelerometer sensor.
* &#x20;Send "**n**" to skip this step.

{% hint style="info" %}
If you want to keep the previous IMU calibration data, please send '**n**'.
{% endhint %}

{% hint style="warning" %}
Halts at the connection stage. To restart it, you can close and reopen the serial monitor or press the reset button on BiBoard. Put the BiBoard **FLAT** on the table, and don't touch it during calibration.

Sometimes, the program halts at the connection stage. To restart it, you can close and reopen the serial monitor or press the reset button on BiBoard.&#x20;

The program starts calibration after playing the melody 6 times.
{% endhint %}

```
Run factory quality assurance program? (Y/n)        
```

Input '**n**' and press **Enter** to continue. Or you can do nothing, it will Auto skip in 5 seconds.

The details of serial port printing information are as follows：

```cpp
* 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

```

When the string "<mark style="color:green;">**Ready!**</mark>" is output in the serial monitor, the program will enter the **regular startup mode**.

Every time the mainboard is powered on, it compares the BIRTHMARK in the EEPROM to determine whether the program has been initialized. If the program has already been initialized, it will **not enter** the **initialization startup mode** again.

{% hint style="info" %}
**Note:** When the mainboard is powered on, the music melodies played in the **Regular Startup Mode** and the **initialization startup mode** are entirely different. This is convenient for users (no need to open the serial monitor) and can also identify the startup mode.&#x20;

If you need to clear the calibration parameters of the servo and recalibrate the joint servo, or recalibrate the IMU, you can send the serial command "<mark style="color:red;">**!**</mark>" in the serial monitor, and the program will **re-enter** the **Initialization Startup Mode**.
{% endhint %}

### 2.9 Switch working mode via the serial commands (Optional)

The default code runs the **Standard** mode (including the **Voice command** function). If you want to switch modes, Please open the serial monitor and send the following serial commands:

<table><thead><tr><th width="172">Serial command</th><th>Function</th></tr></thead><tbody><tr><td>XA</td><td>Voice. For <strong>BiBoard V0</strong>, the switch on the extension hat should be dialed to the <strong>Voice command</strong> side （<strong>default mode</strong>）</td></tr><tr><td>XU</td><td>Ultrasonic. For <strong>BiBoard V0</strong>, the switch on the extension hat should be dialed to the <strong>UART2</strong> side; voice control will not work.</td></tr><tr><td>XC</td><td>Camera</td></tr><tr><td>XL</td><td>Light</td></tr><tr><td>XT</td><td>Touch</td></tr><tr><td>XI</td><td>PIR</td></tr><tr><td>XG</td><td>Gesture</td></tr><tr><td>XD</td><td>IR distance</td></tr><tr><td>XQ</td><td>Quick demo</td></tr><tr><td>XS</td><td>Enable the Serial 2(Tx2, Rx2). For <strong>BiBoard V0</strong>, the switch on the extension hat should be dialed to the <strong>Uart2</strong> side; voice control will not work. </td></tr><tr><td>XB</td><td>Enable the back touch funtion. </td></tr><tr><td>X</td><td>Disable all the module functions above.</td></tr><tr><td>z</td><td>RandomMind (On/Off)</td></tr></tbody></table>

{% hint style="info" %}
The behavior of the official modules is defined in separate header files in **OpenCat/src/**. You can find them in **OpenCat/src/io.h** **-> readSignal()**. The behavior of **Quick demo** mode is defined in **OpenCat/OpenCat.ino ->  quickDemo()**. You can study the example code to write your functions.&#x20;

You can learn about the function of each module through the [**EXTENSIBLE MODULES**](https://guide.petoi.com/extensible-modules/introduction).
{% endhint %}

### 2.10 Power on

* Long-press the battery button and boot up the robot with one side up. It will enter the calibration state automatically in the **regular startup mode**. The picture below shows the head, the upper and lower legs installed after the robot enters the calibration state.

![](/files/mzq2t0vK9IyMU6MU2LJG)

Please refer to [Chapter 5 🔌 Connect Wires](https://bittle.petoi.com/5-connect-wires) and [Chapter 6 📐 Calibration](https://bittle.petoi.com/6-calibration) for the complete calibration process.

* If you power on the robot and it is upright (with its back facing up), it will start in the "rest" posture (fold the legs and unlock the servos) in the **regular startup mode**.

### 3. Configuration with App

The BiBoard has built-in Bluetooth, and you can connect it to the [mobile app](https://guide.petoi.com/mobile-app/introduction) for [joint calibration](https://guide.petoi.com/mobile-app/calibrator) and [remote control](https://guide.petoi.com/mobile-app/controller) (for **Bittle X**, which has the mainboard **BiBoard V0**).


# Serial Monitor

## Mainboard connection

* Wired Connection: The kit includes a **USB Type-C data cable** connecting the robot's mainboard to the computer.
* [Wireless Connection(Bluetooth)](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard): The mainboard's built-in Bluetooth module lets you connect the robot's mainboard to your computer wirelessly.

## Set up in the Arduino IDE

1. Select the port in the [Arduino IDE](https://www.arduino.cc/en/software)(recommended version **1.8.19**).

![](/files/HzLGPoEbbiAkP6ySVyut)

{% hint style="info" %}
If you can't determine which port is correct, unplug and re-plug the USB data cable on the computer side and check the difference in the ***Tools*** menu.

You may install the [drivers](https://guide.petoi.com/technical-support/useful-tools) if no new port is shown in the menu list.
{% endhint %}

2. Open the serial monitor.

You can choose the "Serial Monitor" in the ***Tools*** menu bar or click the ![](/files/rFegvOusKIAfaewQ5pHB) Button to open the serial monitor window:

![](/files/3qVD0VPFEtSelxddsD66) ![](/files/NfoeNDc4SxSFe0pPUCuq)

3. Configure the parameters of the serial monitor.

In the serial monitor, set "***No line ending***" and the baud rate to ***115200***.&#x20;

![](/files/HqQm5fVMgFHfBfpSG7WR)

With the USB adapter / Bluetooth module connecting NyBoard and computer, you have the ultimate interface - **Serial Monitor** to communicate with NyBoard and change every byte on it(via sending the serial commands based on the [serial protocol](https://guide.petoi.com/apis/serial-protocol)).


# Calibrate the joints with Arduino IDE

## Prepare to Enter the Calibration State

Please refer to the [preparation section](https://guide.petoi.com/quick-reference/joint-calibration#prepare-to-enter-the-calibration-state) in the Joint Calibration.

## The rationale for calibration

### Understand the zero state and the coordinate system

After sending the serial command ‘**c**’ in the serial monitor,  the robot will [enter the calibration state](#enter-the-calibration-state), with all servos rotated to their zero angles, attach the head, tail, and legs prepared in the previous section to the body. They are generally perpendicular to their linked body frames.

#### Bittle X+Arm's Calibration State

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FPawv4zrrUnu0MKkRMmDF%252FrotationDirections.jpeg%3Falt%3Dmedia%26token%3D909a19fe-2ab3-467a-86be-8fb76691731b&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=fd852987&#x26;sv=2" alt=""><figcaption><p>Bittle X+Arm's Calibration State</p></figcaption></figure>

Rotating the limbs counterclockwise from their zero states will be positive (the same as in polar coordinates). Viewed from the left side of the robot's body, the counter-clockwise rotation of the joint is defined as the positive direction.

{% hint style="info" %}
The only exception is the head tilt angle for Nybble. It’s more natural to say head up, while it’s the result of rotating clockwise.&#x20;
{% endhint %}

{% hint style="info" %}
However, from the right side of the robot's body, the rotation directions' positive and negative are just opposite.
{% endhint %}

### Discrete angular intervals

If we look closer at the servo shaft, we can see it has a certain number of teeth. That’s for attaching the servo arms and avoiding sliding in the rotational direction. In our servo sample, the gears divide 360 degrees into 25 sectors, each taking **14.4** degrees(offset of -7.2\~7.2 degrees). That means we cannot always get a perfect perpendicular installation.&#x20;

![](/files/v400iIvlmpXjiobnloRS)

## Calibration process

### Enter the calibration state

You must double-check the position and direction of all servos.&#x20;

&#x20;Send the serial command ‘**c**’ in the serial monitor to enter the calibration mode.  Depending on their initial shaft direction, some may travel larger angles until stopping at the middle point.  There will be noise coming from the gear system of the servos. You will see a calibration table like the following:

![](/files/hd4pjWyGSWw4VOVwbSh1)

The first row is the joint indexes; the second row is their calibration offsets:&#x20;

| **Index**  | 0  | 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8  | 9  | 10 | 11 | 12 | 13 | 14 | 15 |
| ---------- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
| **Offset** | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 |

Initial values are “-1” or “0” and should be changed by later calibration.&#x20;

{% hint style="info" %}
The servos use a potentiometer in the feedback loop for position control. When held at a static position, they tend to vibrate around the target angle. A Parkinson 's-like vibration will develop after a short period of use. It won’t affect much during continuous motion. Better servos without these troubles could cost 10 times more, so replacing a failed unit is a more cost-effective solution. &#x20;
{% endhint %}

### Attach body parts to the servos

For the installation for different product, please refer to the subpage of [**Joint Calibrator**](https://docs.petoi.com/desktop-app/joint-calibrator) as abov&#x65;**.**

### Fine-tune the calibration using the serial monitor

#### 1. Joint Control Commands

The command for fine-tuning calibration (refer to the [serial protocol](https://guide.petoi.com/apis/serial-protocol)) is formatted as `cIndex Offset`. Notice that there’s a space between cIndex and Offset.&#x20;

<figure><img src="/files/TiWGIxbc5wk9DdSYQdYx" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
A servo plug has three wires. Plug it in the right direction, or you may burn the chip. The color of the wires may vary across models. However, the darkest-colored wire (Black or Brown) is always the GND (ground) wire by convention. The GND wire should be plugged closest to the board.&#x20;
{% endhint %}

{% hint style="danger" %}
The index number of the joint servo has **no corresponding relationship** with the PWM pin number on the main board. **You don't even need to read the pin numbers on the PCB board.**&#x20;
{% endhint %}

Some customers already have Bittle X (**BiBoard V0**), which can also be equipped with a robotic arm. The joint index is as follows.&#x20;

<figure><img src="/files/6be3SYhSOI5Zk8YgseyF" alt=""><figcaption></figcaption></figure>

For example :

* `c8 6` This means giving the 8th servo an offset of 6 degrees.&#x20;
* `c0 -4` This means giving the 0th servo(the head) an offset of -4 degrees.&#x20;

{% hint style="warning" %}
The resolution of the correction amount is 1 degree; do not use decimals.
{% endhint %}

{% hint style="info" %}
If you find the absolute value of offset is more significant than 9, you are not attaching the limb closest to its zero states. That will decrease the servo's reachable range on either side. Please take off the limb and rotate it by one tooth. It will result in an opposite but smaller offset.&#x20;
{% endhint %}

{% hint style="info" %}
For example, if you have to use -9 as the calibration value, remove the limb, rotate it by one tooth, and then attach it back. The new calibration value should be around 5, i.e., the sum of their absolute values is 14. Avoid rotating the servo shaft during this adjustment.&#x20;
{% endhint %}

Find the best offset that can bring the limb to the zero states.  It's a process of trial and error.

{% hint style="info" %}
For the robotic arm, you can use the serial command "**c-2**" to [auto-calibrate](https://docs.petoi.com/extensible-modules/robot-arm#fine-calibration) the robotic claw joint.
{% endhint %}

After calibration, **remember to type ‘s’ to save the offsets**. Otherwise, they will be forgotten when exiting the calibration state. You can even save every time after you’re done with one servo.&#x20;

#### 2. Use ‘L’ shaped joint tuner

When watching something, one's observations will change from different perspectives. When measuring length, one always wants to read directly above a referencing ruler.&#x20;

You must keep a parallel perspective when calibrating the robot. Use the 'L'-shaped joint tuner as a parallel reference to avoid reading errors. Align the tips on the tuner with the center of the screws in the shoulder and knee joints and the little hole on the tip of the foot. Look along the co-axis of the centers. For each leg, calibrate the shoulder servos (index 8\~11) first, then the knee servos(index 12\~15). When calibrating the knee, use the matching triangle windows on both the tuner and shank to ensure parallel alignment.&#x20;

{% hint style="info" %}
The **pre-assembled** robot should already have the components adequately installed. You can do the joint calibration for fine-tuning directly, without needing to uninstall the head and legs.&#x20;
{% endhint %}

Please use the L-shaped calibration tool included in the package as a calibration reference. According to the joint numbers shown in the calibration interface picture, click and drag the corresponding joint sliders or click the blank areas of the slider tracks to fine-tune the joints to a right angle.

Please note that when calibrating the servos, adjust the upper leg first, then change the lower leg.

![](/files/0HXBQK8Fem9hj1AmppKy)

![Align the upper leg first](/files/QpS91FEEbFx1kWR8Yofo)

![Pay attention to the reference edges for the lower leg](/files/kuwZZVGFrrkgDo4rhGiH)

{% hint style="info" %}
If the offset is more than +/-9 degrees, you need to remove the corresponding leg and reinstall it by rotating one tooth and then dragging the corresponding slider. For example, when it is adjusted to +9 and still not right, remove the corresponding leg and shift one tooth when attaching it. Then, you should get a smaller offset in the opposite direction.&#x20;
{% endhint %}

#### 3. Testing and validation

After calibration, send the serial commands: ‘**d**’, ‘**kup**’,  and '**kwkF**' to validate the calibration. This will result in the robot symmetrically moving its limbs between the rest, stand states, and walk gait. &#x20;

{% hint style="warning" %}
You may need to do a few rounds of calibrations to achieve optimal states.
{% endhint %}

#### 4. Install the screws for the construction kit

After completing the joint calibration, install the center screws to fix the components and servo gears.

#### 5. Center of mass

Try to understand how the robot keeps its balance even during walking. If you add new components to the robot, distribute its weight symmetrically about the spine. You may also need to slide the battery holder back and forth to find the best balance spot. Because the battery is heavier at the front, you can insert it in the opposite direction to shift the center of mass farther back.&#x20;

{% hint style="info" %}
You may need to recalibrate if the center of mass changes.&#x20;
{% endhint %}

Please do not force the robot to lift heavy objects, as this may cause the servos to sweep or get stuck.


# Install Arduino IDE on Chromebook

After [**turning on Linux**](/technical-support/set-up-development-environment-on-chromebook) on the Chromebook, you can access the Linux environment via the terminal app.

Please follow the following steps to install the Arduino IDE:

## Check the type of your OS version

<figure><img src="/files/Fy6jFs5A2deqjAWB6ec3" alt=""><figcaption></figcaption></figure>

## Download package

Open the website ([www.arduino.cc/en/software](https://www.arduino.cc/en/software)) and download the corresponding type of Legacy Arduino IDE:

<figure><img src="/files/qZTrJYJpye9JkGlmAy6q" alt=""><figcaption></figcaption></figure>

## Installation

After downloading complete, set the folder ***Downloads*** in the file browser to share with Linux, as mentioned above. Use the following commands to install the **Arduino IDE,** e.g., ***arduino-1.8.19-linux64.tar.xz*** is the downloading file.

```
cd /mnt/chromeos/MyFiles/Downloads/
sudo apt-get install xz-utils
sudo tar -C /opt -xf arduino-1.8.19-linux64.tar.xz
cd /opt
ls
cd arduino-1.8.19/
ls
sudo ./install.sh
```

## Set up the Arduino IDE development environment for the mainboard

You can open the **Arduino IDE** as follows:

<figure><img src="/files/Ek7txzYIkbwUxU8CPp47" alt=""><figcaption></figcaption></figure>

After using the USB data cable to connect the BiBoard and Chromebook, you will see a prompt: Please click ***Connect to Linux*****.**

<figure><img src="/files/Nt2E99Bos1ByKfFL8C23" alt=""><figcaption></figcaption></figure>

and check in the **Settings** interface, and it should be enabled as follows:

<figure><img src="/files/0JzLQ0XvA2qDbjdWiG3M" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/CpjbjAH0VsYoCQZdZkeH" alt=""><figcaption></figcaption></figure>

Use the following commands to install the library pyserial for uploading the sketch for BiBoard

```
sudo apt install python3 pip
python3 -V
pip -V
cd /usr/lib/python3.11/
sudo rm EXTERNALLY-MANAGED
sudo pip3 install pyserial
pip list
```

{% hint style="info" %}
After downloading the project file **OpenCatEsp32-main.zip** from GitHub: <https://github.com/PetoiCamp/OpenCatEsp32>, use the following commands to unzip it to the ***Downloads*** folder.

<pre><code><strong>cd /mnt/chromeos/MyFiles/Downloads/
</strong>sudo apt-get install unzip
unzip OpenCatEsp32-main.zip
</code></pre>

{% endhint %}

For how to upload the sketch, please refer to [Upload Sketch for BiBoard](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard).


# Nybble Q

## Getting Started

Nybble Q is an open-source, voice-controlled robotic cat. It's a new breed of robotic cat that everyone can learn and play with.

<figure><img src="/files/xkn26rVF3VkUkqTqUU8u" alt=""><figcaption></figcaption></figure>

The small but mighty Nybble Q has these fantastic features:

* Respond to voice commands, performing over **35 predefined actions** such as sit, push-up, and wash-face with high-performance, lifelike movements. You can switch between English and Chinese using simple voice commands.
* Can be programmed with 10 more customized voice commands to perform skills you create. The voice command can be any sound, so it is not necessary to be mapped to any spoken language.
* Support **Petoi** **Coding Blocks(block-based Scratch-like), C++, and Python**.
* **Free** [C++](https://www.petoi.com/pages/free-cplusplus-quadruped-robotics-curriculum) and [Petoi Coding Blocks](https://www.petoi.com/pages/free-quadruped-robotics-curriculum-scratch-coding)(block-based Scratch-like) **curricula**.
* Equipped with BiBoard V1, a high-performance **ESP32** development board supporting additional modules for robotics/AI/IoT applications.

If you have questions about ***why*** or ***how***, please post on [our forum](https://www.petoi.camp/) or [contact us](https://www.petoi.com/pages/contact-us).

There are some [supporting applications, software](https://docs.petoi.com/technical-support/supporting-application-and-software), and [FAQs](https://docs.petoi.com/technical-support/faq-frequently-asked-questions) for your reference.

You can support us by shopping at [Petoi Coding Robot Shop](https://www.petoi.com/store). Our social media (Instagram/Twitter/Facebook/GitHub) account is **@PetoiCamp**. Share your build by tagging **#nybbleQ #petoi #opencat** so we can repost it for you!

{% hint style="info" %}
Last Updated: 11/12/2024
{% endhint %}


# Quick Start Guide

The **Quick Start Guide** section is primarily designed to help you verify that the product is complete after receiving it and to enable you to quickly boot up and use the robot. It includes two parts:&#x20;

1. [**Unboxing**](/product/bittle-x-v2+arm/quick-start-guide/unboxing)&#x20;
2. [**Boot up**](/product/bittle-x-v2+arm/quick-start-guide/boot-up)

**Need help?** Check out our [**FAQ**](/faq-frequently-asked-questions).


# Unboxing

## **Check the Package**

Thank you very much for purchasing our product! We highly value your user experience and hope you will enjoy this delightful journey. To ensure the device was not damaged during transportation and verify all accessories are complete, we recommend following these steps after receiving the package:

1. Verify the recipient's name, address, order number, and other details on the product packaging to confirm they match your order. If any information is incorrect, please do not open the box and contact us or the logistics provider immediately.
2. Inspect the shipping box for integrity. Check for apparent damage, moisture, deformation, or signs of tampering. If packaging damage is found, please photograph it for documentation purposes and avoid accepting, signing for, or opening the package before confirming the device's condition. As shown in the example below, your Nybble Q should arrive fully intact, without any damage, clean and well-presented.

<figure><img src="/files/6Jsi3bKPviz931ynjOVe" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/43xcuaxiEdWr5QdTL6YA" alt=""><figcaption></figcaption></figure>

## Unboxing

### Product List

<figure><img src="/files/yJsvbMVrLDA8kuSv8yCE" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Note: Nybble Q is FDM 3D-printed, and its Z-axis strength is limited. Please do not apply excessive force during use. Avoid placing it near the edge of a table to prevent accidental falls, which may cause component breakage.
{% endhint %}

<table><thead><tr><th width="487.390625">Name</th><th>Quantity</th></tr></thead><tbody><tr><td>Main Unit: Nybble Q robotic cat</td><td>1</td></tr><tr><td>Assembly Components: Tail/Calibrator parts</td><td>1</td></tr><tr><td>Manual: Stickers/Postcard (with voice commands on the back)/Calibrator manual</td><td>1</td></tr><tr><td>Tools: Self-tapping screwdriver/USB cable</td><td>1</td></tr><tr><td>Spare Parts: Spare tail servo horn/Spare servo/Raspberry Pi mount/Springs &#x26; screws</td><td>1</td></tr></tbody></table>

### Assembly

Upon initial unboxing, you only need to assemble the tail and calibrator yourself before interacting with the robot.

If you need to perform operations such as battery removal or replacement, or opening the back cover during use, please refer to the "**Commonly Used Removable Parts**" section below.

#### Assembling the Tail

The tail rotates around a metal shaft and automatically adjusts its vertical range in response to gravity.

It enables Nybble Q to perform advanced movements, such as rolling over, standing upright during boxing actions, and more.

For shipping safety, the body and tail are packed separately. Please assemble them according to the instructions.

<figure><img src="/files/ffE7G0iEgVIkiJYLNfFa" alt=""><figcaption><p>Installing the Tail</p></figcaption></figure>

Steps:

1. Check if the contour surface of the tail servo arm has a smooth transition, avoiding any right-angle bends.
2. Locate the notch on the tail servo arm, then place the metal shaft of the tail onto the notch of the servo arm.
3. Keep the tail body flush against the metal shaft and rotate it downward around the shaft. During this process, the tail body may come into contact with the servo arm. Continue applying downward force until you hear a click, indicating that the metal shaft of the tail has snapped into the notch of the servo arm.
4. To disassemble the tail, follow the reverse of the installation steps.

<figure><img src="/files/QAkUl2GaGj7iuxt63wjy" alt=""><figcaption><p>The red circled area is the surface after the 3D printed supports are removed. It may sometimes be uneven and could affect the installation of the tail. You can use nippers/side cutters to trim it.</p></figcaption></figure>

{% hint style="info" %}
If the wheel on the tail is not rotating smoothly, possible causes could be:

1. Small burrs remaining on the wheel or tail - Trim them with a sprue cutter.
2. The wheel and tail are positioned too closely. Pinch the tail to hold it in place, then grip the wheel and pull it along the axial direction to adjust the spacing.
   {% endhint %}

<figure><img src="/files/ZoBzbSxeG3ARrk0rnfZt" alt=""><figcaption></figcaption></figure>

#### Assemble the Optional Nybble Q Stand

To facilitate debugging the robot and prevent falls, we have designed a specialized bracket. Please assemble the bracket according to the images below, and then gently place the robot onto it. Small snap fasteners between the robot and the bracket will ensure a secure and stable connection.

<figure><img src="/files/PwsmkdhDfu4mJjrGq7f1" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/vJ1idJqnrA2LEqWzGqfz" alt=""><figcaption></figcaption></figure>

{% hint style="info" %} <img src="/files/kcgpBzRLYNvaJvZkChqv" alt="" data-size="original">

We have also published the 3D structure and instructions of the bracket online. If you have a 3D printer, you can print it by yourself. Please check this page for the Nybble Q calibration stand: <https://makerworld.com/en/models/1504533-calibration-and-test-stand-for-nybble-q-robot#profileId-1574352>
{% endhint %}

### Commonly Used Removable Parts

#### **Battery**

When the battery is dead (the indicator light is red) or needs replacement, the battery must be removed from the body.

The battery and the body are connected via a sliding groove with a snap latch. To detach the battery, slide it horizontally in the direction of the cat's head.

<figure><img src="/files/LnoKsJfYmnINqF5BMitY" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To prevent the battery from accidentally detaching during vigorous robot movements, we have designed the buckle mechanism to be secure, which means you will feel some resistance when pushing the battery into place.

Installing and removing the battery are reverse processes.

Please ensure the charging port of the battery aligns with the direction of the robot's head.

<img src="/files/87zUXNzqO7aJx0IQlyoH" alt="" data-size="original">
{% endhint %}

#### **Back Cover**

{% hint style="warning" %}
Please do not forcibly separate the back cover from the body, as a flex cable connects the touch circuit board between them. Excessive force may cause the flex cable to come off or even break.
{% endhint %}

<figure><img src="/files/hypJH0Q1XIEq2EdEQyfK" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/rbQZ0gXqoh4ez8O4KPXt" alt=""><figcaption></figcaption></figure>

The back cover and the body are interlocked with each other via small protrusions. To remove the back cover, locate the indicated points shown in the image and gently squeeze both sides toward the center axis to release the snap-fit connectors.

For proper orientation during reinstallation, align the back cover by referencing its logo—the cat ears should face forward, indicating the correct front orientation.

<figure><img src="/files/ni4EcOjfF01uwFEZxeCA" alt=""><figcaption></figcaption></figure>

#### **Back Cover Touch Circuit Board**

Under normal circumstances, there is no need to remove the flexible printed circuit (FPC) for touch functionality from the back cover. If you wish to detach the back cover FPC completely, please follow these steps:

After removing the back cover, note the relative orientation between the circuit board and the back cover. There is a flip tab on the connector - lift this tab upward. Once the tab is flipped open, the cable beneath it can be fully detached along with the back cover and circuit board.

Reconnecting the cable to the circuit board is the reverse process: align the cable, ensuring proper orientation, and press it firmly into place.

<figure><img src="/files/Al1u8kT9KLZtAp02gnnP" alt=""><figcaption><p>Operation to Remove the Touch FPC</p></figcaption></figure>

#### **Side Panel**

The side panels are decorative components that conceal the servo wires inside the robot. They connect to the main body via snap-fit connectors.

During subsequent use, when components such as servos or batteries need replacement, the abdominal side panels of the Nybble Q must be removed. The process is simple: locate the notches on both sides of the panel, grip them with your fingernail, and pry outward to detach the side panel.

<figure><img src="/files/tEaXkDFl5tox7Nix5UdN" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/VkWUnayWkIyPyJ7DNyLJ" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/DVIkhw4MmQP9osUv8A7c" alt=""><figcaption></figcaption></figure>

#### Ultrasonic Sensor

The sensor should connect to the first Grove socket.

<figure><img src="/files/nSVU6rZp2NAyQUbN51OD" alt=""><figcaption></figcaption></figure>

## Tools and Accessories

| Tools                        | Notes                                                                                                                                                                                                                                                                                                                                                |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A Windows/Mac/Linux Computer | <p>Download the <a href="https://guide.petoi.com/product/nybble-q/control-and-program/petoi-desktop-app">Petoi Desktop APP</a> <br>Download <a href="https://guide.petoi.com/product/nybble-q/control-and-program/petoi-coding-blocks">Mind+</a> (Optional)<br>Download <a href="https://www.arduino.cc/en/software">Arduino IDE</a> (Optional) </p> |
| USB charging port            | 5V 1A output                                                                                                                                                                                                                                                                                                                                         |
| A smartphone(Android/iOS)    | Download [mobile app](https://guide.petoi.com/product/nybble-q/control-and-program/mobile-app) (Optional)                                                                                                                                                                                                                                            |


# Boot up

## Pre-Startup Posture

To prevent the servos from getting stuck, please adjust the robot's legs to the correct position before powering it on.

<figure><img src="/files/NvASPY7Jek4jpwY1ZtMq" alt=""><figcaption></figcaption></figure>

## Usage Scenario

First, test it on the calibrator and use it on a stable table or floor only after you have familiarized yourself with its operation.

<figure><img src="/files/gy4dsxh5GhsdhJiPKz6x" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
When using it on a table, keep it within your arm's reach to prevent it from falling and avoid damage.
{% endhint %}

## Power On

Turn on the robot's battery to start using it. If you encounter any issues during operation, please refer to the "Other Situations" below.

### Battery Switch

Press and hold the battery button for 2 to 3 seconds to turn the power on or off. You will hear a short melody, and the battery indicator will light up blue. If the indicator is red, refer to the charging method below.

<figure><img src="/files/5U6eIKNYzSKjEWplICva" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
After turning on the battery, the robot requires approximately 5 seconds for initialization, and a melody will play upon completion.

During storage and transportation, the robot's battery charge may decrease. When using it for the first time, please ensure the battery is sufficiently charged.

It is recommended to place the robot on the calibration stand before pressing the button to activate the battery.

If you use the robot on the floor, please ensure the robot is positioned upright after activating the battery. Otherwise, it will continuously attempt to flip itself over or perform other corrective motions upon startup;

If the robot is placed on its side when powered on, it will automatically initiate the calibration posture.
{% endhint %}

### Battery Indicator

Before use, please read the instructions on the bottom of the packaging box carefully to ensure correct operation of the battery.

<figure><img src="/files/zPzOyYdwoAhbelbe2WtE" alt=""><figcaption><p>        Low Power                                  Full Power                               Intermediate Power</p></figcaption></figure>

Press and hold the blue button on the battery for 2–3 seconds to turn the power on or off.\
During charging, the indicator light turns red; after charging is complete, it turns green.\
Press the blue button briefly to check the battery status:

· When fully charged, the indicator light is blue.

· When the voltage is low, the indicator light is red.

· During battery depletion, the indicator color gradually changes from blue to red.

Note the correct use of battery interfaces: Use the Type-C interface for charging, and the 2P 2.54MM red-black wire terminal interface to power Nybble Q. Please don't mix them up:

If the robot detects a low battery, it will pause its movements and beep. In this case, you need to remove the battery and charge it using a standard 5V USB Type-C interface data cable. For safety reasons, the battery will automatically stop supplying power to the robot during charging.

### Buzzer Sound Types

| **Sound**                  | **Trigger Timing**             | **Indication**                       |
| -------------------------- | ------------------------------ | ------------------------------------ |
| Short melody               | Power on or restart            | Program startup successful           |
| Program startup successful | During use                     | Program received command             |
| Repeating melody           | During pauses in use or action | Low battery or battery not connected |

## Other Situations

### Charging

The robot's battery socket has limited dimensions, so when the battery is installed on the battery seat, it cannot be directly charged via USB. The battery needs to be removed from the battery socket before charging.

{% hint style="info" %}
Before charging, turn off the battery (press and hold for 3 seconds). After connecting the charging cable, the battery will automatically shut down (cease external power supply).
{% endhint %}

{% hint style="warning" %}
Please do not confuse the circuit board’s download port with the battery charging port.
{% endhint %}

There are two charging methods:

1. Remove only the battery from the main body, which is a quick and simple process.

<figure><img src="/files/fd8SB612DUx1cpunt2Yo" alt=""><figcaption></figcaption></figure>

2. Remove the side panel first, then detach the battery from the circuit board to fully separate the battery from the main body. This method is suitable for users with spare batteries.

<figure><img src="/files/pIzKZx4zS9pDiGJFslub" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/NXhQz6ZHPiHmBGboPPwQ" alt=""><figcaption><p>When reinstalling the battery, please ensure the battery connector passes through the small hole shown in the image before connecting it to the circuit board on the main body.</p></figcaption></figure>

<figure><img src="/files/vZ9V0959FyhlKVd7cdHQ" alt=""><figcaption></figcaption></figure>

### Replacing the Battery

The operation is the same as the charging method two mentioned above.

### Device Freezing or Unresponsive

There are two solutions：

1\. Check the battery indicator light. If the battery level is too low, please charge it promptly.

2\. If the battery level is normal, remove the back cover and press the reset button on the motherboard, located next to the LED logo, to reboot the robot.

<figure><img src="/files/OC0pJ5dsOUgewiFTtptC" alt=""><figcaption></figcaption></figure>

### Servo

For plastic servos, we have added two protection mechanisms to extend their service life:

1. When subjected to short-term external force impacts, the protection mechanism activates, causing the servo to produce a clicking sound.
2. When the servo is under prolonged force, the protection mechanism activates, causing the servo to release force.

### Clicking Sound

The plastic servo contains a clutch gear for protection.

When powered on, if external obstacles block the servo's rotation, the clicking clutch sound will occur. Examples include:

Manually rotating the servo away from its target angle;

The servo is being physically jammed;

The servo is being obstructed by other objects.

<figure><img src="/files/6IYft7arWTUggbBIVs0X" alt=""><figcaption></figcaption></figure>

### Sudden Servo Stoppage or Force Release

To enhance servo durability, we added stall current detection. If the servo is under prolonged force without triggering the clutch gear, it will automatically enter force-release mode.

The servo returns to normal mode when it receives a new angle command.

<figure><img src="/files/EvlZ5voo6hEOiwciMnpf" alt=""><figcaption></figcaption></figure>


# Control & Program

### Control

* [Voice Command](/product/nybble-q/control-and-program/voice-command)
* [Mobile App](/product/nybble-q/control-and-program/mobile-app)
* [Optional Joystick Controller with Micro:Bit](/product/nybble-q/control-and-program/joystick-with-micro-bit)

### Set up & Build Robotics Skill Visually

* [Petoi Desktop App](/product/nybble-q/control-and-program/petoi-desktop-app)

### Programming

* [Petoi Web Coding Blocks](/petoi-web-coding-blocks/get-started-create-your-first-block-program)
* [Petoi Coding Blocks](/product/nybble-q/control-and-program/petoi-coding-blocks)
* [Python](/apis/python-api)
* [C++](/apis/c++-api) on [Arduino IDE](/product/nybble-q/control-and-program/arduino-ide)
* [Play with feedback servos](/apis/serial-protocol/feedback-servos)
* [Sensor & module programming](/extensible-modules/introduction)
  * [Nybble Q's ultrasonic sensor programming](/extensible-modules/ultrasonic-sensor)
* Various application project demos(see the Applications section on the sidebar)
* Various APIs for advanced users(see the APIs section on the sidebar)

### Curricula

Here are [all the free Petoi curricula](https://bit.ly/petoicur) and [some curricula developed by our community](https://www.petoi.com/blogs/blog/tagged/showcase+curriculum).

Note that these curricula are developed for Bittle robot family.  But most of the programming concepts are applicable to Nybble Q.

### Video tutorials

* [Petoi Skill Composer](https://www.youtube.com/playlist?list=PLHMFXft_rV6MTs8HMxSOvRAQektoXtaMG)
* [Desktop block-based coding tutorial](https://www.youtube.com/playlist?list=PLHMFXft_rV6POrzm8O12Nybdy1-FS1ymg)
  * Note that some of the videos may have been developed by older Petoi robots.  So the setup may be different.  But the programming concept can still apply.&#x20;
* [Advanced tutorials](https://www.youtube.com/playlist?list=PLHMFXft_rV6MWNGyofDzRhpatxZuUZMdg)

### Project ideas

* Get inspired by [Petoi user projects](https://www.petoi.com/blogs/blog/tagged/showcase)
* Work on some [quadruped robotics competition projects and ideas](https://www.petoi.com/blogs/blog/robot-competitions-with-petoi)
  * Every fall, we host [Petoi robotics contests](https://www.petoi.com/blogs/blog/tagged/contest-winners). We'd love to see you!


# Mobile App

📱🤖

Thanks for choosing Petoi's robot. This guide will help you set up your robot buddy and provide a simpler UI to calibrate the joints, control the robot, and program it. For advanced users, we recommend you keep the robot updated with the [OpenCat(for NyBoard)](https://github.com/PetoiCamp/OpenCat) / [OpenCatEsp32(for BiBoard)](https://github.com/PetoiCamp/OpenCatEsp32) firmware on GitHub for the best compatibility and the newest features.&#x20;

## Download and installation

The app works on both Android and iOS devices.

* [iOS 11+](https://apps.apple.com/us/app/petoi/id1581548095)
* [Android 4.4+](https://play.google.com/store/apps/details?id=com.petoi.petoiapp)

#### APK

For Android, you can also download the APK and install it on your phone.&#x20;

* The universal version(try this one first)\
  [v1.4.1-40-2-20251022-app-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-release.apk)
* The **v8a** version of the app mainly supports most of the current new mobile phone models\
  [v1.4.1-40-2-20251022-app-arm64-v8a-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-arm64-v8a-release.apk)
* The **v7a** version of the app is compatible with older mobile phone models\
  [v1.4.1-40-2-20251022-app-armeabi-v7a-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-armeabi-v7a-release.apk)
* The **x86\_64** version of the app indicates that the APK is designed for Android devices using Intel or AMD 64-bit processors. This means the APK contains native code libraries optimized for the x86\_64 architecture, designed to improve performance and compatibility.\
  [v1.4.1-40-2-20251022-app-x86\_64-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-x86_64-release.apk)

{% hint style="info" %}
If the connection panel in the App shows a blank Bluetooth connection list, first check whether you have granted the App Bluetooth and location permissions. If it still shows a blank list, try to install the previous stable version. \
[v1.4.0-37-1-app-release-20251006.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.0/v1.4.0-37-1-app-release-20251006.apk)
{% endhint %}

![](/files/G1cSapHMlJK9sDQ53TMN)

## Connect to the robot

For the mainboard BiBoard, the Bluetooth module is already built into the ESP32 module; you just need to power on the robot by long-pressing the button on the battery.

{% hint style="warning" %}
The app will send a greeting to the Bluetooth device and expect a response from the robot. You must upload the OpenCat (for NyBoard) / OpenCatEsp32 (for BiBoard) firmware to your robot before connecting to the app. Otherwise, the app will consider it "not a Petoi device". A pre-assembled robot should already have the firmware installed. Otherwise, you'll need to upload firmware using the [Petoi Desktop app](https://guide.petoi.com/desktop-app/firmware-uploader).&#x20;
{% endhint %}

{% hint style="warning" %}
For BiBoard, please ensure the program enters the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization)**.**
{% endhint %}

Open the app and scan available Bluetooth devices. **Don't connect the robot with the phone's system-wide Bluetooth settings!** Connect the device with the name Bittle, Petoi, or OpenCat.&#x20;

Please remember to enable Bluetooth and give the app access to it. On some devices, you may also need to allow the app's location service, though we are not using any of that information.

{% hint style="info" %}
On some Android OS, you need to activate the location service as follows:![](/files/tu2Vwheh7gELyuRGt2ZJ)
{% endhint %}

![](/files/-MjZWU2EpJOmFcBOEKGH)

The app will open the Control Panel interface when Bluetooth is connected. If the robot doesn't respond or malfunctions later, press the reset button on the mainboard to restart the robot.

The app should automatically detect the supported robot type based on the latest firmware. Otherwise, it will show the selections for the robot type. The above interface can also be revisited by selecting the option "Select a robot" in the control panel.

![](/files/FG3i4k9cmd0KgFjfCaYH)


# Calibrator

## Prepare for calibration

Please take a look at the section [Connect to the robot](/product/nybble-q/control-and-program/mobile-app#connect-to-the-robot).

## The rationale for calibration

### Understand the zero state and the coordinate system

After the robot [enters the calibration state](#enter-the-calibration-state), with all servos rotated to their zero angles, attach the head, tail, and legs prepared in the previous section to the body. They are generally perpendicular to their linked body frames.&#x20;

![Nybble's Calibration State](/files/AiBp5uskBjNIOASP0BI3)

Install the servo-related components according to the picture above and try to ensure that they are perpendicular to each other (the upper leg is perpendicular to the torso, and the lower leg is perpendicular to the upper leg).&#x20;

{% hint style="warning" %}
Note: Insert the servo-related components directly into the servo output shaft; do not turn the output shaft during this process.
{% endhint %}

Rotating the limbs counterclockwise from their zero states will be positive (the same as in polar coordinates). Viewed from the left side of the robot's body, the counter-clockwise rotation of the joint is defined as the positive direction.

{% hint style="info" %}
The only exception is the head tilt angle for Nybble. It’s more natural to say head up, while it’s the result of rotating clockwise.&#x20;
{% endhint %}

{% hint style="info" %}
However, from the right side of the robot's body, the rotation directions' positive and negative are just opposite.
{% endhint %}

### Discrete angular intervals

If we look closer at the servo shaft, we can see it has a certain number of teeth. That’s for attaching the servo arms and avoiding sliding in the rotational direction. In our servo sample, the gears divide 360 degrees into 25 sectors, each taking **14.4** degrees(offset of -7.2\~7.2 degrees). That means we cannot always get a perfect perpendicular installation.&#x20;

![](/files/v400iIvlmpXjiobnloRS)

## Calibration Interfaces

The calibrator interface for Nybble is as following, this interfaces will be displayed when you calibrate for the first time:

![Calibration Interface](/files/0GXfFnXvrwhFPB6Utc4d)

{% hint style="info" %}
You can also click to open the upper-right menu in the control panel and select **Calibrate** to re-access.

![](/files/JK6QL4MkFti57WTk401r)
{% endhint %}

## Enter the calibration state

After the battery powers on the robot, there are two methods to enter the calibration state.&#x20;

* Click the **Start Calibration** button.<br>

  <figure><img src="/files/LN2I8HPg1QrIwpqb5vyY" alt=""><figcaption></figcaption></figure>
* Click the **Calibration** button in the calibration interface.\ <br>

  <figure><img src="/files/3wfB9NHdDoafWE0m4gNl" alt=""><figcaption></figcaption></figure>

### **Use the included L-shaped tool as a reference**

![](/files/HXHygTlSauC6GsdgjoHb)

<figure><img src="/files/n8IZloi5WmIoBCdtYvOz" alt=""><figcaption></figcaption></figure>

First, select the index number of the joint servo from the diagram(when adjusting the leg servo, adjust the thigh first, and then adjust the calf).&#x20;

Then, click the "+" or "-" button to fine-tune the joint to the desired angle.&#x20;

{% hint style="info" %}
If the offset is more than ±9 degrees, you need to remove the corresponding part of the servo, reinstall it by rotating one tooth, and then press the "+" or "-" button.

For example, if you need to use -10 as the calibration value, remove the limb, rotate it by one tooth, and then reattach it. The new calibration value should be around 4, i.e.,  they sum up to 14. Avoid rotating the servo shaft during this adjustment.&#x20;
{% endhint %}

## Test the calibration effect

<figure><img src="/files/bO4A4lw1w3nU5DipkcNG" alt=""><figcaption><p>Nybble</p></figcaption></figure>

You can click the skill buttons to switch between **Rest**, **Stand**, and **Walk** to test the calibration effect.&#x20;

If you want to continue calibrating, please click the **Calibration** button, and the robot will return to the calibration mode, with all servos immediately moving to their calibration positions.&#x20;

{% hint style="info" %}
Note:&#x20;

You may need a second round of calibrations to achieve optimal results.
{% endhint %}

After calibration, remember to click the **Save** button to save the calibration offset. Otherwise, click "**<**" in the upper left corner to abandon the calibration.

## Install the screws for construction kit

For the construction kit, after completing the joint calibration, install the center screws to fix the leg parts and neck servo gears.


# Controller

In the control panel, you can control the robot to perform various postures, behaviors, and gaits.

<figure><img src="/files/DPKqxK3KRMxeLrYG3iPl" alt=""><figcaption></figcaption></figure>

## Gaits

The left panel sets both the robot's gaits and directions and send combined command, such as "walk left" and "trot forward". The robot will only move if an initial gait and direction are selected. The "step" has no direction, and "backward" has left and right directions. The pause button "||" will pause the robot's motion and turn off the servos, so that you can rotate the joints to any angle. The "Turbo" button ( <img src="/files/YQwDEPEj4FqBZvskEzGI" alt="" data-size="line"> ) turns on/off the gyro, a sensor to detect the robot's body orientation. Turning it on will make the robot keep adjusting to body angles, and will know when it's upside down. Turning it off will reduce calculation and make it walk faster and more stable. &#x20;

## Postures and behaviors

The built-in postures and behaviors can be triggered by pressing the buttons. Don't press the button too frequently and repeatedly. Allow some time for the robot to finish its current tasks.&#x20;

## Customized commands

* **Press and hold** the button and drag to change the button position.&#x20;
* **Double-tap** the command button to edit it.&#x20;
* You can also create a customized single command/group command by pressing the "+" button.

<figure><img src="/files/fe7I74M8yoav8RPAbA4q" alt=""><figcaption></figcaption></figure>

### Create a single command

After pressing the **Create Command** button, you can see the following interface:

![](/files/GL2b8zzRrrpBPi28HZvC)

After entering the editing state, there's a serial console to test the command and configure the robot.&#x20;

The joint index of the robot:

<figure><img src="/files/S9oO78PDcrTkmXr1IDwW" alt=""><figcaption><p>Nybble joint index</p></figcaption></figure>

You can try the following useful serial commands in the **Code** text box:

#### \* move robot's head(robot arm)&#x20;

```
m0 45
```

#### \* move head left and right (move joint1 angle1 joint2 angle2 .... The angle is -127\~128)&#x20;

```
m0 -70 0 70
```

#### \* sit&#x20;

```
ksit
```

#### \* move joints one by one&#x20;

```
m 0 -70 0 70 8 -30
```

#### \* move joints simultaneously&#x20;

```
i 0 -45 8 -30 12 -60
```

#### \* show current joint angles&#x20;

```
j
```

#### \* long meow once (Nybble）

```
u0 1
```

#### \* short meow three times (Nybble）

```
u2 20
```

#### \* mute/unmute the buzzer beep

```
b
```

#### **\* adjust the buzzer volume (b\[0-10])**

```
b1
```

#### \* play a short tone (beep tone duration, duration is 0\~256)&#x20;

```
b12 20
```

#### \* play a melody (beep tone1 duration1, tone2 duration2, tone3 duration3, .... only 64 characters are allowed, the actual duration is calculated as 1/duration)&#x20;

```
b14 4 14 4 21 4 21 4
```

#### More common commands to be added

Please see [this list of common commands](https://docs.google.com/spreadsheets/d/1Lr6Cd1T-H9sSdUi_bI-OeMClkVOKjTQM/edit?usp=sharing\&ouid=106975882561093680387\&rtpof=true\&sd=true) that may be added as customized commands.  You can enter the "Voice command" column values as the "Name" values and the "Customized command code for Petoi mobile app" column values as the "Code" values.

A more detailed command table can be found in the [Serial Protocol](https://guide.petoi.com/apis/serial-protocol).&#x20;

### Import new skills as a customized button

#### Import your local customized skill (created by the [Skill Composer](https://docs.petoi.com/desktop-app/skill-composer))

You can send the skill file to your phone via the Messenger app or email, and open it on the phone using the Petoi App. A button for the new skill will be created; you can see it when you open the control panel.

<figure><img src="/files/LvJ0YdTUfEXeg3zLQzpe" alt=""><figcaption></figcaption></figure>

#### Import new skills from the skill library on GitHub

[The SkillLibrary folder](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary) in GitHub contains new skills for the OpenCat robot, which can be used for your reference. You can use your mobile browser to access the GitHub page of the OpenCat project, open the skill file (such as [Bittle\_Fold.md](https://github.com/PetoiCamp/OpenCat/blob/main/SkillLibrary/Bittle/Bittle_Fold.md)), select the "Code" tab, and share it with the [**Petoi Mobile App**](https://guide.petoi.com/mobile-app/introduction)(make sure the mobile app is connected to your Petoi robot first), as shown in the figures below.  Then you can execute this skill by pressing the newly created command button.

{% hint style="warning" %}
On iOS, you cannot share the .md skill file on GitHub in the Chrome browser. You can download the skill file and refer to the method - [Import your local customized skill](#import-your-local-customized-skill-created-by-the-skill-composer) to import it to this smartphone app.
{% endhint %}

<div><figure><img src="/files/HRcf2PQUkNsEsXHf4mTv" alt=""><figcaption></figcaption></figure> <figure><img src="/files/qRBFhbd4S8Dw5vdTCAE4" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="/files/JfZ7DaAzohvSOAZXpjDj" alt=""><figcaption></figcaption></figure> <figure><img src="/files/pVxNWxunKPStuSMfMRWV" alt=""><figcaption></figcaption></figure></div>

<figure><img src="/files/sl0xZZLUmo4SD3gykCmx" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
You are welcome to create your new skills(using the Skill Composer or [modifying the source code](https://guide.petoi.com/applications/skill-creation)) and share them by sending merge requests to [this folder](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary).
{% endhint %}

### Create a group command

The group command feature lets you chain multiple commands together and play them in sequence.

After pressing the **Create Group Command** button, you can see the following interface:

<figure><img src="/files/2a89mNbjVx27MTjDk8ym" alt=""><figcaption></figcaption></figure>

You can name the command group in the **Name** text box and add the command to the **Command Group** list by clicking the command button in the **Command Library** selection box. In the **Command Group** list, you can ***press and hold*** the command button and **drag** to change the command position.&#x20;

Click the **Test** or **Play (**![](/files/ays18QEsFK31wroXlnAC)**)** button to test the function of the command group. Click the **Pause (**![](/files/9ctc9bRh7LUiaV2Cs6qh)**)** button to interrupt the command list execution flow.

Click the **Delete** button to Delete the group command.

### Make your robot act randomly

{% embed url="<https://www.youtube.com/watch?v=nHLkE74Q3k8>" %}

If your robot doesn't have any random behavior, you may need to upgrade your robot to [the latest firmware](/desktop-app/firmware-uploader).&#x20;

## Updates and support

We keep improving the app and will inform you of the updates when available. Please write to  <support@petoi.com> if you have any questions about the app.&#x20;


# Voice Command

## Demo video

{% embed url="<https://youtu.be/aGW8F4mArAs>" %}

## Function introduction

Using this module, you can control the Petoi robot to perform various skills through voice without using wake words. Currently, the module supports 35 fixed voice commands in two languages (English and Chinese) and ten customized commands by recording any sound clips.&#x20;

## Hardware setup

It is built into the [**BiBoard V1**](https://guide.petoi.com/biboard/biboard-v1-guide) as follows:

<figure><img src="/files/BTXujMNDvdSxFeKDYue9" alt=""><figcaption></figcaption></figure>

## Software setup

### 1. Upload Firmware

There are two methods to upload the firmware for the robot.

* **use the Petoi Desktop App**
* **use the Arduino IDE**

#### **Petoi Desktop App**

You can use the [Firmware Uploader](https://guide.petoi.com/desktop-app/firmware-uploader#select-the-correct-options-to-upload-the-latest-firmware) within the Petoi Desktop App.

Please select the correct ***Product*** type, ***Board version***, and ***Serial port***. The mode should be **Standard**, so press the **Upgrade the Firmware** button.&#x20;

<figure><img src="/files/2ll75oCKWOIzlMsyDDDu" alt=""><figcaption></figcaption></figure>

#### **Arduino IDE**

You can use [Arduino IDE](https://www.arduino.cc/en/software) to [upload the sketch](https://docs.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.-set-up-biboard)(***OpenCatEsp32.ino***).&#x20;

For Bittle or Bittle X:

<pre class="language-cpp"><code class="lang-cpp">#define BITTLE    //Petoi 9 DOF robot dog, also for Bittle X
<strong>//#define NYBBLE  //Petoi 11 DOF robot cat, also for Nybble Q
</strong>//#define CUB
</code></pre>

For Nybble or Nybble Q:

<pre class="language-cpp"><code class="lang-cpp">//#define BITTLE    //Petoi 9 DOF robot dog, also for Bittle X
<strong>#define NYBBLE  //Petoi 11 DOF robot cat, also for Nybble Q
</strong>//#define CUB
</code></pre>

Modify the mainboard model macro definition in OpenCatEsp3&#x32;**.ino** according to the mainboard (BiBoard) version.

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

If the robot(**Bittle X+Arm**) has the robotic arm, you should also activate the macro definition as follows:

<pre class="language-cpp"><code class="lang-cpp"><strong>#define ROBOT_ARM                 // for attaching the head clip arm
</strong></code></pre>

Otherwise, please comment out this line of code.

After the modification is completed, you can click the **Upload** button (as below) to upload the sketch **OpenCatEsp32.ino**, and the changes in the code file will be automatically saved.

<figure><img src="/files/tdpRznaQQrpxXC9osxpY" alt=""><figcaption></figcaption></figure>

### 2. Switch mode

After uploading, the program defaults to Voice mode. If it is in another mode and you want to switch to Voice mode, please open the [Serial Monitor](https://guide.petoi.com/arduino-ide/serial-monitor) and send the **`XA`** command.

## Play with the voice commands

### Common use cases

#### Set the default language

{% hint style="info" %}
This feature is designed for robots using **BiBoard** as their mainboard.
{% endhint %}

When the robot is restarted, the voice module is automatically reset to its default language setting, which is English.

There are two ways to set the default language:

* Using the serial commands
  * Open the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor):
    * To set the default language to **English**, use the command: ***`XAa`***.&#x20;
    * To set it to **Chinese**, use the command: ***`XAb`***.
  * In the [mobile app](https://guide.petoi.com/mobile-app/controller#create-a-single-command):
    * To set the default language to **English**, create a command called **English** and use the code: ***`X65,97`**.*
    * To set it to **Chinese**, create a command called **Chinese** and use the code: ***`X65,98`**.*
* Using the voice commands
  * To set the default language to **English**, you need to say the voice command "**Lizheng**" (phonetic) first and then say "**Bing-Bing**" (phonetic).
  * To set it to **Chinese**, you need to say the voice command "**Attention**" first and then say "**Di-Di**"(phonetic).

#### Switch the language

{% hint style="info" %}
Note: For the **BiBoard**, the language will switch to the default language setting after rebooting the robot. So, if you accidentally switch the language mode, you can restore the default language setting by restarting the robot.
{% endhint %}

* To switch to **English**, you can say "**Bing-Bing**" (phonetic)
* Switch to **Chinese**, you can say "**Di-Di**" (phonetic)

#### Turn on/off the voice command functionality(audio response and robotics reaction)

To turn on

* Speak **Play sound**&#x20;
* Create a command called "**Enable voice**" and use the code: *`X65,99`*

To turn off

* Speak **Be quiet**
* Create a command called **Disable voice** and use the code: *`X65,100`*

#### Use the predefined voice commands

The voice command list for Nybble / Nybble Q:

<figure><img src="/files/Gvv3aH2jOo36n5eTF1ft" alt=""><figcaption></figcaption></figure>

See [**this doc**](https://docs.google.com/spreadsheets/d/1j_h9mJX0vsHcOko-hWNuEEKSgP1hkgTI6VlNFyWi7Qw/edit?gid=2089078196#gid=2089078196) for the latest version.

{% hint style="info" %}
To avoid inadvertently triggering the robot to respond to voice commands, you can say **Be quiet** to the robot to disable the voice module, such as when talking with others.

If the above voice commands don't take effect in **English mode**, try to use the mobile app and create a new button with the code: ***`X65,100`***, or input ***`XAd`*** in the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) to disable the voice module.

<img src="/files/H2dpRnHK6aBYiFVs3Nda" alt="" data-size="original">\
You can say  **Play sound** to the robot to enable the voice module.

Use the mobile app and create a new button with the code: ***`X65,99`***, or input ***`XAc`*** in the [serial monitor](https://docs.petoi.com/arduino-ide/serial-monitor) to enable the voice module.

<img src="/files/ExVu04nKsSn4SfdFdXAQ" alt="" data-size="original">
{% endhint %}

{% hint style="success" %}
The voice command **Climb-up** is a challenge for you. You can [design the behavior](/desktop-app/skill-composer) by yourself. Then, you can post it on the [Petoi Forum Challenge](https://www.petoi.camp/forum/challenge) or email <support@petoi.com>. We may adopt it in our official firmware and send you a gift!

For example, you can share your behavior like this:

{% embed url="<https://www.youtube.com/shorts/RWsQaIZMDqo>" fullWidth="false" %}
{% endhint %}

### How to debug if the voice command doesn't work

In some cases, the voice module may not respond to your voice. Please check the following:

1\. Say **Play sound** to check if the robot responds with **Do-Me-So**. Sometimes, the voice may be accidentally set to muted mode, triggered by **Be Quiet**.

2\. If the module doesn't make any sound with Play sound, say **Bing-Bing** to switch to English mode. You may try different tones and speeds to say **Bing-Bing**. The robot should respond with **Switch English** if not in **English mode**. It won't react with anything if it's already in English.&#x20;

3\. If the voice module still doesn't make any sound, you can try to reset it in our software tools.

* #### Mobile app:

  From version **1.2.0** of the mobile app, you can create a new button with the compound code:&#x20;

  ***`^X65,99;!1000;X65,98;!1000;X65,97`***

  To reset the voice module to English mode. &#x20;

  <figure><img src="/files/lVKQSlzS4IZfH8Bs1no5" alt=""><figcaption></figcaption></figure>

  <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><em><strong><code>X65,99</code></strong></em>, or input <em><strong><code>XAc</code></strong></em> in the <a href="https://guide.petoi.com/arduino-ide/serial-monitor">serial monitor</a> enables the voice module.</p><p><img src="/files/ExVu04nKsSn4SfdFdXAQ" alt="" data-size="original"></p><p><em><strong><code>X65,97</code></strong></em> or input <em><strong><code>XAa</code></strong></em> in the serial monitor is equivalent to saying <strong>Bing-Bing</strong>, but excludes the chance that the voice is not recognized. Then you can try to say <strong>Play sound</strong> again. </p></div>

  <figure><img src="/files/CumkWIADNiXd5ZUXTBf1" alt=""><figcaption></figcaption></figure>
* #### Desktop app:

  From version 1.2.1, you can use the debugger tool to [reset the voice module](https://guide.petoi.com/desktop-app/tools#download-the-latest-version-of-the-petoi-desktop-app).

4. Next, if you say **Hello**, the robot should wave its hand and validate that the complete reaction loop is good. Then, you can try other voice commands.&#x20;
5. Try powering off the mainboard by disconnecting the USB data cable, long-pressing the battery's button, and then re-powering the mainboard.

The above steps validate that the voice module is working. It's powered separately from the motion unit and should work regardless of the robot's status.&#x20;

If the above steps cannot fix the problem, contact <support@petoi.com> for help.

### Record customized voice commands

When the robot works in **English mode**,  you can speak **Start learning** (or input the serial command **XAe** in the serial monitor) into the custom voice command mode and record your voice commands in order.&#x20;

{% hint style="info" %}
If the module is **not** in English mode, you can speak **Bing-Bing** (or input the serial command ***`XAa`*** in the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor)) to switch to **English mode**.
{% endhint %}

You can record up to 10 voice commands, <mark style="color:red;">each with no more than</mark> <mark style="color:red;"></mark><mark style="color:red;">**six**</mark> <mark style="color:red;"></mark><mark style="color:red;">syllables</mark>.

To exit the custom voice command mode in the middle, you can speak **Stop learning** (or input the serial command **XAf** in the serial monitor).&#x20;

After leaving the custom voice command mode, please speak one of the recorded voice commands to trigger the reaction.

Speak **Clear the learning data** to delete all the recordings simultaneously  (you cannot delete a specific recording).

There are **ten** skill strings as custom replies already defined in the `voice.h`:

{% hint style="info" %}
The first 3 commands is standard for all type of petoi robot, which have feedback servos.
{% endhint %}

```cpp
String customizedCmdList[] = {
  "fl",  // learn skill with feedback servos
  "fr",  // replay skill learned with feedback servos
  "fF",  // movement follower demo with feedback servos
#ifdef BITTLE       // also for Bittle X
#ifdef ROBOT_ARM    // for Bittle X+Arm
  "kpickF",                          // pick front 捡起来
  "kputD",                           // put down 放下
  "khuntL",                          // hunt 捕猎
  "kshowOff",                        // show off 展示
  "kputL",                           // put left 收起来
  "ktossL",                          // toss left 左抛
  "klaunchL",                        // launch 发射
  "kclapL",                          // clap 鼓掌
  "ktossF",                          // toss front 前抛
  "qc-2:0>kclap:1000>kpickF:1000>",  // calibrate arm (for QA) 校准(工厂用)
#else
  "kpu1",                                                                  // single-handed pushups
  "m0 80 0 -80 0 0",                                                       // wave head
  "kmw",                                                                   // moonwalk
  "b14,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,\
  21,8,21,8,19,8,19,8,18,8,18,8,16,4,21,8,21,8,19,8,19,8,18,8,18,8,16,4,\
  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",  // twinkle star
  "T",                                                                     // call the last skill data sent by the Skill Composer
  "6th",
  "7th",
  "8th",
  "9th",
  "10th"  // define up to 10 customized commands.
#endif
#elif defined NYBBLE    // also for Nybble Q
  "kluckyL",   // lucky cat 招财猫
  "klkPawsL",  // lick paws 舔爪子
  "qksit:100>i0 20 1 0 8 -70 12 0 15 10:0>o1 0, 0 40 -20 4 0, 1 -30 20 4 30, 8 -70 10 4 60, 12 -10 10 4 0, 15 10 0 4 0:100>m0 0 1 -20 2 0:0>ksit:0",
  // "kwsfL",                                                                 //wash face 洗脸
  "khuntL",                                                                // hunt 捕猎
  "m0 80 0 -80 0 0",                                                       // wave head                                                                //
  "b14,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,\
  21,8,21,8,19,8,19,8,18,8,18,8,16,4,21,8,21,8,19,8,19,8,18,8,18,8,16,4,\
  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",  // twinkle star
  "T",                                                                     // repeat
  "xl",                                                                    // learn a new trick 学习动作
  "xp",                                                                    // play the trick 表演动作
  "10th"                                                                   // define up to 10 customized commands.
#endif
};
```

The response actions (**`kpu1`** means single-handed pushups, **`kmw`** means moonwalk) are already defined in the program.&#x20;

Other serial commands are also supported as responses, such as joint movements(e.g. **`m0 80 0 -80`**  means shaking the head left and right) and playing a melody(e.g. **`b14,8,14,8,21,8,21,8,23,8,23,8,21,4`**)

To use these custom replies above, you need to enter the custom voice command mode, record ten voice commands (such as Single-handed Pushup, Shake Head, Moonwalk, Twinkle Star), and then exit the custom voice command mode.

If you have recorded a voice command and the corresponding custom reply is not a predefined serial command (e.g.,**`6th`**), there is no actual demonstration effect; it only prints a simple message on the serial monitor when you speak the corresponding voice command.

## Advanced usage for developers

### Understand the principle

1. &#x20;Convert the voice command collected by the microphone in the module into a serial command.
2. &#x20;Send the serial command to the mainboard MCU through the soft serial port Serial2.
3. &#x20;After receiving the serial command, the MCU parses it into the corresponding skill command, and finally, the reaction module, according to the skill command, controls the robot to respond accordingly.

Upload the demo sketch **testVoiceCommander.ino**, and you can see every serial command that is sent to MCU(including the custom voice command if you have recorded it)

<figure><img src="/files/B3SFPQ26YbHxxEH4D8i9" alt=""><figcaption></figcaption></figure>

You can open [the serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) to check the raw return values of every voice command.&#x20;

<figure><img src="/files/f8WlQWeFdEp49F3D4A2q" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/2Bjh6ojqNV7qVX4QGNEB" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
After you speak the voice command to the robot, the **Returned value** (**`X A 11`** or **`X A 21 kup`**) is the corresponding serial command sent to the mainboard MCU. The third number(11 or 21) is an invisible character. To understand it, we convert it to a numeric value and print it out.
{% endhint %}

### The test sketch

The test sketch is in the OpenCatEsp32 repository on GitHub (specific path: OpenCatEsp32/ModuleTests/testVoiceCommander). You can visit our GitHub repository <https://github.com/PetoiCamp/OpenCatEsp32> to download the complete code, as shown in the following picture:

<figure><img src="/files/xkAYdahcOoMhWtdwbTNU" alt=""><figcaption></figcaption></figure>

### Serial interface

There are seven related serial commands for configuration; you can input them into the serial monitor.&#x20;

<table><thead><tr><th width="178">Serial Command</th><th width="222">Mobile App Button Code</th><th>Function</th></tr></thead><tbody><tr><td>XAa</td><td>X65,97</td><td>Set the default language to English</td></tr><tr><td>XAb</td><td>X65,98</td><td>Set the default language to Chinese</td></tr><tr><td>XAc</td><td>X65,99</td><td>Turn on the reply tone and enable reaction</td></tr><tr><td>XAd</td><td>X65,100</td><td>Turn off the reply tone and disable reaction</td></tr><tr><td>XAe</td><td>X65,101</td><td>Enter custom voice command mode</td></tr><tr><td>XAf</td><td>X65,102</td><td>Exit custom voice command mode</td></tr><tr><td>XAg</td><td>X65,103</td><td>Delete all the custom voice commands</td></tr></tbody></table>

{% hint style="info" %}
After inputting the command above in the message box, **press Enter** to send the command to the robot.
{% endhint %}

### How to design new reactions

For the robot in Voice mode, to improve the utilization rate of custom voice control commands, you can modify the last **six** skill strings to the skill names with actual action responses.

* Using the task queue to create a sequence of motions, please refer to the source code in the `voice.h` as below:

{% code lineNumbers="true" %}

```cpp
const char *cmd = raw.c_str() + shift;
tQueue->addTask(token, shift > 0 ? cmd : "", 2500);
if (strlen(cmd) > 0) {
  char end = cmd[strlen(cmd) - 1];
  if (!strcmp(cmd, "bk") || !strcmp(cmd, "x") || end >= 'A' && end <= 'Z') {
    tQueue->addTask('k', "up");
  }
}
```

{% endcode %}

{% hint style="info" %}
tQueue is the task queue defined in OpenCat.h; using the method "addTask" of this object, the robot can do some simple skills sequentially as a custom voice command response.&#x20;
{% endhint %}

* Using [the Skill Composer](https://guide.petoi.com/desktop-app/skill-composer) and binding the customized voice command to the new skills

1. &#x20;Use SkillComposer to design new skills and then [export](https://guide.petoi.com/desktop-app/skill-composer#export-the-skill) them to `Instinct***.h`&#x20;
2. &#x20;Modify *voice.h* to bind the customized voice command to the new skills: modify the **`customizedCmdList[]`**（e.g., If you want to bind the sixth customized voice command to the new skill, replace the string "*`6th`*" with **`'k'+the new skill name`**)


# Joystick with Micro:Bit

{% embed url="<https://youtu.be/BRb4nQeWcdQ>" %}

This remote controller is a Micro: Bit-based gamepad. It includes a 4-direction joystick and four undefined buttons. To enhance the gaming experience, it is also paired with a buzzer and vibration motor. It is compact in appearance, comfortable in hand, and can be remotely controlled.

<figure><img src="/files/cWq8AWK04l5QBMYPyAZP" alt=""><figcaption></figcaption></figure>

## Hardware

{% hint style="info" %}
Micro: Bit V1 has a smaller memory. So, the full functionality requires **Micro: Bit V2**.
{% endhint %}

## Software setup

The Joystick's source code is now open-sourced. It can control Bittle X, Bittle X+Arm (Bittle with a robotic arm), and Nybble Q. For more information, please refer to our [GitHub repository](https://github.com/PetoiCamp/ESP32_Microbit_Controller).

You can download the program file([microbit-JoyStick.hex](https://raw.githubusercontent.com/PetoiCamp/ESP32_Microbit_Controller/refs/heads/main/microbit-JoyStick.hex)), then import the program to [the programming platform MakeCode](https://makecode.microbit.org) as follows:

{% hint style="info" %}
We recommend you use a **Chrome** browser.
{% endhint %}

<figure><img src="/files/hFedNL9hJ93oPVbVHOKZ" alt=""><figcaption></figcaption></figure>

Alternatively, you can click "New Project" and drag the program file into the coding window to load it.&#x20;

### Download the program to the Micro: Bit V2

Connect your PC to the Micro: Bit V2 using a USB cable.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/connect-microbit.gif)

After a successful connection, a disk drive named `MICROBIT` is recognized on the computer.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/microbit-drive.png)

Click on the bottom left corner of the ![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-01.png) button， Select `Connect Device`.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-02.png)

Click ![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-03.png) button.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-04.png)

Click![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-05.png)

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-06.png)

Select `BBC micro:bit CMSIS-DAP` in the pop-up window and then select Connect. At this point, our Micro: Bit has connected successfully.

<figure><img src="/files/AYGrUa10XCpIyDScs4KF" alt=""><figcaption></figcaption></figure>

Click to download the program.

![](https://wiki-media-ef.oss-cn-hongkong.aliyuncs.com/docs/microbit/interesting-case/microbit-smart-climate-kit/cases-libraries/images/download-08.png)

## How to use&#x20;

1. [Upload the newest firmware](https://guide.petoi.com/quick-reference/upload-firmware) to the robot (mainboard type: **BiBoard**)
2. Install 2 x #7 AAA batteries and plug in the Micro: Bit V2 to the remote controller. Then, power on the remote controller as follows:\
   ![](/files/4wd4bqBDrhavQ1xEHQuE)
3. Power on the robot. During bootup, it can connect to the controller automatically via Bluetooth.\
   If there are many remote controllers and robots, the connection is one-to-one and first-come, first-served.

{% hint style="info" %}
**Timed lock feature**

This feature limits the play time for each user during exhibitions or science festivals. It is deactivated by default.

After normal startup and Bluetooth connection, you can activate the limited-time usage function for the controller by pressing and holding the middle Logo (touch button) on the Micro:bit while keeping the controller upright (with the left joystick at the bottom). Once activated, the controller will send a rest command to the robot every 20 minutes and no longer respond to subsequent operations. The LED indicator matrix will dynamically display an hourglass pattern, as shown in the figure below:

<img src="/files/9X7ZIZfFs7c3DrOmUZpT" alt="" data-size="original">

You can reset the countdown and reactivate the controller using the same operation described above. The controller will play a prompt tone, and the LED indicator matrix will display an animation of an hourglass reversing.

Once the limited-time feature is activated, it can only be turned off by rebooting the controller. After the controller restarts, you must reset the robot (by clicking the **reset** button on the mainboard) or reboot the robot to reconnect.
{% endhint %}

### To control Nybble Q

<figure><img src="/files/CtHai9XBNzhsf1cBYSAU" alt=""><figcaption></figcaption></figure>


# Petoi Desktop App

The Petoi Desktop App offers a user-friendly graphical interface for configuring the firmware, calibrating the robot, designing customized motions, and utilizing debugging tools. The major function modules are the [Firmware Uploader](https://guide.petoi.com/desktop-app/firmware-uploader), [Joint Calibrator](https://guide.petoi.com/desktop-app/joint-calibrator), [Skill Composer](https://guide.petoi.com/desktop-app/skill-composer), and [Tools](https://guide.petoi.com/desktop-app/tools).

<figure><img src="/files/TDgmz5IOELYasd0r5kXQ" alt=""><figcaption></figcaption></figure>

## Download & Installation

You can download the [latest version](/desktop-app/introduction#download-the-latest-version-of-the-petoi-desktop-app) of the desktop App and unzip it.

Before running the app, you must use the included USB adapter or the Bluetooth dongle to connect to a Petoi robot. You may need to [install drivers](https://docs.petoi.com/technical-support/useful-tools#nyboard-usb-driver-to-access-the-usb-uploader-adapter) for USB connection.

### Windows

Run the UI.exe in the **unzipped** folder.  Do NOT move the UI.exe to another location in Windows.

### Mac

After downloading the Mac version, you must drag it into the **Applications** folder.&#x20;

If you see the error message that **Petoi Desktop App** cannot be opened because the developer cannot be verified, you can right-click the icon, hold the **Shift** key and click **Open**.

![](/files/8358jcqppHBs1YHVE40Z)

{% hint style="warning" %}
The upgraded macOS has introduced some incompatibility with the GUI library. To click/activate an element in the app's interface, press and hold the element, then move your finger slightly and release. Otherwise, the event cannot be recognized.&#x20;

Sorry for the inconvenience. It's been a known issue between macOS and the popular Tkinter library.

<img src="/files/VEUyL4GdnSJyUo1amUuI" alt="" data-size="original">
{% endhint %}

### Linux

Please see the next chapter to run the app from a terminal.

## Run the app from the Terminal for Mac or Linux

In the case of compatibility issues or if you want to modify the source and test, you can also run the code from the Terminal.

The Terminal is a built-in interface on Mac or Linux machines. The equivalent environment on Windows machines is the Command Prompt (CMD). It's recommended that you install [Anaconda](https://www.anaconda.com/) to manage your Python environment (**Python version > 3.7.1)**. It can also provide PowerShell as a Terminal for older Windows machines.

Depending on your existing Python configuration, you may need to upgrade to Python 3 and install the following libraries:

* pyserial
* pillow

You can install them by entering `pip3 install pyserial pillow` in the Terminal or use the package manager in Anaconda.

To run the code:

1. In the Terminal, use the `cd` command to navigate to the `OpenCat/pyUI/` folder. You can use the Tab key to auto-complete the path name.
2. After entering the pyUI/ folder, enter `ls` and ensure you can see the UI.py and other python source codes listed.
3. Enter `python3 UI.py`.

{% hint style="info" %}
For Linux system users,  if you encounter the Python error message "\_tkinter.TclError: no display name and no $DISPLAY environment variable", you can try to install **python3-tk**, **tk-dev**. Taking Debian / Ubuntu as an example, the command is as follows:

`apt install python3-tk`

`apt install tk-dev`

After the installation is complete, reboot the computer.
{% endhint %}

## Open Source Codes

The source code is written in Tkinter using Python 3 and is open-source. The GitHub repository URL is: <https://github.com/PetoiCamp/DesktopAppRelease>

UI.py is the general entry for all the modules in the pyUI file folder:

-> FirmwareUploader.py

-> Calibrator.py

-> SkillComposer.py

-> Debugger.py

-> translate.py provides multi-language support for the UI. You may help to translate the UI into your language.


# Firmware Uploader

Robot's brain is in the firmware.  Robots desire to have the most updated brain!

Please refer to [the introduction](/product/nybble-q/control-and-program/petoi-desktop-app) for installing the Petoi Desktop App and connecting the robot to your computer.

### Open the PetoiDesktopApp

**After** properly connecting the mainboard with the computer via a USB data cable, open the PetoiDesktopApp (for Windows: UI.exe / for Mac: Petoi Desktop App), and select your **Model** and **Language**.

#### Menu bar in Petoi Desktop APP

<div align="left"><img src="/files/qBCd9Bhez4849Yf780QA" alt="Model"> <img src="/files/gR5eBhARz93cFxxlprzO" alt="Language"> <img src="/files/3sAlQfjLKtep2lBKB4Hg" alt="Help"></div>

### Click the Firmware Uploader button

<div align="center"><img src="/files/bmSa9E1wwzopUOGaqGUS" alt="Main interface"></div>

### Auto Detect the Serial Port&#x20;

If there is **no** serial port or **more than one** serial port is detected by the desktop app:

<figure><img src="/files/zPEK9HCklsSKKfOlij4n" alt=""><figcaption></figcaption></figure>

After clicking the **Firmware Uploader** button,  there will be a message box prompt as follows:

<figure><img src="/files/ii8QC9zLeNtH6vwtQWhP" alt=""><figcaption></figcaption></figure>

Please follow the prompts in the message box. \
After clicking the **Confirm** button, If you complete the prompts within 10 seconds, the desktop app will automatically identify the serial port name connecting the robot to the computer.\
If you complete the operation of unplugging and plugging the USB interface on the computer for more than 10 seconds, the desktop application will enter the manual selection of the serial port name mode：

<figure><img src="/files/kgnSTTD7u6lGHXvrUqz1" alt=""><figcaption></figcaption></figure>

Click the **OK** button in the Warning message box first, then you can refresh the serial port list or select one of them (e.g. **COM3**) and click the **OK** button in the **Manual mode** window to open the Firmware Uploader interface as follows:

<figure><img src="/files/IAPsr99lxuNKhqeN7S3w" alt=""><figcaption></figcaption></figure>

Once the Firmware Uploader interface is opened, you can also unplug and replug the USB cable from the COMPUTER side. The desktop app will automatically identify the serial port name used to connect the robot to the computer.

<figure><img src="/files/4910PiAdo9AGvz9107Rb" alt=""><figcaption></figcaption></figure>

If you unplug the **COM5** and replug it on the computer side, it will be discovered by the desktop app as follows:

<figure><img src="/files/VW5yOQDHLRpfGYUgqW7W" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/QDyj6IxfGOZBglAI9zm9" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/6kaCalAgQlbDT7Ivx4cw" alt=""><figcaption></figcaption></figure>

### Select the correct options to upload the latest firmware.&#x20;

{% hint style="warning" %}
The 1.0 software won't work correctly with the Joint Calibrator, the Skill Composer, and other APIs. Use it only when you want to use the CodeCraft, a graphical coding interface provided by our partner, TinkerGen.&#x20;
{% endhint %}

<table><thead><tr><th width="176">Options</th><th width="293">Values</th><th>Notes</th></tr></thead><tbody><tr><td>Product</td><td><p>Bittle (default)</p><p>Bittle X</p><p>Bittle X+Arm<br>Nybble<br>Nybble Q</p></td><td></td></tr><tr><td>Mode</td><td>Standard (default)<br>RandomMind <br>Voice<br>Mind+<br>Camera <br>Ultrasonic <br>RandomMind_Ultrasonic<br>Light<br>Touch<br>PIR<br>Gesture<br>IR distance</td><td><p>Because <strong>Bittle X running on BiBoard</strong> has more memory space, you only need to upload with the <strong>Standard</strong> mode firmware.  Then you can switch between different modes via serial port commands. [1]</p><p></p><p>For NyBoard, these 12 modes can be selected. All of these modes apply to both <strong>Bittle</strong> and <strong>Nybble</strong>.</p><p></p></td></tr><tr><td>Software version</td><td><p>2.0 (default)</p><p>1.0</p></td><td>The 1.0 version is obsolete.</td></tr><tr><td>Serial port</td><td>Auto detection or by manual selection. </td><td>You can find the correct one through unplug and replug the USB socket on the computer side</td></tr><tr><td>Board version</td><td><p>NyBoard_V1_0 (default<em>)</em><br>NyBoard_V1_1<br>NyBoard_V1_2<br>BiBoard_V0_1</p><p>BiBoard_V0_2<br>BiBoard_V1_0</p></td><td>BiBoard_V0_1 or BiBoard_V0_2  is for <strong>Bittle X.</strong>  <br>BiBoard_V1_0 is for <strong>Bittle X V2</strong> and <strong>Nybble Q</strong>.</td></tr></tbody></table>

{% hint style="info" %}
\[1] You can use the serial commands to [switch modes](https://guide.petoi.com/product/nybble-q/control-and-program/petoi-desktop-app/pages/8ajuxMEplUPiNYi4SRyi#id-2.9-switch-working-mode-via-the-serial-commands-optional) for **BiBoard**:\
For **BiBoard,** Mind+ mode is supported by default, so it doesn't require a serial command to switch on.\
You can learn about the functionw of each module through the [**EXTENSIBLE MODULES**](https://guide.petoi.com/extensible-modules/introduction).
{% endhint %}

{% hint style="warning" %}
There's no correlation between the board (hardware) version and the code (software) version.
{% endhint %}

### Uploading options

* **Factory Reset**\
  After upgrading the firmware, the board will enter the [**initialization startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization) and ask whether to clear the joint calibration parameters and calibrate the IMU.
* **Upgrade the Firmware**\
  It will upgrade the firmware, skip the steps of clearing joint calibration parameters and the IMU calibration(it's equivalent of sending serial command "**n**"), and automatically enter the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization).
* **Update the Mode Only**\
  It has the same function as the **Upgrade the Firmware** at present.

#### **Factory reset** process

After clicking the **Factory Reset** button, the uploading process will start immediately. The board will enter the [**initialization startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization) after uploading the firmware. Some message windows will pop up in sequence for you to confirm or cancel:

1. Reset joint offsets? (Y/N)<br>

   <figure><img src="/files/xp2AMD7ENMG0QPFcJMRr" alt=""><figcaption></figcaption></figure>

Select **Yes**, and the program will reset all servo calibration parameters to zero. The status bar will update the corresponding process and result in real time.

Select **No** to preserve the calibration value(so that you don't need to calibrate again if you have already done so). &#x20;

2. Calibrate IMU? (Y/N)<br>

<figure><img src="/files/kNL86GYJtsuQDf6aOUNE" alt=""><figcaption></figcaption></figure>

Select **Yes**,  and the program will calibrate the gyroscope (IMU) to balance the robot correctly. The status bar will update the corresponding process and result in real time.

Select **No**, and the program will skip this step.

After that, the board will enter the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization)**.**

{% hint style="danger" %}
Note:&#x20;

Ensure the microcontroller is positioned horizontally for IMU calibration before clicking the "Yes" button.&#x20;
{% endhint %}

### Finish uploading the firmware

After the upload, the status bar will update the corresponding result, such as the success or failure of firmware uploading. If the uploading is successful, a message window of "Firmware upload complete!" will pop up simultaneously.

<figure><img src="/files/LoanvpTqxeu9rGHNDzAj" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Note:&#x20;

1. For NyBoard, when you open the software and upload the firmware for the first time, the program will first upload the "**Parameters**" firmware and then the "**Main function**" firmware.&#x20;
2. After uploading the firmware, if the NyBoard or BiBoard V1 is not connected to the battery and powered on, you will hear repetitive descending melodies, indicating that the battery is low or disconnected. You need to connect the battery and turn on its power.&#x20;
   {% endhint %}

### Check the log

From the desktop app version **1.2.7**, the log information will be output in the console box at the bottom of the interface:

<figure><img src="/files/Kusypy1JUioDU1uI0sgi" alt=""><figcaption></figcaption></figure>

You can directly click the **Copy** button to copy all the log information, or you can first select specific key information in the console output box with your mouse, then click the **Copy** button to copy only that portion of the log information, and then paste this information into an email and send it to support.petoi.com for assistance.

{% hint style="info" %}
For the old version of the desktop app, if the upload fails, the following message box will pop up:

<img src="/files/dlpmDOhPH7XgCXMd5IgK" alt="" data-size="original">

the log file is located at:

* For Windows: The log file is in the same directory as **UI.exe**

  ![](https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FNl61Gr6RNtDYEuJek7Gm%252Fimage.png%3Falt%3Dmedia%26token%3D0e0ea071-11e4-48e7-9f80-cbfbca10ccac\&width=768\&dpr=4\&quality=100\&sign=996aee40\&sv=2)
* For macOS: You can check the log file as follows:

  ![](https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FGLeXErV4KpBrfbJQhO3o%252Fimage.png%3Falt%3Dmedia%26token%3Dee485581-cf60-4008-aba7-5c4a91b16ee3\&width=768\&dpr=4\&quality=100\&sign=d6a8daf1\&sv=2)![](https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FL7O8qDstl6NwlwRQ4ZmJ%252Fimage.png%3Falt%3Dmedia%26token%3D972abd2e-b715-4f05-8601-baa99d22ad17\&width=768\&dpr=4\&quality=100\&sign=a61fc3b5\&sv=2)

When you contact our **<support@petoi.com>**, please attach the log file to your email.
{% endhint %}

### Run Firmware Uploader in the terminal

{% hint style="info" %}
There may be some OS platform compatibility issues with different computers.

You can still run the app directly from your terminal:

1. Go to OpenCat/pyUI/ in your terminal.
2. Install **PySerial** and **Pillow** for your Python installation. You may get a clean Anaconda environment and `pip3 install pyserial pillow`
3. Run `python3 UI.py`

For **NyBoard**, the firmware uploader calls the application **avrdude** to upload firmware files to the microcontroller.&#x20;

For **BiBoard**, the firmware uploader calls the application **esptool** to upload firmware files to the microcontroller.&#x20;

**Linux OS**

For Linux system users, in addition to the above steps, you also need to perform the following steps:

1\. Install **avrdude**&#x20;

* Fedora: dnf install avrdude
* CentOS: yum install avrdude
* Debian / Ubuntu: apt install avrdude

2\. Modify the variable **avrdudeconfPath** in FirmwareUploader.py

* Fedora / CentOS : `avrdudeconfPath = '/etc/avrdude/'`
* Debian / Ubuntu : `avrdudeconfPath = '/etc/'`
  {% endhint %}

{% hint style="info" %}
If you have experience with the Arduino IDE, you will see the same log message when uploading.

* For the BiBoard, please review the [Upload Sketch for BiBoard](/arduino-ide/upload-sketch-for-biboard).
* For the NyBoard, please review the [Upload Sketch for NyBoard](/arduino-ide/upload-sketch-for-nyboard).
  {% endhint %}


# Joint Calibrator

Robots can be precisely calibrated using the Petoi Desktop App.

Please refer to [the introduction](/product/nybble-q/control-and-program/petoi-desktop-app) for installing the Petoi Desktop App and connecting the robot to your computer.

## The rationale for calibration

### Understand the zero state and the coordinate system

After [entering the calibration state](#enter-the-calibration-state), with all servos rotated to their zero angles, attach the head, tail, and legs prepared in the previous section to the body. They are generally perpendicular to their linked body frames. The calibration pose is shown below:

![Nybble's Calibration State](/files/AiBp5uskBjNIOASP0BI3)

Install the servo-related components according to the picture above and try to ensure that they are perpendicular to each other (the upper leg is perpendicular to the torso, and the lower leg is perpendicular to the upper leg).&#x20;

{% hint style="warning" %}
Note: Insert the servo-related components directly into the servo output shaft; do not turn the output shaft during this process.
{% endhint %}

Rotating the limbs counterclockwise from their zero states will be positive (the same as in polar coordinates). Viewed from the left side of the robot's body, the counter-clockwise rotation of the joint is defined as the positive direction.

{% hint style="info" %}
The only exception is the head tilt angle for Nybble. It’s more natural to say head up, while it’s the result of rotating clockwise.&#x20;
{% endhint %}

{% hint style="info" %}
However, from the right side of the robot's body, the rotation directions' positive and negative are just opposite.
{% endhint %}

### Discrete angular intervals

If we look closer at the servo shaft, we can see it has a certain number of teeth. That’s for attaching the servo arms and avoiding sliding in the rotational direction. In our servo sample, the gears divide 360 degrees into 25 sectors, each taking **14.4** degrees(offset of -7.2\~7.2 degrees). That means we cannot always get a perfect perpendicular installation.&#x20;

![](/files/v400iIvlmpXjiobnloRS)

## Calibration process

### Enter the calibration state

{% hint style="info" %}
Connect the battery to the mainboard, then long-press the battery button for more than 3 seconds to power on the robot.
{% endhint %}

&#x20;After a battery powers on the robot, there are two methods to enter the calibration mode:

* It will automatically enter calibration mode when you click the **Joint Calibrator** button.<br>

  <figure><img src="/files/CS20IELy2ji3gHVEWbTd" alt=""><figcaption></figcaption></figure>
* Click the **Calibrate** button in the **Joint Calibrator** interface.&#x20;

{% hint style="info" %}
The servo slider is not available in the light yellow background area in the interface.
{% endhint %}

The joint calibration interface for Nybble Q in the Petoi Desktop App is as follows:

<figure><img src="/files/ebvP1ctbrQfNvfrOeyhX" alt=""><figcaption><p>The interface for Nybble Q</p></figcaption></figure>

### Fine-tuning

Please use the L-shaped calibration tool included in the package as a calibration reference. According to the joint numbers shown in the picture within the calibration interface, click and drag the corresponding joint sliders or click on the blank areas of the slider tracks to fine-tune the joints to a right angle.

Please note that when calibrating the servos, adjust the upper leg first, then change the lower leg.

![](/files/HXHygTlSauC6GsdgjoHb)

{% hint style="info" %}
If the offset exceeds ±9 degrees, you must remove the corresponding leg and reinstall it by rotating one tooth and then dragging the corresponding slider. For example, if it is adjusted to +9 and still not correct, remove the corresponding leg and shift it one tooth when reattaching it. Then, you should get a smaller offset in the opposite direction.&#x20;
{% endhint %}

### Validation and Save data

<figure><img src="/files/bO4A4lw1w3nU5DipkcNG" alt=""><figcaption><p>Nybble</p></figcaption></figure>

You can switch between  "**Rest**", "**Stand up**" and "**Walk**" to test the calibration effect.&#x20;

If you want to continue calibrating, please click the **Calibration** button, and the robot will be in the calibration state again (all servos will move to the calibration position immediately).&#x20;

{% hint style="warning" %}
Note: You may need a second round of calibrations to achieve optimal results.
{% endhint %}

After calibration, remember to click the "**Save**" button to save the calibration offset. Otherwise, click the "**Abort**" button to abandon the calibration data. You can save the calibration in the middle in case your connection is interrupted.&#x20;

{% hint style="info" %}
When you close this window, there is a message box shown below:

![](/files/iEbvluamYhzOnshzp9Bn)

To save the calibration data, please click the "**Yes**" button; otherwise, click the "**No**" button. Click the "**Cancel**" button to cancel or quit.
{% endhint %}


# Skill Composer

Petoi Skill Composer is a robobics skill design too for Petoi robots. Good tools are a prerequisite for job success.

Please refer to [the introduction](/product/nybble-q/control-and-program/petoi-desktop-app) for installing the Petoi Desktop App and connecting the robot to your computer.

## A Brief Introduction to the Interface

{% embed url="<https://www.youtube.com/playlist?list=PLHMFXft_rV6MTs8HMxSOvRAQektoXtaMG>" %}

### See [the video tutorials](https://www.youtube.com/playlist?list=PLHMFXft_rV6MTs8HMxSOvRAQektoXtaMG)

Open Petoi Desktop App, click the "**Skill Composer**" button, and open the Skill Composer interface.&#x20;

![](/files/4OWjfHFhnNsvmqWomxmj)

## The Skill Composer Interface

{% hint style="info" %}
The servo slider is not available in the light yellow background area in the interface.
{% endhint %}

<figure><img src="/files/Kvs2MfnoMokWMSFHOkpF" alt=""><figcaption><p>For Nybble / Nybble Q</p></figcaption></figure>

{% hint style="info" %}
Note: Most of the buttons on the interface have a tooltip when the mouse hovers over.
{% endhint %}

### Menu Options

* Model

  * Nybble
  * Nybble Q
  * Bittle
  * Bittle X
  * Bittle X+Arm

  Nybble cat and Bittle dog have different back leg joint directions. Their skill data are not interchangeable. Select the correct model before operating the Skill Composer. Otherwise, some joints may conflict with the robot's body.
* Language

  Currently, there are English, 中文, and Italian. You may contribute to the [translation script](https://github.com/PetoiCamp/DesktopAppRelease/blob/main/pyUI/translate.py).
* Utility

  We will keep adding small gadgets to the utility tab. We have an eye color picker for the Nybble cat's ultrasonic sensor with built-in LEDs. We also have an entry where you can add your creator credentials to the skills you create.

### Connection and State Dials

<figure><img src="/files/h24YX0YiSDhpIJol5NRJ" alt=""><figcaption><p>Connection and State Dials</p></figcaption></figure>

#### Listening / Connect button

for BiBoard:

* Wired connection: The kit includes a **USB Type-C data cable** connecting the robot's mainboard to the computer.
* Wireless connection (Bluetooth): The motherboard's [**built-in Bluetooth**](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard) module allows you to connect the robot's mainboard to the computer wirelessly.

{% hint style="info" %}
For NyBoard:

You can connect the robot to your computer via the [USB uploader](https://guide.petoi.com/communication-modules/usb-downloader-ch340c#connect-nyboard) or the system [Bluetooth settings](https://guide.petoi.com/communication-modules/dual-mode-bluetooth#connection-with-nyboard), then open up this desktop app.&#x20;
{% endhint %}

It should automatically detect and connect to the robot. The robot's serial port will appear in the following drop-down menu. The button should turn from "<mark style="color:yellow;">**Listening**</mark>" to "<mark style="color:green;">**Connected**</mark>". If the robot fails to connect for the first time, you can click the "<mark style="color:yellow;">**Listening**</mark>" button to disconnect all the ports, then press the "<mark style="color:red;">**Connect**</mark>" button again.

{% hint style="info" %}
Note: The desktop app will keep listening to the serial port and send a handshake signal to the newly added device. If the device responds with a pre-defined signal, it will be recognized as a Petoi device and added to the drop-down menu.
{% endhint %}

#### Servo

The robot's joints will hold position when the force is on. You should **NOT** rotate them by hand. Turning it off can allow you to rotate the robot's joints freely. It's helpful to quickly pose the robot to plan its center of mass for balancing.

#### Gyro

The robot has a gyroscope to detect its body angle and movements. It's used for balancing and roll-recovering. Turning it off can avoid unexpected reactions when rotating the robot.

#### Random

{% hint style="info" %}
For the robot with Nyboard, In certain experimental modes (e.g. [RandomMind mode](https://guide.petoi.com/desktop-app/firmware-uploader#select-the-correct-options-to-upload-the-latest-firmware)), the robot will move randomly. This button can toggle the behavior on/off.
{% endhint %}

### Send a serial command

<div align="left"><figure><img src="/files/jPvAyy2O5upvVQsmYkfx" alt=""><figcaption></figcaption></figure></div>

Like the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor), you can enter a [serial command](https://guide.petoi.com/apis/serial-protocol) in the text box and send it to the robot by pressing the **Enter** key or clicking the **Send** button.

### Preset Postures

![](/files/y1tu9IWMbAZMtwVRjo6F)

A few preset static postures move the robot's joints to specific positions. You can use them as a starting point to build your motion sequence. We usually start with the "balance" posture, with the robot standing on all four legs.

You can switch between different postures and observe how the sliders in the **Joint Controller** area update to reflect the changes in joint angles.

### Joint Controller

<figure><img src="/files/5L6d1N7UGvOWRZvjMFnt" alt=""><figcaption></figcaption></figure>

The angle sliders can show the robot's current joint angles. They can reversely rotate the robot's joints if you change their values. You can drag the slider bar for large angle adjustments or click above or below the slider bar for fine adjustments (by 1 degree). Some joints will have smaller accessible ranges than the sliders. Try to use angles between -125 and 125 degrees. Sending larger angles will increase the response time.

The sliders correspond to the robot joints if you look down at the robot's body with its head pointing forward. Joints closer to the body are closer to the center of the panel. The robot's joints can be mapped to your own body and become your avatar.

{% hint style="info" %}
Note: Some sliders with a light yellow background are disabled for joints that don't exist on specific models.
{% endhint %}

You can control multiple joints by clicking the dial "**+**" or "**-**" on each slider. All sliders with their "**+**" pressed will change by the same increments. Sliders with their "**-**" button pressed will change by the negative increments. The button can be toggled on and off. Click the "<mark style="color:red;">Unbind All</mark>" button to disengage all the joints at once.

You can also control the robot's whole body joints with the sliders in the center panel. You can tune these central sliders to adjust the robot's global orientation and translation. The neutral "**balance**" posture can generate better results than other tilted postures.

| Global Orientation and Translation | Effect                          |
| ---------------------------------- | ------------------------------- |
| Pitch                              | Adjust the pitch angle          |
| Roll                               | Adjust the roll angle           |
| Spinal                             | Move in the spinal direction    |
| Height                             | Raise or lower the robot's body |

### Skill Editor

<figure><img src="/files/nDnxRqJy00T1puNCMal1" alt=""><figcaption></figcaption></figure>

The previous functions can modify a single posture. The Skill Editor is a stop-motion animation scheduler. You can add, delete, and insert frames of poses and make the robot perform continuous and smooth motions.

Every frame has a row of buttons and input fields as parameters. The first static row contains the column header to indicate the parameters' names.

## Basic Operation

### The Activated Frame

You can click the "<mark style="color:blue;">**=**</mark>" button (**the 2nd item** of a frame) to activate the corresponding frame and move the robot to the frame's posture. The frame will hold all your new edits on the robot's current posture. The "<mark style="color:blue;">**=**</mark>" symbol will become bold, and the button will become larger. The "=" symbol will become a red "!" mark if the current frame is edited. You can click this button to save your edits. Otherwise, the current edits will be abandoned if you click the "<mark style="color:blue;">**=**</mark>" buttons of the other frames.

### Add a Frame

You can click the "<mark style="color:green;">**v**</mark>" button (**the 9th item** of a frame) to add a frame after the current frame and activate it. The new frame will be identical to the **previous activated frame**.&#x20;

{% hint style="info" %}
Note: The new frame doesn't necessarily copy the "<mark style="color:green;">**v**</mark>" button's frame.
{% endhint %}

### Insert a Frame

You don't always add a new frame after the last frame. You can click the "<mark style="color:green;">**v**</mark>" button (**the 9th item** of a frame) of any intermediate frames to insert a new frame below the "<mark style="color:green;">**v**</mark>" button. The new frame carries information identical to the previously **activated frame**.

### Mirror a frame

You can mirror the activated frame's posture by clicking the "**>|<**" button.

### Delete a Frame

You can click the "<mark style="color:red;">**<**</mark>" button (**the 8th item** of a frame) to delete the current frame holding the button. All the following frames will shift up. If **the activated frame** is deleted, its preceding frame will be activated. If **the activated frame** is the first frame and is deleted, its following frame will be activated.

### Add a Note to a Frame

You may lose track of what each frame holds with multiple edits to the frame list. Switching to individual frames can be time-consuming. We provide a "**Note**" field (**the 7th item** of a frame) where you can add short keywords to identify the frames. By default, a random animal name will be added to a frame when created.

<figure><img src="/files/rKC7CRO4y7yUGvwIASQU" alt=""><figcaption></figcaption></figure>

### Bound joints and passed-through edits

If a joint's angle is the same in the current frame and the next frame, editing and saving its angle will also update the angles in the following frames until the angle differs. For example, if joint 8's angles are 4,4,4,4,6,7 in all the frames, changing the angle in the second frame to 8 will update the sequence to 4,8,8,8,6,7.

### Play the Skill Sequence

Besides manually clicking the "<mark style="color:blue;">**=**</mark>" button (**the 2nd item** of a frame) to view the single posture, you can click the "<mark style="color:green;">**Play**</mark>" button to show the postures in order starting from **the activated frame**. During playing time, the button's text becomes "<mark style="color:red;">**Stop**</mark>" to allow you to stop in the middle.

### Export the skill

After clicking the "<mark style="color:blue;">**Export**</mark>" button, you can choose a location and filename to save the skill (from **the activated frame**. If **the activated frame** is the last action frame, all action frames in the action frame list are exported) as a text file. You can cancel the savings to skip. The desktop app will still send the skill to the robot for real-time performance. And you can call the last exported skill by the serial token "**T**." There are two ways:

* Open [the serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) and input the serial command "**T**."
* Open [the mobile app](https://guide.petoi.com/mobile-app/controller), use the [Create Command](https://guide.petoi.com/mobile-app/controller#create-a-single-command) function, and enter the serial port command "**T**" in the **Code** text box.

{% hint style="info" %}
The last skill exported by the Skill Composer is stored in temporary memory. It can stay after the power is off and rebooted but **will be overwritten by a new export**.&#x20;

From version **1.1.3**, When exporting a skill, the desktop app automatically saves it to /Users/{username}/.config/Petoi/SkillLibrary/. Note the ***.config*** is a hidden directory but can be visited in the terminal or through a specific view setting. Therefore, you can easily manage the skills in [Mind+](https://guide.petoi.com/block-based-programming/petoi-coding-blocks#perform-the-skill-in-the-file).

The [Skill Creation](/applications/skill-creation) chapter focuses on the code and data structure so that you can integrate any number of new skills into the source code. The skill data array in the exported text file (\*.txt or \*.md) content *can be copied and pasted into the Instinct*\*\*.h file to be used as a skill array.
{% endhint %}

* [Export the skill ](/mobile-app/controller#import-new-skills-as-a-customized-button)as a customized button in the mobile app. It can be **permanent** even if you create multiple skills.&#x20;

### Import the Skill

You will see a pop-up window after clicking the <mark style="color:blue;">"Import"</mark> button. It allows you to copy-paste a skill data array in the text editor or import an existing skill file you or other users created. You can find example skill data in OpenCat/src/**InstinctBittle.h** or **InstinctNybble.h**. A complete skill format should include the "**{ }**" pair and the numbers between them. Only **the first one** will be imported if there are multiple skill arrays. The importer will do some simple format checks.

{% hint style="info" %}
[The SkillLibrary folder](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary) in GitHub is a collection of new skills of the OpenCat robot, which can be used for your reference (after downloading, use the import function to save a single skill to the robot's memory, and then use the [play](#play-the-skill-sequence) or [export](#export-the-skill) to view the specific effect).&#x20;

You are welcome to share your new skills by sending merge requests to this folder.
{% endhint %}

### Reset the Skill Editor

You can use the "<mark style="color:red;">**Restart**</mark>" button to clear the Skill Editor panel and start over.

## Advanced operation

### Set up Action Frame Loops

If you need some consecutive action frames in [the action frame list](#skill-editor) to run multiple times in a loop, you can first enter the number of loops in the **Repeat** text box above [the action frame list](#skill-editor) (on the **left side** of the label "**Set**"), and then use the left mouse button to select them in turn, The index numbers (**the 1st item** of a frame) of the **first** and **last** two frames of the continuous action frame that want to achieve cyclic motion (the index number button will appear in a recessed state after selection), as shown in the following figure:

<figure><img src="/files/UJIa23LB49MEBFqt22Il" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you enter **-1** in the **Repeat** text box, the looping action frames will keep looping forever unless you press the reset button on the mainboard of the robot.
{% endhint %}

### Set Movement Speed

In [the action frame list](#skill-editor), you can set the running speed of each frame of action (**the 3rd item** of a frame). There are the following 9 options for you to choose from (speed up the running speed in the order of numerical value):

1，2，4，8，12，16，32，48，max

{% hint style="info" %}
Note:

* In the options box, you can also enter any integer value in the range of 0\~125 (0 means max).
* By clicking the "<mark style="color:green;">**Play**</mark>" button in the "**Skill Editor**" area, you can **NOT** see the real running speed effect of the action; only after clicking the "<mark style="color:blue;">**Export**</mark>" button will you see the real running speed effect.
* Moving at the fastest speed for a long time will cause damage to the servo, so it is generally recommended **NOT** to set it to "**max**".
* When the "<mark style="color:green;">**Gyro**</mark>" button in the "[**State Dials**](#connection-and-state-dials)" area is turned on (the font color is <mark style="color:green;">green</mark>), after adjusting the joint angle value in the action frame or the running speed of the action frame, [<mark style="color:green;">**play**</mark>](#play-the-skill-sequence) it to view the debugging effect, or [<mark style="color:blue;">**export**</mark>](#export-the-skill) the action behavior, the robot It will try to maintain its own body balance in real-time, so it may be seen that when the robot is doing preset actions (especially when running relatively violent actions), its body will shake back and forth or even overturn, and the robot will automatically recover. Action may disrupt your original operation steps. Therefore, it is recommended that you click the "<mark style="color:green;">**Gyro**</mark>" button when designing the action to turn off the gyroscope (the font color changes to <mark style="color:red;">red</mark>), and the robot will not perform balance feedback actions in real-time. When turning on the gyroscope, click the "<mark style="color:red;">**Gyro**</mark>" button again.
  {% endhint %}

### Set Delay

In [the action frame list](#skill-editor), the "**Delay**" option (**the 6th item** of a frame) in each action frame indicates how long the robot delays before doing the next frame of action after the action of this frame is completed.

There are **17** presets for you to choose from: 0，50，100，200，300，400，500，600，700，800，900，1000，2000，3000，4000，5000，6000.

Of course, you can also enter any integer value in the range of 0\~6000 in the "**Delay**" option box. The unit is milliseconds (ms).

### Set Trigger and Angle

<figure><img src="/files/TnxUVWmiNoM5md5KDEyI" alt=""><figcaption></figcaption></figure>

The "**Trigger**" option (**the 4th item** of a frame) in the action frame is used to set the body rotation direction when the robot triggers the next action frame. There are the following **5** setting options:

* **None** means that there is no trigger and the angle condition is set
* **Pitch** means the robot body rotates nose-down
* **-Pitch** means the robot body rotates nose-up
* **Roll** means that the robot body rolls to its left side (counter-clockwise when looking from the tail)
* **-Roll** means the robot body rolls to its right side (clockwise when looking from the tail)

The "**Angle**" option (**the 5th item** of a frame) is defined with reference to the angle of the polar coordinate system. As shown in the figure above, when the body is horizontal, the angle of the polar coordinate axis is 0 degrees. If the polar coordinate axis rotates counterclockwise, the angle is positive and gradually increases. The angle setting range is an integer value between **-125\~125**.

When a specific trigger and angle are set in the action frame, the next frame of action will be triggered only when the robot rotates over the trigger angle in the trigger's direction. If a delay time is also set in this action frame, it will delay an additional time after the trigger condition is met before moving to the next frame.

When creating actions related to the rotation of the robot body (such as backflips, doing high bar exercises, etc.), it's vital to trigger the motion at a certain body angle whose timing can be hard to estimate, and it may also change during the motion. We can use the gyroscope to monitor the rotation angle of the robot body in real-time, so that the robot can trigger the joint servo at the exact time of the trigger event.&#x20;

### Export Mirror Actions

When exporting the action frames, if you want to mirror all the action frames in [the action frame list](#skill-editor) (the robot's left and right side joints will be exchanged, as if seen in a mirror), you can first click the "[<mark style="color:blue;">**MirrorAll**</mark>](#skill-editor)" button, and then click the "[**Export**](#export-the-skill)" button. If you want to cancel the mirrored export, you can deselect the "<mark style="color:blue;">**MirrorAll**</mark>" button.

### Behavior and Gait Options

Before exporting action frames, select the "**Behavior**/**Gait**" options in the "[**Skill Editor**](#skill-editor)" area as "<mark style="color:blue;">**Behavior**</mark>". After clicking the "[<mark style="color:blue;">**Export**</mark>](#export-the-skill)" button, the program will run on the robot and automatically interpolate between these action frames to make the robot move smoothly. All action frames will execute for only one round.

If the "<mark style="color:blue;">**Gait**</mark>" option is selected before you click the "[<mark style="color:blue;">**Export**</mark>](#export-the-skill)" button, the robot will continue to execute in a loop, and each action frame will run at the fastest speed; **NO** interpolation between action frames will be added. The motion can be quite brutal. Therefore, it is recommended that beginners always use the "**Behavior**" option to develop new skills.

When importing some pre-built skill array, the desktop app will automatically select the "**Behavior**/**Gait**" option according to the data format. The frames will be loaded into the frame editor, and the robot will automatically move to the first frame's posture.

{% hint style="info" %}
After sending a command, the desktop app will wait for the robot to return a confirmation token. It may freeze if the robot's program halts or the connection is lost. You don't need to close the desktop app and lose the unsaved action frames but press the "**reset**" button on the robot's main board to break the app's waiting loop. If the program still does not respond, you can click a posture button in the "[**Preset Postures**](#preset-postures)" area or try to reconnect the robot using the "Connect/Listening" button.
{% endhint %}

### Simultaneous Control of Multiple Robots

The desktop app supports connecting multiple robots via their own USB data cables or via [Bluetooth ](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard)to achieve simultaneous control. The desktop app can only recognize a serial port as a robot.&#x20;

{% hint style="info" %}
For the robot with NyBoard:

* [USB data cable](https://guide.petoi.com/communication-modules/usb-downloader-ch340c#connect-nyboard)\
  Connect the USB uploader to the robot's mainboard, then connect the data cable to the computer's USB port.
* [Bluetooth](https://guide.petoi.com/communication-modules/dual-mode-bluetooth#connection-with-nyboard)\
  Plug the Bluetooth module into the robot's mainboard, then pair it with the computer's Bluetooth settings interface.&#x20;
  {% endhint %}

So after the robot is powered on normally, the desktop app will keep detecting if there is a new serial port connection. When multiple serial ports are successfully connected, the serial port option button in the "[**State Dials**](#connection-and-state-dials)" area will change to "<mark style="color:blue;">**All**</mark>." Click the drop-down list to view all serial ports that have been successfully connected. All robots will be synchronized in real-time in this way. You can also select any one of the serial ports to control the corresponding robot.&#x20;

If you unplug a USB serial port on the computer (or disconnect the Bluetooth module in the Bluetooth setting interface), the corresponding serial port will be removed from the drop-down list in real-time.

If you unplug all USB serial ports (disconnect all Bluetooth modules), the serial port option button displays "**None**," and the left button displays "<mark style="color:yellow;">**Listening**</mark>." The desktop app still automatically detects whether there is a serial port connection. When a robot is reconnected to the computer through the serial port, the button on the left side of the drop-down menu will display "<mark style="color:green;">**Connected**</mark>." The corresponding serial port name is displayed in the serial port option button.

If you want the desktop app to stop detecting serial connections, click the "<mark style="color:green;">**Connected**</mark>" / "<mark style="color:yellow;">**Listening**</mark>" button. The text in the button will change to "<mark style="color:red;">**Connect**</mark>," and all serial connections will be disconnected. Click the "<mark style="color:red;">**Connect**</mark>" button again to restart the real-time detection function.

## Professional extensions

You can modify the source code of the Skill Composer in **OpenCat/pyUI/SkillComposer.py**.&#x20;

## Teach by pulling the legs using the feedback servo

{% hint style="warning" %}
This function requires the servos after March 2024, the BiBoard, and the latest firmware.&#x20;
{% endhint %}

We have added the position feedback feature to recent batches of Petoi servos. The servo can reply to a specific PWM pulse (3500µs) with its current position in the form of pulse length. The central controller (BiBoard) can convert the signal to angles for more interaction.

{% embed url="<https://youtu.be/vlHBf_dN4R0>" %}

First, [send the robot a serial command](https://guide.petoi.com/arduino-ide/serial-monitor#set-up-in-the-arduino-ide) "**fl**" to start the learning process. In the demo, it's triggered by our customized voice command. The robot's servo driver will switch to reading mode. Joint jigs can occur during this transition. Organize the robot's legs and then hold it still. Learning begins when no significant movements are detected.

Pull the legs, and the movement will be recorded. Stopping in the middle is okay because identical postures will be skipped. The recording will stop if the maximum frame is reached or if the robot's joints remain stationary for 2 seconds.

The recorded command can be replayed by typing "**fr**". The skill data is also printed to the screen, allowing you to save it and import it into the Skill Composer or other OpenCat interfaces.

The control logic is defined in **OpenCatEsp32/src/reaction.h** and **motion.h**.


# Tools

From the desktop app version **1.2.1**, the Petoi Desktop App includes a new module: **Tools**. This module provides convenient tools to fix your robot's frequent problems.&#x20;

<figure><img src="/files/9H11VrUWgmVvULuTcD1S" alt=""><figcaption></figcaption></figure>

## Reset voice module <a href="#download-the-latest-version-of-the-petoi-desktop-app" id="download-the-latest-version-of-the-petoi-desktop-app"></a>

It is used to reset the [voice command module](https://guide.petoi.com/extensible-modules/voice-command-module), simplifying its [debugging process](https://guide.petoi.com/extensible-modules/voice-command-module#how-to-debug-if-the-voice-command-doesnt-work).  If the voice module does not respond to your voice, you can use this tool to reset it. It's pretty simple to use: click the **Reset voice module** button.

<figure><img src="/files/K5BT0zg61pnYk911sxII" alt=""><figcaption></figcaption></figure>

Please follow the instructions in the message box.&#x20;

<figure><img src="/files/d6uJBBIu4n5Y4lrtR6Kd" alt=""><figcaption></figcaption></figure>

If the problem persists, please email <support@petoi.com>.

## Calibrate gyroscope

{% hint style="info" %}
From the desktop app version **1.2.4**, the interface has added this new function.
{% endhint %}

It is used to calibrate the gyroscope sensor on the mainboard. If you notice that the robot cannot maintain balance while performing skill movements (such as sitting down) and its body keeps shaking, you need to recalibrate the gyroscope. To calibrate the gyroscope, click the **Calibrate gyroscope** button.

<figure><img src="/files/nPiZL3EettB9GlNynmvq" alt=""><figcaption></figcaption></figure>

Follow the instructions in the message box:

<figure><img src="/files/oK9OXmO0clF6DxNY73Zo" alt=""><figcaption></figcaption></figure>

If the problem persists, please email <support@petoi.com>.

## The Serial monitor

From the desktop app version **1.2.7**, we added the serial monitor feature in this interface.

If the robot and computer are already connected via a USB Type-C cable, the program will automatically enable serial communication after the interface opens. You can then directly enter serial commands in the ***serial command input box*** and press the **Enter** key on your keyboard or click the **Send** button to send the serial commands to the robot.

<figure><img src="/files/aHqWIcppwjKp8MU3WbCU" alt=""><figcaption></figcaption></figure>

If you encounter any problems, you can click the **Copy** button below to copy all the information in the output box, or you can select part of the relevant information in the output box with your mouse and then click the **Copy** button to copy the selected information. Paste the copied the information into your email and send it to support.petoi.com for assistance.


# Petoi Coding Blocks

How to use the extension library specially developed for the Petoi robot in Mind+

## Prepare Mind+

* Download the latest version from the [Mind+ official website](https://mindplus.cc/download-en.html)
  * For Windows: Mind+ version **>= V1.7.0**
  * For macO&#x53;**:** Mind+ version **>= V1.7.3 RC2.0**

{% hint style="warning" %}
If you cannot download the software from Mind+'s official website, you can download a stable version from [the Google Drive folder](https://drive.google.com/drive/folders/1V9WSnNiEOKZznP05W_RPxUD0TqAFFK7T). However, we strongly recommend that you download and use the official latest version.
{% endhint %}

{% hint style="info" %}
**For macOS only:** If you have already installed the old Mind+ version (**<=**&#x56;1.7.2 RC3.0), we recommend that:

1. You uninstall it first
2. Delete this folder /Users/\[vour username]/Documents/mindplus-pv/environment/Python3.6.5.64/ib/python3.6/site-packages/
3. Download and install the latest version of **Mind+**.
   {% endhint %}

* After the installation is complete, you can open Mind+

{% hint style="info" %}
If the default installation language is Chinese, you can switch to **English** as follows:

<img src="/files/y8C9aqhcfz6ItOCnwh25" alt="" data-size="original">
{% endhint %}

## Watch the video tutorials

We provide [a series of video tutorials](https://www.youtube.com/playlist?list=PLHMFXft_rV6POrzm8O12Nybdy1-FS1ymg) on using Petoi Coding Blocks with [the free Scratch-like robotics coding curriculum](https://www.petoi.com/pages/free-quadruped-robotics-curriculum-scratch-coding).   Be sure to click next to go through all the videos.

{% embed url="<https://www.youtube.com/playlist?list=PLHMFXft_rV6POrzm8O12Nybdy1-FS1ymg>" %}

## Prepare Petoi Robot

Please follow the instructions in the subpages to prepare according to the robot's mainboard.

For BiBoard products, such as [**Bittle X**](https://bittle-x.petoi.com/) ([BiBoard V0](https://guide.petoi.com/biboard/biboard-v0)), **Bittle X V2** ([BiBoard V1](https://guide.petoi.com/biboard/biboard-v1-guide)),  **Bittle X+Arm** (BiBoard V1), and **Nybble Q**(BiBoard V1), no software modification is required. By default, all functional blocks in Mind+ are supported.&#x20;

#### Plug the battery socket into the BiBoard, install it in the chassis, and long-press the battery button to power on the robot.

### Connection method

* Wired connection: The kit includes a **USB Type-C data cable** connecting the robot's mainboard to the computer.
* Wireless connection (Bluetooth): The mainboard's [**built-in Bluetooth**](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard) module allows you to connect the robot's mainboard to the computer wirelessly.

## Import Petoi Mind+ extension library

<figure><img src="/files/o27cet8NjxztUuFEzXWi" alt=""><figcaption></figcaption></figure>

Paste the GitHub URL(<https://github.com/PetoiCamp/Petoi_MindPlusLib>) in the text box of the import interface:

<figure><img src="/files/MFD3xnGLRViJZQJzpK10" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/gG9DcmsJsKnHEtxXh3sG" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
For macOS (if the Mind+ version **<= V1.7.2 RC3.0**), you need to download [PetoiRobot.zip](https://github.com/PetoiCamp/Petoi_MindPlusLib/raw/main/PetoiRobot.zip) and copy the extracted folder (PetoiRobot) to /Users/{your username}/Documents/mindplus-py/environment/Python3.6.5-64/lib/python3.6/site-packages/

![](/files/AZu2HURU7HI2m7vqwC2M)
{% endhint %}

{% hint style="info" %}
You can also download the latest extension library file (***\*.mpext***) from the [GitHub repository](https://github.com/PetoiCamp/Petoi_MindPlusLib/tree/main). And then import it  as follows:

![](/files/bwMseGKJ9q0AYBNtK24X)

![](/files/jtuV53VTfGH5H4Z4Whtc)
{% endhint %}

## Programming and Running

<figure><img src="/files/Vvv2cFA7C2IapMsyP6zY" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Petoi Coding Blocks is a user-extended library of Mind+.&#x20;

If you open **Mind+** by double-clicking the icon![](/files/92YALGSXvECxpZe0MY4r), it will not automatically load this extension library, and you need to re-import it manually every time you open the app.&#x20;

If you open Mind+ by double-clicking the code file(suffix **mp** or **sb3**) that uses this extension library or load these code files after opening Mind+, Mind+ will automatically load this extension library.
{% endhint %}

## The principle and process

This extension library can control the robot without compiling and uploading the code to the robot's main board. Click the "Run" button directly to run the program on the Python level and send instructions to the robot's serial port. If you need to stop the program while running, you can click the "Stop" button anytime. The process of the program can be divided into three steps:

1. &#x20;Open the serial port
2. &#x20;Control the robot
3. &#x20;Close the serial port

## The instructions for blocks

### Open the serial port

There are two ways to open the serial port:

* Automatically identify and open the serial port\
  ![](/files/hSINs1yNcWlGsf0u4q7n)
* Enter the name of the serial port to open the serial port\
  ![](/files/S1iOlfySZBn7om16Mdku)

{% hint style="info" %}
If it fails to open the serial port, you can refer to the printed information in the terminal window to replace the name of the serial port:

![](/files/i0bQFkVv43dnbccZ6361)
{% endhint %}

### Perform built-in skills

<div align="left"><figure><img src="/files/7jKeQh2wGwuFwgDAkCLb" alt=""><figcaption></figcaption></figure></div>

Use this block to let the robot perform skills pre-built on the robot's main board. Skills from "**sit**" to "**zero**" are **postures** (containing only one action frame).  Skills from "**boxing**" to "**sniff**" are **behaviors** (containing multiple posture frames and are performed only once).  Skills from "**stepping**" to "**trotRight**" are **gaits** (containing multiple posture frames, and are repeated in periodical loops until stopped).&#x20;

After finishing the current block's task, the program will wait a short time (delay xx seconds) before moving to the next block.&#x20;

### Perform the last skill exported from the Skill Composer

<div align="left"><figure><img src="/files/QZ1G3oIJaRp0PrfyTotm" alt=""><figcaption></figcaption></figure></div>

Use this block to let the robot perform the last skill exported from the [Skill Composer](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-desktop-app/skill-composer#export-the-skill).&#x20;

{% hint style="info" %}
It is equivalent to inputting the serial command 'T' in the [serial monitor](https://guide.petoi.com/arduino-ide/serial-monitor) and then delaying the preset time.
{% endhint %}

### Perform the skill in the file

<div align="left"><figure><img src="/files/N3EGVSD6wBrTkR0YWFCD" alt=""><figcaption></figcaption></figure></div>

Use this block to let the robot perform the skill in the skill files, which are in the following directory:

* **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}

The folder name **{model}** is Bittle or Nybble. When [exporting](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-desktop-app/skill-composer#export-the-skill) a skill file from the **Skill Composer**, it will automatically save the skill file to this directory.

{% hint style="info" %}
Tips: You can also copy & paste the [SkillLibrary](https://github.com/PetoiCamp/OpenCat/tree/main/SkillLibrary) folder from the source code of the OpenCat project on GitHub to the ***.config/Petoi*** directory. Therefore, you can use some sample skills for your Mind+ program, and there is no need to use the export function in the Skill Composer.

![](/files/lIGPo06pBWsggE5hDgwn)
{% endhint %}

{% hint style="info" %}
The folder **.config** is a hidden directory on MacOS/Linux but can be visited in the terminal or through a specific view setting:

* MacOS\
  open the directory /Users/{username} in Finder, then press the “**Command**” + “**Shift**” + “**.**” (period) keys at the same time.<br>

  <figure><img src="/files/Vr4Q0OJZtyFDYhoeCJ9L" alt=""><figcaption></figcaption></figure>

{% endhint %}

### Rotate joints in a sequence.

<div align="left"><figure><img src="/files/l3eF6NwhpeuazKTPEglh" alt=""><figcaption></figcaption></figure></div>

Use this block to control one joint or multiple joints to rotate in sequence. There are several ways to use the blocks for reference:

* Controls individual joint rotations to an absolute angle value.<br>

  <figure><img src="/files/xSXiZEeFCJfTYwtkw0KV" alt=""><figcaption></figcaption></figure>
* Controls individual joint rotations to a relative angle value.<br>

  <figure><img src="/files/yAUrkV4FKyn1Vl0KgfTM" alt=""><figcaption></figcaption></figure>
* Control multiple joints to rotate sequentially to **absolute** angle values or **relative** angle values.<br>

  <figure><img src="/files/G9fc47tePSrHTivPlfKq" alt=""><figcaption></figcaption></figure>
* Use the joint angle list to control multiple joints to rotate to absolute angle values in a sequence.<br>

  <div align="left"><figure><img src="/files/KZDShPYUizPcrOsFR8pd" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}

* <img src="/files/j5rjUZf7qLCmZdG0KBEH" alt="" data-size="original">, <img src="/files/9b6l2VUoNHYuxEhfffBz" alt="" data-size="original">represents a list consisting of a [joint index](https://app.gitbook.com/o/-M-_eWZUjFA4usjshHcZ/s/-MQ6a951Q6Jn1Zzt5Ajr-887967055/~/changes/285/petoi-robot-joint-index) and an angle value. For example, \[Head panning to 30 degrees] represents the list \[0, 30].
* <img src="/files/FyKxGaW0vddwqdYXceTc" alt="" data-size="original">\
  It consists of one or more pairs of[ joint index](https://app.gitbook.com/o/-M-_eWZUjFA4usjshHcZ/s/-MQ6a951Q6Jn1Zzt5Ajr-887967055/~/changes/285/petoi-robot-joint-index) + angle value, and the specific format is as follows: \
  \[joint index, angle value, joint index, angle value...]
  {% endhint %}

### Rotate joints simultaneously&#x20;

<div align="left"><figure><img src="/files/nCFY0sIXcipRPkDrjeRW" alt=""><figcaption></figcaption></figure></div>

Using this block can control multiple joints to rotate at the same time. There are several ways to use the blocks for reference:

* Control multiple joints to rotate to absolute angle values or relative angle values at the same time<br>

  <figure><img src="/files/soKQzuS4ylvcdCHG4L0R" alt=""><figcaption></figcaption></figure>
* Use the joint angle list to control the simultaneous rotation of multiple joints to absolute angle values.<br>

  <div align="left"><figure><img src="/files/Vh2XMoCWbfZ7yWfafXdX" alt=""><figcaption></figcaption></figure></div>

### Get the current angle value of a joint.

<div align="left"><figure><img src="/files/Brc9uT3zfvELerhTX5mN" alt=""><figcaption></figcaption></figure></div>

Use this block to get the current angle value of the selected joint. It is recommended to assign it to a variable first and then use the variable and algorithm to control other joints to rotate.

{% hint style="info" %}
The return value of this block is only an angle value, which cannot be filled in the "Turn sequentially" and "'Turn simultaneously" blocks alone.
{% endhint %}

#### Demo code

<figure><img src="/files/YZuJo0R5UyAWjq4Ea42T" alt=""><figcaption></figcaption></figure>

{% file src="/files/dTxtuiDyT9RbbPkwqO4S" %}

### Transform to frame

<div align="left"><figure><img src="/files/hRZwOu0SW2rvJtJSCgbI" alt=""><figcaption></figcaption></figure></div>

Use this block to control all joints to rotate at the same time. Please use it with the "**Action frame**" block. As shown below:

<div align="left"><figure><img src="/files/9JGREsuYLcSu0SolRpyD" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
The "Action frame" block represents a list of 16 angle values. Each angle value corresponds to the absolute angle value to which the corresponding [joint index](https://app.gitbook.com/o/-M-_eWZUjFA4usjshHcZ/s/-MQ6a951Q6Jn1Zzt5Ajr-887967055/~/changes/285/petoi-robot-joint-index) servo rotates.
{% endhint %}

### Play a melody

![](/files/NqKpHKy7twOf1TuiguBg)

Use this block to control the robot to play music. There are several ways to use  blocks together for reference:

* A list made up of multiple "Tone + Duration" blocks<br>

  <div align="left"><figure><img src="/files/gOG2tmvrP0Xn1zS331B4" alt=""><figcaption></figcaption></figure></div>
* Using a tone duration list<br>

  <div align="left"><figure><img src="/files/3NUr3wQkTxyhf3Qrwd6D" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
![](/files/7KMmq9wgWd8om7CeTaO3)

Consists of one or more pairs of Tone + Duration, the specific format is as follows:

\[tone, duration, tone, duration, tone, duration...]
{% endhint %}

### Execute a serial command

<div align="left"><figure><img src="/files/sPOyyF6TzwjUHvSLaStM" alt=""><figcaption></figcaption></figure></div>

Use this block to send a serial command to the robot, which can provide you with more and more flexible control methods. For example, you can input "**kkcL**" (kick the left front leg), and "**khiR**" (raise the right front leg to say hello). For more serial port commands, please refer to [the serial protocol](https://guide.petoi.com/apis/serial-protocol).&#x20;

### Write analog value

<div align="left"><figure><img src="/files/MqRx61qOySKFFMj7szCw" alt=""><figcaption></figcaption></figure></div>

Use this block to write an analog value to a specified pin. Analog value range: 0\~255

### Read analog value

![](/files/PlKNs3jjcUo0R2kf1M78)

Use this block to read an analog value from a specified pin.

### Write digital value

![](/files/HfD7apmmfLmGvZORMmaG)

Use this block to write a high/low-level value to the specified pin. High-level: 1; Low-level: 0.

### Read digital value

![](/files/WpiPm0lFfejX3m1gjTAA)

Use this block to read the high/low-level value of the specified pin.

### Read Ultrasonic sensor distance

<div align="left"><figure><img src="/files/l6XlAPafftMxUdjVJztQ" alt=""><figcaption></figcaption></figure></div>

Use this block to read the distance value from the ultrasonic sensor.

For the [Petoi RGB Ultrasonic Sensor](https://guide.petoi.com/extensible-modules/ultrasonic-sensor) (or **RUS-04**), you can set the two pins ( Trigger and Echo) like this:

* **NyBoard** (connects to the D6 and D7 pins)<br>

  <div align="left"><figure><img src="/files/Jc2cIVpIGzq7HzwkMLKq" alt=""><figcaption></figcaption></figure></div>
* **BiBoard** (connects to the Rx and Tx pins)<br>

  <div align="left"><figure><img src="/files/Jf90Y6ovj7a9NmRH1eAg" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
For other ultrasonic sensor models (e.g., **HC-SR04** connects to the D6 and D7 pins), you can set the two pins like this:

<img src="/files/wo5NE5VbCl2g8ZYjK0Gr" alt="" data-size="original">
{% endhint %}

#### Demo code

You can download the demo code from the [GitHub repository](https://github.com/PetoiCamp/Petoi_MindPlusLib/tree/main).

* BiBoard\
  examples/BiBoard/avoidObs\_BiBoard.mp
* NyBoard\
  examples/NyBoard/avoidObs\_NyBoard.mp

### Read the target coordinates

<div align="left"><figure><img src="/files/rJOcAU7G0ZR7OLhR10AP" alt="" width="510"><figcaption></figcaption></figure></div>

Use this block to Read the coordinates of the identified target from the camera module([MU camera](/extensible-modules/mu-camera) / [Petoi AI Vision module](/extensible-modules/petoi-ai-vision-module)) which connect to the BiBoard.

#### Demo code

<figure><img src="/files/dUL12wp13goeVxGcAQjY" alt=""><figcaption></figcaption></figure>

You can download this test code ([**testCamera.mp**](https://github.com/PetoiCamp/Petoi_MindPlusLib/raw/refs/heads/main/examples/BiBoard/testCamera.mp)) and run in the Mind+.

### Close the serial port

![](/files/3CNpi9KxnwBBHuT5JaNg)

Generally, at the end of the program, it is recommended to use this block to close the serial port communication.

### Demos

We provide some demos to download for reference in the [GitHub repository](https://github.com/PetoiCamp/Petoi_MindPlusLib) (Petoi\_MindPlusLib/examples).

<figure><img src="/files/T75f4JrnKdj4EfQevufc" alt=""><figcaption></figcaption></figure>

### You may adapt [the free block coding curriculum for Bittle X](https://drive.google.com/drive/folders/1OU5LT47dbgWb5Av9Z4Qurq1GKlZyxNeD) for Nybble Q


# Python coding mode in Mind+

## Switch to the Python coding mode

If you are familiar with the Petoi coding blocks and Python language, you can change to the **Code** mode in Mind+ as follows:

<figure><img src="/files/kDOa6QNU6XJGxyDruHbK" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/kUYqfTeFxjfa4RGYMc9M" alt=""><figcaption></figcaption></figure>

The **Code** mode is a Python 3 development environment. You can write any Python script in it and call all the PetoiRobot library APIs imported by Mind+.&#x20;

You can find the PetoiRobot library in the following directory. There are all the [definitions of API interfaces](/apis/python-api#available-apis) in the **robot.py**

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

Here is a sample code :

```python
# The code starts here
from PetoiRobot import *    # must import the PetoiRobot library

# enter the code below
# auto connect serial ports
autoConnect()

# call the APIs to control the Petoi robot
sendSkillStr('ksit', 0.5)
sendCmdStr('T', 0.5)
loadSkill("skillFileName", 0.2)

# close the serial port
closePort()
```

You can also copy the code in the **Auto-Generate** area in the **Blocks** mode and then paste it into the code file in the **Code** mode. Then you can edit and run the code.


# Install Mind+ on Chromebook

## Configure the Linux environment

You need to [**turn on Linux**](/technical-support/set-up-development-environment-on-chromebook) on the Chromebook to access the Linux environment via the terminal app.

Then, follow the following steps to install Mind+.

## Check the processor architecture

Use the following command to check the processor architecture in the terminal:\
***`uname -m`***\
The output will be similar to "i686", "x86\_64" or "armv7":\
i686 (or similar) - 32-bit Intel/AMD processor (common in older computers).\
x86\_64 (or similar) - 64-bit Intel/AMD processors (modern laptops, desktops, and most Chromebooks).\
armv7 (or higher) - ARM processor. (Mobile phones, tablets, 2nd and 3rd generation Raspberry Pis running Ubuntu Mate, and some Chromebooks. Most are 32-bit now)<br>

## Download package

According to different architectures to download different versions:<https://mindplus.dfrobot.com/linux><br>

## Installation

Use the following command in the terminal to install it (Replace **\*\*\*\*\*** with the file name of the installation package):\
***`sudo dpkg -i *****.deb`***\
***`sudo apt-get -f install`***

After installed, you can start the **Mind+** app in the Chromebook launcher:

<figure><img src="/files/pA5kAwIdHsOfQZobDZjp" alt=""><figcaption></figcaption></figure>

## Run Mind+

Now, you can proceed to the [Mind+ tutorial](https://guide.petoi.com/product/bittle-x-v2/control-and-programming/petoi-coding-blocks).

{% hint style="warning" %}
Currently, connection via Bluetooth is not supported.&#x20;
{% endhint %}


# Arduino IDE

This chapter is for Advanced users with programming experience.

## 1. Download and Install

Please follow [the instructions](https://docs.arduino.cc/software/ide-v2/tutorials/getting-started/ide-v2-downloading-and-installing/).

For installation on Chromebook, please check [this guide](/product/bittle-x-v2+arm/control-and-program/arduino-ide/install-arduino-ide-on-chromebook).

## 2. Set up BiBoard&#x20;

For the specific parameters of each functional module of BiBoard, please refer to：

* [BiBoard V1 Guide](https://guide.petoi.com/biboard/biboard-v1-guide)
* [BiBoard V0 Guide](https://guide.petoi.com/biboard/biboard-v0)

### 2.1 Prepare the ESP32 development environment

Open “**Preferences**” in Arduino IDE, add ESP32 development board URL:

`https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json`

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FBeD6sfV1LKR8HOsRvvef%252Fimage.png%3Falt%3Dmedia%26token%3D469f106e-c18c-4e7e-9e36-cac3ea9cdda5&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=75d0ba4e&#x26;sv=2" alt=""><figcaption></figcaption></figure>

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252Fm4kA0SnO0HlaNRggKhTV%252Fimage.png%3Falt%3Dmedia%26token%3D7b4d2178-dc79-402e-886e-bccd277bd1e8&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=f8cdc92a&#x26;sv=2" alt=""><figcaption></figcaption></figure>

Click **OK** to save it and then exit.

Open “**Boards Manager...**” and wait for updates from external board support links. Search “esp32” and install the support package.

{% hint style="warning" %}
Please install the latest available version **2.0.12**. Installing version 2.0.13 and above may cause the motherboard to fail to startup.
{% endhint %}

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FkaI7GwGmYWxJLTksqswt%252Fimage.png%3Falt%3Dmedia%26token%3Ddda85ff5-f77c-4636-ae1d-1c4c49ef6618&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=d474360&#x26;sv=2" alt=""><figcaption></figcaption></figure>

<figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252Fymh9lMUwgWJEB2eHT2kv%252Fimage.png%3Falt%3Dmedia%26token%3D509f781c-fbbe-47e4-91ec-48e57d7eba8b&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=e4d6c4ea&#x26;sv=2" alt=""><figcaption></figcaption></figure>

After showing “**INSTALLED**”, the BiBoard board support package is finished.

### 2.2 Modify the code file in the package

* #### sdkconfig.h

{% hint style="info" %}

* For Windows:\
  C:\Users\\{username}\AppData\Local\Arduino15\packages\esp32\hardware\esp32\2.0.\*\tools\sdk\esp32\qio\_qspi\include\sdkconfig.h
* For Mac:\
  /Users/{username}/Library/Arduino15/packages/esp32/hardware/esp32/2.0.\*/tools/sdk/esp32/qio\_qspi/include/sdkconfig.h
* For Ubuntu:\
  Arduino root directory/.arduino15 (hidden file)/packages/esp32/hardware/esp32/2.0.12/tools/sdk/esp32/qio\_qspi/include/sdkconfig.h
  {% endhint %}

Append a line of code at the end of the file:

```cpp
#define CONFIG_DISABLE_HAL_LOCKS 1
```

### 2.3 Set up the board options

Please set up the board's upload speed, CPU frequency, etc, as shown in the picture below.&#x20;

There is a setting for the **Flash Size** and **Partition Scheme** among the options. For more information, refer to the next section.&#x20;

<figure><img src="/files/wzC46EwxIGDjVcKwEaSw" alt=""><figcaption></figcaption></figure>

### 2.4 Choose hardware partition

The **BiBoard V0** uses an ESP32 with a **16M** flash. To simplify, you can use the **default** **4 MB** partition map without a problem. There's plenty of programming space for the standard OpenCatEsp32 firmware.&#x20;

The **BiBoard V1** uses an ESP32 with a **4M** flash.

#### 4 MB partition

You can use the **Minimal SPIFFS (1.9MB APP with OTA/190KB SPIFFS)**. You can also use other partition schemes under the 4 MB flash limit, such as "No OTA" or "Huge APP".&#x20;

<figure><img src="/files/ZD0w7RMRATD8ehzC757t" alt=""><figcaption></figcaption></figure>

#### 16 MB partition

Suppose you want to fully utilize the 16 MB flash on **BiBoard V0** (it's unnecessary and takes longer to upload). You can read the user manual for the [Add hardware partition configuration option in Arduino IDE](https://guide.petoi.com/biboard/demo-applications/13.add-hardware-partition-configuration-option-in-arduino-ide).

### 2.5 Download the source code & install the library

{% hint style="info" %}
We keep updating the code as an open-source project. You can star-mark and follow our GitHub repository to get the newest features and bug fixes. You can also share your codes with worldwide OpenCatEsp32 users.&#x20;

You can check the update history information in the [**ChangeLog.md**](https://github.com/PetoiCamp/OpenCatEsp32/blob/main/ChangeLog.md)**.**
{% endhint %}

1. Download the ​OpenCatEsp32 repository from GitHub repository: <https://github.com/PetoiCamp/OpenCatEsp32>\
   We suggest you utilize GitHub’s version control feature. Otherwise, make sure you download the **WHOLE OpenCatEsp32 FOLDER** every time. All the codes have to be the same version to work together.&#x20;

<figure><img src="/files/J1dPxUacMfknKagtEw03" alt=""><figcaption></figcaption></figure>

2. If you download the Zip file of the codes, you will get an **OpenCatEsp32-main** folder after unzipping. Please rename it to **OpenCatEsp32** before opening the **OpenCatEsp32.ino** so that the two names match.&#x20;

{% hint style="warning" %}
No matter where you save the folder, the file structure should be:

![](/files/it5Ae2o7Ot6JhN9Hi28A)&#x20;
{% endhint %}

There are several **test\*\*\*.ino** codes in the **ModuleTests** folder. You can upload them separately to test specific modules (I recommend using **testBuzzer.ino** as your first test sketch).

3. Install the libraries
   * Download and install the [MU Vision Sensor library](https://github.com/mu-opensource/MuVisionSensor3) into the Arduino IDE.<br>

     <figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FrwlwHLV03mwtrtqVazop%252FmuLib.png%3Falt%3Dmedia%26token%3Df7721966-efb2-4388-9563-002c9aa93c3a&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=852f24b1&#x26;sv=2" alt=""><figcaption></figcaption></figure>

     <figure><img src="https://docs.petoi.com/~gitbook/image?url=https%3A%2F%2F1565080149-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-MQ6a951Q6Jn1Zzt5Ajr-887967055%252Fuploads%252FRN0NyFXOV0ct9IOI0AqU%252FaddZipLib.png%3Falt%3Dmedia%26token%3D4803980c-41cf-406c-907c-3aaff81672ec&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=13cd3321&#x26;sv=2" alt=""><figcaption></figcaption></figure>

   * Install **ArduinoJson** in the Library Manager<br>

     <figure><img src="/files/IRiCEQUFLCVMECjd86bg" alt=""><figcaption></figcaption></figure>

     <figure><img src="/files/chUPMWLsfRiaSkCfylgo" alt=""><figcaption></figcaption></figure>

   * Install **WebSockets** in the Library Manager.<br>

     <figure><img src="/files/kDERHzH9sG2PSYjnqK2e" alt=""><figcaption></figcaption></figure>

### 2.6 [Connect to BiBoard](/quick-reference/upload-firmware#biboard) via USB type-C data cable

Set the serial port in the Arduino IDE:

<figure><img src="/files/i0UrTG4kz2OUwWUj58mb" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you cannot find the serial port after connecting to your computer:

* for BiBoard V0:

  You need to install [the driver](https://guide.petoi.com/technical-support/useful-tools/biboard-v1) for the CP210x chip.&#x20;
* For BiBoard V1:

  You need to install the driver as below:

  * Windows: <https://www.wch-ic.com/downloads/CH343SER_EXE.html>
  * Mac: <https://www.wch-ic.com/downloads/CH34XSER_MAC_ZIP.html>
* If the battery powers on the BiBoard, please long-press the button on the battery >=3s to power off the BiBoard, so that the BiBoard is only powered through the USB cable and only the blue LED is lit up.&#x20;
  {% endhint %}

### 2.7 Compile and upload the sketch

For Bittle or Bittle X:

<pre class="language-cpp"><code class="lang-cpp">#define BITTLE    //Petoi 9 DOF robot dog, also for Bittle X
<strong>//#define NYBBLE  //Petoi 11 DOF robot cat, also for Nybble Q
</strong>//#define CUB
</code></pre>

For Nybble or Nybble Q:

<pre class="language-cpp"><code class="lang-cpp">//#define BITTLE    //Petoi 9 DOF robot dog, also for Bittle X
<strong>#define NYBBLE  //Petoi 11 DOF robot cat, also for Nybble Q
</strong>//#define CUB
</code></pre>

Modify the mainboard model macro definition in OpenCatEsp3&#x32;**.ino** according to the mainboard (BiBoard) version.

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

If the robot(**Bittle X+Arm**) has the robotic arm, you should also activate the macro definition as follows:

<pre class="language-cpp"><code class="lang-cpp"><strong>#define ROBOT_ARM                 // for attaching the head clip arm
</strong></code></pre>

Otherwise, please comment out this line of code.

After the modification is completed, you can click the **Upload** button (as below) to upload the sketch **OpenCatEsp32.ino**, and the changes in the code file will be automatically saved.

<figure><img src="/files/tdpRznaQQrpxXC9osxpY" alt=""><figcaption></figcaption></figure>

### 2.8 Program Initialization

If the **version date** of the currently uploaded sketch is **newer** than the version date of the mainboard firmware, it will automatically enter the **Initialization Startup Mode** after the sketch upload is completed.

{% hint style="warning" %}
Please click the **Serial Monitor** button to open it and set the configuration parameters to **115200** baud rate and **No line ending**.
{% endhint %}

<figure><img src="/files/glEjFxmuYkPy8rRP367h" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/FR7Ns4IvrqMetC1dz3oR" alt=""><figcaption></figcaption></figure>

* You can check the version date of the currently uploaded sketch in the source code file (OpenCatEsp32/src/OpenCat.h):\
  `#define DATE "250218"  // YYMMDD`
* You can send the serial command "**?**" in the serial monitor to check the version date of the mainboard firmware:\
  ![](/files/cjbt1P99Ydx1pEjpJh8m)

When the mainboard is powered on, open the serial monitor and you will see the startup information:

```
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
```

{% hint style="info" %}
If you do not see the startup information after opening the serial monitor, please short press the **Reset** button on the mainboard.
{% endhint %}

Next you will see the following prompt questions:

```cpp
Reset the joints' calibration offsets? (Y/n): 
```

* Send '**Y**' to the question, which means resetting all servo corrections to zero.
* &#x20;Send "**n**" to skip this step.

{% hint style="info" %}
If you want to keep the previous joint calibration data, please send '**n**'.
{% endhint %}

```cpp
- Calibrate the Inertial Measurement Unit (IMU)? (Y/n): 
```

* Send '**Y**' to the question, which means calibrating the IMU, i.e. the gyro/accelerometer sensor.
* &#x20;Send "**n**" to skip this step.

{% hint style="info" %}
If you want to keep the previous IMU calibration data, please send '**n**'.
{% endhint %}

{% hint style="warning" %}
Halts at the connection stage. To restart it, you can close and reopen the serial monitor or press the reset button on BiBoard. Put the BiBoard **FLAT** on the table, and don't touch it during calibration.

Sometimes, the program halts at the connection stage. To restart it, you can close and reopen the serial monitor or press the reset button on BiBoard.&#x20;

The program starts calibration after playing the melody 6 times.
{% endhint %}

```
Run factory quality assurance program? (Y/n)        
```

Input '**n**' and press **Enter** to continue. Or you can do nothing, it will Auto skip in 5 seconds.

The details of serial port printing information are as follows：

```cpp
* 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

```

When the string "<mark style="color:green;">**Ready!**</mark>" is output in the serial monitor, the program will enter the **regular startup mode**.

Every time the mainboard is powered on, it compares the BIRTHMARK in the EEPROM to determine whether the program has been initialized. If the program has already been initialized, it will **not enter** the **initialization startup mode** again.

{% hint style="info" %}
**Note:** When the mainboard is powered on, the music melodies played in the **Regular Startup Mode** and the **initialization startup mode** are entirely different. This is convenient for users (no need to open the serial monitor) and can also identify the startup mode.&#x20;

If you need to clear the calibration parameters of the servo and recalibrate the joint servo, or recalibrate the IMU, you can send the serial command "<mark style="color:red;">**!**</mark>" in the serial monitor, and the program will **re-enter** the **Initialization Startup Mode**.
{% endhint %}

### 2.9 Switch working mode via the serial commands (Optional)

The default code runs the **Standard** mode (including the **Voice command** function). If you want to switch modes, Please open the serial monitor and send the following serial commands:

<table><thead><tr><th width="172">Serial command</th><th>Function</th></tr></thead><tbody><tr><td>XA</td><td>Voice. For <strong>BiBoard V0</strong>, the switch on the extension hat should be dialed to the <strong>Voice command</strong> side （<strong>default mode</strong>）</td></tr><tr><td>XU</td><td>Ultrasonic. For <strong>BiBoard V0</strong>, the switch on the extension hat should be dialed to the <strong>UART2</strong> side; voice control will not work.</td></tr><tr><td>XC</td><td>Camera</td></tr><tr><td>XL</td><td>Light</td></tr><tr><td>XT</td><td>Touch</td></tr><tr><td>XI</td><td>PIR</td></tr><tr><td>XG</td><td>Gesture</td></tr><tr><td>XD</td><td>IR distance</td></tr><tr><td>XQ</td><td>Quick demo</td></tr><tr><td>XS</td><td>Enable the Serial 2(Tx2, Rx2). For <strong>BiBoard V0</strong>, the switch on the extension hat should be dialed to the <strong>Uart2</strong> side; voice control will not work. </td></tr><tr><td>XB</td><td>Enable the back touch funtion. </td></tr><tr><td>X</td><td>Disable all the module functions above.</td></tr><tr><td>z</td><td>RandomMind (On/Off)</td></tr></tbody></table>

{% hint style="info" %}
The behavior of the official modules is defined in separate header files in **OpenCat/src/**. You can find them in **OpenCat/src/io.h** **-> readSignal()**. The behavior of **Quick demo** mode is defined in **OpenCat/OpenCat.ino ->  quickDemo()**. You can study the example code to write your functions.&#x20;

You can learn about the function of each module through the [**EXTENSIBLE MODULES**](https://guide.petoi.com/extensible-modules/introduction).
{% endhint %}

### 2.10 Power on

* Long-press the battery button and boot up the robot with one side up. It will enter the calibration state automatically in the **regular startup mode**. The picture below shows the head, the upper and lower legs installed after the robot enters the calibration state.

![](/files/mzq2t0vK9IyMU6MU2LJG)

Please refer to [Chapter 5 🔌 Connect Wires](https://bittle.petoi.com/5-connect-wires) and [Chapter 6 📐 Calibration](https://bittle.petoi.com/6-calibration) for the complete calibration process.

* If you power on the robot and it is upright (with its back facing up), it will start in the "rest" posture (fold the legs and unlock the servos) in the **regular startup mode**.

### 3. Configuration with App

The BiBoard has built-in Bluetooth, and you can connect it to the [mobile app](https://guide.petoi.com/mobile-app/introduction) for [joint calibration](https://guide.petoi.com/mobile-app/calibrator) and [remote control](https://guide.petoi.com/mobile-app/controller) (for **Bittle X**, which has the mainboard **BiBoard V0**).


# Serial Monitor

## Mainboard connection

* Wired Connection: The kit includes a **USB Type-C data cable** connecting the robot's mainboard to the computer.
* [Wireless Connection(Bluetooth)](https://guide.petoi.com/quick-reference/bluetooth-connection/biboard): The mainboard's built-in Bluetooth module lets you connect the robot's mainboard to your computer wirelessly.

## Set up in the Arduino IDE

1. Select the port in the [Arduino IDE](https://www.arduino.cc/en/software)(recommended version **1.8.19**).

![](/files/HzLGPoEbbiAkP6ySVyut)

{% hint style="info" %}
If you can't determine which port is correct, unplug and re-plug the USB data cable on the computer side and check the difference in the ***Tools*** menu.

You may install the [drivers](https://guide.petoi.com/technical-support/useful-tools) if no new port is shown in the menu list.
{% endhint %}

2. Open the serial monitor.

You can choose the "Serial Monitor" in the ***Tools*** menu bar or click the ![](/files/rFegvOusKIAfaewQ5pHB) Button to open the serial monitor window:

![](/files/3qVD0VPFEtSelxddsD66) ![](/files/NfoeNDc4SxSFe0pPUCuq)

3. Configure the parameters of the serial monitor.

In the serial monitor, set "***No line ending***" and the baud rate to ***115200***.&#x20;

![](/files/HqQm5fVMgFHfBfpSG7WR)

With the USB adapter / Bluetooth module connecting NyBoard and computer, you have the ultimate interface - **Serial Monitor** to communicate with NyBoard and change every byte on it(via sending the serial commands based on the [serial protocol](https://guide.petoi.com/apis/serial-protocol)).


# Calibrate the joints with Arduino IDE

## Prepare to Enter the Calibration State

Please refer to the [preparation section](https://guide.petoi.com/quick-reference/joint-calibration#prepare-to-enter-the-calibration-state) in the Joint Calibration.

## The rationale for calibration

### Understand the zero state and the coordinate system

After sending the serial command ‘**c**’ in the serial monitor,  the robot will [enter the calibration state](#enter-the-calibration-state), with all servos rotated to their zero angles, attach the head, tail, and legs prepared in the previous section to the body. They are generally perpendicular to their linked body frames.

#### Nybble Q's Calibration State

![Nybble's Calibration State](/files/AiBp5uskBjNIOASP0BI3)

Install the servo-related components according to the picture above and try to ensure that they are perpendicular to each other (the upper leg is perpendicular to the torso, and the lower leg is perpendicular to the upper leg).&#x20;

{% hint style="warning" %}
Note: Insert the servo-related components directly into the servo output shaft; do not turn the output shaft during this process.
{% endhint %}

Rotating the limbs counterclockwise from their zero states will be positive (the same as in polar coordinates). Viewed from the left side of the robot's body, the counter-clockwise rotation of the joint is defined as the positive direction.

{% hint style="info" %}
The only exception is the head tilt angle for Nybble. It’s more natural to say head up, while it’s the result of rotating clockwise.&#x20;
{% endhint %}

{% hint style="info" %}
However, from the right side of the robot's body, the rotation directions' positive and negative are just opposite.
{% endhint %}

### Discrete angular intervals

If we look closer at the servo shaft, we can see it has a certain number of teeth. That’s for attaching the servo arms and avoiding sliding in the rotational direction. In our servo sample, the gears divide 360 degrees into 25 sectors, each taking **14.4** degrees(offset of -7.2\~7.2 degrees). That means we cannot always get a perfect perpendicular installation.&#x20;

![](/files/v400iIvlmpXjiobnloRS)

## Calibration process

### Enter the calibration state

You must double-check the position and direction of all servos.&#x20;

&#x20;Send the serial command ‘**c**’ in the serial monitor to enter the calibration mode.  Depending on their initial shaft direction, some may travel larger angles until stopping at the middle point.  There will be noise coming from the gear system of the servos. You will see a calibration table like the following:

![](/files/hd4pjWyGSWw4VOVwbSh1)

The first row is the joint indexes; the second row is their calibration offsets:&#x20;

| **Index**  | 0  | 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8  | 9  | 10 | 11 | 12 | 13 | 14 | 15 |
| ---------- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
| **Offset** | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 |

Initial values are “-1” or “0” and should be changed by later calibration.&#x20;

{% hint style="info" %}
The servos use a potentiometer in the feedback loop for position control. When held at a static position, they tend to vibrate around the target angle. A Parkinson 's-like vibration will develop after a short period of use. It won’t affect much during continuous motion. Better servos without these troubles could cost 10 times more, so replacing a failed unit is a more cost-effective solution. &#x20;
{% endhint %}

### Attach body parts to the servos

For the installation for different product, please refer to the subpage of [**Joint Calibrator**](https://guide.petoi.com/desktop-app/joint-calibrator) as abov&#x65;**.**

### Fine-tune the calibration using the serial monitor

#### 1. Joint Control Commands

The command for fine-tuning calibration (refer to the [serial protocol](https://guide.petoi.com/apis/serial-protocol)) is formatted as `cIndex Offset`. Notice that there’s a space between cIndex and Offset.&#x20;

<figure><img src="/files/S9oO78PDcrTkmXr1IDwW" alt=""><figcaption><p>Nybble joint index</p></figcaption></figure>

For example :

* `c8 6` This means giving the 8th servo an offset of 6 degrees.&#x20;
* `c0 -4` This means giving the 0th servo(the head) an offset of -4 degrees.&#x20;

{% hint style="warning" %}
The resolution of the correction amount is 1 degree; do not use decimals.
{% endhint %}

{% hint style="info" %}
If you find the absolute value of offset is more significant than 9, you are not attaching the limb closest to its zero states. That will decrease the servo's reachable range on either side. Please take off the limb and rotate it by one tooth. It will result in an opposite but smaller offset.&#x20;
{% endhint %}

{% hint style="info" %}
For example, if you have to use -9 as the calibration value, remove the limb, rotate it by one tooth, and then attach it back. The new calibration value should be around 5, i.e., the sum of their absolute values is 14. Avoid rotating the servo shaft during this adjustment.&#x20;
{% endhint %}

Find the best offset that can bring the limb to the zero states.  It's a process of trial and error.

{% hint style="info" %}
For the robotic arm, you can use the serial command "**c-2**" to [auto-calibrate](https://docs.petoi.com/extensible-modules/robot-arm#fine-calibration) the robotic claw joint.
{% endhint %}

After calibration, **remember to type ‘s’ to save the offsets**. Otherwise, they will be forgotten when exiting the calibration state. You can even save every time after you’re done with one servo.&#x20;

#### 2. Use ‘L’ shaped joint tuner

When watching something, one's observations will change from different perspectives. When measuring length, one always wants to read directly above a referencing ruler.&#x20;

You must keep a parallel perspective when calibrating the robot. Use the 'L'-shaped joint tuner as a parallel reference to avoid reading errors. Align the tips on the tuner with the center of the screws in the shoulder and knee joints and the little hole on the tip of the foot. Look along the co-axis of the centers. For each leg, calibrate the shoulder servos (index 8\~11) first, then the knee servos(index 12\~15). When calibrating the knee, use the matching triangle windows on both the tuner and shank to ensure parallel alignment.&#x20;

Please use the L-shaped calibration tool included in the package as a calibration reference. According to the joint numbers shown in the picture within the calibration interface, click and drag the corresponding joint sliders or click on the blank areas of the slider tracks to fine-tune the joints to a right angle.

Please note that when calibrating the servos, adjust the upper leg first, then change the lower leg.

![](/files/HXHygTlSauC6GsdgjoHb)

{% hint style="info" %}
If the offset exceeds ±9 degrees, you must remove the corresponding leg and reinstall it by rotating one tooth and then dragging the corresponding slider. For example, if it is adjusted to +9 and still not correct, remove the corresponding leg and shift it one tooth when reattaching it. Then, you should get a smaller offset in the opposite direction.&#x20;
{% endhint %}

#### 3. Testing and validation

<figure><img src="/files/bO4A4lw1w3nU5DipkcNG" alt=""><figcaption><p>Nybble</p></figcaption></figure>

After calibration, send the serial commands: ‘**d**’, ‘**kup**’,  and '**kwkF**' to validate the calibration. This will result in the robot symmetrically moving its limbs between the rest, stand states, and walk gait. &#x20;

{% hint style="warning" %}
You may need to do a few rounds of calibrations to achieve optimal states.
{% endhint %}

#### 4. Center of mass

Try to understand how the robot keeps its balance even during walking. If you add new components to the robot, distribute its weight symmetrically about the spine. You may also need to slide the battery holder back and forth to find the best balance spot. Because the battery is heavier at the front, you can insert it in the opposite direction to shift the center of mass farther back.&#x20;

{% hint style="info" %}
You may need to recalibrate if the center of mass changes.&#x20;
{% endhint %}

Please do not force the robot to lift heavy objects, as this may cause the servos to sweep or get stuck.


# Install Arduino IDE on Chromebook

After [**turning on Linux**](/technical-support/set-up-development-environment-on-chromebook) on the Chromebook, you can access the Linux environment via the terminal app.

Please follow the following steps to install the Arduino IDE:

## Check the type of your OS version

<figure><img src="/files/Fy6jFs5A2deqjAWB6ec3" alt=""><figcaption></figcaption></figure>

## Download package

Open the website ([www.arduino.cc/en/software](https://www.arduino.cc/en/software)) and download the corresponding type of Legacy Arduino IDE:

<figure><img src="/files/qZTrJYJpye9JkGlmAy6q" alt=""><figcaption></figcaption></figure>

## Installation

After downloading complete, set the folder ***Downloads*** in the file browser to share with Linux, as mentioned above. Use the following commands to install the **Arduino IDE,** e.g., ***arduino-1.8.19-linux64.tar.xz*** is the downloading file.

```
cd /mnt/chromeos/MyFiles/Downloads/
sudo apt-get install xz-utils
sudo tar -C /opt -xf arduino-1.8.19-linux64.tar.xz
cd /opt
ls
cd arduino-1.8.19/
ls
sudo ./install.sh
```

## Set up the Arduino IDE development environment for the mainboard

You can open the **Arduino IDE** as follows:

<figure><img src="/files/Ek7txzYIkbwUxU8CPp47" alt=""><figcaption></figcaption></figure>

After using the USB data cable to connect the BiBoard and Chromebook, you will see a prompt: Please click ***Connect to Linux*****.**

<figure><img src="/files/Nt2E99Bos1ByKfFL8C23" alt=""><figcaption></figcaption></figure>

and check in the **Settings** interface, and it should be enabled as follows:

<figure><img src="/files/0JzLQ0XvA2qDbjdWiG3M" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/CpjbjAH0VsYoCQZdZkeH" alt=""><figcaption></figcaption></figure>

Use the following commands to install the library pyserial for uploading the sketch for BiBoard

```
sudo apt install python3 pip
python3 -V
pip -V
cd /usr/lib/python3.11/
sudo rm EXTERNALLY-MANAGED
sudo pip3 install pyserial
pip list
```

{% hint style="info" %}
After downloading the project file **OpenCatEsp32-main.zip** from GitHub: <https://github.com/PetoiCamp/OpenCatEsp32>, use the following commands to unzip it to the ***Downloads*** folder.

<pre><code><strong>cd /mnt/chromeos/MyFiles/Downloads/
</strong>sudo apt-get install unzip
unzip OpenCatEsp32-main.zip
</code></pre>

{% endhint %}

For how to upload the sketch, please refer to [Upload Sketch for BiBoard](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard).


# Quaddle (Under construction)

## Getting Started

Quaddle is an open-source robotics kit for makers, hackers & STEAM educators. Learn robotics, coding, AI, and 3D printing on one desk robot — then personalize its looks, tricks, and AI persona to make it yours.

<figure><img src="/files/ABo7veTILphrbeeFmVvL" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/shOVy2DC4tC6Y5ikNivk" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
All three product models support controller operation.
{% endhint %}

<figure><img src="/files/RROFdubmuXsQDrcsBKHd" alt=""><figcaption></figcaption></figure>

The small but mighty Quaddle has these fantastic features:

* World's first 4-servo omnidirectional robot dog. Fast running, gliding, sideways motion, and crisp in-place spins—all with just four servos. Less complexity. More possibilities.
* Learn & replay your tricks. Physically guide Quaddle through any movement — no code or app needed. Just tap to record and replay via its feedback servos.
* Support **Petoi** **Coding Blocks(block-based Scratch-like), C++, and Python**.
* **Free** [C++](https://www.petoi.com/pages/free-cplusplus-quadruped-robotics-curriculum) and [Petoi Coding Blocks](https://www.petoi.com/pages/free-quadruped-robotics-curriculum-scratch-coding)(block-based Scratch-like) **curricula**.
* Equipped with a **Motion core** board (AI core board on Buddy/Scout), a high-performance **ESP32S3** development board supporting additional modules for robotics/AI conversation/IoT applications.

If you have questions about ***why*** or ***how***, please post on [our forum](https://www.reddit.com/r/Petoi) or [contact us](https://www.petoi.com/pages/contact-us).

There are some [supporting applications, software](https://docs.petoi.com/technical-support/supporting-application-and-software), and [FAQs](https://docs.petoi.com/technical-support/faq-frequently-asked-questions) for your reference.

You can support us by shopping at [Petoi Coding Robot Shop](https://www.petoi.com/store). Our social media (Instagram/Twitter/Facebook/GitHub) account is **@PetoiCamp**. Share your build by tagging **#quaddle #petoi #opencat** so we can repost it for you!

{% hint style="info" %}
Last Updated: 05/08/2026
{% endhint %}


# Quick Start Guide

The **Quick Start Guide** section is primarily designed to help you verify that the product is complete upon receipt and to enable you to quickly boot up and use the robot. It includes three parts:&#x20;

1. [**Unboxing**](/product/quaddle-under-construction/quick-start-guide/unboxing)
2. [**Boot up**](/product/quaddle-under-construction/quick-start-guide/boot-up)
3. [**Assembling (for debugging or DIY)**](/product/quaddle-under-construction/quick-start-guide/assembling)

**Need help?** Check out our [**FAQ**](/faq-frequently-asked-questions).


# Unboxing

## Check the Package

Thank you very much for purchasing our product! We highly value your user experience and hope you will enjoy this delightful journey. To ensure the device was not damaged during transportation and verify all accessories are complete, we recommend following these steps after receiving the package:

1. Verify the recipient's name, address, order number, and other details on the product packaging to confirm they match your order. If any information is incorrect, please do not open the box and contact the logistics provider or us immediately.
2. Inspect the shipping box for integrity. Check for apparent damage, moisture, deformation, or signs of tampering. If packaging damage is found, please photograph it for documentation purposes and avoid accepting, signing for, or opening the package before confirming the device's condition. As shown in the example below, your Quaddle should arrive fully intact, clean, and well-presented, without any damage.

## Unboxing

### Builder

{% hint style="info" %}
This model does not include an AI core board or sensor modules.
{% endhint %}

{包装盒图片} ，{开箱时形态图片}

配件清单

### Buddy

{% hint style="info" %}
This model has an AI core board but lacks a sensor module.
{% endhint %}

{包装盒图片} ，{开箱时形态图片}

配件清单

### Scout

{% hint style="info" %}
This model features both an AI core motherboard and a sensor module.
{% endhint %}

{包装盒图片} ，{开箱时形态图片}

配件清单

#### Assemble the sensor module on Scout

{组装动画}

## Installing and removing the battery

### Installling

{演示动画}

### Removing

{演示动画}

## Assemble the Quaddle Stand

{安装步骤图}


# Boot up

## Pre-Startup Posture

To prevent the servos from getting stuck, please position the robot's legs correctly before powering it on.

{上电启动前姿势图片}

## Usage Scenario

First, test it on the Quaddle stand and use it on a stable table or floor only after you have familiarized yourself with its operation.

{Quaddle架在支架上的图片}

{% hint style="warning" %}
When using it on a table, keep it within your arm's reach to prevent it from falling and avoid damage.
{% endhint %}

## Power on / Power off

### Power on

When the battery is sufficiently charged and properly installed, simply press the power button on the bottom of the robot briefly to turn it on.

{展示电源按钮图片}

{% hint style="info" %}
You can also power on the robot without the battery installed by connecting a USB Type-C cable between the robot's rear USB port and a computer's USB port; this method is typically used for program debugging.\
{使用USB数据线连接机器人与电脑，为机器人上电图片}
{% endhint %}

### Power off

Quickly **press** the power button on the bottom of the robot **twice** to turn it off.

## Information displayed on the screen upon startup

{显示屏显示画面图片}

Associated explanatory text

## Charging the battery

When the battery level is low, you can charge the robot by connecting it to a computer via a USB Type-C cable. During charging, the current progress (displayed as a real-time percentage) appears on the front display screen, and the four LEDs at the bottom of the robot flash sequentially. Once fully charged, the display shows 100%, and all four LEDs remain steadily lit.

{充电状态下的图片}

{充电完成时的图片}

{% hint style="info" %}
You can also charge the battery using a dedicated battery charging dock (专用充电盒参数).

{电池专用充电盒图片}
{% endhint %}

### Exiting charging mode

If you want to wake up the robot while it is charging, you can exit charging mode in the following ways:

* If the robot is equipped with an **AI Core** mainboard, you can exit charging mode by touching the "**F**" button on the back panel (for approximately 0.5 seconds) in response to the screen prompt ("Tap F to wake").
* If the robot is not equipped with an AI Core mainboard, you can exit charging mode by flipping the robot's body over (rotating it 180 degrees).

## Back panel button functions

If the robot is equipped with an **AI Core** mainboard, there are four function buttons (**F, R, B, L**) on the back of the robot; their functions are listed in the table below:

### Basic Operations

<table><thead><tr><th width="147.5999755859375">Operation</th><th>How to Use</th></tr></thead><tbody><tr><td>Single tap</td><td>Briefly touch the button once and release it. The command runs after a delay of approximately 0.55 seconds.</td></tr><tr><td>Double tap</td><td>Briefly touch the same button twice, with no more than 0.55 seconds between consecutive taps.</td></tr><tr><td>Triple tap</td><td>Briefly touch the same button three times, with no more than 0.55 seconds between consecutive taps. The command runs immediately after the third release.</td></tr><tr><td>Long press</td><td>Touch and hold the button for at least 0.75 seconds. The command runs as soon as the threshold is reached, and releasing the button does not trigger a single-tap command.</td></tr><tr><td>Touch feedback</td><td>The robot beeps whenever it recognizes a new button press.</td></tr></tbody></table>

### Button Functions

<table><thead><tr><th width="106.5999755859375">Button</th><th>Single Tap</th><th>Double Tap</th><th>Triple Tap</th><th>Long Press</th></tr></thead><tbody><tr><td><strong>F</strong></td><td><strong>Forward/backward motion sequence:</strong> walk forward for 5 cycles → trot forward for 5 cycles → walk backward for 8 cycles.</td><td><strong>Drag-to-learn:</strong> enters motion-recording mode, allowing you to create a motion by manually moving the joints.</td><td><strong>Automatic servo calibration:</strong> starts the automatic calibration procedure for all joints.</td><td><strong>Crawl forward</strong> for 8 cycles.</td></tr><tr><td><strong>R</strong></td><td><strong>Right-turn sequence:</strong> pivot right by 180° → walking right turn by 45° → trotting right turn by 45° → lean sideways to the right for 3 seconds → stand.</td><td><strong>Replay learned motion:</strong> replays the most recently recorded drag-to-learn motion.</td><td><strong>Stair-climbing motion:</strong> runs the <code>qStep</code> stair-climbing sequence and returns to the standing posture.</td><td><strong>Crawl right</strong> by 45°.</td></tr><tr><td><strong>L</strong></td><td><strong>Left-turn sequence:</strong> pivot left by 180° → walking left turn by 45° → trotting left turn by 45° → lean sideways to the left for 3 seconds → stand.</td><td><strong>Servo-follow mode:</strong> releases the servos and makes other joints follow when the associated joints are moved manually.</td><td><strong>Three-legged motion:</strong> assumes the left preparation posture, then moves forward without using the right rear leg, with a parameter of 5000 ms.</td><td><strong>Crawl left</strong> by 45°.</td></tr><tr><td><strong>B</strong></td><td><strong>Jump-and-slide sequence:</strong> jump-slide → slide for 3 seconds → walk backward for 5 cycles.</td><td><strong>Buddy configuration:</strong> alternates between the <code>hds</code> and <code>hi</code> greeting motions.<br><strong>Scout configuration:</strong> cycles through the environmental-interaction modules listed below.</td><td><strong>Dance:</strong> runs the <code>qDance</code> dance sequence.</td><td><strong>Buddy configuration:</strong> performs a backflip followed by a recovery roll.<br><strong>Scout configuration:</strong> raises its rear for 0.5 seconds and then returns to the standing posture.</td></tr></tbody></table>

### Scout Back-Button Double-Tap Module Cycle

Each double tap of the Back button switches to the next environmental-interaction module. Only the selected module remains active at a time.

<table><thead><tr><th width="78.60003662109375">Step</th><th width="135.5999755859375">Module Code</th><th>Function</th></tr></thead><tbody><tr><td>1</td><td><code>XL</code></td><td>Dual light sensors / light-following mode</td></tr><tr><td>2</td><td><code>XD</code></td><td>Dual infrared distance sensors / obstacle-avoidance mode</td></tr><tr><td>3</td><td><code>XG</code></td><td>Gesture-sensor mode</td></tr><tr><td>4</td><td><code>XM</code></td><td>Dual-microphone sound-source localization mode</td></tr><tr><td>5</td><td>All off</td><td>Disables all the environmental-interaction modules listed above. The next double tap restarts the cycle at <code>XL</code>.</td></tr></tbody></table>

### Controls in Special Modes

<table><thead><tr><th width="221">Situation</th><th width="223.7999267578125">Button</th><th>Function</th></tr></thead><tbody><tr><td>During drag-to-learn recording</td><td>Briefly touch Left</td><td>Records the current key pose and uses it as the starting point of a new motion segment.</td></tr><tr><td>During drag-to-learn recording</td><td>Briefly touch Right</td><td>Ends recording and retains the learned motion. Double-tap Right afterward to replay it.</td></tr><tr><td>While automatic servo calibration is waiting for confirmation</td><td>Briefly touch Front</td><td>Confirms and continues calibration.</td></tr><tr><td>While automatic servo calibration is waiting for confirmation</td><td>Briefly touch Left, Right, or Back</td><td>Cancels the current automatic calibration procedure.</td></tr><tr><td>On the USB-charging sleep screen</td><td>Press Front</td><td>Wakes the robot. This touch is consumed as a wake command and does not run the Front single-tap walking sequence.</td></tr></tbody></table>

### Notes and Safety Information

<table><thead><tr><th width="226.800048828125">Item</th><th>Description</th></tr></thead><tbody><tr><td>Multi-tap timing</td><td>If the interval between taps exceeds approximately 0.55 seconds, the next tap is treated as the start of a new tap sequence.</td></tr><tr><td>Touching during a motion</td><td>If a queued motion sequence is running, a new touch first stops the current motion. To start the newly selected function, wait for the robot to stabilize and perform the touch operation again.</td></tr><tr><td>Safe operating area</td><td>Some commands, including the Right triple-tap and Back long-press actions, involve large movements. Place the robot on a level, nonslip surface with no nearby obstacles or edges.</td></tr><tr><td>Automatic calibration</td><td>Before calibration, place the robot flat on a level table and follow the on-screen instructions. Do not touch or move the robot during calibration.</td></tr><tr><td>Module status</td><td>The four buttons do not respond if the back-touch module is disconnected, is not detected by the system, or has been disabled in the module settings.</td></tr></tbody></table>


# Assembling

{% hint style="info" %}
If you need to replace parts yourself or do some DIY design, you can refer to the contents of this section.
{% endhint %}

Using **Buddy** as an example, the components are displayed in the image below：

<figure><img src="/files/lNJvaaugzhRn6Qe3wopq" alt=""><figcaption></figcaption></figure>

### Assembly video

{Buddy 组装演示视频}

### Assembly example

<figure><img src="/files/GNQr9fFkbf89mFDMxOfQ" alt="LEGO-compatible body shell — snap on any brick to personalize the look."><figcaption><p>LEGO-compatible body shell — snap on any brick to personalize the look.</p></figcaption></figure>

<figure><img src="/files/PyqBkAc6q8zRpe51fanb" alt="Arduino/ESP32 module support"><figcaption><p>Arduino/ESP32 module support</p></figcaption></figure>

<figure><img src="/files/qtmSZRnK0F4XnRG8bRtu" alt="Raspberry Pi Zero &#x26; ROS-ready"><figcaption><p>Raspberry Pi Zero &#x26; ROS-ready</p></figcaption></figure>


# Control & Program

### Control

* [Controller](/product/quaddle-under-construction/control-and-program/controller)
* Mobile App

### Set up & Build Robotics Skill Visually

* Petoi Desktop App

### Programming

* Petoi Web Coding Blocks
* Petoi Coding Blocks
* Python
* C++ on Arduino IDE
* Play with feedback servos
* Sensor & module programming
  * Quaddle's  sensor programming
* Various application project demos(see the Applications section on the sidebar)
* Various APIs for advanced users(see the APIs section on the sidebar)

### Curricula

Here are [all the free Petoi curricula](https://bit.ly/petoicur) and [some curricula developed by our community](https://www.petoi.com/blogs/blog/tagged/showcase+curriculum).

Note that these curricula are developed for the Bittle robot family.  But most programming concepts apply to Quaddle.

### Video tutorials

* [Petoi Skill Composer](https://www.youtube.com/playlist?list=PLHMFXft_rV6MTs8HMxSOvRAQektoXtaMG)
* [Desktop block-based coding tutorial](https://www.youtube.com/playlist?list=PLHMFXft_rV6POrzm8O12Nybdy1-FS1ymg)
  * Note that some of the videos may have been developed by older Petoi robots.  So the setup may be different.  But the programming concept can still apply.&#x20;
* [Advanced tutorials](https://www.youtube.com/playlist?list=PLHMFXft_rV6MWNGyofDzRhpatxZuUZMdg)

### Project ideas

* Get inspired by [Petoi user projects](https://www.petoi.com/blogs/blog/tagged/showcase)
* Work on some [quadruped robotics competition projects and ideas](https://www.petoi.com/blogs/blog/robot-competitions-with-petoi)
  * Every fall, we host [Petoi robotics contests](https://www.petoi.com/blogs/blog/tagged/contest-winners). We'd love to see you!


# Controller

{Game controller operation demonstration video}

<figure><img src="/files/qmuUz5854vc1aJXckNwc" alt=""><figcaption></figcaption></figure>

## How to use

Quaddle is compatible with firmware-supported BM769, GamepadSpace-Q34B, and GamepadSpace-Q37 Bluetooth gamepads.

Before powering on the controller, please dial the mode switch on the back of the controller to the **D** position.

{Image of the mode switch on the back of the controller}

{% hint style="info" %}
The raw A/B and X/Y bits on the Q37 differ from those on the Q34B. The firmware automatically swaps them before mapping the controls to the physical labels printed on the gamepad. Users can therefore always follow the A, B, X, and Y labels shown on the gamepad itself.
{% endhint %}

### Connecting and Getting Started

{% stepper %}
{% step %}

### Power on

Press the **Home** button (![](/files/Mhtq49iMBW7UaCeJk3a5)) to turn on the controller and make it discoverable, then start the robot. At startup, the robot scans for a supported controller for approximately 1 second. When one is found, the robot automatically enters **GamepadClient** mode and connects. Simultaneously, the controller will emit vibration feedback.
{% endstep %}

{% step %}

### Finishing control

Return the left stick to the center to stop any movement it initiated and restore the standing posture. Click the **Pair** button at the top of the controller to power it off. If the controller disconnects unexpectedly, the robot program also automatically sends the "**kup**" safe-standing command.
{% endstep %}
{% endstepper %}

{% hint style="info" %}

### Note

**Wait for the gamepad to connect**

A previously saved gamepad is given priority when reconnecting. Once connected, the sticks and buttons can directly control the robot.

**No gamepad is found during startup**

Bluetooth enters mobile App Server mode. If the mobile app is not connected, briefly press the mainboard BOOT button to clear the old gamepad information, return to gamepad scanning, and pair the current gamepad.

**How to connect to the other gamepad**&#x20;

When the robot successfully connects to a controller for the first time, it saves the controller information. Upon the next power-up, it will connect only to the controller that was saved via Bluetooth and will not connect to other controllers. If you are sure you want to connect to another controller in this case, without connecting to the mobile app, first press the **Home** button on the new controller to power it on, and then briefly press the **Boot** button on the side of the robot. This will clear the previously saved controller Bluetooth information and then establish a Bluetooth connection with the new controller.
{% endhint %}

{% hint style="warning" %}
Holding the **Boot** button on the side of the robot for 2 seconds clears Wi-Fi configuration; it is not a gamepad-pairing operation.&#x20;

If the mobile app is connected, briefly pressing **Boot** on the side of the robot will **not** interrupt the app session (just clear the previously saved controller Bluetooth information) or switch to gamepad mode.
{% endhint %}

### Basic Functions

The image below shows all the function joysticks and buttons, and their functions after individual movement, long press, or click:

<figure><img src="/files/UxACZ9tfeWlubu3F9h68" alt=""><figcaption></figcaption></figure>

### Combination button functions

The image below shows the functions when you simultaneously press a button on the controller, move a joystick, or press a steering wheel button.

<figure><img src="/files/7dAe9ttLXQjW5wfKokLq" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="123">Control</th><th>Operation</th><th>Function</th><th>Command/Notes</th></tr></thead><tbody><tr><td>Left stick</td><td>Move in any direction without holding a modifier button</td><td>Make the robot walk forward, backward, sideways, or diagonally</td><td>Uses the eight-direction mapping shown below.</td></tr><tr><td>Left stick</td><td>Release and return to center</td><td>Stop the movement initiated by the left stick and restore the standing posture</td><td>Sends <code>kup</code> once only if a left-stick movement was actually executed earlier. Center jitter immediately after connecting does not trigger repeated commands.</td></tr><tr><td>Left stick</td><td>Hold A/B/X/Y/ZR (labeled R2 on some gamepads), then move the stick</td><td>Execute an action or special gait assigned to that modifier</td><td>The current version no longer distinguishes between “half-push” and “full-push.” Once the stick leaves the center dead zone, the combination for that direction is executed.</td></tr><tr><td>Left stick</td><td>Hold R1, then move the stick</td><td>Execute one of four special Quaddle movements</td><td>Forward: biped gait; backward: rear scoot; left: front scoot; right: glide posture.</td></tr><tr><td>Right stick</td><td>Move left or right</td><td>Turn the head and make the body lean sideways; the eyes move with it when the TFT eye interface is active</td><td>Continuously sends <code>Jr x y</code> control data. The horizontal output is limited by the input layer.</td></tr><tr><td>Right stick</td><td>Move up or down</td><td>Coordinate the front and rear legs to change body pitch/posture; the eyes move with it when the TFT eye interface is active</td><td>Returning the stick to center restores the head and related leg joints to the neutral position for this control.</td></tr></tbody></table>

#### 2.1 Eight-Direction Left-Stick Movement Without a Modifier

#### 2.2 R1 + Left Stick

| Combination                   | Function                   | Action ID     |
| ----------------------------- | -------------------------- | ------------- |
| Hold R1 + left stick forward  | Enter biped movement       | `qBiped`      |
| Hold R1 + left stick backward | Enter rear-scoot movement  | `qScoot`      |
| Hold R1 + left stick left     | Enter front-scoot movement | `qFrontScoot` |
| Hold R1 + left stick right    | Enter the glide posture    | `glide`       |

### 3. Individual Button Functions

Each ABXY button has an approximately 200 ms combination-detection window. Its individual function is executed after waiting approximately 200 ms, or immediately if the button is released sooner. If the left stick or D-pad is operated during this window, the combination action takes priority, preventing accidental execution of the individual button action.

| Button/Operation                    | Function                                         | Instructions                                                                                                                                                                              | Command                                                                  |
| ----------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| A individually                      | Handstand action                                 | Briefly press A without operating the left stick or D-pad at the same time.                                                                                                               | `khds`                                                                   |
| B individually                      | Enter the servo-calibration posture              | Briefly press B. This posture is used when attaching the legs or fine-tuning joint zero offsets; avoid triggering it accidentally during normal play.                                     | `c`                                                                      |
| X individually                      | Rest and disable the servos                      | Briefly press X. The robot enters its rest posture and releases the servos.                                                                                                               | `d`                                                                      |
| Y individually                      | Wave/greeting action                             | Briefly press Y.                                                                                                                                                                          | `khi`                                                                    |
| L1                                  | Glide posture                                    | Press once to trigger. Release it before triggering it again.                                                                                                                             | `kglide`                                                                 |
| R2                                  | Toggle posture balancing                         | Each press toggles gyroscope posture balancing once. Release it before toggling again.                                                                                                    | `g`, supplemented with `F/f` according to the current sampling precision |
| ZL short press (less than 1 second) | Direct step-climbing sequence                    | Release within 1 second. The step-climbing sequence starts from its second stage.                                                                                                         | `kqStepHalf`                                                             |
| ZL long press (at least 1 second)   | Full step-climbing sequence                      | Hold for approximately 1 second to trigger the full sequence. Releasing after the long-press action fires does not also trigger the short-press action.                                   | `kqStep`                                                                 |
| MINUS                               | Replay the most recent combination action        | If an A/B/X/Y/ZR + left-stick or D-pad combination has been executed, the most recent combination is forced to execute again. Otherwise, the most recent temporary skill data is invoked. | Most recent `k...` combination; `T` if none is recorded                  |
| PLUS short press                    | Stop recording, start playback, or stop playback | Its behavior depends on the current macro state. See “Macro Recording and Playback.”                                                                                                      | Internal macro control                                                   |
| PLUS long press (at least 1 second) | Start a new macro recording                      | Clears the previous macro and starts recording subsequent valid gamepad commands and their timing intervals.                                                                              | Internal macro control                                                   |
| O (Q34B/Q37)                        | Enable/disable IMU data updates                  | Each press alternates between stopping and resuming updates. The first press stops updates.                                                                                               | Alternates between `gu` and `gU`                                         |
| T (Q34B/Q37)                        | Invoke the most recent temporary skill data      | Press once to execute. It only has an effect if temporary skill data was previously sent through the serial port or app.                                                                  | `T`                                                                      |
| HOME                                | No robot-control function is currently assigned  | The firmware recognizes this button, but the current control layer does not execute a command for it.                                                                                     | None                                                                     |

> The BM769 right trigger is reported as R2 in firmware events, while the internal button-bit enum calls it `ZR`. ZR and R2 therefore refer to the same right trigger in this document. In the current code, pressing it first toggles R2 gyroscope balancing once. Continuing to use the left stick or D-pad while holding it also executes the corresponding combination action. O and T are additional face buttons on the Q34B/Q37 and are generally not present on the BM769.

### 4. D-Pad Functions

#### 4.1 Using the D-Pad by Itself

| D-Pad Direction | Function                                        | Details                                                                                                                                           | Command |
| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| Up              | Enable the dual-light-sensor module             | Switches to light detection/light-following. Availability depends on whether the hardware is installed and enabled in the current firmware build. | `XL`    |
| Left            | Enable the dual infrared distance-sensor module | Switches to dual infrared distance detection. Availability depends on the hardware configuration.                                                 | `XD`    |
| Right           | Enable the gesture-sensor module                | Switches to Grove I2C gesture recognition. Availability depends on the hardware configuration.                                                    | `XG`    |
| Down            | Enable the second Grove serial-port module      | Switches to the Grove UART2 module.                                                                                                               | `XS`    |

#### 4.2 Modifier Button + D-Pad Action Matrix

Recommended operating order: hold the modifier button first, then tap a D-pad direction. These D-pad combinations replace the “modifier + left-stick half-push” actions used in earlier versions.

| Held Modifier | D-Pad Up                 | D-Pad Left            | D-Pad Right                | D-Pad Down                      |
| ------------- | ------------------------ | --------------------- | -------------------------- | ------------------------------- |
| Y             | Trot forward `trF`       | Trot left `trL`       | Trot right `trR`           | `bdF` action                    |
| X             | Crawl forward `crF`      | Crawl left `crL`      | Crawl right `crR`          | Drag-walk forward `dragWkF`     |
| B             | Front flip `ff`          | Roll over `flipRoll`  | Jump and slide `jumpSlide` | Backflip `bf`                   |
| A             | Tiptoe forward `tiptoeF` | Move left `sideL`     | Move right `sideR`         | March in place/forward `marchF` |
| ZR/R2         | Tripod forward `triCatF` | Tripod left `triCatL` | Tripod right `triCatR`     | Circle action `circle2L`        |

### 5. Modifier Button + Left-Stick Action Matrix

Hold the modifier button first, then move the left stick in a primary direction. The current version has only a center dead zone and an active directional zone; there is no need to deliberately push the stick halfway or fully.

| Held Modifier | Left Stick Forward       | Left Stick Left              | Left Stick Right              | Left Stick Backward         |
| ------------- | ------------------------ | ---------------------------- | ----------------------------- | --------------------------- |
| Y             | Trot forward `trF`       | Trot left `trL`              | Trot right `trR`              | Slide `slide`               |
| X             | Crawl forward `crF`      | Crawl left `crL`             | Crawl right `crR`             | Drag-walk forward `dragWkF` |
| B             | Front flip `ff`          | Roll over `flipRoll`         | Jump and slide `jumpSlide`    | Backflip `bf`               |
| A             | Tiptoe forward `tiptoeF` | Turning movement left `vt2L` | Turning movement right `vt2R` | Pace forward `paceF`        |
| ZR/R2         | Tripod forward `triCatF` | Tripod left `triCatL`        | Tripod right `triCatR`        | Combined dance `qDance`     |

> If multiple modifier buttons are held simultaneously, the firmware uses this fixed priority: A > B > Y > X > ZR/R2. R1 + left stick is a separate override and takes priority over the face-button combinations above. Using a ZR/R2 combination also triggers the button's individual gyroscope-balancing toggle once.

### 6. Macro Recording and Playback

| Stage              | Gamepad Operation                                                            | Result                                                                                                                                 |
| ------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Start recording    | Hold PLUS for at least 1 second                                              | Clears the old macro and starts recording. The serial output displays `[MACRO] recording`.                                             |
| Record actions     | Operate the sticks and buttons normally                                      | Records up to 48 robot commands that were actually accepted, including the interval between adjacent commands.                         |
| Stop and save      | Briefly press PLUS                                                           | Stops recording and retains the macro in runtime memory. The serial output displays the number of saved steps.                         |
| Start playback     | Briefly press PLUS again                                                     | Plays from the first step using the recorded timing intervals.                                                                         |
| Interrupt playback | Briefly press PLUS during playback, or execute another valid gamepad command | Stops the current playback immediately.                                                                                                |
| Clear the macro    | Hold PLUS again, disconnect/re-pair, or restart                              | A long press clears the old macro and starts a new recording. Resetting the connection state or restarting clears the in-memory macro. |

### 7. Operating Precautions

| Scenario                                                               | Recommendation or Firmware Behavior                                                                                                                                             |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Performing rolls, jumps, handstands, step climbing, or similar actions | Place the robot on an open, level, nonslip surface, away from table edges, people, and fragile objects.                                                                         |
| Using button combinations                                              | Hold A/B/X/Y/ZR/R1 before moving the left stick or tapping the D-pad. Moving the stick first may initiate normal walking. Pressing ZR/R2 also toggles gyroscope balancing once. |
| Rapidly changing the left-stick direction                              | The firmware discards older unexecuted stick-movement states and retains the latest direction, reducing control lag.                                                            |
| Gamepad disconnects or is turned off                                   | The firmware clears pending gamepad commands and macro state, then queues `kup` for a safe standing posture. New input is required after reconnecting.                          |
| During Wi-Fi provisioning                                              | If a gamepad is connected, the firmware may disconnect it temporarily to avoid BLE/Wi-Fi coexistence congestion. It scans and reconnects automatically after provisioning.      |
| A D-pad module shortcut has no effect                                  | Check that the corresponding sensor module is installed, its build option is enabled, and its interface is connected correctly.                                                 |
| An action name is unavailable on a particular robot model              | The mapping sends the same action ID, but actual availability depends on the current robot model and its skill table.                                                           |


# Tuya AI

Quaddle's **AI core** board supports running Tuya-based AI conversation programs. Please follow these steps to authorize and activate your device:

{% stepper %}
{% step %}

### Download the tyutool

Please [download ](https://tuyaopen.ai/tyutool#download)and install the version of **tyutool** that corresponds to your current operating system.
{% endstep %}

{% step %}

### Authorize

After installation, connect the **AI ​​core** board to your computer using a **USB Type-C** data cable and complete the device authorization process as follows:

<figure><img src="/files/AL00E2rTwoVgd3UgFIwl" alt=""><figcaption></figcaption></figure>

Open the **Firmware tools** tab:

1. Select the **serial port device name** connected to the AI ​​core board.
2. Select the serial communication baud rate: **115200**
3. Select the chip platform: **ESP32-S3**
4. Select the option: **Authorize**
5. Input the provided **UUID** and **AuthKey**.
6. Click the **Start authorization** button.
   {% endstep %}

{% step %}

### Upload the firmware

You can connect the **AI ​​core** board to your computer using a **USB Type-C** data cable and upload the Tuya-based upgrade firmware as follows:

<figure><img src="/files/V6PBfWghHO4743sqcqQT" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/Lap56dpyBGTC7m8XiWwS" alt=""><figcaption></figcaption></figure>

1. Select the **serial port device name** connected to the AI ​​core board.
2. Select the serial communication baud rate: **460800**
3. Select the chip platform: **ESP32-S3**
4. Select the option: **Flash**
5. Click the Browse... button to open the file browser and select the **.bin** file containing "**QIO**" as shown in the image above.
6. Click the **Start flash** button.
   {% endstep %}
   {% endstepper %}


# Petoi robot joint index

We humans and many other legged animals have many joints. They give us the freedom to move in many ways. Though it's difficult to reproduce those complex motions on a robot, we can simplify all those joints to limited numbers of actuators.&#x20;

When controlling so many joints, the first thing is to index them. We can define an order according to their distance from the torso. For example, the shoulder joint is closer to the torso than the elbow joint, and the joint that let us look around is closer to the torso than the joint that let us nod. If we had tails, it would be as close as the head compared to the shoulder joints.&#x20;

So we can order the joints in this way: head panning, head tilting, tail panning, tail tilting, 4x shoulder (or hip) roll, 4x shoulder (or hip)  pitch, 4x elbows (or knees). For the joints in the same distance group, we can index them clockwise from the front-left corner if the body is looked at from behind.&#x20;

<figure><img src="/files/YcCWuNn1mYK9dIgl94c9" alt="" width="375"><figcaption></figcaption></figure>

## **Coordinate values and directions.**&#x20;

<figure><img src="/files/vwLmQGFpvfSeroTpUwTX" alt=""><figcaption></figcaption></figure>

The rotation angle range of the joint servo is between \[-125\~125]. For the leg servo, when viewed from the left side of the robot, when the leg rotates counterclockwise from the 0-degree position around the joint center point (the screw fixing position), the angle is a positive value; clockwise rotation, the angle is a negative value; viewed from the right side of the robot, the leg rotation angle is mirror-symmetrical to the left side (when rotating clockwise from the 0-degree position around the joint center point, the angle is a positive value; Rotate counterclockwise, the angle is negative). For the robot's neck servo, looking down from the top of the robot's head, when the neck rotates counterclockwise from the position of 0 degrees around the joint center point (the position where the screw is fixed), the angle is a positive value; when it rotates clockwise, the angle is a negative value.&#x20;

{% hint style="info" %}
For the Nybble head servo (No. 1 servo) observed on the right side of the robot, the head rotates counterclockwise from the 0-degree position around the joint center point (screw fixed position), and the angle is positive; when it rotates clockwise, the angle is negative.&#x20;

For the Nybble tail servo (No. 2 servo) facing the tail and looking down, the tail rotates counterclockwise from the 0-degree position around the center point (screw fixing position), and the angle is positive; when it rotates clockwise, the angle is negative.
{% endhint %}


# Joint Pins on BiBoard V1

&#x20;Although the BiBoard V1 has only 12 pins, the joint index numbers are configured in the same order as the NyBoard. The ordering for the joint servo pins on BiBoard V1 is like below:

<figure><img src="/files/6ylp0fw97uc1L6vVqt4A" alt=""><figcaption></figcaption></figure>


# Bittle X

<figure><img src="/files/parvvv9mSALj4nWqNRft" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
A servo plug has three wires. Plug it in the right direction or you may burn the chip. The color of wires may vary for different models. However, the darkest-colored (Black or Brown) wire (GND for ground) is always the GND wire as a convention. The GND wire should be plugged closest to the board.&#x20;
{% endhint %}

{% hint style="danger" %}
The index number of the joint servo has **no corresponding relationship** with the PWM pin number on the main board. **You don't even need to read the pin numbers on the PCB board.**&#x20;
{% endhint %}


# Bittle X+Arm

<figure><img src="/files/TiWGIxbc5wk9DdSYQdYx" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
A servo plug has three wires. Plug it in the right direction, or you may burn the chip. The color of the wires may vary across models. However, the darkest-colored wire (Black or Brown) is always the GND (ground) wire by convention. The GND wire should be plugged closest to the board.&#x20;
{% endhint %}

{% hint style="danger" %}
The index number of the joint servo has **no corresponding relationship** with the PWM pin number on the main board. **You don't even need to read the pin numbers on the PCB board.**&#x20;
{% endhint %}


# Nybble Q

<figure><img src="/files/tfDa6Y341SthUMNMhwTM" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
A servo plug has three wires. Plug it in the right direction or you may burn the chip. The color of wires may vary for different models. However, the darkest-colored (Black or Brown) wire (GND for ground) is always the GND wire as a convention. The GND wire should be plugged closest to the board.&#x20;
{% endhint %}

{% hint style="danger" %}
The index number of the joint servo has **no corresponding relationship** with the PWM pin number on the main board. **You don't even need to read the pin numbers on the PCB board.**&#x20;
{% endhint %}


# Joint Pins on BiBoard V0

&#x20;Although the BiBoard V0 has only 12 pins, the joint index numbers are configured in the same order as the NyBoard. The ordering for the joint servo pins on BiBoard V0 is like below:

<figure><img src="/files/NL9IOwOkdzlLBaQq9nhq" alt=""><figcaption></figcaption></figure>


# Bittle X

<figure><img src="/files/TADxsl8wHmABHuk5CNYu" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
A servo plug has three wires. Plug it in the right direction or you may burn the chip. The color of wires may vary for different models. However, the darkest-colored (Black or Brown) wire (GND for ground) is always the GND wire as a convention. The GND wire should be plugged closest to the board.&#x20;
{% endhint %}

{% hint style="danger" %}
The index number of the joint servo has **no corresponding relationship** with the PWM pin number on the main board. **You don't even need to read the pin numbers on the PCB board.**&#x20;
{% endhint %}


# Bittle X+Arm

<figure><img src="/files/6be3SYhSOI5Zk8YgseyF" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
A servo plug has three wires. Plug it in the right direction or you may burn the chip. The color of wires may vary for different models. However, the darkest-colored (Black or Brown) wire (GND for ground) is always the GND wire as a convention. The GND wire should be plugged closest to the board.&#x20;
{% endhint %}

{% hint style="danger" %}
The index number of the joint servo has **no corresponding relationship** with the PWM pin number on the main board. **You don't even need to read the pin numbers on the PCB board.**&#x20;
{% endhint %}


# Joint Pins on NyBoard

When we map those joints to a specific robot, the indexing becomes more practical. The ordering for the joint servo pins on NyBoard is like below:

<figure><img src="/files/amivRd7x32Cr8FCcfmis" alt=""><figcaption></figcaption></figure>


# Nybble

<figure><img src="/files/GpBjpbPSZiCMrAm2h952" alt=""><figcaption><p>Nybble</p></figcaption></figure>

{% hint style="danger" %}
A servo plug has three wires. Plug it in the right direction or you may burn the chip. The color of wires may vary for different models. However, the darkest-colored (Black or Brown) wire (GND for ground) is always the GND wire as a convention. The GND wire should be plugged closest to the board.&#x20;
{% endhint %}

{% hint style="danger" %}
The index number of the joint servo has **no corresponding relationship** with the PWM pin number on the main board. **You don't even need to read the pin numbers on the PCB board.**&#x20;
{% endhint %}


# Bittle

<figure><img src="/files/zXsWFU29J0FdgO0D904f" alt=""><figcaption><p>Bittle</p></figcaption></figure>

{% hint style="danger" %}
A servo plug has three wires. Plug it in the right direction or you may burn the chip. The color of wires may vary for different models. However, the darkest-colored (Black or Brown) wire (GND for ground) is always the GND wire as a convention. The GND wire should be plugged closest to the board.&#x20;
{% endhint %}

{% hint style="danger" %}
The index number of the joint servo has **no corresponding relationship** with the PWM pin number on the main board. **You don't even need to read the pin numbers on the PCB board.**&#x20;
{% endhint %}


# Bluetooth Connection

If you want to use [Joint Calibrator](https://guide.petoi.com/desktop-app/joint-calibrator), [Skill Composer](https://guide.petoi.com/desktop-app/skill-composer) in the Petoi Desktop App, or a coding block in [Mind+](https://guide.petoi.com/block-based-programming/petoi-coding-blocks) via computer Bluetooth, you need to pair the mainboard's Bluetooth with the computer first.


# BiBoard

## Connection steps

Power on the mainboard via the battery (plug in the battery to the mainboard, and long-press the battery button > 3 seconds); after powering on, the mainboard's <mark style="color:blue;">blue</mark> LED and <mark style="color:yellow;">yellow</mark> LED should be on.

### **Windows**

1. Open the Bluetooth & other devices  setting page, and turn on the Bluetooth button as follows:<br>

   <figure><img src="/files/8MZtWsB9dTUiyKDkM1JD" alt=""><figcaption></figcaption></figure>

2. Add the BiBoard Bluetooth for the first time as follows:<br>

   <figure><img src="/files/EMBjnz6BXCvRDGIqrESD" alt=""><figcaption></figcaption></figure>

   <figure><img src="/files/rDztNMN6GMrwwsZasM4G" alt=""><figcaption></figcaption></figure>

3. Select the one with the name <mark style="color:blue;">**Bittle\*\*\_SSP**</mark>:

<figure><img src="/files/2LBnqG19FCd010jlb2FI" alt=""><figcaption></figcaption></figure>

After paired successfully, it shows：

<figure><img src="/files/6RzyPljmoJIzhnYGYBLB" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
For **Windows 11**, after the initial Bluetooth pairing, the device might show “not connected” as follows. However, as long as the robot is not rebooted after the pairing, the associated COM port is still registered in the system. You can connect to the serial port within the Petoi application, such as the Desktop app and the Mind+.

<img src="/files/bjrePVb63RzI599B5gzB" alt="" data-size="original">
{% endhint %}

Check the **outgoing** serial port, which we will use later in the Mind+ or Petoi Desktop App in the **More Bluetooth options**:

<figure><img src="/files/F1nrQLCNbw0i57r0VHhz" alt=""><figcaption><p>More Bluetooth options</p></figcaption></figure>

<figure><img src="/files/83po78ykZFchNkU3lc6j" alt=""><figcaption><p>Bluetooth Settings</p></figcaption></figure>

### macOS

Open the system settings window, click the **Bluetooth** option, and enable the Bluetooth function. Find the Petoi robot device, e.g. "**Bittle\*\*\_SSP**", and click the **Connect** button.

<figure><img src="/files/PAq3wIM8jq51Wy3IT65t" alt=""><figcaption></figcaption></figure>

After the Petoi robot device is connected, it will be shown in the **My Devices** section, as follows:

<figure><img src="/files/LUh2wDWnYrPyaXNSdVsO" alt=""><figcaption></figcaption></figure>

## Test in Mind+

### Windows

<figure><img src="/files/YXoZprln9cvBUqzugyQX" alt=""><figcaption></figcaption></figure>

### macOS

<figure><img src="/files/2bF7jIuwAX5UfOj5UNCE" alt=""><figcaption></figcaption></figure>


# Upload Firmware

## Connect to the mainboard

You must use the USB data cable to do firmware uploading.

{% hint style="warning" %}

* Some USB cables are just for charging and do not have data transfer capability. Using the original data cable in the kit is better for making the uploading successful. &#x20;
* Some new laptops only have USB-C ports, so users use a hub to connect standard USB-B to their computers. However, the intervening hubs prevent the app from recognizing the serial port. The solution was to connect the USB-C cable DIRECTLY to the computer using EITHER a USB-C to USB-C cable OR a tiny C to B adaptor (not a hub).
  {% endhint %}

## Upload the firmware

There are two methods to Upload the firmware to the robot:

* The simplest method is to use the [**Petoi Desktop App**](https://guide.petoi.com/desktop-app/introduction). No programming is involved. You can play with some preset modes.&#x20;
* If you have some programming experience, you can use the [**Arduino IDE**](https://www.arduino.cc/en/software)[.](https://www.arduino.cc/en/software) You will be able to modify the open-source codes for your new projects.&#x20;
  * If you are using BiBoard, please refer to [**Upload Sketch for BiBoard**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard).
  * If you are using NyBoard, please refer to [**Upload Sketch for NyBoard**](https://guide.petoi.com/arduino-ide/upload-sketch-for-nyboard).

{% hint style="info" %}
If you are using BiBoard and it **cannot** upload firmware on Windows, please refer to [the FAQ instructions](/faq-frequently-asked-questions#biboard-can-not-upload-firmware-on-windows-os).
{% endhint %}

{% hint style="danger" %}
If you have a NyBoard(with Bittle and Nybble), we highly recommend using the green USB programmer to upload the firmware. The Bluetooth dongle is not as stable and may cause the mainboard's bootloader to crash if interrupted in the middle.&#x20;

For BiBoard(with Bittile X), the USB/Bluetooth connections are built on the board already.
{% endhint %}


# BiBoard V1

When you use a USB type-C data cable to upload the firmware for the mainboard **BiBoard V1.**

\[picture of USB data connection]

* On Windows, if there is **no** serial port in the port list of **Device Manager**:

<figure><img src="/files/OQ9sDgrC0Wgihg1niixC" alt=""><figcaption></figcaption></figure>

* On Mac, open the **Terminal** program under the **Applications**-**Utilities** folder and type the following commands. If no serial device name starting with "***tty.wchusbserial***" or "***cu.wchusbserial***" is found:

  ```
  cd /dev
  ls
  ```

#### Please download and install the USB driver:

* Windows: <https://www.wch-ic.com/downloads/CH343SER_EXE.html>
* Mac: <https://www.wch-ic.com/downloads/CH34XSER_MAC_ZIP.html>

For the macOS(from the version ***Sequoia 15.1***), after installing the driver, you need to enable the driver, as follows:

**Settings** -> **General** -> **Login Items** & **Extensions** -> **Driver Extensions**

<figure><img src="/files/NfPl5sfaV5CR4d3lEu4K" alt=""><figcaption></figcaption></figure>


# BiBoard V0

When you use a USB type-C data cable to upload the firmware for the **BiBoard V0**,  if there is **no** serial port in the port list of Device Manager.&#x20;

{% hint style="info" %}
Note: The connection for uploading firmware is to be made directly to the **BiBoard V0** and NOT to the outside charging port on the battery.
{% endhint %}

<figure><img src="/files/dHx9pOYm6CpIVsjzZOyT" alt=""><figcaption><p>Bittle X</p></figcaption></figure>

<figure><img src="/files/iWHiJdXpXOl2NKWucUEx" alt=""><figcaption></figcaption></figure>

Please download and install the USB driver:

{% embed url="<https://www.silabs.com/developer-tools/usb-to-uart-bridge-vcp-drivers?tab=downloads>" %}

For more details, please refer to the [BiBoard V0 USB Driver to access the serial port](https://app.gitbook.com/o/-M-_eWZUjFA4usjshHcZ/s/XLpFdG7mubqEHWylLK3w/~/edit/~/changes/75/technical-support/useful-tools/biboard-v0).


# NyBoard

When you use a [USB uploader](https://guide.petoi.com/communication-modules/usb-downloader-ch340c) to upload the firmware for the **NyBoard**,  if there is **no** serial port in the port list of Device Manager.&#x20;

<div align="left"><figure><img src="/files/t845ynqudt61CnY0kVWb" alt="" width="375"><figcaption><p>Nybble</p></figcaption></figure> <figure><img src="/files/QFSgcrGDgYU3m9tKSn3z" alt="" width="375"><figcaption><p>Bittle</p></figcaption></figure></div>

<figure><img src="/files/3sSB2vSZupl5T66oQ9LB" alt=""><figcaption></figcaption></figure>

Please download and install the USB driver:

* Mac: <http://www.wch-ic.com/download/CH341SER_MAC_ZIP.html>
* Windows: <http://www.wch-ic.com/downloads/CH341SER_EXE.html>
* Linux: <http://www.wch-ic.com/downloads/CH341SER_LINUX_ZIP.html>


# Joint Calibration

{% hint style="info" %}
Joint calibration is vital for the robot to work properly.&#x20;
{% endhint %}

The pre-assembled robot should have the legs installed, but you can further improve its performance by fine-tuning the joints' calibration.&#x20;

Make sure you have uploaded the OpenCat [Main function firmware](https://guide.petoi.com/arduino-ide/upload-sketch-for-nyboard#id-10.-upload-the-major-functionalities-sketch) before calibrating.&#x20;

This is a cool tutorial video made by one of our users, which briefs the process and explains its logic.&#x20;

{% embed url="<https://youtu.be/IA4FbYpPtbI?t=139>" %}

{% hint style="info" %}
We have published the 3D structure of the Bittle / Bittle X (Bittle X+Arm)'s calibration bracket online. If you have a 3D printer, you can print it by yourself. Please check this page:&#x20;

<https://makerworld.com/en/models/1523424-calibration-and-test-stand-for-bittle-x-r-robot#profileId-1596686>\
![](/files/apdn333Pwwiw564gWN2u)![](/files/TDCPOgBtQ6YiA6p63dnB)\
\
OR:

<https://github.com/PetoiCamp/NonCodeFiles/blob/master/stl/BittleStand/standWithCalibration.stl>\
![](/files/4ZrEDJtZ91rzsaTQkNNz)<br>
{% endhint %}

## \* The logic behind calibration is:

1. &#x20;You don't know where the servos are pointing before they are powered and calibrated. So if you attach the legs, the legs will rotate to random angles and may collide with the robot's body or other legs and get stuck. If a servo is stuck for a long time, it may break.&#x20;
2. &#x20;The robot has a "**calib**" posture with all joints set at zero degrees. You can [put the robot to the **calib** posture](#enter-the-calibration-state) so that you know all the joints should be rotated to their zero points (though you cannot see because the legs are not attached to the servos yet). Then, you can attach the legs to the servos **one joint by one joint**, perpendicular to their nearby references on the body frame. <br>

   <figure><img src="/files/VfCFfvRlaB12iOiP3JII" alt=""><figcaption><p>Calib Posture</p></figcaption></figure>
3. &#x20;Because the servo's gear teeth are discrete, aligning the legs to the right angles perfectly is impossible. So, you will need to fine-tune the offsets within the software. <br>

   <figure><img src="/files/UbmKitO9lx8Cn1AwDy0D" alt=""><figcaption><p>Servo gear</p></figcaption></figure>

The principles are the same for Nybble and Bittle.&#x20;

## Prepare to Enter the Calibration State

Entering calibration mode requires the following preparations: ‌

1. The mainboard has completed the [firmware uploading](https://guide.petoi.com/quick-reference/upload-firmware)
2. All servo circuits are connected to the mainboard&#x20;
3. The battery is plugged into the controller board and is turned on (long-press the button on the battery to turn on/off the power)
4. Connect the robot to a computer or mobile phone

* Fon NyBoard, the [USB adapter](https://guide.petoi.com/communication-modules/usb-downloader-ch340c#connect-nyboard) or [Bluetooth dongle](https://guide.petoi.com/communication-modules/dual-mode-bluetooth#connection-with-nyboard) is used to connect the robot to a computer / mobile phone
* For BiBoard, the USB data cable connection must be made directly to **the BiBoard** and NOT to the battery's outside charging port. You can also connect to the computer / mobile phone via [Bluetooth](https://guide.petoi.com/quick-reference/bluetooth-connection).

{% hint style="info" %}
If you build the robot from an unassembled kit, do not install the head and leg components before entering the calibration state.&#x20;
{% endhint %}

{% hint style="info" %}
If you have a pre-assembled kit with the feedback servos, you can do [automatic calibration](https://docs.petoi.com/apis/serial-protocol/feedback-servos) to save time.

Note: For robots with robot arms, the automatic calibration function does **not** include the claw joint.
{% endhint %}

## Enter the Calibration State

The robot's legs may point to unknown angles when booting up. When entering the calibration state, the joints will be moved to their zero positions. You can see the output gears of the servos rotate and then stop. Then, you can attach the legs and fine-tune the joint offsets in the software interface. There are 3 software interfaces to enter the calibration state and fine-tune the joints.&#x20;

* Use the Mobile App [**Petoi**](https://guide.petoi.com/mobile-app/calibrator)
* Use [**Petoi Desktop App**](https://guide.petoi.com/desktop-app/joint-calibrator)
* Use [**Arduino IDE**](https://guide.petoi.com/arduino-ide/calibrate-the-joints-with-arduino-ide)

{% hint style="info" %}
You can also enter the calibration state by booting up the robot with one side up. This method doesn't require any computer, remote, or smartphone app, so it's convenient when you are focused on assembling the robot from the kit.&#x20;

![](/files/TecxzDUFsbh5ci2j2WLw)
{% endhint %}

## Install the screws

After completing the joint calibration, install the center screws to fix all the joint parts and servo gears.

<figure><img src="/files/nd3WdYZD2oQos33dgV5i" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/yc6AQaZClovTR1NEs1SM" alt=""><figcaption></figcaption></figure>


# Remote Controller

It's simple to control Nybble / Bittle(with NyBoard) / Bittle X( with BiBoard V0) via the remote controller.  This doesn't work with Bittle X V2(with BiBoard V1).

### 1. Preparation

#### BiBoard V0

The infrared receiver for **Bittle X** (mainboard type: BiBoard V0) is on the microcontroller near the neck of Bittle X.

<figure><img src="/files/iiUISCI6TqnNYAWBm9bL" alt=""><figcaption><p>BiBoard V0_x</p></figcaption></figure>

#### NyBoard V1

The infrared receiver for NyBoard is near the tail of **Bittle/Nybble**.

<figure><img src="/files/IWI3bsRQGEHq7DUGfi5Q" alt=""><figcaption><p>NyBoard V1_*</p></figcaption></figure>

<figure><img src="/files/JvETISvNdMLJzSlfDpZi" alt=""><figcaption><p>NyBoard V1_*</p></figcaption></figure>

#### Remote connection

The remote doesn't require pairing. Make sure its plastic insulation sheet is removed, and point the remote‘s transmitter to the receiver on the robot's back when operating.&#x20;

If the robot doesn't respond, you can use your phone's camera to check the transmitter: \
If it doesn't blink when clicking a button, you need to change its battery. \
If it blinks, it may indicate the program on the robot is not configured correctly.&#x20;

### 2. Keymap

Only the position of the buttons matters, though those symbols can help you remember the functionalities. It's better to define position-related symbols to refer to those keys, such as **K00** for the 1st row and 1st column, and **K32** for the 4th row and 3rd column.&#x20;

Abbreviations for key definitions can reduce SRAM usage. Due to the limited keys of a physical remote, you can change the definitions for convenience.&#x20;

{% hint style="warning" %}
The following map is just an illustration. Check the **`#define KXX command`**&#x69;n OpenCat/src/infrared.h for the actual key definitions in effect. They are also open to your customization.
{% endhint %}

<img src="/files/DeVvsNEm2LkSbi81O0rZ" alt="" width="325">

### 3. Check out the following featured motions

* **Rest** puts the robot down and shuts down the servos. It's always safe to click it if the robot is doing something awkward.
* **Balance** is the neutral standing posture. You can push the robot from the sides and it will try to recover. You can test its balancing ability on a fluctuating board. Balancing is activated in most postures and gaits.
* Pressing **Front/Left/Right** will make the robot move forward/left/right.
* **Back** will make the robot move backward
* **Calibrate** puts the robot into calibration posture and turns off the gyro.
* **Stepping** lets the robot step at the original spot.
* **Crawl/walk/trot** are the gaits that can be switched and combined with the direction buttons.
* Buttons after **trot** are preset postures or other skills.
* **Gyro** will turn on/off the gyro for self-balancing. Turning off the gyro can accelerate and stabilize the slower gaits. But it’s NOT recommended for faster gaits such as trot. Self-righting will be disabled because the robot no longer knows it's flipped.&#x20;
* Different surfaces have different friction and will affect walking performance. The carpet will be too bushy for the robot's short legs. It can only crawl (command **kcr**) over this kind of tough terrain.&#x20;
* You can pull the battery pack down and slide along the longer direction of the belly. That will tune the center of mass, which is very important for walking performance.&#x20;
* When the robot is walking, you can let it climb up/down a small slope (<10 degrees).

{% hint style="info" %}

* If the robot keeps beeping after you connect the USB uploader, with "Low power: " and numbers printed on the serial monitor, it’s the low voltage alarm being triggered. You need to power the mainboard with the battery to pass the threshold.
* The servos are designed to be driven by internal gears. Avoid rotating the servos too fast from the outside.&#x20;
* **Don’t keep the robot running for too long.** It will overheat the electronics and reduce the servos’ life span.&#x20;
* If you feel something is wrong with the robot, press the reset button on the main board to restart the program.&#x20;
* Be kind as if you were playing with a real kitten/puppy. (^=◕ᴥ◕=^)
  {% endhint %}

For users of the older remotes, we have created customized remote panels in the newer batches. You can download the design file and print it on A4 paper for easy reference.

{% file src="/files/lRm5r44irjNYSBmAuHsP" %}

![](/files/YhSiKBzsbvmB2G0eXWfo)


# Introduction

📱🤖

Thanks for choosing Petoi's robot. This guide will help you set up your robot buddy and provide a simpler UI to calibrate the joints, control the robot, and program it. For advanced users, we recommend you keep the robot updated with the [OpenCat(for NyBoard)](https://github.com/PetoiCamp/OpenCat) / [OpenCatEsp32(for BiBoard)](https://github.com/PetoiCamp/OpenCatEsp32) firmware on GitHub for the best compatibility and the newest features.&#x20;

## Download and installation

The app works on both Android and iOS devices.

* [iOS 11+](https://apps.apple.com/us/app/petoi/id1581548095)
* [Android 4.4+](https://play.google.com/store/apps/details?id=com.petoi.petoiapp)

#### APK

For Android, you can also download the APK and install it on your phone.&#x20;

* The universal version(try this one first)\
  [v1.4.1-40-2-20251022-app-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-release.apk)
* The **v8a** version of the app mainly supports most of the current new mobile phone models\
  [v1.4.1-40-2-20251022-app-arm64-v8a-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-arm64-v8a-release.apk)
* The **v7a** version of the app is compatible with older mobile phone models\
  [v1.4.1-40-2-20251022-app-armeabi-v7a-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-armeabi-v7a-release.apk)
* The **x86\_64** version of the app indicates that the APK is designed for Android devices using Intel or AMD 64-bit processors. This means the APK contains native code libraries optimized for the x86\_64 architecture, designed to improve performance and compatibility.\
  [v1.4.1-40-2-20251022-app-x86\_64-release.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.1/v1.4.1-40-2-20251022-app-x86_64-release.apk)

{% hint style="info" %}
If the connection panel in the App shows a blank Bluetooth connection list, first check whether you have granted the App Bluetooth and location permissions. If it still shows a blank list, try to install the previous stable version. \
[v1.4.0-37-1-app-release-20251006.apk](https://github.com/PetoiCamp/MobileApp/releases/download/1.4.0/v1.4.0-37-1-app-release-20251006.apk)
{% endhint %}

![](/files/G1cSapHMlJK9sDQ53TMN)

## Connect to the robot

For the robot's mainboard, you need to set it up according to the related subpage instructions.

{% hint style="warning" %}
The app will send a greeting to the Bluetooth device and expect a response from the robot. You must upload the OpenCat (for NyBoard) / OpenCatEsp32 (for BiBoard) firmware to your robot before connecting to the app. Otherwise, the app will consider it "not a Petoi device". A pre-assembled robot should already have the firmware installed. Otherwise, you'll need to upload firmware using the [Petoi Desktop app](https://guide.petoi.com/desktop-app/firmware-uploader).&#x20;
{% endhint %}

{% hint style="warning" %}
For BiBoard, please ensure the program enters the [**regular startup mode**](https://guide.petoi.com/arduino-ide/upload-sketch-for-biboard#id-2.8-program-initialization)**.**
{% endhint %}

Open the app and scan available Bluetooth devices. **Don't connect the robot with the phone's system-wide Bluetooth settings!** Connect the device with the name Bittle, Petoi, or OpenCat.&#x20;

Please remember to enable Bluetooth and give the app access to it. On some devices, you may also need to allow the app's location service, though we are not using any of that information.

{% hint style="info" %}
On some Android OS, you need to activate the location service as follows:![](/files/tu2Vwheh7gELyuRGt2ZJ)
{% endhint %}

![](/files/-MjZWU2EpJOmFcBOEKGH)

The app will open the Control Panel interface when Bluetooth is connected. If the robot doesn't respond or malfunctions later, press the reset button on the mainboard to restart the robot.

The app should automatically detect the supported robot type based on the latest firmware. Otherwise, it will show the selections for the robot type. The above interface can also be revisited by selecting the option "Select a robot" in the control panel.

![](/files/FG3i4k9cmd0KgFjfCaYH)


# Connect to BiBoard

For the mainboard BiBoard, the Bluetooth module is already built into the ESP32 module; you just need to power on the robot by long-pressing the button on the battery.




---

[Next Page](/llms-full.txt/1)