Peabot-Library

KO | EN

gitlite — search

#react #ai #typescript #golang #machine-learning #macos #windows #awesome #cli #kubernetes #vue #security #mcp #open-source

(★ 21)

Peabot: quadruped robot library for Raspberry Pi

Peabot-Library Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Peabot

## Overview

This software controls a custom-built quadruped robot. Namely, this guy (or anyone like him):

![Pibot photo](https://raw.githubusercontent.com/mpmumau/Peabot-Library/master/images/pibot.jpg)

## Software Features
* Full solution for controlling a quadruped robot.
* Includes many "motions" for moving the robot (walk, turn, extend arms, etc.).
* Interactive command prompt for sending the robot commands.
* RESTful web API for controlling the robot through HTTP requests.
* Multiple configuration options (config file, command line, interactive prompt).

## Planned Features
* Artificial intelligence.
* Sensor data management and automatic motion stabilization.
* Additional walk gates, and other movements.
* Front-end control application.
* Authentication and encryption of RESTful requests.

## Requirements.

Peabot is written to be run on any robot that can run c programs on its microprocessor. 
Likewise, out of the box, it is presumed that you will use the PCA-9685 PWM bus chip.
However, with minimal modifications, it should be capable of running on any hardware
that supports PWM servo control.

Peabot also assumes you are running the Raspbian operating system.

![Pibot photo](https://raw.githubusercontent.com/mpmumau/Peabot-Library/master/images/disassembled.jpg)

This software is written in such a way that if future contributers would like to use
more servos on their robots (for example a hexapod, etc.), then they may do so by
modifying it to their purposes and recompiling. In general, Peabot is a framework
for handling generic robotic functions; however, for quadrupeds with eight servos, 
it's an all-in-one solution. Simply install the application on any Raspberry Pi, 
and you'll have the ability to get your bot up and walking with minimal configuration.

## Mechanical Considerations

In a standard quadruped, each of the robot's four legs is moved by two separate 
micro 9G servos. That makes for a total of eight servos. Peabot's default 
animations presume that you will be using an eight-servo robot.

Typical hobby servos are able to rotate about 165 degrees, although 
physical joints of a robot may rotate somewhat less so. As such, you should be aware
that your robot may need to be configured such that servo motions can compensate for
such an offset.

## Electronic Components

The default target electronics for a Peabot robot are presumed to be as such:

![Pibot components](https://raw.githubusercontent.com/mpmumau/Peabot-Library/master/images/components.jpg)

### Raspberry Pi Zero
The central component of a Peabot robot is a Raspberry Pi, which is a 
fully functioning computer, configured to run the Raspbian operating system.

### Adafruit PCA9685 servo controller breakout
This controller is able to take I2C input from the Raspberry Pi's applicable 
pins, and multiplex that signal through 16 channels. In this case, the robot 
uses 8 of the controller's pins, 0-7, to control its 8 servos.

*Note* A 1000mf capacitor should be soldered to PCA-9685 as indicated by 
the manufacturer in order to provide consistent power to the servos.

### RioRand ESO8MA 9G micro servos
These are the robot's source of mechanical movement, allowing for precise 
rotation of the robot's joints. Any 9g servos may be used, however.

### HC-SR04 ultrasonic distance sensor
In addition to serving as a neato robot face, this sensor detects the distance 
between itself and any obstructions directly in front of it using ultrasonic 
echos (like a bat). Use of the UDS is optional, and configurable.

### MPU-9250 9DOF sensor breakout
This sensor is able to capture gyroscopic rotation, magnetic bearing and 
acceleration of the robot. In future versions of the robot's software, the 
robot will be able to use this information to navigate on its own. Use of
this board is optional, and configurable.

## Example Wiring and Pins

![Pibot components](https://raw.githubusercontent.com/mpmumau/Peabot-Library/master/images/wiring.jpg)

You may assemble and connect the electronic components of the robot in the 
following way:

### Raspberry Pi GPIO Pins:

**GPIO 1** -> PCA9685 INPUT VCC

**GPIO 2** -> HC-SR04 VCC

**GPIO 3** -> PCA9685 INPUT SDA

**GPIO 4** -> 3.4V LIPO +

**GPIO 5** -> PCA9685 INPUT SCL

**GPIO 6** -> 3.4V LIPO -

**GPIO 9** -> PCA9685 INPUT GROUND

**GPIO 30** -> MPU-9250 GROUND

**GPIO 31** -> HC-SR04 ECHO

**GPIO 32** -> HC-SR04 TRIG

**GPIO 34** -> HC-SR04 GROUND

### PCA9685

***Note*** "Input" refers to the left-hand side of the breakout, when situated 
in a left-to-right orientation.

[INPUT SIDE]

**GND** -> RPI GPIO 9

**SCL** -> RPI GPIO 5

**SDA** -> RPI GPIO 3

**VCC** -> RPI GPIO 1

[OUTPUT SIDE]

**GND** -> MPU-9250 GND

**SCL** -> MPU-9250 SCL

**SDA** -> MPU-9250 SDA

**VCC** -> MPU-9250 VCC

[CHANNELS]

**0** - BACK LEFT KNEE SERVO

**1** - BACK LEFT HIP SERVO

**2** - FRONT LEFT HIP SERVO

**3** - FRONT LEFT KNEE SERVO

**4** - BACK RIGHT KNEE SERVO

**5** - BACK RIGHT HIP SERVO

**6** - FRONT RIGHT KNEE SERVO

**7** - FRONT RIGHT HIP SERVO

### MPU-9250

**GND** -> PCA9685 OUTPUT GND

**SCL** -> PCA9685 OUTPUT SCL

**SDA** -> PCA9685 OUTPUT SDA

**VCC** -> PCA9685 OUTPUT VCC
 
### HC-SR04

**VCC** -> RPI GPIO 2

**ECHO** -> RPI GPIO 32 (WiringPi 26)

**TRIG** -> RPI GPIO 31 (WiringPi 22)

**GROUND** -> RPI GPIO 34

## Power

A Peabot robot should use two separate power sources to do its work. The Raspberry Pi Zero, 
the PCA-9685 (I2C-side), the HC-SR04 and the MPU-9250 may be run from a rechargable 3.4v 
lipo battery, while the servos may be powered from two 18650 batteries, connected 
in series, for about 8v. This may be reduced through a Hobbywing 5V/6V 3A 
switch-mode UBEC (or similar), and wired into the PCA-9586's screw terminals.

Optionally, you have an Adafruit MCP73833 lipo charger installed into the battery pack 
itself, which may recharge the 3.4v battery inline. The 18650 batteries 
should be removed and recharged in a separate battery charging device.

## 3D Printed Parts

Recommended legs for a Peabot robot are from Javier Isabel's Kame robot, which is available 
on Thingiverse.com:

http://www.thingiverse.com/thing:1265766

The STL models for a body, top and battery compartment which I had customized 
for this robot are included in the 3d_models directory of this repository for 3D printing. 
Recommended print settings are around .3mm layer height, with temps as per your 
material of choice.

The battery holder model includes customized support structures, which may be 
removed after printing.

## Required Packages

It is presumed that you will be using the Raspbian operating system on your
Raspberry Pi.

This software requires that two packages are installed:

**WiringPi** http://wiringpi.com/download-and-install/

**Reinbert/pca9685** https://github.com/Reinbert/pca9685

Instructions for installing those packages are available via their respective 
links.

## Log Files

Log files are stored in `/var/log/peabot` on your system by default. This directory may
be configured via the application's configuration file. Options are also
available in the configuration file to log only the information in which you are
most interested.

## Installation

To install Peabot, clone this repository to any directory of your Raspberry Pi
(i.e. /opt/peabot). Run `make` then `make install` (as root or sudo) from 
the command line from within the directory of the repository.

To uninstall, type `make full-uninstall` (as root or sudo). This will remove Peabot from your 
system, while keeping log files in `/var/log/peabot`.

Peabot must be run with permissions to access the Raspberry Pi's GPIO; use `sudo` to
run peabot if your user does not have permissions to the Raspberry Pi's GPIO.

The command `peabot` may be run after installation to start the program (e.g. `sudo peabot`).

## Command Prompt

If you run Peabot manually from the command line (by typing `peabot`) you
will see a command prompt, from which you may send commands directly to the 
robot.

The following commands are available:

### walk [#times[ex: 3]] [halftime [ex: 1.0]]

Execute `#times` iterations of the walk cycle, with each cycle lasting 
(`halftime` * 2) seconds long.

### elevate [time [ex: 5.3]] [reverse [ex: 0 or 1]]

Execute the robot's "elevate" motion, which fully extends or retracts its knees 
(defined by the `reverse` param). Lasts a total of `time` seconds.

### extend [time [ex:3.7]] [reverse [ex: 0 or1]]

Extends the robot's "hip" servos to either their fully extended or fully
retracted position. Last a total of `time` seconds.

### reset

Reset all servos to their "home" position.

### halt

Halt the robot entirely.

### quit

Quit the application and shut down the robot.

## Command Line Options

Various command line options can be set when running the Peabot application. The
following is a list of those options, their format and what they do.

### `-c` or `--config` [path to config]

Allows the user to specify the path of a configuration file to use.

### `--log_stdin`

If present, log all raw standard-in input from the application's prompt.

### `--log_prompt`

If present, log all command prompt activity.

###  `--log_event_add`

If present, log all system events as they are added to the application's queue.

### `--log_event_callback`

If present, log all callbacks, which occur when an event is executed.

### `--log_keyframes`

If present, log when keyframes have been executed.

### `--pca-9685-hertz` [integer]

Set the PCA-9685's signal frequency.

### `--pca-9685-pin-base` [integer]

Set the PCA-9685's pin base.

### `--pca-9685-max-pwm` [integer]

Set the PCA-9685's maximum PWM value.

### `-s` or `--servos` [integer]

Set the number of servos used by the robot.

### `-t` or `--servo_tick` [decimal number]

Set the robot's update function to the val (which represents seconds).

### `--transitions-enable`

If present, enable automatic transitions between keyframes.

### `--transitions-time` [decimal number]

The amount of time in seconds to allocate for transition keyframes.

### `--walk-hip-delta` [decimal number]

The magnitude of servo position change for hips during the walk animation.

### `--walk-knee-delta` [decimal number]

The magnitude of servo position change for knees during the walk animation.

### `--walk-knee-pad-a` [decimal number]

The percentage of the walk animation where its initial knee movement is delayed.

### `--walk-knee-pad-b` [decimal number]

The percentage of the walk animation where its second knee movement is delayed.

## Config File

As explained above, if the user specifies the `-c` or `--config` option via
the command line when the application is run, then the Peabot application will
load the file at the provided path in order to determine its initial settings.

A config file uses `#` to indicate that a line is a comment, and ignores empty
lines. Options are set in a key-value format, wherein each [KEY] is followed
by a [VALUE]; extra spaces between [KEY] and [VALUE] are ignored.

The following options are available to be set via a configuration file:

### `log_file_dir` [path]

The directory in which to store log files.

### `log_stdin` [true|false]

Whether or not to log raw standard-in input.

### `log_prompt_commands` [true|false]

Whether or not to log prompt activity.

### `log_event_add` [true|false]

Whether or not to log when events are added to the application's event queue.

### `log_event_callbacks` [true|false]

Whether or not to log event callback functions when an event is acted upon.

### `log_keyframes` [true|false]

Whether or not to log keyframes after they have been executed.

### `pca_9685_pin_base` [integer]

Set the PCA-9685's pin base.

### `pca_9685_max_pwm` [integer]

Set the PCA-9685's maximum PWM value.

### `pca_9685_hertz` [integer]

Set the PCA-9685's signal frequency.

### `servos_num` [integer]

Set the total number of servos in use on the robot.

### `robot_tick` [decimal number]

Set the time in seconds to use for the robot's update function.

### `transitions_enable` [true|false]

Whether or not to enable transition motions between differing keyframes.

### `transition_time` [decimal number]

The time in seconds to use for each transition animation.

### `walk_hip_delta` [decimal number]

Set the robot's hip change magnitude during the walk animation.

### `walk_knee_delta` [decimal number]

Set the robot's knee change magnitude during the walk animation.

### `walk_knee_pad_a` [decimal number]

Set the percentage of the robot's walk animation during which the initial knee 
motion is delayed.

### `walk_knee_pad_b` [decimal number]

Set the percentage of the robot's walk animation during which the second knee 
motion is delayed.

### `back_left_knee` [integer]
### `back_left_hip` [integer]
### `front_left_knee` [integer]
### `front_left_hip` [integer]
### `back_right_knee` [integer]
### `back_right_hip` [integer]
### `front_right_knee` [integer]
### `front_right_hip` [integer]

Set the position [0-16] on the PCA-9685 for each servo position.

### `back_left_knee_limits` [min-max]
### `back_left_hip_limits` [min-max]
### `front_left_knee_limits` [min-max]
### `front_left_hip_limits` [min-max]
### `back_right_knee_limits` [min-max]
### `back_right_hip_limits` [min-max]
### `front_right_knee_limits` [min-max]
### `front_right_hip_limits` [min-max]

Set the minimum and maximum PWM values to set for the individual
servos. These settings are very useful for calibrating your robot,
especially if you were unable to perfectly center your servos
when installing them onto your robot. Caution should be used such
that these PWM values do not exceed the physical limitations of the
robot.

## RESTful Web Service

Peabot provides a RESTful HTTP service on the port specified on the configuration file,
if HTTP_ENABLED is set to true.

The RESTful service may be used to send commands to the robot via HTTP, or to retrieve
data from the robot. This is useful for building a front-end web application to control
the robot (think: mobile app!)

All POST requests return a response with a JSON body, containing the value boolean `success`
indicating the success of the operation.

Typical RESTful requests made to Peabot are either general GET requests for retrieving
information or POST requests with JSON data in the request body to specify command
paramters. The format of specific RESTful requests is as follows:

### POST /event/walk

Begins the robot's walk animation, up to the given amount of cycles, each lasting "duration" 
seconds. If reverse, walk backwards.

`
{
    "cycles": 10,
    "duration": 1.54,
    "reverse": true
}
`

### POST /event/turn

Begins the robot's turn animation, up to the given amount of cycles, each lasting "duration" 
seconds. If reverse, turn the opposite direction.

`
{
    "cycles": 15,
    "duration": 0.75,
    "reverse": true
}
`

### POST /event/elevate

Extends the robot's "knees" to either fully extended or retracted.

`
{
    "duration": 0.45,
    "reverse": false
}
`

### POST /event/extend

Extends the robot's "hips" to either fully extended or retracted.

`
{
    "duration": 0.45,
    "reverse": false
}
`

### POST /event/reset

Reset the robot to its neutral position.

No data required.

### POST /event/halt

Halt all robot movement.

No data required.

### GET /uds/get

Get the current distance indicated by the ultra-sonic distance sensor. Returns:

`{ "distance": 16.51 }`

Peabot-Library

Peabot-Library Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Peabot-Library

Peabot-Library Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README