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.

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

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.

This is the Petoi product documentation hub. We keep fast iteration on our models and codes to bring bionic robotic pets to the world. Please read the notes regarding versions carefully to configure your robot.

Hardware Products

Intelligent Search

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

Hi, thanks for getting a Petoi robot.

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

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

   • Play with group commands

3. Do some coding

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.

Connect to the mainboard

NyBoard

please download and install the driver:

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:

Upload the firmware

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

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)

Download and installation

The app works on both Android and iOS devices.

APK

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

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

Connect to your robot

The LED on the Bluetooth dongle should blink, waiting for a connection. Open the app and scan available Bluetooth devices. Don't connect the robot with the phone's system-wide Bluetooth settings! Connect the device with the name Bittle, Petoi, or OpenCat. Remember to open the Bluetooth service and grant the app access to the service. On some devices, you may also need to allow the location service for the app, though we are not using any of that information.

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

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

Calibrate the joints

Nybble

Bittle

Prepare for calibration

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

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

Use the included L-shaped tool as a reference!

Nybble

Bittle

When calibrating, first select the index number of the joint servo from the diagram(when adjusting the leg servo, adjust the thigh first, and then adjust the calf), and then click the "+" or "-" button to fine-tune the joint to the right angle state.

You can click the skill buttons to switch between Rest, Stand, 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 "<" in the upper left corner to abandon the calibration.

Install the screws

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

Prepare for calibration

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.

Connect the mainboard to the computer

NyBoard(for Bittle & Nybble)

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

Download & Installation

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.

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

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.

Gaits

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)

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

* sit

* move joints one by one

* MOVE joints simultaneously

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

* long meow once (Nybble）

* short meow three times (Nybble）

* mute/unmute the buzzer beep

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

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

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

More common commands to be added

Import new skills as a customized button

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

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.

A Brief Introduction to the Interface

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.

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

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

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)

Connect Bluetooth uploader (optional)

Download the OpenCat package

• 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

4. Plug the USB uploader into the NyBoard

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.

1. Read the Quick Start Guide

2. Set up BiBoard

2.1 Prepare the ESP32 development environment

2.2 Modify code file in the package

• sdkconfig.h

Append a line of code at the end of the file:

#define CONFIG_DISABLE_HAL_LOCKS 1

2.3 Setup the options

Please refer to the option list to set up the board's upload speed, CPU frequency, etc.

There is a setting for the Flash Size and Partition Scheme among the options. For more information, refer to the next section.

2.4 Choose hardware partition

The BiBoard uses an ESP32 with a 16 M flash. To simplify, you can use the default 4 MB partition map without a problem. There's plenty of programming space for the standard OpenCatEsp32 firmware.

4 MB partition

You can use the default 4MB with spiffs. You can also use other partition schemes under the 4 MB flash limit, such as "No OTA" or "Huge APP".

16 MB partition

2.5 Download the OpenCatEsp32 package

• If you download the Zip file of the codes, you will get an OpenCatEsp32-main folder after unzipping. You need to rename it to OpenCatEsp32 before opening the OpenCatEsp32.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)

Set the serial port in the Arduino IDE:

2.7 Compile and upload the sketch

Modify the device type macro definition in BiBoard.ino according to the device type.

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

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

After the modification is completed, you can click the upload button to upload BiBoard.ino, and the changes in the program will be automatically saved.

2.8 Open the serial monitor and do a factory reset (Optional)

If you want a factory reset, please connect the BiBoard and the computer via USB type-C data cable, and open the serial monitor. You can find the button either under Tools, or at the top-right corner of the Arduino IDE.

Input the serial command '!' and press Enter in the serial monitor to start over. You will see several questions:

Reset the joints' calibration offsets? (Y/n): 

Input 'Y' to the question, which means resetting all servo corrections to zero.

- Calibrate the Inertial Measurement Unit (IMU)? (Y/n): 

Input 'Y' to the question, which means calibrating the MPU6050, i.e. the gyro/accelerometer sensor.

Run factory quality assurance program? (Y/n)        

Input 'n' and press Enter to continue.

The details of serial port printing information are as follows：

* Start *
Bittle
Software version: B01_231206
Scanning I2C network...
- I2C device found at address 0x54  !
- I2C device found at address 0x68  !
- done
Set up the new board...
- Name the new robot as: Bittle2E
- Reset the joints' calibration offsets? (Y/n):   
Y
Initializing MPU...
OK
- Testing MPU connections...attempt 0
- MPU6050 connection successful
- Initializing DMP...
- Calibrate the Inertial Measurement Unit (IMU)? (Y/n):    
Y

Put the robot FLAT on the table and don't touch it during calibration.
>....................>....................
MPU offsets:
//           X Accel  Y Accel  Z Accel   X Gyro   Y Gyro   Z Gyro
//OFFSETS     1447,    -349,    1298,      89,      90,      16
- Enabling DMP...
- Enabling interrupt detection (Arduino external interrupt 26)...
- DMP ready! Waiting for the first interrupt...
Bluetooth name: Bittle2E
Waiting for a client connection to notify...
Bluetooth name: Bittle2E
The device is started, now you can pair it with bluetooth!
Setup ESP32 PWM servo driver...
Calibrated Zero Position
135 120 135 135 190 80 190 80 190 80 80 190
Build skill list...60
Run factory quality assurance program? (Y/n)
n
Init voice
Number of customized voice commands on the main board:
10
TaskQ
Ready!
rest
g
d

After the IMU calibration is completed, every time the robot is powered on, it will enter the regular power-on program.

2.9 Power on

• long-press the button which is on the battery and boot up the robot with one side up, it will enter the calibration state automatically. The picture below shows the upper legs and lower legs installed after the robot enters the calibration state.

• If you power on the robot and it is upright (with its back upward), the robot will start from the "rest" posture (fold the legs and unlock the servos).

2.10 Standard mode and special modes

The default code runs the Standard mode (including the Voice command function). If you have some extensible modules, you may uncomment the 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.

3. Configuration with App

The BiBoard has built-in Bluetooth, and you can connect it with the new Android app:

You can check the update history and added features in ChangeLog.md (BiBoard\ChangeLog.md)

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.

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.

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.

Connect the USB Adapter

Open up the serial monitor and set up the baud rate. With NyBoard V1_*, set "No line ending" and the baud rate to 115200 in the serial monitor.

Connect Bluetooth uploader (optional)

Then you can select it under Tools->Port of Arduino IDE, and use it in the same way as the USB adapter.

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

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

• “ksit”

• “m0 30”

• “m0 -30”

• “kbalance”

• “kwkF”

• “ktrL”

• “d”

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

Some more available commands for skills:

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

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

Preparation

1. Install python (version≥ 3.6, such as Anaconda3-5.2.0-Windows-x86_64.exe)

2. Install pyserial library (version 3.5)

Connect the serial port

When using the Bluetooth module, there are two serial port numbers:

Open Terminal (such as Anaconda Prompt), enter the path where the script is located (***\serialMaster), you can use the following command to run the script, the script will automatically identify the serial port number at the very beginning, and complete the connection.

Run the script

Method 1: Run the ardSerial.py

***\serialMaster>python3 ardSerial.py kbalance

Of course, you can also run this script without any parameters:

***\serialMaster>python3 ardSerial.py

When the system recognizes that there are multiple serial port numbers, the script will automatically identify all serial port numbers that have been connected to the robot (you can send serial commands to multiple robots at the same time). When the script starts running, it will print out the following prompt information:

__main__ - INFO - port[0] is COM11
__main__ - INFO - port[1] is COM5
__main__ - INFO - port[2] is COM10
Waiting for the robot to booting up
Waiting for the robot to booting up
['b', '\n* Start *\nBittle\nReady!\np\n']
Adding COM5
['b', '\n* Start *\nBittle\nReady!\np\n']
Adding COM11
__main__ - INFO - Connect to usb serial port:
__main__ - INFO - COM5
__main__ - INFO - COM11

When the script formally starts running, the following prompt information is printed out:

You can type 'quit' or 'q' to exit.

Next, you can enter serial commands in Terminal to control the robot to do various interesting actions 😃 e.g.

Kbalance        # Command to control the robot to stand normally
m 0 -30 0 30    # Command to control the robot head to swing left and right

Method 2: Run the custom scheduler, example.py

***\serialMaster>python3 example.py

The list testSchedule in example.py is used to test various serial port commands. Run the following script code to see the execution effect of each serial port command in the list:

for task in testSchedule:
    wrapper(task)

You can also refer to the content of the testSchedule list (in ***\serialMaster\demos\hlw.py), write a list of behaviors according to your actual needs, and realize your creativity. 🤩 It was used in a Halloween puppet show.

Note: When running the scripts under the path of \serialMaster\demos, you must first use the "cd demos" command to enter the path where the scripts are located (\serialMaster\demos), and then use the python3 command to run the script (e.g. "python3 hlw.py")

Explanation of the serial port commands in the list testSchedule:

['kbalance', 2]

• 'kbalance' indicates the command to control Bittle to stand normally

• 2 indicates the postponed time after finishing the command in seconds.

• m indicates the command to control the rotation of the joint servo

• 0 indicates the index number of joint servo

• -20 indicates the rotation angle (this value is expressed relative to the reference 0 value used after calibration). The unit is in degrees.

• 1.5 indicates the postponed time after finishing the command in seconds. It can be a float number.

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

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

The meaning of this example is the same as the previous command.

['d', 2]

• d indicates the command to put the robot down and shut down the servos

• 2 indicates the postponed time after finishing the command in seconds

['c', 2]

• c indicates the command to enter calibration mode

• 2 indicates the postponed time after finishing the command in seconds. After these motion commands are completed, the next command will be executed after a 2-second delay.

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

• c indicates the command to enter calibration mode

• 0 indicates the index number of joint servo

• -9 indicates the rotation angle. The unit is in degrees.

• 2 indicates the postponed time after finishing the command in seconds

Using this format, you can enter the calibration mode to calibrate the angle of a certain joint servo. Note: If you want the correction value in this command to take effect, you need to enter the "s" command after executing this command.

The meaning of this example: the joint servo with serial number 0 rotates -9 degrees. After these motion commands are completed, the next command will be executed after a 2-second delay.

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

• m indicates the command to control the rotation of the joint servo

• 0 indicates the index number of joint servo

• -20 indicates the rotation angle (this angle refers to the origin rather than additive). The unit is in degrees.

• 1.5 indicates the postponed time after finishing the command in seconds. It can be a float number.

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

Using this format, multiple joint servo rotation commands can be issued at one time, and these joint servo rotation commands are executed SEQUENTIALLY, not at the same time. The joint angles are treated as ASCII characters, so they can be entered directly by humans.

The meaning of this example is: the joint servo with index number 0 is first rotated to the 45-degree position, then rotated to the -45 degree position, and so on. After these motion commands are completed, the following command will be executed after a 2-second delay.

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

Using this format, multiple joint servo rotation commands can be issued at one time, and these joint servo rotation commands are executed AT THE SAME TIME. The joint angles are treated as ASCII characters, so they can be entered directly by humans.

The meaning of this example is the joint servos with index numbers 8, 9 are rotated to the -15, -20 degree positions at the same time. After these motion commands are completed, the following command will be executed after a 2-second delay.

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

• M indicates the command to rotate multiple joint servos SEQUENTIALLY. The angles are encoded as BINARY numbers for efficiency.

• 8, 9, 10, 11, 0 indicate the index numbers of joint servos

• 50, 50, 50, 50, 0 indicate the rotation angle (this angle refers to the origin rather than additive ). The unit is in degrees

• 3 indicates the postponed time after finishing the command, in seconds

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

The meaning of this example is the same as the previous command.

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

• 'I' indicates the command to control all joint servos to rotate AT THE SAME TIME (currently, the command supports 16 degrees of freedom, that is, 16 servos). The angles are encoded as BINARY numbers for efficiency.

• 20,0,0,0,0,0,0,0,45,45,45,45,36,36,36,36 indicate the rotation angle of each joint servo corresponding to 0-15 (this angle refers to the origin, rather than additive). The unit is in degrees.

• 5 indicates the postponed time after finishing the command. The unit is in seconds.

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

• b indicates the command to control the buzzer to beep

• 10 indicates the music tone

• 2 indicates the lengths of duration, corresponding to 1/duration second

• 2 indicates the postponed time after completing the tone. The unit is in seconds

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

• b indicates the command to control the buzzer to beep

• 0, 14, 14, 21... indicate the music tones

• 1, 8, 8, 8 indicates the lengths of duration, corresponding to 1/duration second

• The last '3' indicates the postponed time after the music melody is played. The unit is in seconds.

Using this format, multiple-tone commands can be issued at once, and a simple melody can be played.

The meaning of this example is: play a simple melody and delay 3 seconds after the music melody is played.

ck = [

-3, 0, 5, 1,

0, 1, 2,

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

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

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

]

['K', ck, 1]

• 'K' indicates the skill data to send to Bittle in realtime

• The skill array is sent to the robot on the go and executed locally on the robot

• You may insert the skills in the skill library or InstinctX.h in this format

Please help Nybble and Bittle find their sparks. Wish you have fun! 😍

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

Prepare Mind+

• • Windows: >= V1.7.0

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

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

Watch the video tutorials

Prepare Petoi Robot

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

• #define GROVE_SERIAL_PASS_THROUGH
• 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.

Import Petoi Mind+ extension library

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

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}

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

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.

• 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

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.

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.

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.

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.

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

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

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

3. Code introduction

The group control code is divided into 3 parts:

• Query the MAC address of the module

• Transmitter program

• receiver program

3.1 Query the MAC address of the module

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

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

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

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

3.2 Transmitter program

The transmitter program consists of the following parts:

• Enable the WiFi function of the module

• Configure the ESP-NOW protocol and enable it

• Add a node (peer) that needs to communicate

• Send a message

The specific code is as follows:

3.3 Receiver program

The receiver program is mainly composed of the following parts:

• Enable the WiFi function of the module

• Configure the ESP-NOW protocol and enable it

• Add a node (peer) that needs to communicate

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

The specific code is as follows:

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

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

• Rename the code file to main.py;

• Modify the boot.py ;

For beginners, we recommend the first method.

3.4 Communication-Command Converter

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

Prepare to Enter to the Calibration State

Entering calibration state requires the following preparations: ‌

Prepare to Enter the Calibration State

Entering the calibration state requires the following preparations: ‌

1. All servo circuits are connected to the motherboard

2. The battery is fully charged

If you are building the robot with an unassembled kit, do not install the head and leg components until calibrated.

You need to install the battery and long-press the button on the battery to power the robot.

The calibration has 3 steps:

1. Power on the robot with battery, let servos rotate freely to zero angle/calibration state

2. Attach body parts to the servos

3. Fine-tune the offsets in serial monitor

1. Enter the calibration state

You must plug the servos and external batteries into the NyBoard and check the position and direction of all servos.

Type ‘c’ in the serial monitor to enter the calibration state. Depending on their initial shaft direction, some may travel larger angles until stopping at the middle point. There will be noise coming from the gear system of the servos. You will see a calibration table like the following:

The first row is the joint indexes; the second row is their calibration offsets:

Initial values are “-1” or “0”, and should be changed by later calibration.

2. The rationale for calibration

2.1 Understand the zero state and the coordinate system

After typing ‘c’ in the serial monitor, with all servos rotated to their zero angles, now attach the head, tail, and legs prepared in the previous section to the body. They are generally perpendicular to their linked body frames. The calibration pose is shown below:

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

2.2 Discrete angular intervals

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

2.3 Attach body parts to the servos

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.

3. Fine-tune the calibration using the serial monitor

3.1 Joint Control Commands

For example :

• c8 6 means giving the 8th servo an offset of 6 degrees.

• c0 -4 means giving the 0th servo(the head) an offset of -4 degrees.

Find the best offset that can bring the limb to the zero states. It's a process of trial and error.

After calibration, remember to type ‘s’ to save the offsets. Otherwise, they will be forgotten when exiting the calibration state. You can even save every time after you’re done with one servo.

3.2 Use ‘L’ shaped joint tuner

When watching something, the observation will change from different perspectives. That’s why we always want to read directly above a referencing ruler when measuring length.

It’s especially important that you keep a parallel perspective when calibrating Bittle. Use the 'L'-shaped joint tuner as a parallel reference to avoid reading errors. Align the tips on the tuner with the center of the screws in the shoulder and knee joints, and the little hole on the tip of the foot. Look along the co-axis of the centers. For each leg, calibrate the shoulder servos (index 8~11) first, then the knee servos(index 12~15). When calibrating the knee, use the matching triangle windows on both the tuner and shank to ensure parallel alignment.

Nybble

Bittle

3.3 Testing and validation

After calibration, type ‘d’ or ‘kup’ to validate the calibration. It will result in Bittle / Nybble symmetrically moving its limbs between rest and stand state.

You may need to do a few rounds of calibrations to achieve optimal states.

Take Bittle for example, as follows:

3.4 Install the screws

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

3.5 Center of mass

Try to understand how the robot keeps balance even during walking. If you are adding new components to the robot, try your best to distribute its weight symmetrically about the spine. You may also need to slide the battery holder back and forth to find the best spot for balancing. Because the battery is heavier in the front, you can also insert it in a reversed direction to shift the center of mass more toward the back.

Please do not force the robot to add heavy objects, which may cause the servos to sweep or get stuck.

Use the library in your own project

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

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

Examples

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

Free curricular

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

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

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

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.

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.