5.1. About Library & Hardware

5.1.1. Requirements

Before using this chapter’s classes, you need to be able to import the following modules.

import easygopigo3
import easysensors

Or you may prefer this approach:

from easygopigo3 import *
from easysensors import *

If you have issues importing these two modules, then make sure:

  • You have followed the steps found in Getting Started guide.

  • You have installed either Raspbian For Robots or the GoPiGo3 repository’s python package.

  • You have the gopigo3 package installed by typing the command pip freeze | grep gopigo3 on your Raspberry Pi’s terminal. If the package is installed, then a string with the gopigo3==[x.y.z] format will show up.

If you encounter issues that aren’t covered by our Getting Started guide or FAQ chapter, please head over to our forum.

5.1.2. Hardware Ports

In this graphical representation, the GoPiGo3 board has the following ports available for use. The quoted literals are to be used as pin identifiers inside the python scripts.

../_images/gpg3_ports.jpg

These ports have the following functionalities:

  • Ports "AD1" and "AD2" - general purpose input/output ports.

  • Ports "SERVO1" and "SERVO2" - servo controller ports.

  • Ports "I2C" - ports to which you can connect I2C-enabled devices.

  • Port "SERIAL" - port to which you can connect UART-enabled device.

Note

Use the quoted port names when referencing them inside a python script like in the following example.

import easygopigo3
# we need an EasyGoPiGo3 object for instantiating sensor / actuator objects
gpg3_obj = easygopigo3.EasyGoPiGo3()

# we're using the quoted port names from the above graphical representation

# here's a LightSensor object binded on port AD2
light_obj = gpg3_obj.init_light_sensor("AD2")

# here's a UltraSonicSensor object binded on port AD1
us_obj = gpg3_obj.init_ultrasonic_sensor("AD1")

# here's a LineFollower object binded on port I2C
line_follower_obj = gpg3_obj.init_line_follower("I2C")

# and so on

See also

For more technical details on the GoPiGo3 robot, please check our technical specs page.

5.1.3. Library Structure

5.1.3.1. Classes Short-List

Each of the following classes are organized in 3 modules: gopigo3, easygopigo3 and easysensors. Out of these 3 modules, we’re only interested in easygopigo3 and easysensors as gopigo3 is meant for more advanced users.

Note

The following graphic isn’t just a photo (PNG, JPEG, etc), but it’s an interactive graphic on which if you click on a class, you’ll land on the documentation of a given class.

Inheritance diagram of easysensors, easygopigo3

For intializing Sensor-derived objects, there are 2 ways to do it:

  1. Either by using the init methods of the EasyGoPiGo3 class. This is the preffered way.

  2. Or by using the constructor of each class (DHTSensor, Led, etc), which is harder because it also requires passing a EasyGoPiGo3 object for instantiation.

Note

Class easysensors.AnalogSensor does not only deal with sensors, but outputs as well like easysensors.Led and easysensors.Buzzer. While we agree this isn’t the best name for this class, we’re going to keep it this way due to compatibility reasons we don’t want to break (for now).

5.1.3.2. Functions Short-List

Here’s a short summary of the methods of all classes that are documented. We start off with a couple of lists for the methods/functions/methods of the easygopigo3 module and then we finish with another few for the easysensors module, so that we can create a visual distinction one from another and thus make it more easy to search around.

5.1.3.2.1. GoPiGo3 Movement

easygopigo3.EasyGoPiGo3([config_file_path, …])

This class is used for controlling a GoPiGo3 robot.

easygopigo3.EasyGoPiGo3.volt()

This method returns the battery voltage of the GoPiGo3.

easygopigo3.EasyGoPiGo3.set_speed(in_speed)

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

easygopigo3.EasyGoPiGo3.get_speed()

Use this method for getting the speed of your GoPiGo3.

easygopigo3.EasyGoPiGo3.reset_speed()

This method resets the speed to its original value.

easygopigo3.EasyGoPiGo3.stop()

This method stops the GoPiGo3 from moving.

easygopigo3.EasyGoPiGo3.backward()

Move the GoPiGo3 backward.

easygopigo3.EasyGoPiGo3.right()

Move the GoPiGo3 to the right.

easygopigo3.EasyGoPiGo3.spin_right()

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

easygopigo3.EasyGoPiGo3.left()

Move the GoPiGo3 to the left.

easygopigo3.EasyGoPiGo3.spin_left()

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

easygopigo3.EasyGoPiGo3.steer(left_percent, …)

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

easygopigo3.EasyGoPiGo3.orbit(degrees[, …])

Control the GoPiGo so it will orbit around an object.

easygopigo3.EasyGoPiGo3.forward()

Move the GoPiGo3 forward.

easygopigo3.EasyGoPiGo3.drive_cm(dist[, …])

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

easygopigo3.EasyGoPiGo3.drive_inches(dist[, …])

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

easygopigo3.EasyGoPiGo3.drive_degrees(degrees)

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

easygopigo3.EasyGoPiGo3.target_reached(…)

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

easygopigo3.EasyGoPiGo3.reset_encoders([…])

Resets both the encoders back to 0.

easygopigo3.EasyGoPiGo3.read_encoders()

Reads the encoders’ position in degrees.

easygopigo3.EasyGoPiGo3.turn_degrees(degrees)

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

5.1.3.2.1.1. GoPiGo3 LEDs

easygopigo3.EasyGoPiGo3.blinker_on(id)

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

easygopigo3.EasyGoPiGo3.blinker_off(id)

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

easygopigo3.EasyGoPiGo3.set_left_eye_color(color)

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

easygopigo3.EasyGoPiGo3.set_right_eye_color(color)

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

easygopigo3.EasyGoPiGo3.set_eye_color(color)

Sets the LED color for Dexter mascot’s eyes.

easygopigo3.EasyGoPiGo3.open_left_eye()

Turns ON Dexter mascot’s left eye.

easygopigo3.EasyGoPiGo3.open_right_eye()

Turns ON Dexter mascot’s right eye.

easygopigo3.EasyGoPiGo3.open_eyes()

Turns ON Dexter mascot’s eyes.

easygopigo3.EasyGoPiGo3.close_left_eye()

Turns OFF Dexter mascot’s left eye.

easygopigo3.EasyGoPiGo3.close_right_eye()

Turns OFF Dexter mascot’s right eye.

easygopigo3.EasyGoPiGo3.close_eyes()

Turns OFF Dexter mascot’s eyes.

5.1.3.2.1.2. GoPiGo3 Constants

easygopigo3.EasyGoPiGo3.load_robot_constants([…])

Load wheel diameter and wheel base width constants for the GoPiGo3 from file.

easygopigo3.EasyGoPiGo3.save_robot_constants([…])

Save the current wheel diameter and wheel base width constants (from within this object’s context) for the GoPiGo3 to file for future use.

easygopigo3.EasyGoPiGo3.set_robot_constants(…)

Set new wheel diameter and wheel base width values for the GoPiGo3.

5.1.3.2.1.3. GoPiGo3 Init Methods

easygopigo3.EasyGoPiGo3.init_light_sensor([port])

Initialises a LightSensor object and then returns it.

easygopigo3.EasyGoPiGo3.init_sound_sensor([port])

Initialises a SoundSensor object and then returns it.

easygopigo3.EasyGoPiGo3.init_loudness_sensor([port])

Initialises a LoudnessSensor object and then returns it.

easygopigo3.EasyGoPiGo3.init_ultrasonic_sensor([port])

Initialises a UltraSonicSensor object and then returns it.

easygopigo3.EasyGoPiGo3.init_buzzer([port])

Initialises a Buzzer object and then returns it.

easygopigo3.EasyGoPiGo3.init_led([port])

Initialises a Led object and then returns it.

easygopigo3.EasyGoPiGo3.init_button_sensor([port])

Initialises a ButtonSensor object and then returns it.

easygopigo3.EasyGoPiGo3.init_line_follower([port])

Initialises a EasyLineFollower object and then returns it.

easygopigo3.EasyGoPiGo3.init_servo([port])

Initialises a Servo object and then returns it.

easygopigo3.EasyGoPiGo3.init_distance_sensor([port])

Initialises a EasyDistanceSensor object and then returns it.

easygopigo3.EasyGoPiGo3.init_dht_sensor([…])

Initialises a DHTSensor object and then returns it.

easygopigo3.EasyGoPiGo3.init_remote([port])

Initialises a Remote object and then returns it.

easygopigo3.EasyGoPiGo3.init_motion_sensor([port])

Initialises a MotionSensor object and then returns it

5.1.3.2.1.4. Sensor/Actuator

easysensors.LoudnessSensor([port, gpg, …])

Class for the Grove Loudness Sensor.

easysensors.Buzzer([port, gpg, use_mutex])

Class for the Grove Buzzer.

easysensors.Buzzer.sound(freq)

Sets a musical note for the Grove Buzzer.

easysensors.Buzzer.sound_off()

Turns off the Grove Buzzer.

easysensors.Buzzer.sound_on()

Turns on the Grove Buzzer at the set frequency.

easysensors.Led([port, gpg, use_mutex])

Class for the Grove LED.

easysensors.Led.light_on(power)

Sets the duty cycle for the Grove LED.

easysensors.Led.light_max()

Turns on the Grove LED at full power.

easysensors.Led.light_off()

Turns off the Grove LED.

easysensors.Led.is_on()

Checks if the Grove LED is turned on.

easysensors.Led.is_off()

Checks if the Grove LED is turned off.

easysensors.MotionSensor([port, gpg, use_mutex])

Class for the Grove Motion Sensor.

easysensors.MotionSensor.motion_detected([port])

Checks if the Grove Motion Sensor detects a motion.

easysensors.ButtonSensor([port, gpg, use_mutex])

Class for the Grove Button.

easysensors.ButtonSensor.is_button_pressed()

Checks if the Grove Button is pressed.

easysensors.Servo([port, gpg, use_mutex])

Class for controlling servo motors with the GoPiGo3 robot.

easysensors.Servo.rotate_servo(servo_position)

Rotates the servo at a specific angle.

easysensors.Servo.reset_servo()

Resets the servo straight ahead, in the middle position.

easysensors.Servo.disable_servo()

Disable (or “float”) the servo.

easysensors.Remote([port, gpg, use_mutex])

Class for interfacing with the Infrared Receiver.

easysensors.Remote.read()

Reads the numeric code received by the Infrared Receiver.

easysensors.Remote.get_remote_code()

Returns the symbol of the pressed key in a string format.

5.1.3.2.1.5. Retired Sensor/Actuator

easysensors.LightSensor([port, gpg, use_mutex])

Class for the Grove Light Sensor.

easysensors.SoundSensor([port, gpg, use_mutex])

Class for the Grove Sound Sensor.

easysensors.UltraSonicSensor([port, gpg, …])

Class for the Grove Ultrasonic Sensor.

easysensors.UltraSonicSensor.is_too_close()

Checks whether the Grove Ultrasonic Sensor measures a distance that’s too close to a target than what we consider a safe distance.

easysensors.UltraSonicSensor.set_safe_distance(dist)

Sets a safe distance for the Grove Ultrasonic Sensor.

easysensors.UltraSonicSensor.get_safe_distance()

Gets what we call the safe distance for the Grove Ultrasonic Sensor.

easysensors.UltraSonicSensor.read_mm()

Measures the distance from a target in millimeters.

easysensors.UltraSonicSensor.read()

Measures the distance from a target in centimeters.

easysensors.UltraSonicSensor.read_inches()

Measures the distance from a target in inches.

easysensors.DHTSensor([gpg, sensor_type, …])

Class for interfacing with the Grove DHT Sensor.

easysensors.DHTSensor.read_temperature()

Return the temperature in Celsius degrees.

easysensors.DHTSensor.read_humidity()

Return the humidity as a percentage.

easysensors.DHTSensor.read()

Return the temperature and humidity.

5.1.3.2.1.6. Base Sensor

easysensors.Sensor(port, pinmode, gpg[, …])

Base class for all sensors.

easysensors.Sensor.__str__()

Prints out a short summary of the class-instantiated object’s attributes.

easysensors.Sensor.set_pin(pin)

Selects one of the 2 available pins of the grove connector.

easysensors.Sensor.get_pin()

Tells us which pin of the grove connector is used.

easysensors.Sensor.set_port(port)

Sets the port that’s going to be used by our new device.

easysensors.Sensor.get_port()

Gets the current port our device is connected to.

easysensors.Sensor.get_port_ID()

Gets the ID of the port we’re set to.

easysensors.Sensor.set_pin_mode(pinmode)

Sets the pin mode of the port we’re set to.

easysensors.Sensor.get_pin_mode()

Gets the pin mode of the port we’re set to.

easysensors.Sensor.set_descriptor(descriptor)

Sets the object’s description.

easysensors.AnalogSensor(port, pinmode, gpg)

Class for analog devices with input/output capabilities on the GoPiGo3 robot.

easysensors.AnalogSensor.read()

Reads analog value of the sensor that’s connected to our GoPiGo3 robot.

easysensors.AnalogSensor.percent_read()

Reads analog value of the sensor that’s connected to our GoPiGo3 robot as a percentage.

easysensors.AnalogSensor.write_freq(freq)

Sets the frequency of the PWM signal.