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