Connecting to sources…

How to build Petoi Bittle X

146 steps to build Petoi Bittle X, with the source documents.

Bittle X $319, Bittle $289 (vendor page)

Assemble

  • Install construction kit screws

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

  • Connect the mainboard to the computer

    Connect the computer to the robot's mainboard with a USB cable and follow the subsequent sub-page for the mainboard model.

Software

  • Delete the WebSocketsServer library and restart Arduino IDE

    Go to ~/Documents/Arduino/libraries/, delete the "WebSocketsServer" folder, then restart Arduino IDE so only the "WebSockets" library remains.

  • Let Arduino IDE choose the library automatically

    The code will work with either library; Arduino IDE will use the first one it finds.

  • ESP8266 generates a unique SSID after upload

    After uploading, the ESP8266 generates a unique SSID in the format Petoi-AP[XXXX], where XXXX is a random 4-digit number.

  • SSID and random number are saved to EEPROM

    The SSID and random number are saved to EEPROM and persist across reboots.

  • WiFiManager creates a configuration portal when no credentials are saved

    If no saved WiFi credentials exist, WiFiManager will create a configuration portal with the generated SSID.

  • Change the WiFi Name

    Send `n[newName]`, such as `nLittleDog`, `nMyRobot`, or `nBittle`. The SSID becomes `[newName]-AP`, removing the random number.

  • Clear Saved WiFi Credentials

    Send `w!` to clear saved WiFi credentials. The device will show the configuration portal on the next restart.

  • Reset Saved WiFi Credentials

    Send `r` to clear saved WiFi credentials. The device will show the configuration portal on the next restart.

  • Erase All EEPROM Data

    Send `E` to clear all stored data, including the SSID and WiFi settings.

  • Use the Serial Monitor

    Open the Serial Monitor at 115200 baud, send any of the above commands, and restart the device for the changes to take effect.

  • Connect the Example Web Client

    Use the supplied HTML/JavaScript example to connect to `ws://192.168.4.1:81`. Enter a command and click Send; the client sends JSON containing `command` and `wait: 0`, displays received messages in `output`, and updates the status to Connected or Disconnected.

  • Send a Base64-Encoded Command

    Place `b64:QgoBDgERAX4=` in the `commands` array and send JSON with `type: "command"` and `taskId: "12345"`. The system detects the `b64:` prefix, decodes the Base64 data, and sends the raw bytes with the proper terminator; the example decodes to `[0x42, 0x0A, 0x01, 0x0E, 0x01, 0x11, 0x01, 0x7E]`.

  • Configure Intelligent Timeout Management

    Configure the web coding module using the OpenCatEsp32/PetoiWebBlock timeout configuration.

  • Add Task Completion Tracking

    Provide detailed progress tracking for commands with a taskId so web clients can monitor execution.

  • Send Immediate Acknowledgment

    Immediately return an acknowledgment response with type ack and the command name.

  • Record Task Completion Results

    After completion, return the taskId, completed status, and results array.

  • Handle Task Error Status

    When a task fails, return the taskId, error status, and error details such as timeout.

  • Clear the Serial Buffer

    Clear the serial buffer before sending commands so old data does not interfere.

  • Terminate by Command Type

    Automatically select and send the appropriate terminator for the command type.

  • Wait for Complete Robot Responses

    When collecting a response, wait for the robot to return a complete response.

  • Add Timeout Protection

    Use timeout protection to prevent indefinite waits for serial responses.

  • Optimize Serial Buffer Management

    Set the serial buffer management timeout to 40 ms.

  • Extend Movement Response Waiting

    Use an extended response waiting time for movement commands.

  • Optimize JSON Parsing

    Optimize JSON parsing with ArduinoJson 7.x.

  • Configure Smart Heartbeat

    Set the smart heartbeat mechanism timeout to 25 seconds.

  • Save Memory and Optimize Storage

    Place the global Base64 alphabet in PROGMEM to save RAM, and optimize string operations, buffer clearing, and settings storage.

  • Install Python

    Install Python version 3.6 or newer, such as Anaconda3-5.2.0-Windows-x86_64.exe.

  • Install pyserial library

    Install the pyserial library version 3.5.

  • Identify the USB serial port

    When connecting Nybble or Bittle with a USB adapter, there is usually only one serial port number.

  • Identify the Bluetooth serial ports

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

  • Open the script directory

    Open Terminal, such as Anaconda Prompt, and enter the serialMaster path where the script is located.

  • Run ardSerial.py

    Run ardSerial.py with the kbalance parameter; kbalance is a serial port command representing Nybble or Bittle skills.

  • Run without parameters

    You can also run ardSerial.py without any parameters.

  • Run a custom script

    Run example.py in the serialMaster directory.

  • Execute the test command list

    The testSchedule list in example.py is used to test various serial port commands; the loop runs each task in the list in turn.

  • Send a buzzer tone command

    Send a buzzer command in the [10, 255, 2] format. 10 is the music tone, 255 is the duration with a range of 0~255, and the command waits 2 seconds after the sound finishes.

  • Send a multi-tone melody command

    Send the listed multi-tone buzzer command to play tones 14, 14, 21, 21, 23, 23, and 21. Their durations are 90, 90, 90, 90, 90, 90, and 180, followed by a 5-second delay after the melody finishes.

  • Connect a Petoi robot

    Connect a Petoi robot using the included USB adapter or Bluetooth dongle before running the app.

  • Download precompiled binaries

    Download the pre-compiled binaries from the project's GitHub Releases.

  • Run on Windows

    Double-click the exe file to run the app. Keep all the files in the Win folder when moving the app.

Calibrate and test

  • Use software version 2.0

    Only version 2.0 can calibrate the joints through this App.

  • Prepare for the mainboard

    Follow the subpage instructions to prepare for calibration according to the robot's mainboard.

  • Power on with the battery

    Connect the battery to the mainboard, then long-press the battery button for more than 3 seconds to power on the robot.

  • Enter the calibration state

    After the robot is powered on by the battery, use either of the two methods shown to enter the calibration state.

  • Type c in the serial monitor

    Type ‘c’ in the serial monitor so that all servos rotate to their zero angles.

  • Attach the head, tail, and legs

    With all servos at their zero angles, attach the prepared head, tail, and legs to the body; they should generally be perpendicular to their linked body frames.

  • Install the servo-related components

    When building from a kit, install the servo-related components as shown and try to keep the upper leg perpendicular to the torso and the lower leg perpendicular to the upper leg.

  • Insert components into the output shaft

    Insert the servo-related components directly into the servo output shaft, and do not turn the output shaft during this process.

  • Confirm the positive joint direction

    Counter-clockwise rotation of a limb from its zero state is positive; viewed from the robot's left side, counter-clockwise joint rotation is defined as positive.

  • Use the calibration reference tool

    Use the included L-shaped tool as a reference during calibration, and follow the product-specific subpage instructions to install and fine-tune.

  • Test the calibration effect

    Switch between "Rest", "Stand up", and "Walk" to test the calibration effect.

  • Continue calibrating

    Click the Calibration button to continue; the robot returns to the calibration state and all servos immediately move to the calibration position.

  • Perform a second calibration round

    A second round of calibration may be needed to achieve optimal results.

  • Save or abandon calibration data

    After calibration, click "Save" to save the calibration offset, or click "Abort" to abandon the calibration data.

  • Save calibration midway

    You can save the calibration midway in case the connection is interrupted.

  • Handle the close-window prompt

    When the window closes, click "Yes" to save the calibration data or "No" otherwise. Click "Cancel" to cancel or quit.

  • Connect your phone or computer to the ESP8266 WiFi network

    Connect to the ESP8266's WiFi network from your phone or computer.

  • Open the captive portal or navigate to 192.168.4.1

    A captive portal should open automatically; otherwise navigate to http://192.168.4.1.

  • Select Configure WiFi and pick your home network

    Select "Configure WiFi" and choose your home WiFi network.

  • Enter the WiFi password and click Save

    Enter your WiFi password and click "Save".

  • Device restarts and connects to your WiFi network

    The device will restart and connect to your WiFi network.

  • Note the IP address shown in the Serial Monitor

    Note the IP address displayed in the Serial Monitor.

  • Generate the Default SSID

    On first boot, the system generates a random 4-digit number and uses the `Petoi-AP[XXXX]` format for the SSID. The number is saved to EEPROM and reused on subsequent boots.

  • Reset Joint Offsets

    Confirm the reset of the joint offsets in the serial prompt.

  • Calibrate the IMU

    Place the robot flat on a table. It emits six long beeps, reads sensor data, saves the offsets, and beeps when finished.

  • Calibrate the Joints

    Boot the robot with one side up to enter calibration mode, or calibrate it directly through the Serial Monitor.

Use it

  • Connect to the WebSocket

    Connect to the WebSocket server on port 81 of the ESP8266 at `ws://[ESP8266_IP]:81`.

  • Send a Task JSON Command

    Send a JSON object containing `type`, `taskId`, `commands`, and `timestamp`. The command sends `?` to the robot.

  • Send a Token JSON Command

    Send a JSON object containing `token` and `command`. The command sends `ksit` to the robot.

  • Send a Command-Only JSON Message

    Send a JSON object containing only `command`. The command sends `khi` to the robot.

  • Send a Plain Text Command

    Send the plain text `ksit` directly. The robot receives `ksit`.

  • Send a Base64 Command

    Send `b64:QgoBDgERAX4=`. It decodes to the binary music command `B 10 1 14 1 17 1~` and sends the raw bytes to the robot.

  • Send the rest position

    Send `d\n` to put the robot in its rest position.

  • Send the greetings command

    Send `khi\n` to make the robot perform its greeting.

  • Send the push-up command

    Send `kpu\n` to make the robot perform push-ups.

  • Send the walk forward command

    Send `kwkF\n` to make the robot walk forward.

  • Send the trot forward command

    Send `ktrF\n` to make the robot trot forward.

  • Send the sit command

    Send `ksit\n` to make the robot sit.

  • Turn on the gyro

    Send `g\n` to turn on the robot's gyro.

  • Turn off the gyro

    Send `G~` to turn off the robot's gyro.

  • Send indexed binary movement

    Send `I~` to perform indexed simultaneous binary movement.

  • Send indexed simultaneous movement

    Send `i0 90\n` to perform indexed simultaneous movement.

  • Control all joints binary

    Send `L~` to control all joints in binary mode.

  • Send indexed sequential movement

    Send `m1 45 0 45\n` to perform indexed sequential movement.

  • Query the joint angles

    Send `j\n` to query the robot's joint angles.

  • Read the gyro value

    Send `gu\n` to read the robot's gyro value.

  • Send Base64 music

    Send `b64:QgoBDgERAX4=`; the Base64 data decodes to `B 10 1 14 1 17 1~`.

  • Send a binary beep

    Send `B~` to run the binary beep command.

  • Send an ASCII beep

    Send `b12 8 14 8\n` to run the ASCII beep command.

  • Handle the connected event

    When the client connects, handle `WStype_CONNECTED`; the server sends a welcome message.

  • Handle the disconnected event

    Handle the `WStype_DISCONNECTED` event when the client disconnects.

  • Handle a heartbeat message

    Send `{"type":"heartbeat"}`; the system responds with a timestamp.

  • Clear the serial buffer first

    When handling a client text command, remove existing serial-buffer data before sending the command.

  • Parse JSON command formats

    Parse either `{"token":"k", "command":"sit"}` or `{"type":"command","taskId":"123","commands":["ksit"]}`.

  • Combine token and command

    Combine the token and command, then send `ksit` to the robot.

  • Decode a Base64 command

    Decode commands prefixed with `b64:` to handle binary data such as music commands.

  • Add the correct terminator

    Uppercase commands A-Z get `~`, while lowercase commands get `\n`, such as `G~`, `i0 90\n`, and `m1 45\n`.

  • Send immediate acknowledgment

    Immediately return the acknowledgment `{"type":"ack","command":"ksit"}` after sending the command.

  • Configure command timeouts

    Movement, complex skill, music or binary command, and heartbeat timeouts are 30 seconds, 30 seconds, 30 seconds, and 25 seconds respectively; sensor readings and simple commands time out after 5 seconds.

  • Wait for movement confirmation

    For movement commands, wait until token confirmation is received before detecting a complete response.

  • Return a task response

    Return `{"taskId":"123","status":"completed","results":["robot_reply"]}` when a task command completes.

  • Return a regular response

    Regular commands return `{"type":"response","data":"robot_reply"}`; a timeout returns a task error or `{"type":"timeout","command":"ksit"}`.

  • Open the Status Page

    Access the WebSocket server at the root path `/` to view the status page.

  • Read JSON Status Information

    Access `/status` to retrieve status information in JSON format.

  • Control and exit the robot

    After the script starts, enter serial port commands in Terminal to control Nybble or Bittle; type quit or q to exit.

  • Write a behavior command list

    In testSchedule, the kbalance command makes Bittle stand normally; the number in the list indicates the delay in seconds after the command finishes. You can also refer to the stepUpSchedule list in stepup.py and write a behavior list according to your needs.

Common problems

  • Firmware exceeds onboard storage and memory, causing compilation failure #2 #65
  • Main firmware lacks sensor output and cannot use gyro with ultrasonic sensors together #77 #93
  • Missing dependencies, camera example errors, and lint violations break builds #5 #38 #41
  • Zero-position storage is incorrect and calibration may divide by zero #3 #12
  • Serial ports and resource paths are misdetected on Linux and Raspberry Pi #16 #70 #88
  • Serial commands are sent, but the robot does not execute the requested motion #19
  • Bluetooth failures or firmware updates block robot programming and control #42 #64 #67
  • Apps crash on Apple Silicon while voice and mobile sessions lose connectivity #31 #47 #62

Datasets

Parts

  • Box contents not listed on the page checked; Arduino-based controller

Tools

  • Not stated

Skills

  • C++, Python or block coding

Software

  • OpenCat

Documents