Connect to the mainboard

NyBoard

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

please download and install the driver:

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

• Windows: http://www.wch-ic.com/downloads/CH341SER_EXE.html

• Linux: http://www.wch-ic.com/downloads/CH341SER_LINUX_ZIP.html

BiBoard

When you use a USB type-C data cable to upload the firmware for the BiBoard, if there is no serial port in the port list of Device Manager.

please download and install the driver:

For more details, please refer to BiBoard Driver to access the serial port.

Upload the firmware

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

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

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

  • If you are using NyBoard, please refer to Upload Sketch for NyBoard.

  • If you are using BiBoard, please refer to Upload Sketch for BiBoard.

1. Preparation

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)

Gaits

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

Postures and behaviors

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

Customized commands

• Press and hold the button and drag to change the button position.

• Double-tap the command button to edit it.

• You can also create a customized single command/group command by pressing the "+" button.

Create a single command

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

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

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

* move Bittle's head (move joint angle)

m0 45

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

m0 -70 0 70

* sit

ksit

* move joints one by one

m 0 -70 0 70 8 -30

* MOVE joints simultaneously

i 0 -45 8 -30 12 -60

Below are the indexes of the joints for your reference. Observe the patterns of the ordering and try to remember them.

* show current joint angles

j

* long meow once (Nybble）

u0 1

* short meow three times (Nybble）

u2 20

* mute/unmute the buzzer beep

b

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

b1

* play a short tone (beep tone duration, duration is 0~256)

b12 20

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

b14 4 14 4 21 4 21 4

More common commands to be added

Please see this list of common commands that may be added as customized commands. You can enter the "Voice command" column values as the "Name" values and the "Customized command code for Petoi mobile app" column values as the "Code" values.

A more detailed command table can be found in the Serial Protocol.

Import new skills as a customized button

Import your local customized skill (created by the Skill Composer)

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

Import new skills from the skill library on GitHub

Create a group command

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

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

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

Click the Delete button to Delete the group command.

Make your robot act randomly

If your robot doesn't have any random behavior, you may need to upgrade your robot to the latest firmware.

Updates and support

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

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.

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

NyBoard

BiBoard

Although the BiBoard has only 12 pins, the joint index numbers are configured in the same order as the NyBoard. The connection between the joint servo and the pin is shown in the figure below：

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.

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 坐下
}

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:

git submodule add https://github.com/PetoiCamp/opencat_serial_cpp opencat_serial

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

cmake_minimum_required(VERSION 3.0.2)
project(serial_examples)
option(CATKIN_ENABLE "Enable using the Catkin make extension to cmake (ie for ROS)" OFF)
add_subdirectory(opencat_serial)
add_executable(serial_examples path/to/cpp)
target_link_libraries(serial_examples opencat_serial)

Examples

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

#include "opencat_serial/opencat_serial.hpp"
int main(int argc, char *argv[])
{
    // connect to the serial device
    OpenCat::Robot rob("/path/to/port");
    // create task
    OpenCat::Task task;
    // set command type to calibration pose
    task.command = OpenCat::Command::CALIB_POSE;
    // time delayed after execution
    task.delay = 2;
    // send command
    rob.SendTask({OpenCat::Command::CALIB_POSE, 2});
    return 0;
}

see examples for a more comprehensive example.

Free curricular

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.

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 Pi standoff can be 3D printed.

As shown in the serial protocol, 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 ardSerial.py 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.

KERNEL=="ttyS0", SYMLINK+="serial0" GROUP="tty" MODE="0660"
KERNEL=="ttyAMA0", SYMLINK+="serial1" GROUP="tty" MODE="0660"

sudo chgrp -h tty /dev/serial0
sudo chgrp -h tty /dev/serial1

sudo adduser $USER tty
sudo adduser $USER dialout

sudo chmod g+r /dev/ttyS0
sudo chmod g+r /dev/ttyAMA0

2. Change the permission of ardSerial.py

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.

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

Download & Installation

You can download the latest version of the desktop App and unzip it.

Before running the app, you must use the included USB adapter or the Bluetooth dongle to connect to a Petoi robot.

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 Anaconda 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 open source.

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.

Hi, thanks for getting a Petoi robot.

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

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 simple joint control

   • Add to the controller panel

   • Play with group commands

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

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

3. Do some coding

   • Follow to

   • some new robotics skills with

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

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.

** Download the latest version of the . **

Prepare for calibration

You need to connect the and USB data cable or (for NyBoard only ) to the computer, install the battery and long-press the button on the battery to power the robot.

Enter the calibration state

After the robot is powered on, there are 2 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.

The Joint Calibrator interface

Nybble

Bittle

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.

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.

Nybble

Bittle

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

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

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

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

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

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

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 motherboard

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)

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.

Install the screws

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

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

Using ROS on Raspberry Pi

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

• install docker on Raspberry Pi ()

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

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

Update：

NyBoard V1_1 is a V1 refreshed version mainly focused on the shortage of the ATMEGA328P-MU in our supply chain.

1. Replace the ATMEGA328P-MU（QFN32=）with the ATMEGA328P-AU（TQFP32）

2. Removed 7 WS2812 LEDs to optimize the area.

3. A green LED is connected to the D10 port with PWM functions.

4. There's no changes of sockets and pin definitions from V1_0, the bootloader and the OpenCat sketchs is fully compatible.

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.

• 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-AU, the same MCU of the Arduino Nano (UNO Compatible).

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

LED（NEW!)

The WS2812 serial RGB LEDs are replaced by a single green LED. You can easily use it with standard Arduino GPIO control commands.

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.

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 regulator 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 servos are powered by 2S Li-ion batteries directly. Pay attention not to short connect the power or any pins on the NyBoard.

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

Prepare Mind+

• Download the latest version from Mind+ official website

  • Windows: >= V1.7.0

  • Mac: version: >= V1.7.3 RC2.0

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

Watch the video tutorials

We provide a series of video tutorials on using Petoi Coding Blocks with the free Scratch-like robotics coding curriculum. Be sure to click next to go through all the videos.

Prepare Petoi Robot

• For Nyboard products (Nybble, Bittle), there are two ways to upload the firmware (Mind+ mode), which supports the Mind+ extension library, and

• Using the Petoi Desktop App

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

• Using the Arduino IDE Please download the latest code from GitHub. Follow the steps for uploading. Set up the configuration mode and activate this line of code in OpenCat.ino #define MAIN_SKETCH

  #define GROVE_SERIAL_PASS_THROUGH

  Then, upload the major functionalities sketch and power on the robot. Use the data cable and USB uploader to connect with the computer or the Bluetooth module 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.

• For BiBoard products (such as Bittle and Bittle X), there is no need to modify any software code. By default, all functional blocks in Mind+ are supported. At the same time, the gyroscope function is turned on; that is, the robot can self-balance and auto-recover.

Import Petoi Mind+ extension library

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

Programming and Running

The principle and process

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

1. Open the serial port

2. Control the robot

3. Close the serial port

The instructions for blocks

Open the serial port

There are two ways to open the serial port:

Deactivate Gyro

When the gyroscope function is turned on, the robot can balance its body in real-time. It may be seen that when the robot is doing preset actions (especially when performing more violent actions), the body will shake back and forth, and even the body will tip over. The robot will automatically perform recovery actions, which may disrupt your preset steps.

If the uploaded sketch is Mind+ mode sketch(#define GROVE_SERIAL_PASS_THROUGH this line is activated), the gyroscope function will be turned off, and the robot will not be able to balance or auto-recover, so there is no need to add this block.

Perform inherent skills

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

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

Perform the last skill exported from the Skill Composer

Use this block to let the robot perform the last skill exported from the Skill Composer.

Perform the skill in the file

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

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

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

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

The folder name {model} is Bittle or Nybble. When exporting a skill file from the Skill Composer, it will automatically save the skill file to this directory.

Rotate joints in a sequence.

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

• Controls individual joint rotations to an absolute angle value.
• Controls individual joint rotations to a relative angle value.
• Control multiple joints to rotate sequentially to absolute angle values or relative angle values.
• Use the joint angle list to control multiple joints to rotate to absolute angle values in a sequence.

Rotate joints simultaneously

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

• Control multiple joints to rotate to absolute angle values or relative angle values at the same time
• Use the joint angle list to control the simultaneous rotation of multiple joints to absolute angle values.

Get the current angle value of a joint.

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

Demo code:

Transform to frame

Use this block to control all joints to rotate at the same time. Please use it with the "Action frame" block. As shown below:

Play a melody

Use this block to control the robot to play music. There are several ways to use blocks together for reference:

• A list made up of multiple "Tone + Duration" blocks
• Using a tone duration list

Execute a serial command

Use this block to send a serial command to the robot, which can provide you with more and more flexible control methods. For example, you can input "kkcL" (kick the left front leg), and "khiR" (raise the right front leg to say hello). For more serial port commands, please refer to the serial protocol.

Write analog value

Use this block to write an analog value to a specified pin. Analog value range: 0~255

Read analog value

Use this block to read an analog value from a specified pin.

Write digital value

Use this block to write a high/low-level value to the specified pin. High-level: 1; Low-level: 0.

Read digital value

Use this block to read the high/low-level value of the specified pin.

Read Ultrasonic sensor distance

Use this block to read the distance value from the ultrasonic sensor.

For the Petoi RGB Ultrasonic Sensor (or RUS-04), you can set the two pins ( Trigger and Echo) like this:

• NyBoard (connects to the D6 and D7 pins)
• BiBoard (connects to the Rx and Tx pins)

Close the serial port

Generally, at the end of the program, it is recommended to use this block to close the serial port communication.

Demos

We provide some demos to download for reference in the GitHub repository (Petoi_MindPlusLib/examples).

Free curricular

A Brief Introduction to the Interface

See .

The Skill Composer Interface

Nybble

Bittle

Menu Options

• Model

  • Nybble

  • Bittle

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

• Language
• Utility

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

Connection and State Dials

Listening / Connect button

Servo

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

Gyro

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

Random

Send a serial command

Preset Postures

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

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

Joint Controller

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

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

You can control multiple joints by clicking the dial "+" or "-" on each slider. All sliders with their "+" pressed will change by the same increments. Sliders with their "-" button pressed will change by the negative increments. The button can be toggled on and off. Click the "Unbind All" button to disengage all the joints at once.

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

Skill Editor

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

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

Basic Operation

The Activated Frame

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

Add a Frame

You can click the "v" button (the 9th item of a frame) to add a frame after the current frame and activate it. The new frame will be identical to the previous activated frame.

Insert a Frame

You don't always add a new frame after the last frame. You can click the "v" button (the 9th item of a frame) of any intermediate frames to insert a new frame below the "v" button. The new frame carries information identical to the previously activated frame.

Mirror a frame

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

Delete a Frame

You can click the "<" button (the 8th item of a frame) to delete the current frame holding the button. All the following frames will shift up. If the activated frame is deleted, its preceding frame will be activated. If the activated frame is the first frame and is deleted, its following frame will be activated.

Add a Note to a Frame

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

Bound joints and passed-through edits

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

Play the Skill Sequence

Besides manually clicking the "=" button (the 2nd item of a frame) to view the single posture, you can click the "Play" button to show the postures in order starting from the activated frame. During playing time, the button's text becomes "Stop" to allow you to stop in the middle.

Export the skill

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

Import the Skill

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

Reset the Skill Editor

You can use the "Restart" button to clear the Skill Editor panel and start over.

Advanced operation

Set up Action Frame Loops

Set Movement Speed

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

Set Delay

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

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

Set Trigger and Angle

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

• None means that there is no trigger and the angle condition is set

• Pitch means the robot body rotates nose-down

• -Pitch means the robot body rotates nose-up

• Roll means that the robot body rolls to its left side (counter-clockwise when looking from the tail)

• -Roll means the robot body rolls to its right side (clockwise when looking from the tail)

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

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

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

Export Mirror Actions

Behavior and Gait Options

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

Simultaneous Control of Multiple Robots

• USB

First, connect the USB uploader to the main board of the robot, and then use the data cable to connect it to the computer's USB interface.

• Bluetooth

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

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

If you want the desktop app to stop detecting serial connections, click the "Connected" / "Listening" button. The text in the button will change to "Connect," and all serial connections will be disconnected. Click the "Connect" button again to restart the real-time detection function.

Professional extensions

You can modify the source code of the Skill Composer in OpenCat/pyUI/SkillComposer.py.

** Download the latest version of the . **

Petoi Desktop App works on both Nybble and Bittle controlled by NyBoard based on ATmega328P or Bittle X controlled by based on ESP32. For NyBoard, more detailed documentation can be found at NyBoard V1_0, NyBoard V1_1, or NyBoard V1_2 (which is similar to NyBoard V1_1).

Connect the mainboard to the computer

NyBoard(for Bittle & Nybble)

Use the .

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

NyBoard Version

You can find the board version number on the NyBoard.

BiBoard(for Bittle X)

BiBoard Version

You can find the board version number on the BiBoard:

Upload the firmware with 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

Select the correct options to upload the latest firmware

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.

  • 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 will show the current progress in real time, as well as the results of key processes.

After the Parameters firmware has been successfully uploaded, the board starts to run the configuration program by itself. 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 pop up showing "Parameter initialization complete!" You must confirm to proceed to the second round of uploading the main functional code.

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.

If you have Arduino IDE programming experience

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.

# Simple script：
print("Hello MicroPython")

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:

from machine import Pin
import time

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

if __name__ == "__main__":
    blink()

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.

from machine import UART
import time

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

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

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

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

                    connected = True
                    break
            time.sleep_ms(10)

        if connected:
            break

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

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

    
if __name__ == "__main__":
    actSeq()
    

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

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

import espnow

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.

import ubinascii
import network

wlan_sta = network.WLAN(network.STA_IF)
wlan_sta.active(True)
wlan_mac = wlan_sta.config('mac')
print(ubinascii.hexlify(wlan_mac).decode())Pythonp

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:

import network
import espnow
import time

sta = network.WLAN(network.STA_IF)    # Enable station mode for ESP
sta.active(True)
sta.disconnect()        # Disconnect from last connected WiFi SSID

e = espnow.ESPNow()     # Enable ESP-NOW
e.active(True)

peer1 = b'\xe8\x68\xe7\x4e\xbb\x19'   # MAC address of peer1's wifi interface
e.add_peer(peer1)                     # add peer1 (receiver1)

peer2 = b'\x60\x01\x94\x5a\x9c\xf0'   # MAC address of peer2's wifi interface
e.add_peer(peer2)                     # add peer2 (receiver2)

print("Starting...")            # Send to all peers

e.send(peer1, "walk", True)     # send commands to pear 1
e.send(peer2, "walk", True)     # send commands to pear 2
time.sleep_ms(2000)
e.send(peer1, "walk", True)
e.send(peer2, "back", True)
time.sleep_ms(2000)

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:

import network
import espnow
from machine import UART

def espnow_rx():
    #config UART
    uart = UART(0, baudrate=115200)

    # A WLAN interface must be active to send()/recv()
    sta = network.WLAN(network.STA_IF)
    sta.active(True)
    sta.disconnect()                # Disconnect from last connected WiFi SSID

    e = espnow.ESPNow()                  # Enable ESP-NOW
    e.active(True)

    peer = b'\x5c\xcf\x7f\xf0\x06\xda'   # MAC address of peer's wifi interface
    e.add_peer(peer)                     # Sender's MAC registration

    while True:
        host, msg = e.recv()
        if msg:                          # wait for message
            if msg == b'walk':           # decode message and translate
                uart.write("kwkF")       # to the NyBoard's command
            elif msg == b'back':
                uart.write('kbk')
            elif msg == b'stop':
                uart.write('d')

if __name__ == "__main__":
    espnow_rx()
    

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.

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

Below are the supported functions in the library. You may refer to the auto-generated Python code in the Blocks mode to learn its formats.

# use to print debug information
def printH(head, value)

# deactivate the Gyro
def deacGyro()

# get the current angle list of all joints
def getAngleList()
    return angleList

# get the current angle value of a joint 
def getCurAng(index)

# creat an absolut value list
def absValList(num1, num2)

# rotate angle from relative value to absolute value
# creat an offset value list
def relativeValList(index, symbol, angle)

# rotate the joints sequentially or simultaneously
def rotateJoints(token, var, delayTime)

# play tones
def play(token, var, delayTime)

# encode the character to bytes
def encode(in_str, encoding='utf-8')
 
def printSkillFileName()

# open the serial port 
def openPort(port)

# auto connect serial ports
def autoConnect()

# send a short skill string
def sendSkillStr(skillStr, delayTime)

def loadSkill(fileName, delayTime):

# send a command string
def sendCmdStr(cmdStr, delayTime)

def sendLongCmd(token, var, delayTime)

# get the analog value of a pin
def readAnalogValue(pin)

# get the digital value of a pin
def readDigitalValue(pin)

# set the analog value of a pin
def writeAnalogValue(pin, val)
 
# set the digital value of a pin
def writeDigitalValue(pin, val)

# close the serial port
def closePort()

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.

Setup Process

OpenCat software works on both Nybble and Bittle, controlled by NyBoard based on ATmega328P. More detailed documentation can be found at the NyBoard V1_0 or NyBoard V1_1.

Dial the I2C switch (SW2) to Arduino.

The I2C switch changes the master of I2C devices (gyro/accelerometer, servo driver, external EEPROM). On default “Arduino”, NyBoard uses the onboard ATmega328P as the master chip; On “RPi”, NyBoard uses external chips connected through the I2C ports (SDA, SCL) as the master chip.

Quick Start Tutorial Video

The setup process for Nybble is almost the same, except that you need to change the model definition to #define NYBBLE. Make sure you read through the following detailed steps.

Downloads and installations of Arduino IDE

With NyBoard V1_*, you can simply choose Arduino Uno.

Connect the uploader (sometimes referred to as the programmer)

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

Connect Bluetooth uploader (optional)

For specific steps, please refer to the Connect NyBoard section in the Dual-Mode Bluetooth Module.

Download the OpenCat package

• Download a fresh ​OpenCat repository from GitHub: https://github.com/PetoiCamp/OpenCat. It’s better if you utilize GitHub’s version control feature. Otherwise, make sure you download the WHOLE OpenCat FOLDER every time. All the codes have to be the same version to work together.

• If you download the Zip file of the codes, you will get an OpenCat-main folder after unzipping. Rename it to OpenCat before opening the OpenCat.ino, so that the two names match.

• There are several testX.ino codes in ModuleTests folder. You can upload them to test certain modules separately. Open any testX.ino sketch with prefix “test”. (I recommend using testBuzzer.ino as your first test sketch)

• Open up the serial monitor and set up the baud rate. With NyBoard V1_*, choose the board as Arduino Uno and later set the baud rate to 115200 in both the code and the serial monitor.

• Compile the code. There should be no error messages. Upload the sketch to your board and you should see Tx and Rx LEDs blink rapidly. Once they stop blinking, messages should appear on the serial monitor.

Upload

To configure the board, please follow these steps:

1. Configure the robot type and board version

Open the file OpenCat.ino and select your robot and board version. For example:

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

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

2. Setup the configuration mode

Comment out #define MAIN_SKETCH so that it will turn the code to the board configuration mode. Upload and follow the serial prompts to proceed.

// #define MAIN_SKETCH

3. Plug the USB uploader into your computer

Install the driver if no USB port is found under Arduino -> Tools -> Port.

4. Plug the USB uploader into the NyBoard

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

5. Upload the configuration mode sketch

Press the upload button.

6. Open the serial monitor

You can find the button either under Tools, or at the top-right corner of the IDE.

Set the serial monitor as No line ending and 115200 baud rate.

7. Reset joint offsets

The serial prompts:

Reset joint offsets? (Y/n):

Input ‘Y’ and hit enter if you want to reset all the joint offsets to 0.

The program will do the reset and then update the constants and instinctive skills in the static memory.

8. IMU (Inertial Measurement Unit) calibration

The serial prompts:

Calibrate the IMU? (Y/n): 

Input ‘Y’ and hit enter, if you have never calibrated the IMU or want to redo calibration.

Put the robot flat on the table and don't touch it. The robot will long beep six times to give you enough time. Then it will read hundreds of sensor data and save the offsets. It will beep when the calibration finishes.

When the serial monitor prints "Ready!", you can close the serial monitor to do the next step.

9. Calibrate the servo controller chip PCA9685 on the NyBoard

After the IMU calibration, there's an optional step to calibrate the servo driver.

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

If later you find one of the servos stops working but can resume working after re-powering it, it's probably due to an inaccurate PWM driver signal. You must redo the previous uploading, and this step CANNOT be skipped.

This calibration makes the servo controller (PCA9685 chip)'s angle signal more precise. Use a short jumper wire to connect the PWM pin 3 (the signal pin of one of the servo pins) and Grove pin A3 and hold the wire steady. It doesn’t have to be a dedicated jumper wire. Any thin metal wire, such as a straightened paper clip, can work as long as it can connect the pins.

The program will measure the pulse width of the signal and automatically calibrate the chip after getting three identical readings successively. It usually takes less than 2 seconds. The board will beep three times to indicate the calibration is done. The calibration offset will be saved to the board for the next time of bootup. The process should be done at least once, and we have calibrated every board after October 2022. But you can still do it by yourself, just in case.

10. Upload the major functionalities sketch

Uncomment #define MAIN_SKETCH to make it active. This time the code becomes the normal program for the major functionalities. Then upload the code.

#define MAIN_SKETCH

Open the serial monitor. When the serial monitor prints "Ready!", the robot is ready to take your next instructions.

11. The module macro in the code

The default code runs the standard mode. If you have some extensible modules, you may uncomment the macro definition of a specific module. It will disable the Gyro code to save some programming space and activate the demo of the module.

The behavior of the official modules is defined in separate header files in OpenCat/src/. You can find them in OpenCat/src/io.h -> readSignal(). The behavior of OTHER_MODULES is defined in OpenCat/OpenCat.ino -> otherModule(). You can study the example code to write your own functions.

12. Modify the "joint - pin" mapping

In certain cases, you may want to modify the "joint - pin" mapping of the robot. You can modify it in OpenCat/src/OpenCat.h. Make sure you are modifying the code block corresponding to the board version at the beginning of OpenCat.ino. After the modification, remember to save the changes and redo the uploading process from step 2.

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.

1. Introduction

BiBoard is a robot dog controller based on ESP32 developed by Petoi LLC. Unlike NyBoard for normal users and robot lovers, BiBoard is mainly facing developers and geeks. High-performance processors, larger memory and storage, 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 shown “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 serial1 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.

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.

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.

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.

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.

// Ain 34 - 0dB Gain - ADC_0db
analogSetPinAttenuation(34, ADC_0db);

// Ain 35 - 2.5dB Gain - ADC_2_5db
analogSetPinAttenuation(35, ADC_2_5db);

// Ain 36 - 6dB Gain - ADC_6db
analogSetPinAttenuation(36, ADC_6db);

// Ain 39 - 11dB Gain - ADC_11db    (default)
analogSetPinAttenuation(39, ADC_11db);

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.

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

#include <Wire.h>

#define EEPROM_ADDRESS 0x54
#define EEPROM_CAPACITY 8192       // 64Kbit
#define EEPROM_TESTBYTES 16

// write 1 byte EEPROM by address
void writeEEPROM(int deviceaddress, unsigned int eeaddress, byte data ) 
{
  Wire.beginTransmission(deviceaddress);
  Wire.write((int)(eeaddress >> 8));   // MSB
  Wire.write((int)(eeaddress & 0xFF)); // LSB
  Wire.write(data);
  Wire.endTransmission();
 
  delay(5);
}

// read 1 byte EEPROM by address
byte readEEPROM(int deviceaddress, unsigned int eeaddress ) 
{
  byte rdata = 0xFF;
 
  Wire.beginTransmission(deviceaddress);
  Wire.write((int)(eeaddress >> 8));   // MSB
  Wire.write((int)(eeaddress & 0xFF)); // LSB
  Wire.endTransmission();
 
  Wire.requestFrom(deviceaddress,1);
 
  if (Wire.available()) 
    rdata = Wire.read();
  return rdata;
}

void testI2CEEPROM(){

    byte tmpData = 0;

    Serial.println("EEPROM Testing...");
    
    // write EEPROM from 0 to EEPROM_TESTBYTES
    for(int i = 0; i < EEPROM_TESTBYTES; i++){
        writeEEPROM(EEPROM_ADDRESS, i, i % 256);
        delay(1);
    }

    Serial.println();
    
    // read from 0 to EEPROM_TESTBYTES
    for(int i = 0; i < EEPROM_TESTBYTES; i++){
        tmpData =  (int)readEEPROM(EEPROM_ADDRESS, i);
        Serial.print(tmpData);
        Serial.print("\t");
    }
}


void setup(){

    Serial.begin(115200);
    Wire.begin();
    
    testI2CEEPROM();
}

void loop(){
  
}

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.

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.

Bluetooth Low Energy (BLE, Bluetooth Low Energy) serial port pass-through is widely used. On Apple's iOS platform, Classic Bluetooth requires MFi certification to connect with Apple's iOS devices. The Bluetooth low energy device does not have this restriction.

The protocol stack and principle of Bluetooth low energy will not be repeated here, there are many related articles and videos. In short, the bluetooth service is provided in the form of a profile, and there are N characters with independent IDs (UUID) under the profile of each service. Each character has different permissions (read, write, notify, indicate). After the user defines the character and combines it with the authority, a complete service can be provided.

What BLE pass-through is actually to establish a BLE Service, and there are 2 characters under this profile.

#define SERVICE_UUID           "6E400001-B5A3-F393-E0A9-E50E24DCCA9E" // UART service UUID
#define CHARACTERISTIC_UUID_RX "6E400002-B5A3-F393-E0A9-E50E24DCCA9E"
#define CHARACTERISTIC_UUID_TX "6E400003-B5A3-F393-E0A9-E50E24DCCA9E"

One for TX (transmit data) and one for RX (receive data). For this they have different permissions. The following code is to create a new service and character:

  // Create the BLE Service
  BLEService *pService = pServer->createService(SERVICE_UUID);
  
  // Create a BLE Characteristic
  pTxCharacteristic = pService->createCharacteristic(
										CHARACTERISTIC_UUID_TX,
										BLECharacteristic::PROPERTY_NOTIFY
									);
                      
  pTxCharacteristic->addDescriptor(new BLE2902());

  BLECharacteristic * pRxCharacteristic = pService->createCharacteristic(
											 CHARACTERISTIC_UUID_RX,
											BLECharacteristic::PROPERTY_WRITE
										);

Next are two callback functions, which are performed when there is a connection and when there is a write RX character:

class MyServerCallbacks: public BLEServerCallbacks {
    void onConnect(BLEServer* pServer) {
      deviceConnected = true;
    };

    void onDisconnect(BLEServer* pServer) {
      deviceConnected = false;
    }
};

class MyCallbacks: public BLECharacteristicCallbacks {
    void onWrite(BLECharacteristic *pCharacteristic) {
      std::string rxValue = pCharacteristic->getValue();

      if (rxValue.length() > 0) {
        Serial.println("*********");
        Serial.print("Received Value: ");
        for (int i = 0; i < rxValue.length(); i++)
          Serial.print(rxValue[i]);

        Serial.println();
        Serial.println("*********");
      }
    }
};

Finally, the main loop is the control of the connection, which determines whether there is a connection and whether it is disconnected.

    if (deviceConnected) {
        pTxCharacteristic->setValue(&txValue, 1);
        pTxCharacteristic->notify();
        txValue++;
		    delay(10); // bluetooth stack will go into congestion, if too many packets are sent
	  }
    
    // disconnecting
    if (!deviceConnected && oldDeviceConnected) {
        delay(500); // give the bluetooth stack the chance to get things ready
        pServer->startAdvertising(); // restart advertising
        Serial.println("start advertising");
        oldDeviceConnected = deviceConnected;
    }
    // connecting
    if (deviceConnected && !oldDeviceConnected) {
		// do stuff here on connecting
        oldDeviceConnected = deviceConnected;
    }

For the complete code, see the example of the official library: ble_uart, and the debugging tool can use LightBlue.

Calibrate the joints

Nybble

Bittle

Prepare for calibration

You need to connect the Bluetooth module (for NyBoard only) with computer, install the battery and long-press the button on the battery to power the robot.

Enter the calibration state

After the robot is powered on, there are 2 methods to enter the calibration state:

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

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