This is the Petoi robot product documentation hub. 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 write to [email protected] or post on our forum at petoi.camp.

Hardware Products

Check the Getting Started guide.

😼 Nybble Cat User Manual

🐶 Bittle Dog User Manual

🐶 Bittle X User Manual

🐱 Nybble Q User Manual

Intelligent Search

You can use the find (Cmd+K/Ctrl+K) feature on this site. It supports Lens, a ChatGPT-based service.

Hi, thanks for getting a Petoi robot.

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

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

    • pay attention to

    • select BiBoard V1 during the firmware upload process with

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

   • Add to the controller panel

   • Play with to make your robot perform multiple actions in sequence

2. (for Bittle X or any robot with the voice command module)

   • If the robot doesn’t respond to your voice commands, please see .

   • You can (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 .

4. Do some coding

   • Follow to

   • some new robotics skills with

   • Follow to code some Petoi robotics moves in C++

   • For Bittle/Bittle X, you may to make your robot not run around while you program it.

5. Work on some

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 on our official website or in the Petoi Doc Center.

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

If you want to use Joint Calibrator, Skill Composer in the Petoi Desktop App, or a coding block in Mind+ 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 USB Type-C data cable connecting the robot's mainboard to the computer.

• Wireless connection(Bluetooth)： The motherboard's built-in Bluetooth communication module allows you to establish a wireless connection between the robot's mainboard and the computer.

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

• Nybble

• Bittle / Bittle X

• Bittle X+Arm

The interface for each kind of product, please refer to the following subpages:

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.

Use the included L-shaped tool as a reference

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:

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:

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

Installation

After entering 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:

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

Fine-tuning

Use the included L-shaped tool as a reference during calibration. According to the index numbers of the joints shown at the top of the interface (when calibrating the servos, adjust the upper leg first, then adjust the lower leg). Drag the corresponding slider (below the index number), or click the blank part of the slider track to fine-tune the joint to right angles.

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

Check the BiBoard V1 version

The uploading options and the Factory reset process are the same as BiBoard V0.

The interface for Bittle X+Arm:

Configure the Linux environment

You need to turn on Linux 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)

Download package

According to different architectures to download different versions:https://mindplus.dfrobot.com/linux

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:

Run Mind+

Now, you can proceed to the Mind+ tutorial.

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.

• V1_2 supports both ATmega328p AU (bigger) and MU (smaller) chips.

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 calibration interface for Bittle (NyBoard) in the Petoi Desktop App is as follows:

The calibrator interface for Bittle is as following:

After the robot enter 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

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:

• 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:

Please download and install the USB driver:

• Windows:

• Mac:

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

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:

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

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 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, and do not install the lower leg backward, as shown in the picture.

Fine-tuning

Use the included L-shaped tool as a reference during calibration. According to the index numbers of the joints shown at the top of the interface (when calibrating the servos, adjust the upper leg first, then adjust the lower leg). Drag the corresponding slider (below the index number), or click the blank part of the slider track to fine-tune the joint to right angles.

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.

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:

Connect to the mainboard

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

Upload the firmware

There are two methods to Upload the firmware to the robot:

• The simplest method is to use the . No programming is involved. You can play with some preset modes.

• If you have some programming experience, you can use the You will be able to modify the open-source codes for your new projects.

  • If you are using NyBoard, please refer to .

  • If you are using BiBoard, please refer to .

BiBoard

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

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

Connect method

• 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 communication module allows you to establish a wireless connection between the robot's mainboard and the computer.

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.

• Wireless connection(Bluetooth)： The kit includes a connecting the robot's mainboard to the computer.

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.

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

• It doesn't matter if you use ',' or space ' ' to separate the numbers. However, using ',' to group can clarify one joint's parameters.

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.

• frequency defines how many cycles the joint can oscillate in one loop.

• phase is defined as -120 to 120. So phase = 30 means shifting by Pi/2. 120 is one entire period.

• For example, the head’s pan/tilt angles can be bound to form the Lissajous Figure.

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

** Download the latest version of the . **

• 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].

When you use a 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:

• Windows:

• Linux:

Hardware Connection

Please connect the corresponding pins of the Raspberry Pi and the 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.

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 .

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.

We use "analogSetPinAttenuation(PIN_NAME, attenuation)" to configure the gain of a single input pin, or use "analogSetAttenuation(attenuation)" to configure the gain of all analog input pins.

In the actual test, when the 1V standard voltage is input, the ADC values are: 3850/2890/2025/1050. In future productions, the ADC range can be changed by changing the ADC gain without the replacement of the reference voltage source.

Hardware Connection

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

The white 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

The interface for Bittle / Bittle X :

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 .

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 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 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:

#define DAC1 25 

void setup() {  
}

void loop() {
  
  // 8bit DAC, 255 = 3.3V, 0 = 0.0V 
  for(int i = 0; i < 255; i++){
    dacWrite(DAC1, i);
    delay(10);
  }
}

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+:

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.

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 initialization startup mode 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 regular startup mode.

• 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 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 regular startup mode.

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

You can find the PetoiRobot library in the following directory. There are all the definitions of API interfaces in the PetoiRobot.py

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

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

Here is a sample code :

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

BiBoard is equipped with an infrared sensor, which is connected to the 23rd pin. The use of infrared is exactly the same as which is on Arduino UNO based on AVR.

First download the 2.6.1 version of the IRremote library, you need to manually select the 2.6.1 version. Because the infrared-related codes have changed in later versions, if you use the 3.X version, the commands will not be translated. In order to be compatible with our previous products, we decided to use the 2.6.1 version after testing.

When using NyBoard, in order to ensure that the code can be compiled smoothly, we need to remove unnecessary code in the IRremote library, that is, remove the encoder/decoder that we don't use, and only keep the NEC_DECODER, which is the 38KHz signal decoder in NEC format.

Due to the flash memory capacity of BiBoard is “huge”, we don’t need to remove unnecessary code in the IRremote library.

Finally, a demo is attached, which accepts infrared signals and prints via the serial port. You can also use official demo for testing.

#include <Arduino.h>
#include <IRremote.h>

int RECV_PIN = 23;

IRrecv irrecv(RECV_PIN);

decode_results results;

void setup() {
  Serial.begin(115200);
  irrecv.enableIRIn();
  Serial.println("IR Receiver ready");
}

void loop() {
  if (irrecv.decode(&results)) {
    Serial.println(results.value, HEX);
    Serial.print(" - ");
    irrecv.resume(); // Receive the next value
  }
  delay(300);
}

MPU6050 is the most widely used 6-axis gyroscope, which can not only measure 3-axis angular velocity and 3-axis acceleration more accurately, but also use the built-in digital motion processor (DMP) for hardware based attitude fusion calculation. So novices can use it very conveniently. For this reason, we also use MPU6050 gyroscope.

There are many demos of MPU6050 on Arduino UNO, the most famous is jrowberg's I2Cdev and MPU6050DMP library:

Unfortunately, this library cannot be run directly on BiBoard based on ESP32. We found the ported library on Github, which is easy to use. This library adds the definition of PGMSpace for the ARM and ESP series, adds the calibration function, and removes the FIFO overflow processing function (friends who are interested can use Beyond Compare for code comparison). The library contains I2Cdev and MPU6050, the address and compressed package are as follows:

After the download is complete, create a MPU6050 folder under Documents/Arduino/library, and copy the library files in the compressed package into it. The library of this modified MPU6050 is also compatible with ARM and AVR, so if you have the original I2Cdev and MPU6050 libraries in your computer, you can delete them.

We can use the official MPU6050_DMP6 demo.

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.

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 , , and .

Download & Installation

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

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 Mac 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 older Windows machines.

Depending on your existing Python configuration, you may need to upgrade to Python3 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.

Open Source Codes

The source code is written with Tkinker in Python3 and is.

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

• UI.py

-> FirmwareUploader.py

-> Calibrator.py

-> SkillComposer.py

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

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 .

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 on Github for the best compatibility and the newest features.

Download and installation

The app works on both Android and iOS devices.

APK

You can also download the Android APK and install it on your phone. You need to unzip it before installation.

If the Bluetooth dongle blinks while the connection panel within the App shows a blank Bluetooth connection list, first check if you have given the Bluetooth and location permission to the App. If it still shows a blank list, you may try to install the previous stable version.

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

The usage of EEPROM is the same as Arduino UNO, there are two operations: read and write.

Read:

• I2C address of EEPROM

• The internal address of EEPROM (the address for storing data)

• Read data

Write:

• I2C address of EEPROM

• The internal address of EEPROM (the address for storing data)

• Write data

In the BiBoard demo, the address of EEPROM on the I2C bus is 0x54, and the capacity is 8192Bytes (64Kbit). We sequentially write a total of 16 values from 0 to 15 in the EEPROM from the first address, and then read them for comparison. Theoretically, the data written in EEPROM and the data read from the corresponding address should be the same.

In the NyBoard factory test, we also use this method, but it is more complicated. We will use a fixed list to fill the EEPROM and read it out for comparison.

Note: the EEPROM operations, especially write operations, are generally not put into the loop() loop. Although the EEPROM is resistant to erasing (100,000 times), if a certain block is frequently written in the loop, It will cause the EEPROM to malfunction.

After 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

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:

Do joint calibration automatically

• Serial Monitor: Send serial command "c16". The robot will enter its resting posture. Push the robot down flat onto the table, move its head straight forward, and send a space character(‘ ’) in the serial monitor. The robot will automatically set the calibration values of all its joints. Some joints can still be off and require standard calibration, but it saves most of the time.

• Mobile app: Create called "Auto calibrate"(customizable) and use the code: c16 . The robot will enter its resting posture. Push the robot down flat onto the table, and and move its head straight forward. Create called "Quit"(customizable) and use the code: "d" to continue to the automatic calibration step. The robot will automatically set the calibration values of all its joints. Some joints can still be off and require standard calibration, but it saves most of the time.

Movement following

• Serial Monitor: Send the serial command "fF", then slowly drag one of the legs. The other legs will follow the motion. Send another serial command to quit.

• Mobile app: Create called "following"(customizable) and use the code: fF Create called "Quit"(customizable) and use the code: d to quit this mode.

Learn a new skill by rotating servos

• Serial Monitor: Send serial command 'fl', which means learning new movements. Move the legs to your intended starting position, then keep the robot steady for about 2 seconds. The robot will count down and then beep slightly to indicate that it has started recording. It won't record small movements, so you can pause in the middle. After 124 frames, if you enter any character in the serial monitor or stop moving it for over 2 seconds, it will stop recording. Send serial command 'fr', which means replay to recall the taught movement.

• Mobile app: Create called "start learning"(customizable) and use the code: fl which means learning new movements. Move the legs to your intended starting position, then keep the robot steady for about 2 seconds. The robot will count down and then beep slightly to indicate that it has started recording. It won't record small movements, so you can pause in the middle. After 124 frames, if you enter any character in the serial monitor or stop moving it for over 2 seconds, it will stop recording. Create called "replay"(customizable) and use a space character as the code: fr to which means replay to recall the taught movement.

• The skill will also be printed on the (as pictured below), and you can import it into and the .

If you wish to write new applications based on the feedback servo, refer to the source codes in OpenCatEsp32/src/espServo.h.

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

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.

4. Follow the on-screen instructions(default settings). Setup can take 10 minutes or more.

5. A terminal window opens. You have a Debian 11 (Bullseye) environment. You can run Linux commands, install more tools using the APT package manager, and customize your shell.

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:

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”

• “kbalance”

• “kwkF”

• “ktrL”

• “d”

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

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.

  • If you have upgraded the firmware at least once after a new download, You can click the Update the Mode Only button. It's faster to only switch the modes without refreshing the parameters.

• Please download the latest code from . Follow the steps for . and activate this line of code in OpenCat.ino #define MAIN_SKETCH

  #define GROVE_SERIAL_PASS_THROUGH

  Then, upload and power on the robot. Use the data cable and to connect with the computer or and complete the pairing.

Note that the gyroscope function is turned off with the Mind+ mode on NyBoard to save memory space. The robot won't be able to self-balance and auto-recover.

After uploading the firmware, plug in the battery to the NyBoard, install it to the chassis and long-press the battery button to power on the robot.

Connect method

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

• Wireless connection(Bluetooth)： The kit includes a connecting the robot's mainboard to the computer.

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:

Examples

Below is a very simple example on how to use the library.

see for a more comprehensive example.

Free curricular

The pre-assembled robot should have the legs installed, but you can further improve its performance by fine-tuning the joints' calibration.

Make sure you have uploaded the OpenCat Main function firmware before calibrating.

This is a cool tutorial video made by one of our users, which briefs the process and explains its logic.

Calibration Stand

* The logic behind calibration is:

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

2. The robot has a "calib" posture with all joints set at zero degrees. You can put the robot to the calib posture 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.
3. 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.

The principles are the same for Nybble and Bittle.

Prepare to Enter the Calibration State

Entering calibration mode requires the following preparations: ‌

1. All servo circuits are connected to the mainboard

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

3. Connect the robot to a computer or mobile phone

• Fon NyBoard, the USB adapter or Bluetooth dongle 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.

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.

• Use the Mobile App Petoi

• Use Petoi Desktop App

• Use Arduino IDE

Install the screws

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

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

1. Preparation

BiBoard V0

The infrared receiver for Bittle X (mainboard type: BiBoard V0) is on the microcontroller near the neck of Bittle X.

NyBoard V1

The infrared receiver for Nyboard is near the tail of the Bittle robot dog.

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

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.

Abbreviations for key definitions can reduce SRAM usage. Due to the limited keys of a physical remote, you can change the definitions for convenience.

We also made a customized remote panel for future batches. Previous users can download the design file and print it on A4 paper.

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 Nybble 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 F/L/R will make the robot move forward/left/right

• B 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.

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

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

• When the robot is walking, you can let it climb up/down a small slope (<10 degrees)

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.

Part 1: Hardware Setup

1.1 hardware list

• USB Uploader (CH340C)

• WiFi ESP8266

1.2 Connection

Insert the ESP8266 module into the module configuration interface of the USB uploader, and find the corresponding COM port in the Windows device manager.

Part 2: Software Setup

2.1 Download Thonny

Download the latest version of Thonny, an out-of-the-box Python editor that natively supports MicroPython.

Download address: https://thonny.org/

2.2 Download the MicroPython firmware

The compiled ESP8266 firmware is provided on the MicroPython official website, because our WiFi module is 4MB, please select the latest firmware with the name of ESP8266 with 2MiB+ flash, and download the bin file.

Firmware download address: https://micropython.org/download/esp8266/

2.3 Upload the MicroPython firmware to the ESP8266 module

There are two ways to upload the MicroPython firmware to the ESP8266 module:

• Using the ESPtool download tool, you can more precisely control the partition and use of Flash.

• Using Thonny's built-in tool.

For convenience, we use Thonny's built-in tool. The specific steps are as follows:

1. Open the Thonny, the main interface is as shown below. Thonny uses the Python interpreter in the installation directory by default.
2. Open Tools -> Options to enter the options page. In the first tab General, we can choose the language we need (needs to be restarted).
3. Open the second tab Interpreter, we replace the default Python3 interpreter with MicroPython (ESP8266) and select the corresponding port.
4. At this time, the ESP8266 module has not yet uploaded the MicroPython firmware. Click "Install or update firmware" in the lower right corner of the above picture to update the firmware using the built-in tool.

5. Select the port (COMx) where the ESP8266 module is located, and select the location where the downloaded MicroPython firmware (.bin file) is located. Check the flash mode: from image file (keep) (the speed will be slower, but it only needs to be burned once and it is not easy to make mistakes), and check the option Erase flash before installing. Press the Install button.
6. The progress will be displayed in the lower-left corner of the interface, erase the Flash first, and then write the firmware. When the word Done appears, it means that the programming has been completed.
7. The software preparation work is over, and the following display will appear after closing the download interface. The red text is garbled because ESP8266 will print a string of codes with a baud rate other than 115200 when it starts up. This code cannot be recognized by MicroPython Shell. When Python’s iconic symbol >>> appears, it means that the firmware is uploaded successfully.

There's also a ROS wrapper for developpers to easily connect to the ROS environment. It is recommended to use ROS with Raspberry Pi.

Using ROS on Raspberry Pi

Currently, it's recommended to install ROS using docker.

• install docker on Raspberry Pi (ref)

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

• prepare workspace

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

• run the container

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

• source files and build inside the container

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

• run examples (see Examples for more)

rosrun opencat_examples opencat_examples_serial

Using ROS for remote control

Ros is designed with distributed computing in mind. Here's a simple example on how to run nodes on different machines.

• on host machine (usually more powerful than Raspberry Pi)

# launch server
roscore

• run service node on Raspberry Pi

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

• send command from host

rosrun opencat_examples opencat_examples_client_cpp

Examples

• using serial library

rosrun opencat_examples opencat_examples_serial

• using ROS service

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

Projects

There are some great projects from the users who contributed:

• Bittle_ROS2

• FinoBot

1. The introduction of PWM function on BiBoard (ESP32)

The ESP32 used by BiBoard is different from the 328P used by UNO. Because the PWM of ESP32 uses the matrix bus, it can be used on unspecified pins.

The PWM of ESP32 is called LED controller (LEDC). The LED PWM controller is mainly used to control LEDs, and it can also generate PWM signals for the control of other devices. The controller has 8 timers, corresponding to 8 high-speed channels and 8 low-speed channels, totaling 16 channels.

Compared with UNO, directly use "analogWrite()" to input any duty ratio between 0-255. The PWM control of ESP32 on BiBoard is more troublesome. The parameters that need to be controlled are as follows:

1. Manual selection of PWM channels (0-15) also improves the flexibility of the use of pins

2. The number of bits of the PWM waveform determines the resolution of the duty cycle of the PWM waveform. The higher the number of bits, the higher the accuracy.

3. The frequency of the PWM waveform determines the speed of the PWM waveform, the higher the frequency, the faster the speed.

The frequency of the PWM waveform and the number of bits are relative, the higher the number of bits, the lower the frequency. The following example is quoted from the ESP32 programming manual:

For example, when the PWM frequency is 5 kHz, the maximum duty cycle resolution can be 13 bits. This means that the duty cycle can be any value between 0 and 100%, with a resolution of ~0.012% (2 ** 13 = 8192 discrete levels of LED brightness).

The LED PWM controller can be used to generate high-frequency signals, enough to clock other devices such as digital camera modules. Here the maximum frequency can be 40 MHz, and the duty cycle resolution is 1 bit. In other words, the duty cycle is fixed at 50% and cannot be adjusted.

The LED PWM controller API can report an error when the set frequency and duty cycle resolution exceed the hardware range of the LED PWM controller. For example, if you try to set the frequency to 20 MHz and the duty cycle resolution to 3 bits, an error will be reported on the serial port monitor.

2. Configure the PWM frequency on BiBoard in Arduinoin Arduino

As shown above, we need to configure the channel, frequency and number of bits, and select the output pin.

Step 1: Configure the PWM controller

Step 2: Configure the PWM output pins

Step 3: Output PWM waveform

In the demo, we choose IO2 as the output pin, connect IO2 to an LED, and you can observe the effect of the LED breathing light.

3. Complete code:

The previous tutorial realized the function of the robot to perform sequence actions by editing Python code offline. But this is very inconvenient. Whenever we need to modify the code, we need to unplug the WiFi module for modification, and we cannot flexibly pause and modify parameters during execution. The reason is that ESP8266 only has one serial port, and we need to use it to communicate with NyBoard. Fortunately, MicroPython uses the WiFi function provided by ESP to realize remote wireless Python debugging - WebREPL.

The official document

On the basis of official documents, combined with the characteristics of ESP8266, we wrote the following tutorials:

1. Enable webREPL

After connecting the device, enter import webrepl_setup in the shell interface, and input according to the prompt information:

1. Enable it running on boot: E

2. Set password for it: your own password(e.g. 1234)

3. Repeat the password to confirm

4. Reboot the ESP8266: y

2. The script to setup webREPL

We use the demo script below, to replace the SSID and password with the network information your own around you.

import network
import time
import webrepl

def do_connect():
    
    # WiFi SSID and Password
    wifi_ssid = "YOUR SSID"             # YOUR WiFi SSID
    wifi_password = "YOUR PASSWORD"     # YOUR WiFi PASSWORD

    # Wireless config : Station mode
    station = network.WLAN(network.STA_IF)
    station.active(True)

    # Continually try to connect to WiFi access point
    while not station.isconnected():
    
        # Try to connect to WiFi access point
        print("Connecting...")
        station.connect(wifi_ssid, wifi_password)
        time.sleep(10)

    # Display connection details
    print("Connected!")
    print("My IP Address:", station.ifconfig()[0])
    

if __name__ == "__main__":
    do_connect()
    webrepl.start()

After running the script, it will keep trying to connect to the WiFi network. Once connected, it will automatically start the WebREPL service of the device.

Connected!
My IP Address: 192.168.xxx.xxx
WebREPL daemon started on ws://192.168.xxx.xxx:8266
Started webrepl in normal mode

Remember this IP address (automatically assigned by router DHCP), useful when configuring WebREPL.

3. Configure the WebREPL service

We are now debugging the Python script through WebREPL, and the previous serial port is used to communicate with NyBoard. So in the options, change the previous USB-COMx interface to WebREPL.

Then we fill in the IP address, port and password of WebREPL, and click OK.

When WebREPL Connected is displayed, the connection is successful.

We can try some simple scripts, such as blink.py.

WebREPL saves serial ports and supports wireless debugging. The disadvantage is that the speed is slow (because of network delay), and the waiting time for software reset is relatively long.

4. Separate the serial port from the debugger

Now we can use webREPL to debug the script, but when we open the serial port monitor, we will find that whenever we run the script, the serial port will send out a series of debugging content: These massive strings will cause the NyBoard to be too late to process and crash. As shown below：

We hope that when debugging the program, the serial port only outputs the commands we want to output, not the Debug information. Open the boot.py on the device, uncomment the line of code uos.dupterm(None, 1) and save it , and unbind the serial port and REPL debug. Restart the module, and the serial port debugging assistant will no longer print the debug information.

As a supplement, we can output debug information through the print() statement, which will be displayed in the Shell through WiFi.

So far, you can easily use the ESP8266 to debug robot through webREPL to edit action sequences based on MicroPython.

Overview

BiBoard Hat V1.0 is the extension board of BiBoard V0, which allows for convenient connection of the voice command and other Grove extensible modules.

Connection to the BiBoard

Peripherals

The extension hat has an onboard voice command module and four grove sockets.

• 1x Serial2 port (GPIO16, 17).You must dial the slide switch to UART2 to free it for regular serial communication or GPIO. In that case, the Tx pin (GPIO 17) can be used to write.

• 1x I2C port （GPIO21, 22). It's already used by the main program to read sensors. If you use the BiBoard as a regular ESP32 board without Bittle's firmware, they can be configured as regular GPIO pins to read and write.

• 2x input-only pins (GPIO 34, 35, 36, 39).

Introduction to the onboard components

Voice command module

It's equivalent to the independent Grove voice module introduced in the extensible modules.

Grove sockets

We adopted the Grove sockets for convenient plug-and-play connections. There are three types of sockets:

UART2 / Voice command switch

UART2 shares the GPIO ports with the voice command module. When the switch is dialed to VOICE COMMAND, the Serial2 port can NOT be used. You can dial the slide switch to UART2 to free it for regular serial communication or GPIO.

The function of the switch is shown in the figure below：

You can solder a 2x5 socket on NyBoard to plug in a Raspberry Pi. Pi 3A+ is the best fit for NyBoard's dimension.

Nybble

Bittle

The red can be 3D printed.

As shown in the , the arguments of tokens supported by Arduino IDE's serial monitor are all encoded as Ascii char strings for human readability. While a master computer (e.g. RasPi) supports extra commands, mostly encoded as binary strings for efficient encoding. For example, when encoding angle 65 degrees:

• Ascii: takes 2 bytes to store Ascii characters '6' and '5'

• Binary: takes 1 byte to store value 65, corresponding to Ascii character 'A'

Obviously, binary encoding is much more efficient than the Ascii string. However, the message transferred will not be directly human-readable. In the OpenCat repository, I have put a simple Python script that can handle the serial communication between NyBoard and Pi.

1. Config Raspberry Pi serial port

In Pi's terminal, type sudo raspi-config

Under the Interface option, find Serial. Disabled the serial login shell and enable the serial interface to use the primary UART:

1. Run raspi-config with sudo privilege: sudo raspi-config.

2. Find Interface Options -> Serial Port.

3. At the option Would you like a login shell to be accessible over serial? select 'No'.

4. At the option Would you like the serial port hardware to be enabled? select 'Yes'.

5. Exit raspi-config and reboot for changes to take effect.

If you plug Pi into NyBoard's 2x5 socket, their serial ports should be automatically connected at 3.3V. Otherwise, pay attention to the Rx and Tx pins on your own AI chip and its voltage rating. The Rx on your chip should connect to the Tx of NyBoard, and Tx should connect to Rx.

2. Change the permission of

If you want to run it as a bash command, you need to make it executable:

chmod +x ardSerial.py

You may need to change the proper path of your Python binary on the first line:

#!/user/bin/python

3. Use ardSerial.py as the commander of robot

Typing ./ardSerial.py <args> is almost equivalent to typing <args> in Arduino's serial monitor. For example, ./ardSerial.py kcrF means "perform skill crawl Forward".

Both ardSerial.py and the parsing section in OpenCat.ino need more implementations to support all the serial commands in the protocol.

Overview

NyBoard V1 is an upgraded version considering the users' feedback on NyBoard V0. It's compatible with previous versions, yet has some new design to make it easier to use.

• It still uses Atmel ATMega328P as the main chip but adopts 16MHz without accelerating it to 20MHz. Now the board is fully compatible with Arduino Uno, much easier for new users to Arduino.

• It keeps driving 16 PWM channels with PCA9685. The pin order is altered, but you don't even need to read the indexes on the board, because the pin mapping is handled within the software.

• Now the 6-axis motion sensor MPU6050 is designed on the PCB, rather than a stand-alone module soldered above the board. It supports a built-in DMP (Digital Motion Processor) to calculate the motion data, as well as providing raw data for your own fusion and filtering algorithms.

• It continues to use an 8KB onboard I2C EEPROM to save constants for skills.

• The power system is redesigned to provide a more stable supply. The structure for peripherals is also optimized.

• From Jan 1st, 2021, We start to include an official Bluetooth dongle for wirelessly uploading and communication. The default baud rate for all the communication ports is set to be 115200.

• The reset button is more accessible on the back of the board.

• We added 4 Grove socket to plug-and-play Seeed Studio's extensible modules. We still provide standard 2.54mm through-holes besides the socket.

• We added 7 WS2812 RGB LEDs on the board as another form of output and status indicator.

• The socket for the battery is now anti-reverse.

Logic diagram of the controller

The configuration of NyBoard V1_0 is shown as below:

Introduction to the onboard components

Main controller

NyBoard V1_0 uses Atmel ATMega328P-MUR as the main controller. We adopted its smaller version of QFN32 for better layout, and it's near-identical to regular TQFP32.

ATMega328P works at 16MHz with a 5V supply. It has 2KB SRAM, 32KB Flash, and 1KB on-chip EEPROM. With the same bootloader of Arduino Uno, you can upload sketches through the serial port.

I2C switch

The main chip runs at 5V, while the other peripherals run at a 3.3V logic level. We use PCA9306 to convert the I2C bus of ATMega328P to 3.3V. We also added an I2C switch on the bus. By dialing it to "Arduino" or "Raspberry Pi", you can change the I2C master of the onboard peripherals.

6-Axis IMU MPU6050

MPU6050 is widely used in many DIY projects to acquire the motion state of devices. It detects the 3 acceleration and 3 angular motion states. It also includes a DMP to calculate the state directly, without using the main controller's computational resources.

On NyBoard V1_0, its I2C address is 0x68. The interrupt pin is connected to the PD2 port of ATMega328P (or the D2 pin of Arduino Uno).

There are a lot of available MPU6050 libraries and we are using I2CDev/6050DMP. You can also use other versions:

PCA9685 and the PWM servo ports

PCA9685 fans out 16 PWM 12-bit channels with instructions from the I2C port. Its address is set to 0x40. There are 16 PWM indexes printed on the PCB, but you don't really need to read them because the pin-mapping is done in the software. The physical wiring pattern is the same as the previous boards. You do need to check the direction of the servo pins. Regular servos have 3 pins for PWM, power(2S), and ground (GND). The ground should connect to the black wire of the servo.

On NyBoard V1_0, the servos' power connects to the 2S Li-ion battery. We designed our servos to be compatible with 8.4V input. Regular servos usually run at 6V. You should not connect regular 9g servos like the SG90 to the board directly.

We use Adafruit PWM Servo Driver Library for PCA9685.

EEPROM

We save the motion skills with an 8KB onboard I2C EEPROM AT24C64. Its I2C address is 0x54. The lookup table of skills is saved in the 1KB on-chip EEPROM of ATMega328P. It uses <EEPROM.h>. You need to pay attention to their differences when developing new codes.

Passive buzzer

The buzzer is driven by PD5 (or the D5 of Arduino UNO). The current is amplified by 2N7002 MOS.

Infrared receiver

We use VS1838B as the Infrared receiver, connected to PD4 (or D4 on Arduino Uno). It's driven by the IRremote library of Arduino, the corresponding remote is encoded in NEC format. You may disable the other protocols in IRremote.h to save Flash (about 10%!)

Voltage detector

The two LEDs in the Petoi logo indicates the powering state of the board. The left eye is blue for the logic chips. The right eye is yellow for the servos' power. When NyBoard is connected to the battery, both LEDs should lit up. When NyBoard is powered by the USB downloader, only the blue LED will lit up.

There's an anti-reverse socket for the battery. The battery's output is connected to ADC7 (or A7 of Arduino Uno) and is not threaded to an open pin. ADC7 collects the voltage over a voltage divider. The actual voltage is approximately 2x of the reading. A safe range of battery voltage is below 10V.

You should charge the battery in time when the battery is lower than 7.4V.

WS2812 RGB LED

We added 7 WS2812 RGB LEDs (or the NeoPixel) on the NyBoard. The pin number is D10. They are powered by the 5V DC-DC power chip for Raspberry Pi and are independent of the 5V network of ATMega328P. So you need to plug in the battery to power the LEDs.

Grove sockets

We adopted the Grove sockets for convenient plug-and-play connections. There are three types of socket:

Power system

The main chips are powered by a Low-dropout (LDO) linear regulators for noise removal and better stability. We use LM1117-5V and XC6206P-3.3V to power 5V and 3.3V chips. The 3.3V LDO is connected in serial after the 5V LDO for better efficiency.

There's a diode between the battery and LM1117-5V to prevent damage by the wrong connection. There's a self-recover fuse (6V 500mA) on the USB uploader to limit the current and protect the USB port.

The Raspberry Pi consumes much more power, so we choose TPS565201 DC-DC to provide a 5V 3A output. The peak output can be 5A and with high-temperature/current/voltage protection. It will cut off the power when the chip keeps outputting >4A and over 100 Celcius degrees until the temperature drops to normal. The WS2812 RGB LEDs are also powered by this DC-DC source.

The servos are powered by 2S Li-ion batteries directly. Pay attention not to short connect the power or any pins on the NyBoard.

Last updated: Jan 13, 2021

After uploading the MicroPython firmware on ESP8266, we can use it run MicroPython scripts.

1. Run the script directly

We can execute the python scripts directly in the interpreter.

2. Use the .py file to run the script

The NyBoard WiFi module ESP8266 uses the IO2 pin to connect with a red LED to indicate the connection status. This LED is programmable. Write a simple python blink script:

Press the green start button on the toolbar, and the script will be sent to the WiFi module through the serial port, and then run after being interpreted by the built-in MicroPython interpreter of ESP8266. Because the Blink script is an endless loop when it needs to stop, press the red stop button to end the program interruption and reset.

3. Upload the .py file to the ESP8266

We can click View -> File to open the file toolbar, and the file is displayed on the left side of Thonny. The upper part is the directory of the local machine, and the lower part is the files stored in the MicroPython device. By default, there is only one boot.py file, please do not delete this file, it is the startup file of the MicroPython device.

We save the script as blink.py and save it on the machine, right-click on the file and select Upload to / :

Select the MicroPython device in the pop-up window:

There is a blink.py file on the device. So the file is saved on the device.

4. Write a script to let robot perform actions sequentially

ESP8266 can send commands to NyBoard through the serial port. We only need to write a simple serial port sending script to send a series of serial port commands to NyBoard, and then the robot can execute sequence actions.

When the actSeq() function is executed, It can output a series of commands through the serial port. Using the serial monitor we can debug. Use the serial port monitor to monitor the output as follows (for the convenience of reading, please use the automatic frame break of the serial port debugger, in fact, there is no automatic line break).

5. Power on and run automatically

After we debug the sequence action, unplug the ESP8266 and plug it into the NyBoard, the robot dog does not respond because the actSeq() function is not running. We want to run the scripts automatically after power on. There are two methods:

• Please change the file name to "main.py" and save to the device (Recommend)

• Modify the Boot.py

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 .

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

Petoi Desktop App works on both Nybble and Bittle controlled by NyBoard based on ATmega328P or Bittle X controlled by BiBoard based on ESP32.

Connect the mainboard to the computer

You can connect the computer to the mainboard using a USB cable, following the instructions on the subsequent sub-pages, which are specific to the robot's mainboard model. To see the sub-pages as in the following picture:

Upload the firmware using the Petoi Desktop app

Open the PetoiDesktopApp

After properly connecting the USB uploader, open the PetoiDesktopApp (for Windows: UI.exe / for Mac: Petoi Desktop App), and select your Model and Language.

Menu bar in Petoi Desktop APP

Click the Firmware Uploader button

Auto Detect the Serial Port

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

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

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：

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:

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 connecting the robot to the computer.

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

Select the correct options to upload the latest firmware.

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.

Check the log file

If the uploading fails, the following message box will pop up:

The log file is located at:

• For Windows: The log file is in the same directory as UI.exe
• For macOS: You can check the log file as follows:

When you contact our [email protected], please attach the log file to your email.

1. Introduction

BiBoard is a robot dog controller based on ESP32 developed by Petoi LLC. Unlike NyBoard, which is for regular users and robot lovers, BiBoard mainly faces developers and geeks. High-performance processors, larger memory and storage (16 MB of Flash), and wireless connections. Audio function is also included.

2. Modules and functions

The function partition for BiBoard is shown below:

Block diagram for BiBoard is shown below:

3. Module details:

3.1 Power

There're 2 ways to power the BiBoard: USB 5V and battery socket 7.4V.

When using USB power, there’s no power output for DC-DC 5V extension and servo. So USB power mainly supplies ICs.

When using battery power at 7.4V (maximum: 8.4V). Both servos and 5V power will be supplied. You can use 5V powering the Raspberry Pi.

3.2 On board modules

3.2.1 Set up ESP32 development environment

Open “Preferences” in Arduino, add ESP32 development board URL:

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

Save it and then exit.

Open “Boards Manager...” and wait for updates from external board support links. Search “esp32” and install the support package.

After showing “INSTALLED”, the BiBoard board support package is finished.

3.2.2 USB Downloader

There’s no USB circuit in the ESP32, so we use the CP2102 USB bridge as officially recommended. The maximum download baud is 921600. The bridge is connected to serial 1 of the ESP32.

We use the USB Type-C port; 2 resistors, CC1 and CC2, are added as the identifier.

We tried the automatic download circuit designed by ESP and the NodeMCU, but none of them works perfectly. So we modified the circuit by adding the third transistor and enlarger the capacitor.

The transistors receive standard serial modem signals DTR and RTS and trigger a unique timing-sequence forcing ESP32 into download mode and then reboot. The detail of the automatic download circuit is shown below.

3.2.3 IMU

We use Invensense MPU6050, the most widely used IMU. Its I2C address is 0x68, and DMP’s interrupt is connected to IO26 of the ESP32.

With the help of Jrowberg’s MPU6050 DMP library, you can easily get the motion status of the Bittle. The Jrowberg’s MPU6050 library must be modified to adapt ESP32. The data types of “int8” and “PGMSpace” should be pre-defined instead of 8-bit AVR macros. We offer the modified library of MPU6050. You can replace the original library so that both AVR boards and ESP boards would be worked normally.

3.2.4 EEPROM

There is a 64Kbit EEPROM on the BiBoard. You can directly use the EEPROM read and write a program that is used on the Arduino UNO. You can use it to store calibration data.

There is also an example program named “EEPROM” in the ESP32 support package. This is not the demo code of the I2C EEPROM. That’s the demo of the simulated EEPROM by ESP32’s QSPI flash memory.

3.2.5 DAC and audio applications

We use DAC output and a class-D amplifier instead of a PWM buzzer to make Bittle more vivid. You can use 3 ways to drive the audio module:

1. Use Arduino “Tone()” function.

2. Use ESP32 “dacWrite()” function like “analogWrite()” in Arduino. The data quality produced by the DAC is better than the PWM.

3. Use ESP MP3 decode library developed by XTronical, you can play MP3 files. You should configure a file system like SPIFFS or FAT in the flash before you use this MP3 decoder.

URL：https://www.xtronical.com/basics/audio/dacs-on-esp32/

3.2.6 IR modules

The IR sensor on Nyboard and BiBoard are the same, so you can directly use the sketch from the Nyboard. The BiBoard’s flash is large enough so that you don’t have to disable macros in IRremote.h.

4. Servo sockets

There’re 12 PWM servo sockets on the BiBoard, and the pin number is marked near the socket.

We transform the direction of the PWM servo socket by 90 degrees since the size of the ESP32 module. You should connect the wires first before you screw the BiBoard on the cage.

5. Extension sockets

There’re 3 extension sockets on the BiBoard that marked with P15, P16 and P17.

5.1 Analog input sockets（P15）

This socket is used for analog input extension, you can try to connect foot press sensors to this socket.

5.2 Bus extension sockets（P16）

This socket is used for bus extension of the ESP32.

5.3 Raspberry Pi interface (P17)

You can use this interface to connect to the Raspberry Pi, but you cannot directly mount the Raspberry Pi above the BiBoard. Use wires or adapters instead.

1. Function introduction

ESP-NOW is another wireless communication protocol developed by Espressif that enables multiple devices to communicate without or using Wi-Fi. This protocol is similar to the low-power 2.4GHz wireless connection commonly found in wireless mice—the devices are paired before they can communicate. After pairing, the connection between the devices is continuous, peer-to-peer, and does not require a handshake protocol. It is a fast communication technology with short data transmission and no connection, which allows low-power controllers to directly control all smart devices without connecting to a router. It is suitable for scenarios such as smart lights, remote control, and sensor data return.

After using ESP-NOW communication, if a certain device suddenly loses power, as long as it restarts, it will automatically connect to the corresponding node to resume communication.

The communication modes supported by ESP-NOW are as follows:

• one-to-one communication

• one-to-many communication

• many-to-one communication

• many-to-many communication

ESP-NOW supports the following features:

• Unicast packet encryption or unicast packet unencrypted communication;

• Mixed use of encrypted paired devices and non-encrypted paired devices;

• Can carry payload data up to 250 bytes;

• Support setting sending callback function to notify the application layer of frame sending failure or success.

At the same time, ESP-NOW also has some limitations:

• Broadcast packets are not supported temporarily;

• There are restrictions on encrypted paired devices

  • In Station mode，a maximum of 10 encrypted paired devices are supported;

  • In SoftAP or SoftAP + Station mixed mode, a maximum of 6 encrypted paired devices are supported;

  • The number of non-encrypted paired devices is supported, and the total number of encrypted devices does not exceed 20;

• Valid payloads are limited to 250 bytes.

Petoi group control can use the ESP-NOW communication function of the ESP8266.

2. Setup for ESP-NOW

2.1 Hardware setup

In this case, two Bittles (equipped with ESP8266) and one computer connected with ESP8266 are prepared.

See below for program uploading and MAC address acquisition of the module in the figure.

2.2 Software setup

Install Thonny on the computer to facilitate the debugging of MicroPython of the ESP8266 module. When using the ESP-NOW protocol, special MicroPython firmware is required (see ). Because the normal version of the 8266-MicroPython firmware will prompt that the library cannot be found.

Open Thonny and use the USB uploader to connect the ESP8266 module, enter in the shelll interface:

If there is an error prompt such as "cannot find espnow module", it means that there is a problem with the firmware uploading; if there is no prompt, it means that the firmware uploading is successful.

3. Code introduction

The group control code is divided into 3 parts:

• Query the MAC address of the module

• Transmitter program

• receiver program

3.1 Query the MAC address of the module

The MAC address is an address used to confirm the location of a network device, and is responsible for the second layer (data link layer) of the OSI network model. The MAC address is also called the physical address and the hardware address. It is burned into the non-volatile memory (such as EEPROM) of the network card when it is produced by the network equipment manufacturer.

The length of the MAC address is 48 bits (6 bytes), usually expressed as 12 hexadecimal numbers. The first 3 bytes represent the serial number of the network hardware manufacturer, which is assigned by IEEE (Institute of Electrical and Electronics Engineers), and the last 3 bytes represent the serial number of a certain network product (such as a network card) manufactured by the manufacturer. As long as you don't change your MAC address, the MAC address is unique in the world. Visually speaking, the MAC address is like the ID number on the ID card, which is unique.

The easiest way to use ESPNOW is to send it by MAC address. We use a small program to query the MAC address of the module.

After running in Thonny, print out the MAC address in the terminal. At this time, you can use a self-adhesive sticker to write the MAC address of the module and paste it on the module.

3.2 Transmitter program

The transmitter program consists of the following parts:

• Enable the WiFi function of the module

• Configure the ESP-NOW protocol and enable it

• Add a node (peer) that needs to communicate

• Send a message

The specific code is as follows:

3.3 Receiver program

The receiver program is mainly composed of the following parts:

• Enable the WiFi function of the module

• Configure the ESP-NOW protocol and enable it

• Add a node (peer) that needs to communicate

• Receive and decode the message, and send commands to NyBoard through the serial port

The specific code is as follows:

This code is encapsulated in a function named espnow_rx() for the convenience of automatically starting the program after power-on.

There are two ways to realize automatic startup after power-on:

• Rename the code file to main.py;

• Modify the boot.py ;

For beginners, we recommend the first method.

3.4 Communication-Command Converter

Writing the serial command conversion at the receiving end will make the program too complicated and difficult to maintain. We can create a new function in which to perform instruction conversion and output commands.

Prepare for calibration

Enter the calibration state

After the robot is powered on by the battery, there are 2 methods to enter the calibration state.

Use Bittle for example:

• Click the Start Calibration button.
• Click the Calibration button in the calibration interface.

For the construction kit, you can install the body parts to the robot torso according to the instructions in the following sub-pages based on the products you choose.

When calibrating, Depending on the product you are using, select the corresponding calibration ruler in the sub-page as an aid. 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), and then click the "+" or "-" button to fine-tune the joint to the right angle state.

Test calibration effect

You can click the skill buttons to switch between Rest, Stand, and Walk to test the calibration effect.

Use Bittle for example:

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

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 servo gears.

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