From Waveshare Wiki
Revision as of 02:33, 21 March 2024 by Eng52 (talk | contribs) (→‎Specification)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

An Open Source Bionic Dog-Like Robot Powered by Raspberry Pi





PIPPY is an open-source bionic dog-like robot powered by Raspberry Pi.


  • The PIPPY is powered by two 2600mAh 18650 batteries (not included), supporting charging when playing.
  • Integrate HY2120 + AO4406A Li-ion battery protection circuit to protect the PIPPY from over-charge, over-discharge, over-current, and short.
  • APW7313 regular is embedded to supply the Raspberry Pi with 5V voltage.
  • 9-DoF motion sensor ICM20948 for robot gestures and self-balancing.
  • 0.91-inch 128 x 32 OLED is added for IP and battery monitoring.
  • AINA219 for measuring voltage and current.


  • Controller: Raspberry Pi 4 Model B (optional)
  • OS: Raspberry Pi OS (Raspbian)
  • Language: Python
  • Camera: 5MP HD resolution, 160° FOV wide-angle camera
  • Display: 0.91" OLED, 128 × 32 pixels
  • WIFI Mode: AP mode (self-generated hotspot) / STA mode (connecting to a router)
  • Protection: overcharge/discharge protection, over current protection, short circuit protection, reverse proof
  • Power Supply: 8.4V, 2 x 18650 battery in series, allows discharging while recharging (batteries NOT included)
  • Servo: MG90S metal gear servo
  • Material: aluminum alloy

Assembly Guides

Note: Please adjust the servo with codes before you assemble the servo arm. DO NOT adjust after assembly, otherwise, you need to take apart the PIPPY first.
Note: Please use the black Nylon-screw to fix the camera, the camera will be damaged because of a short circuit if you use a metal screw.

Software Setup

Note: The guide of software setup is alos included in the assembly video, please watch the video and follow it step by step.


The demo codes are provided in GitHub. you should open a terminal and clone the codes to your Raspberry Pi. And please install dependencies before you run the demo codes.

sudo git clone https://github.com/waveshare/PIPPY.git

Once you've finished typing, press enter to start downloading the bot's program from GitHub, this process will take a while, so be patient and wait for the download to complete.

Install dependencies

Open a terminal and run the setup script to install all the dependencies.

sudo python3 PIPPY/setup.py

Press enter and the next operation is automatically completed by the script program, this process may last for several minutes or hours depending on the network environment, just wait patiently.
After the installation is complete Raspberry Pi will automatically disconnect the SSH connection and reboot, at this time if you are using Putty and other software connected to the Raspberry Pi, there will be a Network error: Software caused connection abort such an error message is also normal, close it.

Run the demo codes

  • The demo will auto-run after booting. If the OLED has information like IP, it means that the script //home/pi/PIPPY/webServer.py is auto-run successfully.
  • The webServer.py will fail to run if you didn't connect the camera of the PIPPY board to Raspberry Pi. Because the codes should use the Raspberry Pi camera and the PCA9685 chip which is integrated into the PIPPY board. The script is stuck if the camera and PCA8265 are not detected.
  • PIPPY will build a WEB server in WLAN, you can access it with a PC or mobile device, which are connected to the same WLAN.
  • Please note that you should connect the PC or mobile phone to the same WLAN with the PIPPY. If the WIFI of PIPPY work in STA mode, the PC/mobile phone should be connected to the same router, if the WIFI of PIPPY work in AP mode, the PC/mobile phone should be connected to the hot-sport of PIPPY (SSID: PIPPY /Password: 12345678).
  • Please use Chrome browser, go to http://<RaspbeeryPi_ip_address>:5000 to access PIPPY. The RaspbeeryPi_ip_address should be the actual IP of PIPPY, which will be displayed in OLED, for example,

PIPPY 01.png

  • If you use a mobile phone, the console should be like the picture below:

PIPPY 02.png

  • If the console is failed to open, please first access Raspberry Pi by SSH, and stop the PIPPY codes to release resources, otherwise, the codes may be stuck because the camera failed to initialize or the port was used.
sudo killall python3
  • Run the webServer.py with the following command:
sudo python3 PIPPY/webServer.py


  • The console should like the picture below after accessing the PIPPY.

PIPPY 01.png


Video: This window is used to display the camera.


Instruction: The description of short-cuts are listed in this window, you can follow it and control the PIPPY with keyboard.
W,A,S,D keys are used to control the PIPPY to forward, turn left, backward, and turn right. I, J, K, L keys are used to control the PIPPY to look up, look left, bow and look right.

Move Control

Move Control: This window is used to control the basic motions of PIPPY.
speed: Adjust the speed of PIPPY.

Arm Control

Arm Control: This window is used to control the gestures of PIPPY, it can rise head, left-wing, bow, and right-wing.

Hard Ware

Hard Ware: this window is used to display the CPU temperature, CPU usage rate, and memory of Raspberry Pi.

FC Control

FC Control: This is used to control the locking-color function of PIPPY.

  • START: Enable the color searching and following function. Click it again to disable the function after starting.
  • COLOR: This is used to choose the color followed.
  • If you open this function, the PIPPY will auto-follow an object which has a certain color, it should be light-yellow by default.
You can also change the following color. If the PIPPY following a color object, the LED of PIPPY turns orange. Because the camera of PIPPY is only 2-DoF, the color following codes doesn't feature to follow in the horizontal direction.


Actions: This window is used to control special functions:

  • MOTION GET: A motion detection function based on OpenCV, the moving object is marked in the Video window if motion is detected by the camera.
  • AUTO MATIC: A auto-obstacle function based on the ultrasonic sensor. PIPPY will turn left if an obstacle is detected in the front, if the obstacle is too close, PIPPY will backward.
  • KEEP DISTANCE: The distance-keeping function based on the ultrasonic sensor. If the distance of the obstacle is long, PIPPY keeps forwarding and it will backward if the obstacle is too close. If the distance is in the defined range, PIPPY will keep waiting.
  • TRACK LINE: Vison tracking function. If you enable this function. Track line figures are displayed in the Video window. The PIPPY can do the line following if combine with the CVFL Control window. Click it again to close the fucntion.
  • STEADY: Steady function. It can use the 9-Dof sensor to do self-balancing and keep the camera horizontally.

Radar Scan Control

Radar Scan Control: This is used to display the distance of the obstacle in front of PIPPY.


PWM INIT SET: This window is used to adjust the angle of the servo.

CVFL Control

CVFL Control: This window is used to control the vision tracking function of PIPPY.

  • START : Enable Vision Tracing function. Click it again to close the function. If you enable the Vision Tracking function. the images in Video will be binarized.
  • COLOR : Switch the tracking modes between the Black-floor-White-line and the White-floor-Black-line. It is a Black-floor-White-line by default, click it to switch.
  • L1 and L2 are used to adjust the top/bottom line positions. The tracking function is featured by analyzing the pixels of two lines. You should adjust them to the black line when running.
  • SP is used to adjust the position of left/right lines. These are the threshold which is defined by vision analysis. When you running the codes, the PIPPY will turn black when it detects these two lines and keep walking inside the area.

SP should be adjusted, Larger the SP value, bigger the tolerance, however, if the SP value is too small, PIPPY cannot focus the target direction and keep stopping.

How to use the API of PIPPY

For secondary development, we provide API for the PIPPY. You can create a new Python file and use the API below to control the PIPPY.
For example, we create a new simpleTest.py file and add the lines below to let the PIPPY move for 10s and stop for 1s, then left for 3s.

import PIPPY
import time

robotCtrl = PIPPY.PIPPY() robotCtrl.start() # Start a process to avoid sutcking the motion function.

robotCtrl.moveStart(100, 'forward', 'no') # PiPPY start to move forward in speed 100.
time.sleep(10) # keep for 10s

robotCtrl.moveStop() # PIPPY stop

robotCtrl.moveStart(100, 'no', 'left') # PIPPY turn left in speed 100.

robotCtrl.moveStop() # PIPPY stop

moveStart(speed, direction, turning)

  • speed: The speed should be in the range of 1-100. When the speed is in 1-50, the PIPPY moves in tripod gait, if the speed is in 51-100, the PIPPY moves in diagonal gait. The larger the speed, the faster the PIPPY.
  • direction: The direction can be 'forward', 'backward', or 'no', This control the direction of the PIPPY when moving.
  • turning: The turning can be 'left', 'right', or 'no', It controls the PIPPY to turn left, turn right or keep straight.

pitchRoll(pInput, rInput)

Gesture control function.
PInput is the status of Pitch;
rInput is the status of Roll. Because the endpoint of the legs can only move in vertical plane, there is no Yaw status.
(Because PIPPY use differential steering for turning, it is not the Yaw motion either).

  • The value of pInput and rInput is determined by the size of the robot's leg connection rod. The size of connection rods determined the motion area of every leg when raising and downing. Generally, the value of pInput and rInput should be in the range from -7.5 to 7.5.
  • If pInput is positive, PIPPY looks up; If pInput is negative, PIPPY looks down. The absolute value of the pInput defines the pitch degree of PIPPY.
  • If rInput is positive, PIPPY is left-wing; If rInput is negative, PIPPY is right-wing. The larger the value of rInpit, the bigger the row degree.

The steady mode of PIPPYis based on this function. It will read the gesture data by the ICM20948 chip and convert to this function after using the Kalman filter.


This function controls the height of the PIPPY, it is a simple version of pitchRoll().

  • heightInput: This data can be random between the shortest and the tallest data of PIPPY, it is in the range from 60 to 85. The range is determined by the size of the legs connection rod of the Robot.

linkageQ(legNumber, x, y)

This is the control function of leg connection rods. Q is Quard. This function is one of the basic functions for motion. You can control the position of the leg's endpoints by inputting the position.

  • legNumber: This can be 1, 2, 3 or 4, it is used to choose the leg control. The left foreleg is 1, the left hindleg is 2, right foreleg is 3 and the right hindleg is 4.
  • x is the front and back position of the endpoint of the leg. If the x is positive, the position is forward. If x is negative, the position is backward. If the x is 0, the endpoint is located at the midpoint of the line of two servo axes.
  • y is the up and down position of the endpoint of the leg, and the y value is always positive. The minimum value is 60 and the maximum value is 85, depending on the size of the robot's leg link.

Note that if you set the y to 85, the moving area for x is limited, we do not recommend you set the PIPPY to move with the tallest gesture.

linkageV(servoNumA, servoNumB, x, y)

Control function of signle leg. This is the basic function of linkageQ(), every leg is controlled by two servo.
servoNumA and servoNumB are the number of front servo and hind servo.
The relationship between servo and the numbers:

left right(forward)
1 -- -- 4
0 -- -- 5
3 -- -- 6
2 -- -- 7

Connecting Rod inverse Solution Function Principle

planeLinkageReverse(), planeLinkageDouble(), middlePosGenout()and animateLine() are all the connecting rod inverse solution function. For more details, please refer to LinkageREVERSE.py file, you can use the same principle to establish the connecting rod inverse kinematic simulation in the PC.
Double-click the file on your PC to open it. Note that python3、numpy and matplotlib are required to run the file

pip3 install numpy
pip3 install matplotlib

linkageREVERSE.py has specific formulas for realizing the inverse solution of the connecting rod, so here we will focus on the principle of inverse solution.

  • The connecting rod inverse solution is roughly divided into two types, one with a unique solution and the other without a unique solution. The structure of PIPPY belongs to a connecting rod structure with a unique solution, which greatly reduces the difficulty of connecting rod inverse solution.
  • First of all, the simplest and most basic is the inverse solution of the plane double link. The initial point and the endpoint of the link can be connected to form a triangle, and what we have to do is to obtain the angle of each internal angle of the triangle to obtain The swing angle of the steering gear.
Basic formula:
First, define a triangle. A, B, and C are the three corners of the triangle, and a, b, and c are the sides corresponding to the angles A, B, and C, so it is cosC = (a*a + b*b - c*c)/(2*a*b)
  • As long as we connect the connecting rods of the front and rear steering gears of a certain leg, the swing angle of the two steering gears can be obtained, so as to realize the most difficult part of the connecting rod inverse solution. For a certain connecting rod extension line above The position of the endpoint of the leg can be obtained by using y=kx+b. The three equations are combined and transformed. With x and y as the known quantity and the angle of the steering gear as the unknown quantity, it is the connection we used above. The function is to be realized by the inverse function of the rod.




Support 3x 18650 battery (not included) with a width of 18mm and a length of 65mm. The voltage of the a single battery is 3.7V and the fully charged voltage is 4.2V.

Before you assemble the servo arm, you need to adjust the gesture of the servo to keep it straight according to the video. The angle of the servo is about 9° tolerant, it is normal and you can adjust the codes for better motion.


Technical Support

If you need technical support or have any feedback/review, please click the Submit Now button to submit a ticket, Our support team will check and reply to you within 1 to 2 working days. Please be patient as we make every effort to help you to resolve the issue.
Working Time: 9 AM - 6 PM GMT+8 (Monday to Friday)