5.2. API - Library - EasyGoPiGo3¶

5.2.1. EasyGoPiGo3¶

class easygopigo3.EasyGoPiGo3(config_file_path='/home/pi/Dexter/gpg3_config.json', use_mutex=False)[source]¶

Bases: GoPiGo3

This class is used for controlling a GoPiGo3 robot.

With this class you can do the following things with your GoPiGo3:

Drive your robot in any number of directions.

Have precise control over the direction of the robot.

Set the speed of the robot.

Turn on or off the blinker LEDs.

Control the GoPiGo3’ Dex’s eyes, color and so on …

Warning

Without a battery pack connected to the GoPiGo3, the robot won’t move.

__init__(config_file_path='/home/pi/Dexter/gpg3_config.json', use_mutex=False)[source]¶

This constructor sets the variables to the following values:

Parameters:

"/home/pi/Dexter/gpg3_config.json" (str config_file_path =) – Path to JSON config file that stores the wheel diameter and wheel base width for the GoPiGo3.
False (boolean use_mutex =) – When using multiple threads/processes that access the same resource/device, mutex has to be enabled.

Variables:

300 (int DEFAULT_SPEED =) – The speed of the motors should go between 0-1000 DPS.
(0,255,255) (tuple(int,int,int) right_eye_color =) – Set Dex’s left eye color to turqoise.
(0,255,255) – Set Dex’s right eye color to turqoise.
300 – Starting speed value: not too fast, not too slow.

Raises:

IOError – When the GoPiGo3 is not detected. It also debugs a message in the terminal.
gopigo3.FirmwareVersionError – If the GoPiGo3 firmware needs to be updated. It also debugs a message in the terminal.
Exception – For any other kind of exceptions.

volt()[source]¶

This method returns the battery voltage of the GoPiGo3.

Returns:: The battery voltage of the GoPiGo3.
Return type:: float

set_speed(in_speed)[source]¶

This method sets the speed of the GoPiGo3 specified by in_speed argument.

The speed is measured in DPS = degrees per second of the robot’s wheel(s).

Parameters:: in_speed (int) – The speed at which the robot is set to run - speed between 0-1000 DPS.

Warning

0-1000 DPS are the preferred speeds for the GoPiGo3 robot. The speed variable can be basically set to any positive value, but factors like voltage, load, battery amp rating, etc, will determine the effective speed of the motors.

Experiments should be run by every user, as each case is unique.

get_speed()[source]¶

Use this method for getting the speed of your GoPiGo3.

Returns:: The speed of the robot measured between 0-1000 DPS.
Return type:: int

reset_speed()[source]¶: This method resets the speed to its original value.

stop()[source]¶

This method stops the GoPiGo3 from moving. It brings the GoPiGo3 to a full stop.

Note

This method is used in conjuction with the following methods:

backward()

right()

left()

forward()

forward()[source]¶

Move the GoPiGo3 forward.

For setting the motor speed, use set_speed(). Default speed is set to 300 - see __init__().

drive_cm(dist, blocking=True)[source]¶

Move the GoPiGo3 forward / backward for dist amount of centimeters.

For moving the GoPiGo3 robot forward, the dist parameter has to be positive.

For moving the GoPiGo3 robot backward, the dist parameter has to be negative.

Parameters:

dist (float) – The distance in cm the GoPiGo3 has to move.
True (boolean blocking =) – Set it as a blocking or non-blocking method.

blocking parameter can take the following values:

True so that the method will wait for the GoPiGo3 robot to finish moving.

False so that the method will exit immediately while the GoPiGo3 robot will continue moving.

drive_inches(dist, blocking=True)[source]¶

Move the GoPiGo3 forward / backward for dist amount of inches.

For moving the GoPiGo3 robot forward, the dist parameter has to be positive.

For moving the GoPiGo3 robot backward, the dist parameter has to be negative.

Parameters:

dist (float) – The distance in inches the GoPiGo3 has to move.
True (boolean blocking =) – Set it as a blocking or non-blocking method.

blocking parameter can take the following values:

True so that the method will wait for the GoPiGo3 robot to finish moving.

False so that the method will exit immediately while the GoPiGo3 robot will continue moving.

drive_degrees(degrees, blocking=True)[source]¶

Move the GoPiGo3 forward / backward for degrees / 360 wheel rotations.

For moving the GoPiGo3 robot forward, the degrees parameter has to be positive.

For moving the GoPiGo3 robot backward, the degrees parameter has to be negative.

Parameters:

degrees (float) – Distance based on how many wheel rotations are made. Calculated by degrees / 360.
True (boolean blocking =) – Set it as a blocking or non-blocking method.

blocking parameter can take the following values:

True so that the method will wait for the GoPiGo3 robot to finish rotating.

False so that the method will exit immediately while the GoPiGo3 robot will continue rotating.

For instance, the following function call is going to drive the GoPiGo3 robot forward for 310 / 360 wheel rotations, which equates to aproximately 86% of the GoPiGo3’s wheel circumference.

gpg3_obj.drive_degrees(310)

On the other hand, changing the polarity of the argument we’re passing, is going to make the GoPiGo3 robot move backward.

gpg3_obj.drive_degrees(-30.5)

This line of code makes the GoPiGo3 robot go backward for 30.5 / 360 rotations, which is roughly 8.5% of the GoPiGo3’s wheel circumference.

backward()[source]¶

Move the GoPiGo3 backward.

For setting the motor speed, use set_speed(). Default speed is set to 300 - see __init__().

right()[source]¶

Move the GoPiGo3 to the right.

For setting the motor speed, use set_speed(). Default speed is set to 300 - see __init__().

Important

The robot will activate only the left motor, whilst the right motor will be completely stopped.

This causes the robot to rotate in very short circles.

spin_right()[source]¶

Rotate the GoPiGo3 towards the right while staying on the same spot.

This differs from the right() method as both wheels will be rotating but in different directions. This causes the robot to spin in place, as if doing a pirouette.

For setting the motor speed, use set_speed(). Default speed is set to 300 - see __init__().

Important

You can achieve the same effect by calling steer(100, -100) (method steer()).

left()[source]¶

Move the GoPiGo3 to the left.

For setting the motor speed, use set_speed(). Default speed is set to 300 - see __init__().

Important

The robot will activate only the right motor, whilst the left motor will be completely stopped.

This causes the robot to rotate in very short circles.

spin_left()[source]¶

Rotate the GoPiGo3 towards the left while staying on the same spot.

This differs from the left() method as both wheels will be rotating but in different directions. This causes the robot to spin in place, as if doing a pirouette.

For setting the motor speed, use set_speed(). Default speed is set to 300 - see __init__().

Important

You can achieve the same effect by calling steer(-100, 100) (method steer()).

steer(left_percent, right_percent)[source]¶

Control each motor in order to get a variety of turning movements.

Each motor is assigned a percentage of the current speed value. While there is no limit on the values of left_percent and right_percent parameters, they are expected to be between -100 and 100.

Parameters:

left_percent (int) – Percentage of current speed value that gets applied to left motor. The range is between -100 (for backward rotation) and 100 (for forward rotation).
right_percent (int) – Percentage of current speed value that gets applied to right motor. The range is between -100 (for backward rotation) and 100 (for forward rotation).

For setting the motor speed, use set_speed(). Default speed is set to 300 - see __init__().

Important

Setting both left_percent and right_percent parameters to 100 will result in the same behavior as the forward() method. The other behavior for backward() method will be experienced if both parameters are set to -100.

Setting both left_percent and right_percent to 0 will stop the GoPiGo from moving.

orbit(degrees, radius_cm=0, blocking=True)[source]¶

Control the GoPiGo so it will orbit around an object.

Parameters:

degrees (int) – Degrees to steer. 360 for full rotation. Negative for left turn.
radius_cm (int) – Radius in cm of the circle to drive. Default is 0 (turn in place).
True (boolean blocking =) – Set it as a blocking or non-blocking method.

Important

Note that while in non-blocking mode the speed cannot be changed before the end of the orbit as it would negate all orbit calculations. After a non-blocking call, set_speed() has to be called before any other movement.

target_reached(left_target_degrees, right_target_degrees)[source]¶

Checks if (wheels have rotated for a given number of degrees):

The left wheel has rotated for left_target_degrees degrees.

The right wheel has rotated for right_target_degrees degrees.

If both conditions are met, it returns True, otherwise it’s False.

Parameters:

left_target_degrees (int) – Target degrees for the left wheel.
right_target_degrees (int) – Target degrees for the right wheel.

Returns:

Whether both wheels have reached their target.

Return type:

boolean.

For checking if the GoPiGo3 robot has moved forward for 360 / 360 wheel rotations, we’d use the following code snippet.

# both variables are measured in degrees
left_motor_target = 360
right_motor_target = 360

# reset the encoders
gpg3_obj.reset_encoders()
# and make the robot move forward
gpg3_obj.forward()

while gpg3_obj.target_reached(left_motor_target, right_motor_target):
    # give the robot some time to move
    sleep(0.05)

# now lets stop the robot
# otherwise it would keep on going
gpg3_obj.stop()

On the other hand, for moving the GoPiGo3 robot to the right for 187 / 360 wheel rotations of the left wheel, we’d use the following code snippet.

# both variables are measured in degrees
left_motor_target = 187
right_motor_target = 0

# reset the encoders
gpg3_obj.reset_encoders()
# and make the robot move to the right
gpg3_obj.right()

while gpg3_obj.target_reached(left_motor_target, right_motor_target):
    # give the robot some time to move
    sleep(0.05)

# now lets stop the robot
# otherwise it would keep on going
gpg3_obj.stop()

Note

You can use this method in conjunction with the following methods:

drive_cm()

drive_inches()

drive_degrees()

when they are used in non-blocking mode.

And almost everytime with the following ones:

backward()

right()

left()

forward()

reset_encoders(blocking=True)[source]¶

Resets both the encoders back to 0.

Parameters:: True (boolean blocking =) – Set it as a blocking or non-blocking method.

blocking parameter can take the following values:

True so that the method will wait for the GoPiGo3 motors to finish resetting.

False so that the method will exit immediately while the GoPiGo3 motors will continue to reset. Sending another motor command to the motors while the reset is under way might lead to confusing behavior.

read_encoders()[source]¶

Reads the encoders’ position in degrees. 360 degrees represent 1 full rotation (or 360 degrees) of a wheel.

Returns:: A tuple containing the position in degrees of each encoder. The 1st element is for the left motor and the 2nd is for the right motor.
Return type:: tuple(int,int)

read_encoders_average(units='cm')[source]¶

Reads the encoders’ position in degrees. 360 degrees represent 1 full rotation (or 360 degrees) of a wheel.

Parameters:: units (string) – By default it’s “cm”, but it could also be “in” for inches. Anything else will return raw encoder average.
Returns:: The average of the two wheel encoder values.
Return type:: int

turn_degrees(degrees, blocking=True)[source]¶

Makes the GoPiGo3 robot turn at a specific angle while staying in the same spot.

Parameters:

degrees (float) – The angle in degress at which the GoPiGo3 has to turn. For rotating the robot to the left, degrees has to negative, and make it turn to the right, degrees has to be positive.
True (boolean blocking =) – Set it as a blocking or non-blocking method.

blocking parameter can take the following values:

True so that the method will wait for the GoPiGo3 robot to finish moving.

False so that the method will exit immediately while the GoPiGo3 robot will continue moving.

In order to better understand what does this method do, let’s take a look at the following graphical representation.

In the image, we have multiple identifiers:

The “heading”: it represents the robot’s heading. By default, “rotating” the robot by 0 degrees is going to make the robot stay in place.

The “wheel circle circumference”: this is the circle that’s described by the 2 motors moving in opposite direction.

The “GoPiGo3”: the robot we’re playing with. The robot’s body isn’t draw in this representation as it’s not the main focus here.

The “wheels”: these are just the GoPiGo3’s wheels - selfexplanatory.

The effect of this class method is that the GoPiGo3 will rotate in the same spot (depending on degrees parameter), while the wheels will be describing a perfect circle.

So, in order to calculate how much the motors have to spin, we divide the angle (at which we want to rotate the robot) by 360 degrees and we get a float number between 0 and 1 (think of it as a percentage). We then multiply this value with the wheel circle circumference (which is the circumference of the circle the robot’s wheels describe when rotating in the same place).

At the end we get the distance each wheel has to travel in order to rotate the robot by degrees degrees.

blinker_on(id)[source]¶

Turns ON one of the 2 red blinkers that GoPiGo3 has.

Parameters:: id (int|str) – 0 / 1 for the right / left led or string literals can be used : "right" and "left".

blinker_off(id)[source]¶

Turns OFF one of the 2 red blinkers that GoPiGo3 has.

Parameters:: id (int|str) – 0 / 1 for the right / left led or string literals can be used : "right" and "left".

led_on(id)[source]¶

Turns ON one of the 2 red blinkers that GoPiGo3 has. The same as blinker_on().

Parameters:: id (int|str) – 0 / 1 for the right / left led or string literals can be used : "right"` and "left".

led_off(id)[source]¶

Turns OFF one of the 2 red blinkers that GoPiGo3 has. The same as blinker_off().

Parameters:: id (int|str) – 0 / 1 for the right / left led or string literals can be used : "right" and "left".

set_left_eye_color(color)[source]¶

Sets the LED color for Dexter mascot’s left eye.

Parameters:: color (tuple(int,int,int)) – 8-bit RGB tuple that represents the left eye’s color.
Raises:: TypeError – When color parameter is not valid.

Important

After setting the eye’s color, call open_left_eye() or open_eyes() to update the color, or otherwise the left eye’s color won’t change.

set_right_eye_color(color)[source]¶

Sets the LED color for Dexter mascot’s right eye.

Parameters:: color (tuple(int,int,int)) – 8-bit RGB tuple that represents the right eye’s color.
Raises:: TypeError – When color parameter is not valid.

Important

After setting the eye’s color, call open_right_eye() or open_eyes() to update the color, or otherwise the right eye’s color won’t change.

set_eye_color(color)[source]¶

Sets the LED color for Dexter mascot’s eyes.

Parameters:: color (tuple(int,int,int)) – 8-bit RGB tuple that represents the eyes’ color.
Raises:: TypeError – When color parameter is not valid.

Important

After setting the eyes’ color, call open_eyes() to update the color of both eyes, or otherwise the color won’t change.

open_left_eye()[source]¶: Turns ON Dexter mascot’s left eye.

open_right_eye()[source]¶: Turns ON Dexter mascot’s right eye.

open_eyes()[source]¶: Turns ON Dexter mascot’s eyes.

close_left_eye()[source]¶: Turns OFF Dexter mascot’s left eye.

close_right_eye()[source]¶: Turns OFF Dexter mascot’s right eye.

close_eyes()[source]¶: Turns OFF Dexter mascot’s eyes.

init_light_sensor(port='AD1')[source]¶

Initialises a LightSensor object and then returns it.

Parameters:: "AD1" (str port =) – Can be either "AD1" or "AD2". By default it’s set to be "AD1".
Returns:: An instance of the LightSensor class and with the port set to port’s value.