This is the Petoi robot product documentation hub for Petoi legacy robot Bittle, Bittle X(but not Bittle X V2), and Nybble. We constantly iterate on our models and codes to bring bionic robotic pets to the world. Please read the notes regarding versions carefully before configuring your robot.

If you need help, please or post on .

Legacy Hardware Products

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:

Hi, thanks for getting a Petoi robot.

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

• Bittle

• Bittle X

  • If you have a Bittle X V2(as indicated on the package barcode label), please visit

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

1. • Play with the default actions

   • Play with

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.

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.

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.

Coordinate values and directions.

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.

The calibrator interface for Nybble is as following:

After the robot enter the calibration state, install the head, legs and tail as the calibration posture.

If you want to use , in the Petoi Desktop App, or a coding block in via computer Bluetooth, you need to pair the mainboard's Bluetooth with the computer first.

Connection method

To run the Skill Composer, you can use the following methods to connect the robot's mainboard to the computer:

• Wired connection: The kit includes a connecting the robot's mainboard to the computer.

At present, There are three kinds of interface for the Petoi robots:

• Nybble

• Bittle / Bittle X

• Bittle X+Arm

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:

The joint calibrator interface for Bittle X+Arm, which uses BiBoard V0 in the Petoi Desktop App, is as follows:

BiBoard

For products (such as and ), there is no need to modify any software code. By default, all functional blocks in Mind+ are supported.

Use the .

Check the BiBoard V1 version

The and the are the same as BiBoard V0.

Plug in the battery and long-press the battery button to power on the robot.

For BiBoard, please ensure the program enters the .

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 via .

Use the USB Type-C data cable for BiBoard V0.

BiBoard V0 version

You can find the board version number on the BiBoard V0:

Uploading options

• Factory Reset After upgrading the firmware, the board will enter the and ask whether to clear the joint calibration parameters and calibrate the IMU.

• Upgrade the Firmware It will upgrade the firmware, skip the clear joint calibration parameters, calibrate the IMU steps (Send serial command "n"), and automatically enter the .

• 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 after uploading the firmware. Some message windows will pop up in sequence for you to confirm or cancel:

1. Reset joint offsets? (Y/N)

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).

1. Calibrate IMU? (Y/N)

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 .

When you use a USB uploader to upload the firmware for the NyBoard, if there is no serial port in the port list of Device Manager.

Please download and install the USB driver:

• Mac: http://www.wch-ic.com/download/CH341SER_MAC_ZIP.html

• Windows:

• Linux:

NyBoard is equivalent to a generic Arduino Uno board with rich peripherals. Besides the native Arduino IDE, you can also program it using Mind+ blocks. But be aware that if you use this mode, the original OpenCat firmware will be over-written, and you will need to re-upload the firmware later to resume the default robot animal function.

Setting up the coding environment is as easy as the following steps.

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.

Please download and install the USB driver:

For more details, please refer to the .

The joint calibration interface for Bittle X+Arm which uses BiBoard V1 in the Petoi Desktop App is as follows:

The interface for Bittle / Bittle X :

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:

For products (, ), there are two ways to upload the firmware (Mind+ mode), which supports the Mind+ extension library:

• • If you just downloaded a new version of this Desktop App. You should click the Upgrade the Firmware button. You can select 'N' to preserve the calibration values.

The calibrator interface for Bittle X+Arm is as follows:

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

When you use a USB type-C data cable to upload the firmware for the mainboard BiBoard V1.

• On Windows, if there is no serial port in the port list of Device Manager:

• On Mac, open the

Connect to the mainboard

You must use the USB data cable to do firmware uploading.

The subpages mention the joint calibration interface for Bittle / Bittle X in the Petoi Desktop App.

Installation for the construction kit

After entering the calibration state, with all servos rotated to their zero angles, attach the head, 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:

The interface for Bittle X+Arm:

The joint calibration interface for Nybble in the Petoi Desktop App is as follows:

At present, there are 3 versions of NyBoard: NyBoard V1_0, NyBoard V1_1 and NyBoard V1_2.

There are just a few differences between NyBoard V1_1 and NyBoard V1_2:

• V1_2 has one NeoPixel LED attached to Pin D10.

Connection method

To run the Skill Composer, you can use the following methods to connect the robot's mainboard to the computer:

• Wired connection: The kit includes a USB Type-C data cable connecting the robot's mainboard to the computer.

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:

The Code mode is a Python3 development environment. You can write any Python script in it and call all the API interfaces of the PetoiRobot library imported by Mind+.

Plug in the battery and long-press the battery button to power on the robot.

For NyBoard, please ensure you have uploaded the OpenCat firmware before calibrating.

You must connect the and USB data cable or to the computer.

The purpose of the DAC is the opposite of that of the ADC. The DAC converts a digital signal into an analog signal for output.

Remember the music when NyBoard is turned on? It is using PWM to make music sound which uses high-speed switching to adjust the duty cycle to output voltage.

Compared with PWM, the DAC will directly output the voltage without calculating the duty cycle. ESP32 integrates a 2-channel 8-bit DAC with a value of 0-255. The voltage range is 0-3.3V. Therefore, the formula for calculating the output voltage of the DAC is as follows:

The demo is as follows:

Configure the Linux environment

You need to on the Chromebook to access the Linux environment via the terminal app.

Then, follow the following steps to install Mind+.

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

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

Since the ESP8266 can be used as a regular Arduino board, we can write a simple Arduino code to open the serial port and send the serial commands to control the robot. It's like a stand-alone serial commander written in C and can go with the robot. You may write hundreds of pre-defined tasks without worrying about the memory limits on the main controller.

You can find a short test8266Master in OpenCat/ModuleTest:

void setup() {
  // put your setup code here, to run once:
  Serial.begin(115200);
  Serial.setTimeout(5);
  bool connected = false;
  while (!connected) {
    Serial.print("b 20 8 22 8 24 8");
    for (byte t = 0; t < 100; t++) {
      if (Serial.available())
        if (Serial.read() == 'b') {
          connected = true;
          while (Serial.available() && Serial.read())
            ;
          break;
        }
      delay(10);
    }
    delay(1000);
  }
}

void sendCMD(const char cmd[], int wait = 0) {
  Serial.print(cmd);
  while (true) {
    if (Serial.available() && toLowerCase(Serial.read()) == cmd[0]) {
      delay(10);
      while (Serial.available() && Serial.read())
        ;
      break;
    }
    delay(2);
  }
  delay(wait);
}

void loop() {
  sendCMD("d", 500);                    //rest and wait 0.5 seconds 趴下并等待0.5秒
  sendCMD("khi");                       //greetings 打招呼
  sendCMD("kpu");                       //pushups 俯卧撑
  sendCMD("kvtF", 1000);                //stepping 原地踏步
  sendCMD("G");                         //Turn off the gyro 关闭陀螺仪
  sendCMD("kwkF", 1500);                //walk 行走
  sendCMD("kck");                       //check 观察
  sendCMD("kpu1");                      //push ups with on hand 单手俯卧撑
  sendCMD("kvtR", 2000);                //spin 旋转
  sendCMD("G", 100);                    //turn on the gyro 打开陀螺仪
  sendCMD("ktrF", 1500);                //trot 跑步
  sendCMD("kjy", 0);                    //joy 加油
  sendCMD("i 0 45 8 -90 9 -90", 1000);  //rotate the head and arm joints 伸手转头
  sendCMD("ksit", 1000);                //sit 坐下
}

There is no separate GPIO port on BiBoard, but the multiplexed serial port 2 (pin 16, 17) or the PWM pin of the unused PWM servo interface can be used as GPIO port. The GPIO port is also relatively simple to use. After configuring the input and output mode, the usage is exactly the same as that of Arduino UNO. You can use any IO control program of Arduino UNO, just change the number of IO .

/* In this demo, we use TX2, RX2 as general purpose IO
*   TX2 : IO17
*   RX2 : IO16
*/

void setup() {
  // initialize digital pin 16 & 17 as an output.
  pinMode(16, OUTPUT);
  pinMode(17, OUTPUT);
}

// the loop function runs over and over again forever
void loop() {
    
  digitalWrite(16, HIGH);            // GPIO 16 & 17 HIGH
  digitalWrite(17, HIGH);
  delay(1000);                       // wait for a second

  digitalWrite(16, LOW);             // GPIO 16 & 17 LOW
  digitalWrite(17, LOW);
  delay(1000);                       // wait for a second
}

There are 2 serial ports,which are separately located on 2 expansion sockets (P16, P17) ,on BiBoard.

The serial port 1 on the P16 can be connected to the USB downloader and the external serial device. Please do not use the downloader and the external serial device at the same time. The serial port voltage division will lead to communication errors.

In the Arduino demo, Serial represents the serial port 0, Serial1 represents the serial port 1.Serial and Serial1 send to each other.

/* In this demo, we use Serial and Serial1 
*  Serial and Serial1 send to each other 
*/

void setup() {
  // initialize both serial ports:
  Serial.begin(115200);
  Serial1.begin(115200);
}

void loop() {
  // read from port 1, send to port 0:
  if (Serial1.available()) {
    int inByte = Serial1.read();
    Serial.write(inByte);
  }

  // read from port 0, send to port 1:
  if (Serial.available()) {
    int inByte = Serial.read();
    Serial1.write(inByte);
  }
}

The calibrator interface for Bittle is as following:

After the robot enters the calibration state, do the following steps:

Install the head

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.

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

Install the legs

Install upper leg and lower leg components to the output teeth of the servos when the Bittle is powered on and in the calibration state. Please keep the torso, upper leg, and lower leg installed vertically as much as possible, and do not install the lower leg backward, as shown in the picture.

Use the included L-shaped tool as a reference

The subpages mention the joint calibration interface for Bittle X+Arm, which uses BiBoard V0 and BiBoard V1 in the Petoi Desktop App.

Prepare for calibration

This robotic arm is already fully assembled.

• For the construction kit Install the short wire servo in the servo slot on the robotic arm with two M2*5 self-tapping screws. [robotic arm installation image 0]

• For the pre-assembled kit

  You only need to install the servo with the neck structure in the servo slot with two M2*5 self-tapping screws.

Installation for the construction kit in the calibration state

For the construction kit, after entering the calibration state, please install the legs and robotic arm as follows:

Install the legs

The process is the same as .

Install the robotic arm

Place the robotic arm as close to the central axis as possible and insert its servo shaft into the servo arm of the neck.

[robotic arm installation image 1]

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

[robotic arm installation image 2]

Fine-tuning

The process of fine-tuning the legs and the Servo 0 is the same as that of Bittle / Bittle Xegs process is the same as .

Please click the blank part of the slider track and follow the calibration posture below to fine-tune Servo 1 on the robotic arm.

Please click the Auto button to fine-tune the claw (Servo 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.

NyBoard

There are two ways to establish a serial port connection：

Connect the USB Adapter

Connect the USB adapter to the mainboard and select the correct serial port. Refer to the section in the USB Adapter(Uploader) Module for specific steps.

Connect Bluetooth module(optional)

Please refer to the in the Dual-Mode Bluetooth Module for the specific steps.

Setup steps in the Arduino IDE

1. Select the port in the (recommend version 1.8.19).

1. Open the serial monitor.

You can choose the "Serial Monitor" in the Tools menu bar or click the button to open the serial monitor window:

1. Config the parameter of the serial monitor.

In the serial monitor, set "No line ending" and the baud rate to 115200.

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 ).

BiBoard

There are two ways to establish a serial port connection：

• and computer using a USB type-C data cable(you should use the original one in the kit).

• Connect the mainboard with a / via Bluetooth.

The setup steps in the Arduino IDE are identical to those .

Nested task queue

You can join multiple serial commands as one task queue:

• The token is T_TASK_QUEUE. ('q')

• Use 'q' to start the sequence.

• Add a sub token followed by the subcommand.

• Use ':' to add the delay time (mandatory)

• Add '>' to end the sub-command

• Example: qk sit:1000>m 8 0 8 -30 8 0:500> will make the robot sit and then move the shoulder joint.

Attach a trigonometric function to each joint to compose smooth and periodical movements

Function

JointAngle[index]= FunctionOf(amplitude, midpoint, freq, phase, resolution, frame)

• The token is T_SIGNAL_GEN. ('o')

• The command format is:o resolution speed,jointIdx1 midpoint amplitude frequency phase,jointIdx2 midpoint amplitude frequency phase,...

• For example: o 1 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

Formula

• The motion's iterator loops from 0 to 360.

• The resolution is how it increases to 360: t += resolution.

• The speed defines the transition speed. It will move by [1~125] degrees towards the target angle. 0 is the maximum speed possible.

Pan+tilt:

qksit:100>o 1 8, 0 0 30 4 0, 1 -30 30 4 30:100>o 1 0, 0 0 30 4 0, 1 -30 30 4 15:100>o 1 0, 0 0 30 4 0, 1 -30 30 8 30:100>o 1 8, 0 0 30 8 0, 1 -30 30 4 30:100>o 1 8, 0 0 30 4 0, 1 -30 30 16 30:100>o 1 0, 0 0 30 32 0, 1 -30 30 8 0:100>Wash face: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

Set up Linux on your Chromebook

Linux is a feature that lets you develop software using your Chromebook. Install Linux command line tools, code editors, and IDEs (integrated development environments) on your Chromebook. These can be used to write code, create apps, and more.

Important: If you use your Chromebook at work or school, you might be unable to use Linux. For more information, contact your administrator.

Turn on Linux

Linux is off by default. You can turn it on at any time from Settings.

1. On your Chromebook, at the bottom right, select the time.

2. Select Settings Advanced Developers.

3. Next to "Linux development environment," select Turn On.

Accessing Linux environment:

• You can access your Linux environment through the terminal app in your Chromebook launcher.
• Files created in Linux are stored in a container and are separate from Chrome OS files. You can access them using the "Linux files" app.
• You can set the shared folders in the file browser and manage them in the Settings

Update and install development tools:

Once the setup is complete, a terminal window will open. You can use the following commands to update the package list and install basic development tools:

** Download the latest version of the Petoi Desktop APP. **

• After downloading the compressed file(.zip), please unzip it first.

• Do NOT move the UI.exe to another location in Windows.

From version 1.2.1, the Petoi Desktop App has included a new module - Tools. This module provides convenient tools to fix your robot's frequent problems.

Reset voice module

It is used to reset the , simplifying its 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.

Follow the instructions in the message box.

If the problem persists, please email [email protected].

Calibrate gyroscope

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.

Follow the instructions in the message box:

If the problem persists, please email [email protected].

Hardware Connection

Please connect the corresponding pins of the Raspberry Pi and the BiBoard extension hat as follows:

5V power --> 5V

Ground --> GND

GPIO 14 (TXD) --> RX2

GPIO 15 (RXD) --> TX2

Dial the switch on the BiBoard extension hat to the UART2 side.

The and are the same as BiBoard V1.

Connection steps

1. 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 blue LED and yellow LED should be on.

2. For Windows, Open the Bluetooth & other devices setting page, and turn on the Bluetooth button as follows:
3. Add the BiBoard Bluetooth for the first time as follows:

   Select the one with the name Bittle**_BLE:

After paired successfully, it shows：

Check the outgoing serial port, which we will use later in the Mind+ or Petoi Desktop App in the More Bluetooth options:

1. Test in Mind+:

Bittle vs Bittle X

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

We introduced the position feedback feature for servos manufactured after March 2024. This feature utilizes the same PWM signal wire to return the servo's actual position, opening up a new control interface for the robot.

This feature should be present on all servos with labels or laser marks after May 2024. If the labels are missing, they may still have it. However, the feature is only available on ESP32-based BiBoards (not NyBoards).

To check it, you need to upgrade your robot's firmware. Enter the serial command 'f' in or the . If the monitor keeps printing values that change when you move the servos, they are position feedback. The number of columns corresponds to the number of servos with feedback.

The servos have to be all feedback servos to perform the following features:

The Petoi Web Coding Block can also be used for the robot, which uses the and the .

Please take a look at the related section in the Wi-Fi module for instructions on and software setup ( and ).

Upload the WiFi Firmware to the WiFi module

Project URL：

Prepare for calibration

Use the library in your own project

The project is built as a dynamic library so that the program can easily link to it. The recommended practice to use the library is to clone it as a git submodule:

If you are using cmake, simply create a CMakeLists.txt file and link the library to your executable:

The instructions of ADC on BiBoard

The 34, 35, 36 and 39 pins of the ESP32 module support input only. We configure it as an analog input port on BiBoard, which makes it convenient for developers to connect 4 foot sensors.

The usage of analog input analog-to-digital converter (ADC) on BiBoard is the same as the basic Arduino UNO, but the accuracy is higher (12 bits, UNO is 10 bits), and a programmable gain amplifier is added to make the ADC work in the best range.

When a 1V voltage signal is input, if 12bit access is used according to the normal configuration, the reference voltage is equal to the power supply voltage (3.3V): the corresponding output is 0～1241, a large part of the ADC range will be wasted, resulting in inaccurate data. When we configure the programmable gain, we can make the 1V input signal fill almost the entire ADC range, and the accuracy and resolution are greatly improved.

This demo uses 4 inputs, respectively configured as: 0/2.5/6/11 decibel amplification gain, it should be noted that the default configuration of ESP32 Arduino is 11 decibel amplification gain.

** Download the latest version of the Petoi Desktop APP. **

Prepare for calibration

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

Calibration process

Enter the calibration state

After the robot is powered on by a battery, there are two methods to enter the calibration state:

• It will enter the calibration state automatically when you click the Joint Calibrator button.
• Click the Calibrate button in the calibrator interface. Take Bittle for example:

2. The rationale for calibration

2.1 Understand the zero state and the coordinate system

After typing ‘c’ in the serial monitor, 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:

Rotating the limbs counter-clockwise from their zero states will be positive (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.

2.2 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.

Installing and Fine-tuning

The joint calibration interface of different products is shown in the following subpages.

There are two kinds of kit: the construction kit and the pre-assembled kit.

• For the construction kit, you must install the components (such as the head, legs, and tail) after the robot enters the calibration state. For more details, please follow the suppage instructions.

• The pre-assembled kit already has the components adequately installed. You can do the joint calibration for fine-tuning.

The included L-shaped tool can be used as a reference during calibration. For more details, please follow the instructions on the subpages.

Validation and Save data

You can switch between "Rest", "Stand up" and "Walk" to test the calibration effect.

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). take Bittle for example:

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.

Install the screws for the construction kit

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

Petoi Desktop App provides a neat graphical user interface to configure the firmware, calibrate the robot, and design customized motions for your robot. The major function modules are the Firmware Uploader, Joint Calibrator, and Skill Composer.

Download & Installation

You can download the latest version 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 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.

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. If it still doesn't open, go to your System Settings -> Privacy and Security and scroll down. There should be an option to allow the app to run.

Linux

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

Run the app from the Terminal

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 macOS or Linux machines. The equivalent environment on Windows machines is called the Command-Line Tool (CMD). It's recommended that you install to manage your Python environment. It can also provide the Powershell as a Terminal for the 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 using 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.

Open Source Codes

The source code is written with Tkinker in Python 3 and is .

UI.py is the general entry for all the modules:

• UI.py

-> FirmwareUploader.py

-> Calibrator.py

-> SkillComposer.py

-> Debugger.py: provides some debugging tools for the Petoi robot.

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

Use the USB uploader for NyBoard.

For more details, please refer to the Connect NyBoard section in the USB uploader module for specific steps.

NyBoard Version

You can find the board version number on the NyBoard.

Uploading options

• Factory Reset Our factory uses it to improve efficiency. However, it automatically resets all the parameters, including the calibration parameters of the servos and the IMU, so it's not recommended for regular users.

• Upgrade the Firmware It will upgrade both the Parameters and the Main function firmware. It is mandatory if you just downloaded a new version of this desktop app.

• Update the Mode Only If you have upgraded the firmware at least once after downloading a new version of this desktop app, you can switch between the modes without refreshing the parameters. It's faster by skipping the firmware upgrade stage.

Upgrade the firmware process for NyBoard

After clicking the Upgrade the Firmware button, the uploading process starts immediately. The status bar at the bottom shows the current progress in real time and the results of key processes.

After the Parameters firmware has been successfully uploaded, the board runs the configuration program. Some message windows will pop up in sequence for you to confirm or cancel:

• Reset joint offsets? (Y/N)

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 done so before).

• Calibrate IMU? (Y/N)

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.

When all the steps are completed, a message window will appear showing "Parameter initialization complete!" You must confirm to proceed to the second round of uploading the Main functional firmware.

Thanks for choosing Petoi's robot, Bittle or Nybble. 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 firmware on Github for the best compatibility and the newest features.

Download and installation

The app works on both Android and iOS devices.

APK

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

• The universal version(try this one first)

• The v8a version of the app mainly supports most of the current new mobile phone models

• The v7a version of the app is compatible with older mobile phone models

Connect to your robot

You need to plug the into the 6-pin socket on the NyBoard. Pay attention to the Bluetooth dongle's pin order. Long-press the button on the battery to turn on the robot's power.

The LED on the Bluetooth dongle should blink, waiting for a connection. 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. Remember to open the Bluetooth service and grant the app access to the service. On some devices, you may also need to allow the location service for the app, though we are not using any of that information.

If Bluetooth is connected, its LED will light steadily. The robot will play a three-tone melody. If the robot doesn't respond or malfunctions later, press the reset button on the NyBoard to restart the program on the NyBoard.

The App should automatically detect Nybble or Bittle with the latest OpenCat firmware. Otherwise, it will show the selections for Nybble or Bittle. The option "Select a robot" also can be re-visited in the control panel.

We have defined a set of serial communication protocols for robots:

All the tokens start with a single ASCII-encoded character to specify their parsing format. They are case-sensitive and usually in lowercase.

Try the following serial commands in :

• “ksit”

• “m0 30”

• “m0 -30”

You can refer to the macro definitions in OpenCat.h to utilize the most updated sets of tokens.

Some more available commands for skills:

The complete set of skills in effect is defined in or : For example:

All the skill names in the list can be called by adding a 'k' to the front and deleting the suffix. For example, there's "sitI" in the list. You can send "ksit" to call the sitting posture. If a skill has "F" or "L" as the second last character, it's a gait. It means walking forward or left. Walking right is a mirror of walking left. So you can send "kwkF", "kwkL", "kwkR" to make the robot walk. Similarly, there are other gaits like trot ("tr"), crawl ("cr"), and stepping ("vt").

After turning on Linux 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

Download package

Open the website () and download the corresponding type of Legacy Arduino IDE:

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.

Set up the Arduino IDE development environment for the mainboard

You can open the Arduino IDE as follows:

NyBoard

For more details, please refer to .

After using the USB uploader and USB data cable to connect the NyBoard and Chromebook, you will see a prompt: Please click Connect to Linux.

and check in the Settings interface, and it should be enabled as follows:

BiBoard

For more details, please refer to .

After using the USB data cable to connect the BiBoard and Chromebook, you will see a prompt: Please click Connect to Linux.

and check in the Settings interface, and it should be enabled as follows:

Use the following commands to install the library pyserial for uploading the sketch for BiBoard

Hardware Connection

You can solder a 5-pin socket on BiBoard V1 to plug in a Raspberry Pi.

The white Pi standoff can be 3D printed.

You can 3D print a new that fits the Raspberry Pi socket, as follows:

After plug in the Raspberry Pi board , power on the BiBoard via USB data cable or Battery.

Software Setup

Open the , and send serial command XS to enable the working mode.

Serial port name on Pi

There's also a for developpers to easily connect to the environment. This ROS wrapper contains two branches: ROS1 and ROS2. It is recommended to use ROS with .

1. Preparation

BiBoard V0

The infrared receiver for

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