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.GoPiGo3
This class is used for controlling a GoPiGo3 robot.
With this class you can do the following things with your GoPiGo3:
- __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
- Raises
- 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
- 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:
- forward()[source]
Move the GoPiGo3 forward.
For setting the motor speed, use
set_speed()
. Defaultspeed
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, thedist
parameter has to be positive.For moving the GoPiGo3 robot backward, thedist
parameter has to be negative.- Parameters
blocking
parameter can take the following values:
- drive_inches(dist, blocking=True)[source]
Move the GoPiGo3 forward / backward for
dist
amount of inches.For moving the GoPiGo3 robot forward, thedist
parameter has to be positive.For moving the GoPiGo3 robot backward, thedist
parameter has to be negative.- Parameters
blocking
parameter can take the following values:
- drive_degrees(degrees, blocking=True)[source]
Move the GoPiGo3 forward / backward for
degrees / 360
wheel rotations.For moving the GoPiGo3 robot forward, thedegrees
parameter has to be positive.For moving the GoPiGo3 robot backward, thedegrees
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: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()
. Defaultspeed
is set to300
- see__init__()
.
- right()[source]
Move the GoPiGo3 to the right.
For setting the motor speed, use
set_speed()
. Defaultspeed
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()
. Defaultspeed
is set to 300 - see__init__()
.Important
You can achieve the same effect by calling
steer(100, -100)
(methodsteer()
).
- left()[source]
Move the GoPiGo3 to the left.
For setting the motor speed, use
set_speed()
. Defaultspeed
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()
. Defaultspeed
is set to 300 - see__init__()
.Important
You can achieve the same effect by calling
steer(-100, 100)
(methodsteer()
).
- 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
andright_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()
. Defaultspeed
is set to 300 - see__init__()
.Important
Setting both
left_percent
andright_percent
parameters to 100 will result in the same behavior as theforward()
method. The other behavior forbackward()
method will be experienced if both parameters are set to -100.Setting both
left_percent
andright_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
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’sFalse
.- Parameters
- 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:
when they are used in non-blocking mode.
And almost everytime with the following ones:
- 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:
- read_encoders()[source]
Reads the encoders’ position in degrees. 360 degrees represent 1 full rotation (or 360 degrees) of a wheel.
- 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
- turn_degrees(degrees, blocking=True)[source]
Makes the GoPiGo3 robot turn at a specific angle while staying in the same spot.
- Parameters
blocking
parameter can take the following values: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.
- led_on(id)[source]
Turns ON one of the 2 red blinkers that GoPiGo3 has. The same as
blinker_on()
.
- led_off(id)[source]
Turns OFF one of the 2 red blinkers that GoPiGo3 has. The same as
blinker_off()
.
- 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()
oropen_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()
oropen_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.
- 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 toport
’s value.
The
"AD1"
and"AD2"
ports are mapped to the following Hardware Ports.The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofLightSensor
class.
- init_sound_sensor(port='AD1')[source]
Initialises a
SoundSensor
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
SoundSensor
class and with the port set toport
’s value.
The
"AD1"
and"AD2"
ports are mapped to the following Hardware Ports.The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofSoundSensor
class.
- init_loudness_sensor(port='AD1')[source]
Initialises a
LoudnessSensor
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
LoudnessSensor
class and with the port set toport
’s value.
The
"AD1"
and"AD2"
ports are mapped to the following Hardware Ports.The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofLoudnessSensor
class.
- init_ultrasonic_sensor(port='AD1')[source]
Initialises a
UltraSonicSensor
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
UltraSonicSensor
class and with the port set toport
’s value.
The
"AD1"
and"AD2"
ports are mapped to the following Hardware Ports.The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofUltraSonicSensor
class.
- init_buzzer(port='AD1')[source]
Initialises a
Buzzer
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
Buzzer
class and with the port set toport
’s value.
The
"AD1"
and"AD2"
ports are mapped to the following Hardware Ports.The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofBuzzer
class.
- init_led(port='AD1')[source]
Initialises a
Led
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
Led
class and with the port set toport
’s value.
The
"AD1"
and"AD2"
ports are mapped to the following Hardware Ports.The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofLed
class.
- init_button_sensor(port='AD1')[source]
Initialises a
ButtonSensor
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
ButtonSensor
class and with the port set toport
’s value.
The
"AD1"
and"AD2"
ports are mapped to the following Hardware Ports.The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofButtonSensor
class.
- init_line_follower(port='I2C')[source]
Initialises a
EasyLineFollower
object and then returns it.- Parameters
"I2C" (str port =) – The only option for this parameter for the old Line Follower Sensor (red board) is
"I2C"
and for the Line Follower Sensor (black board) it can also be"AD1"
/"AD2"
. The default value for this parameter is already set to"I2C"
.- Returns
An instance of the
EasyLineFollower
class and with the port set toport
’s value.
The
"I2C"
,"AD1"
and"AD2"
ports are mapped to the following Hardware Ports.Tip
The sensor can be connected to any of the I2C ports.You can connect different I2C devices simultaneously provided that:The I2C devices have different addresses.
The I2C devices are recognizeable by the GoPiGo3 platform.
The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofEasyLineFollower
class.
- init_servo(port='SERVO1')[source]
Initialises a
Servo
object and then returns it.- Parameters
"SERVO1" (str port =) – Can be either
"SERVO1"
or"SERVO2"
. By default it’s set to be"SERVO1"
.- Returns
An instance of the
Servo
class and with the port set toport
’s value.
The
"SERVO1"
and"SERVO2"
ports are mapped to the following Hardware Ports.The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofServo
class.
- init_distance_sensor(port='I2C')[source]
Initialises a
EasyDistanceSensor
object and then returns it.- Parameters
"I2C" (str port =) – The options for this parameter are
"I2C"
by default,"AD1"
, or"AD2"
.- Returns
An instance of the
EasyDistanceSensor
class and with the port set toport
’s value.- Raises
ImportError – When the
di_sensors
module can’t be found. Check the DI-Sensors documentation on how to install the libraries.
The ports are mapped to the following Hardware Ports.
The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofEasyDistanceSensor
class.Tip
The sensor can be connected to any of the I2C ports.You can connect different I2C devices simultaneously provided that:The I2C devices have different addresses.
The I2C devices are recognizeable by the GoPiGo3 platform.
If the devices share the same address, like two distance sensors for example, you can still use them with the GoPiGo3 provided at least one is connected via the"AD1"
, or"AD2"
, port.
- init_light_color_sensor(port='I2C', led_state=True)[source]
Initialises a
EasyLightColorSensor
object and then returns it.- Parameters
"I2C" (str port =) – The options for this parameter are
"I2C"
by default,"AD1"
, or"AD2"
.False (boolean led_state =) – Turns the onboard LED on or off. It’s best to have it on in order to detect color, and off in order to detect light value.
- Returns
An instance of the
EasyLightColorSensor
class and with the port set toport
’s value.- Raises
ImportError – When the
di_sensors
module can’t be found. Check the DI-Sensors documentation on how to install the libraries.
The ports are mapped to the following Hardware Ports.
The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofEasyLightColorSensor
class.Tip
The sensor can be connected to any of the I2C ports.You can connect different I2C devices simultaneously provided that:The I2C devices have different addresses.
The I2C devices are recognizeable by the GoPiGo3 platform.
If the devices share the same address, like two light/color sensors for example, you can still use them with the GoPiGo3 provided at least one is connected via the"AD1"
, or"AD2"
, port.
- init_imu_sensor(port='I2C')[source]
Initialises a
EasyIMUSensor
object and then returns it.- Parameters
"AD1" (str port =) – The options for this parameter are
"AD1"
by default,"AD2"
.- Returns
An instance of the
EasyIMUSensor
class and with the port set toport
’s value.- Raises
ImportError – When the
di_sensors
module can’t be found. Check the DI-Sensors documentation on how to install the libraries.
The ports are mapped to the following Hardware Ports.
The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofEasyIMUSensor
class.Tip
The sensor can be connected to any of the I2C ports.You can connect different I2C devices simultaneously provided that:The I2C devices have different addresses.
The I2C devices are recognizeable by the GoPiGo3 platform.
If the devices share the same address, like two IMU sensors for example, you can still use them with the GoPiGo3 provided at least one is connected via the"AD1"
, or"AD2"
, port.
- init_dht_sensor(sensor_type=0)[source]
Initialises a
DHTSensor
object and then returns it.- Parameters
0 (int sensor_type =) – Choose
sensor_type = 0
when you have the blue-coloured DHT sensor orsensor_type = 1
when it’s white.- Returns
An instance of the
DHTSensor
class and with the port set toport
’s value.
The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofDHTSensor
class.Important
The only port to which this device can be connected is the
"SERIAL"
port, so therefore, there’s no need for a parameter which specifies the port of device because we’ve only got one available.The
"SERIAL"
port is mapped to the following Hardware Ports.
- init_remote(port='AD1')[source]
Initialises a
Remote
object and then returns it.- Parameters
"AD1" (str port =) – Can be set to either
"AD1"
or"AD2"
. Set by default to"AD1"
.- Returns
An instance of the
Remote
class and with the port set toport
’s value.
The
"AD1"
port is mapped to the following Hardware Ports.The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofRemote
class.
- init_motion_sensor(port='AD1')[source]
Initialises a
MotionSensor
object and then returns it- Parameters
"AD1" (str port =) – Can be set to either
"AD1"
or"AD2"
. Set by default to"AD1"
.- Returns
An instance of the
MotionSensor
class and with the port set toport
’s value.
The
"AD1"
port is mapped to the following Hardware Ports.The
use_mutex
parameter of the__init__()
constructor is passed down to the constructor ofMotionSensor
class.