Dexter Industries GoPiGo3 Documentation!¶

About GoPiGo3¶

Who are we and what we do.¶

Dexter Industries is an American educational robotics company that develops robot kits that make programming accessible for everyone.

What’s this documentation about.¶

This documentation is all about the GoPiGo3 robot. Within this, you will find instructions on:

How to get started with the GoPiGo3 robot - assembling, setting up the environment, etc.

How to get started with the example programs found in our repo.

How to operate the GoPiGo3 with our API. The user has a comprehensive documentation of all the modules/functions/classes that are needed for controlling the robot.

How to troubleshoot the GoPiGo3 in case of unsuspected situations.

Getting Started¶

Buying a GoPiGo3¶

To buy a GoPiGo3 robot, please head over to our online shop and search for the GoPiGo3 robot. From our shop, you can get sensors for your robot such as the Distance Sensor, the Grove Light Sensor, etc.

Assembling GoPiGo3¶

For assembling your GoPiGo3 robot, read the instructions from the following page: assembling instructions.

Connecting to GoPiGo3¶

For connecting to your GoPiGo3 robot with a computer or laptop, read the instructions on the following page: connecting to robot.

Program your GoPiGo3¶

For programming your GoPiGo3 to do anything you want, read the instructions found here: programming your robot.

Tutorials - Basic¶

This chapter revolves around the easygopigo3 module.

Please make sure you have followed all the instructions found in Getting Started before jumping into tutorials. In all these tutorials, you will need:

A GoPiGo3 robot.

Sensor/Actuator specific for the tutorial : i.e.: a Grove Buzzer, a Line Follower, etc.

Flashing an LED¶

Our goal¶

In this tutorial, we are making a Grove Led flash continuously, while it’s being connected to a GoPiGo3 robot.

The code we analyse¶

The code we’re analyzing in this tutorial is the following one.

# import the EasyGoPiGo3 drivers
import time
import easygopigo3 as easy

# Create an instance of the GoPiGo3 class.
# GPG will be the GoPiGo3 object.
gpg = easy.EasyGoPiGo3()


# create the LED instance, passing the port and GPG
my_led = gpg.init_led("AD1")
# or
# my_LED = easy.Led("AD1", GPG)

# loop 100 times
for i in range(100):
    my_led.light_max() # turn LED at max power
    time.sleep(0.5)

    my_led.light_on(30)  # 30% power
    time.sleep(0.5)

    my_led.light_off() # turn LED off
    time.sleep(0.5)

The source code for this example program can be found here on github.

The modules¶

Start by importing 2 important modules:

import time
import easygopigo3 as easy

The easygopigo3 module is used for interacting with the GoPiGo3 robot, whilst the time module is generally used for delaying actions, commands, setting timers etc.

The objects¶

After this, we need to instantiate an easygopigo3.EasyGoPiGo3 object. We are using the EasyGoPiGo3 object for creating an instance of Led class, which is necessary for controlling the Grove Led device.

gpg = easy.EasyGoPiGo3()

Now that we have an EasyGoPiGo3 object, we can instantiate a Led object. The argument of the initializer method is the port to which we connect the Grove Led and it’s set to "AD1".

my_led = gpg.init_led("AD1")

Note

See the following graphical representation as a reference to where the ports are.

Main part¶

In this section of the tutorial we are focusing on 3 methods of the easygopigo3.Led class.

The light_max() method - which turns the LED at the maximum brightness.

The light_on() method - used for turning the LED at a certain percent of the maximum brightness.

The light_off() method - used for turning off the LED.

All in all, the following code snippet turns on the LED to the maximum brightness, then it sets the LED’s brightness at 30% and in the last it turns off the LED. The delay between all these 3 commands is set at half a second.

for i in range(100):
    my_led.light_max() # turn LED at max power
    time.sleep(0.5)

    my_led.light_on(30)  # 30% power
    time.sleep(0.5)

    my_led.light_off() # turn LED off
    time.sleep(0.5)

Running it¶

Connect the Grove Led to your GoPiGo3 robot to port "AD1" and then let’s crank up the Raspberry Pi. For running the analyzed example program, within a terminal on your Raspberry Pi, type the following 2 commands:

cd ~/Desktop/GoPiGo3/Software/Python/Examples
python easy_LED.py

Pushing a Button¶

Our goal¶

In this tutorial, we are going to control GoPiGo3 Dex’s eyes with a Grove Button.

When the Grove Button is pressed, Dex’s eyes turn on.

When the Grove Button is released, Dex’s eyes turn off.

The code we analyse¶

In the end the code should look like this.

# import the time library for the sleep function
import time

# import the GoPiGo3 drivers
import easygopigo3 as easy

# Create an instance of the GoPiGo3 class.
# GPG will be the GoPiGo3 object.
gpg = easy.EasyGoPiGo3()

# Put a grove button in port AD1
my_button = gpg.init_button_sensor("AD1")

print("Ensure there's a button in port AD1")
print("Press and release the button as often as you want")
print("the program will run for 2 minutes or")
print("Ctrl-C to interrupt it")


start = time.time()
RELEASED = 0
PRESSED = 1
state = RELEASED

while time.time() - start < 120:

    if state == RELEASED and my_button.read() == 1:
        print("PRESSED")
        gpg.open_eyes()
        state = PRESSED
    if state == PRESSED and my_button.read() == 0:
        print("RELEASED")
        gpg.close_eyes()
        state = RELEASED
    time.sleep(0.05)

print("All done!")

The source code for this example program can be found here on github.

The modules¶

Start by importing 2 important modules:

import time
import easygopigo3 as easy

The easygopigo3 module is used for interacting with the GoPiGo3 robot, whilst the time module is generally used for delaying actions, commands, setting timers etc.

The objects¶

After this, we need to instantiate an easygopigo3.EasyGoPiGo3 object. The EasyGoPiGo3 object is used for 2 things:

For turning ON and OFF the GoPiGo3 Dex’s eyes.

For instantiating a ButtonSensor object for reading the Grove Button’s state.

gpg = easy.EasyGoPiGo3()

Now that we have an EasyGoPiGo3 object, we can instantiate a ButtonSensor object. The argument of the initializer method is the port to which we connect the Grove Button and it’s set to "AD1".

my_button = gpg.init_button_sensor("AD1")

Note

See the following graphical representation as a reference to where the ports are.

Setting variables¶

Define 2 states for the button we’re using. We are setting the default state to "RELEASED".

start = time.time()
RELEASED = 0
PRESSED = 1
state = RELEASED

There’s also a variable called start to which we assign the clock time of that moment. We use it to limit for how long the script runs.

Main part¶

The main part is basically a while loop that’s going to run for 120 seconds. Within the while loop, we have 2 if / else blocks that define a simple algorithm: whenever the previous state is different from the current one, we either turn on or close Dex’s eyes. Here’s the logic:

If in the previous iteration of the while loop the button was released and now the button is 1 (aka pressed), then we turn on the LEDs and save the new state in state variable.

If in the previous iteration of the while loop the button was pressed and now the button is 0 (aka released), then we turn off the LEDs and save the new state in state variable.

This way, we don’t call gpg.open_eyes() all the time when the button is pressed or gpg.close_eyes() when the button is released. It only needs to call one of these 2 functions once.

while time.time() - start < 120:

  if state == RELEASED and my_button.read() == 1:
    print("PRESSED")
    gpg.open_eyes()
    state = PRESSED
  if state == PRESSED and my_button.read() == 0:
    print("RELEASED")
    gpg.close_eyes()
    state = RELEASED

  time.sleep(0.05)

time.sleep(0.05) was added to limit the CPU time. 50 mS is more than enough.

Running it¶

Make sure you have connected the Grove Button to your GoPiGo3 robot to port "AD1". Then, on the Rasperry Pi, from within a terminal, type the following commands.

cd ~/Desktop/GoPiGo3/Software/Python/Examples
python easy_Button.py

Ringing a Buzzer¶

Our goal¶

In this tutorial, we are making a Grove Buzzer play different musical tones on our GoPiGo3 robot. We start off with 3 musical notes and finish by playing the well-known “Twinkle Twinklle Little Star” song.

The code we analyse¶

The code we’re analyzing in this tutorial is this.

# import the time library for the sleep function
import time

# import the GoPiGo3 drivers
import easygopigo3 as easy

# Create an instance of the GoPiGo3 class.
# GPG will be the GoPiGo3 object.
gpg = easy.EasyGoPiGo3()

# Create an instance of the Buzzer
# connect a buzzer to port AD2
my_buzzer = gpg.init_buzzer("AD2")

twinkle = ["C4","C4","G4","G4","A4","A4","G4"]

print("Expecting a buzzer on Port AD2")
print("A4")
my_buzzer.sound(440)
time.sleep(1)
print("A5")
my_buzzer.sound(880)
time.sleep(1)
print("A3")
my_buzzer.sound(220)
time.sleep(1)

for note in twinkle:
    print(note)
    my_buzzer.sound(my_buzzer.scale[note])
    time.sleep(0.5)
    my_buzzer.sound_off()
    time.sleep(0.25)

my_buzzer.sound_off()

The source code for this example program can be found here on github.

The modules¶

Start by importing 2 important modules:

import time
import easygopigo3 as easy

The easygopigo3 module is used for interacting with the GoPiGo3 robot, whilst the time module is generally used for delaying actions, commands, setting timers etc.

The objects¶

After this, we need to instantiate an easygopigo3.EasyGoPiGo3 object. We will be using the EasyGoPiGo3 object for creating an instance of Buzzer class, which is necessary for controlling the Grove Buzzer device.

gpg = easy.EasyGoPiGo3()

Now that we have an EasyGoPiGo3 object, we can instantiate a Buzzer object. The argument of the initializer method is the port to which we connect the Grove Buzzer and it’s set to "AD2".

my_buzzer = gpg.init_buzzer("AD2")

Note

See the following graphical representation as a reference to where the ports are.

Setting variables¶

To play the “Twinkle Twinkle Little Star” song, we need to have a sequence of musical notes that describe this song. We’re encoding the musical notes into a list (called twinkle) of strings, where each string represents a musical note.

twinkle = ["C4","C4","G4","G4","A4","A4","G4"]

Main part¶

The main zone of the code is divided into 2 sections:

The 1st section, where we only play 3 musical notes with a 1 second delay.

The 2nd section, where we play the lovely “Twinkle Twinkle Little Start” song.

In the 1st section, we use the easygopigo3.Buzzer.sound() method, which takes as a paramater, an integer that represents the frequency of the emitted sound. As you can see in the following code snippet, each musical note corresponds to a certain frequency:

The frequency of A4 musical note is 440Hz.

The frequency of A5 musical note is 880Hz.

The frequency of A3 musical note is 220Hz.

print("A4")
my_buzzer.sound(440)
time.sleep(1)

print("A5")
my_buzzer.sound(880)
time.sleep(1)

print("A3")
my_buzzer.sound(220)
time.sleep(1)

In the 2nd section we are using the scale dictionary. In this dictionary there are stored the frequencies of each musical note. So, when using the twinkle list in conjuction with scale attribute, we’re basically retrieving the frequency of a musical note (found in twinkle attribute) from the scale dictionary.

for note in twinkle:
    print(note)
    my_buzzer.sound(buzzer.scale[note])
    time.sleep(0.5)
    my_buzzer.sound_off()
    time.sleep(0.25)

Running it¶

The only thing left to do is to connect the Grove Buzzer to your GoPiGo3 robot to port "AD2". Then, on your Raspberry Pi, from within a terminal, type the following commands:

cd ~/Desktop/GoPiGo3/Software/Python/Examples
python easy_Buzzer.py

Tip

Please don’t expect to hear a symphony, because the buzzer wasn’t made for playing tones. We use the buzzer within this context to only demonstrate that it’s a nice feature.

Detecting Light¶

Our goal¶

In this tutorial, we are making a Grove Light Sensor light up a Grove Led depending on how strong the intensity of the light is. The Grove Light Sensor and the Grove Led are both connected to the GoPiGo3 and use the following ports.

Port "AD1" for the light sensor.

Port "AD2" for the LED.

Important

Since this tutorial is based on Led tutorial, we recommend following that one before going through the current one.

The code we analyse¶

The code we’re analyzing in this tutorial is the following one.

# import the time library for the sleep function
import time

# import the GoPiGo3 drivers
import easygopigo3 as easy

# Create an instance of the GoPiGo3 class.
# GPG will be the GoPiGo3 object.
gpg = easy.EasyGoPiGo3()

# Create an instance of the Light sensor
my_light_sensor = gpg.init_light_sensor("AD1")
my_led = gpg.init_led("AD2")

# loop forever while polling the sensor
while(True):
    # get absolute value
    reading = my_light_sensor.read()
    # scale the reading to a 0-100 scale
    percent_reading = my_light_sensor.percent_read()

    # check if the light's intensity is above 50%
    if percent_reading >= 50:
      my_led.light_off()
    else:
      my_led.light_max()
    print("{}, {:.1f}%".format(reading, percent_reading))

    time.sleep(0.05)

The source code for this tutorial can also be found here on github.

The modules¶

Start by importing 2 important modules:

import time
import easygopigo3 as easy

The easygopigo3 module is used for interacting with the GoPiGo3 robot, whilst the time module is generally used for delaying actions, commands, setting timers etc.

The objects¶

After this, we need to instantiate an easygopigo3.EasyGoPiGo3 object. We are using the EasyGoPiGo3 object for creating an instance of Led class, which is necessary for controlling the Grove Led and for reading off of the Grove Light Sensor.

gpg = easy.EasyGoPiGo3()

Now that we have an EasyGoPiGo3 object, we can instantiate a LightSensor and Led objects. The argument of each of the 2 initializer methods represents the port to which a device is connected.

my_light_sensor = gpg.init_light_sensor("AD1")
my_led = gpg.init_led("AD2")

Note

See the following graphical representation as a reference to where the ports are.

Main part¶

Let’s make the LED behave in the following way.

When the light’s intensity is below 50%, turn on the LED.

When the light’s intensity is above 50%, turn off the LED.

To do this, we need to read the percentage value off of the light sensor - the variable responsible for holding the value is called percent_reading. Depending on the determined percentage, we turn the LED on or off.

To do all this, check out the following code snippet.

while(True):
    # get absolute value
    reading = my_light_sensor.read()
    # scale the reading to a 0-100 scale
    percent_reading = my_light_sensor.percent_read()

    # check if the light's intensity is above 50%
    if percent_read >= 50:
      my_led.light_off()
    else:
      my_led.light_max()
    print("{}, {:.1f}%".format(reading, percent_reading))

    time.sleep(0.05)

Running it¶

Here’s the fun part. Let’s run the python script.

Connect the Grove Light Sensor to your GoPiGo3 robot to port "AD1" and Grove Led to port "AD2". Within a terminal on your Raspberry Pi, type the following 2 commands:

cd ~/Desktop/GoPiGo3/Software/Python/Examples
python easy_Light_Sensor.py

Measuring with the Distance Sensor¶

Our goal¶

In this tutorial, we are using a Distance Sensor for measuring the distance to a target with the GoPiGo3 robot. We are going to print the values on a terminal.

The code we analyse¶

The code we’re analyzing in this tutorial is the following one.

# import the GoPiGo3 drivers
import time
import easygopigo3 as easy

# This example shows how to read values from the Distance Sensor

# Create an instance of the GoPiGo3 class.
# GPG will be the GoPiGo3 object.
gpg = easy.EasyGoPiGo3()

# Create an instance of the Distance Sensor class.
# I2C1 and I2C2 are just labels used for identifyng the port on the GoPiGo3 board.
# But technically, I2C1 and I2C2 are the same thing, so we don't have to pass any port to the constructor.
my_distance_sensor = gpg.init_distance_sensor()

while True:
    # Directly print the values of the sensor.
    print("Distance Sensor Reading (mm): " + str(my_distance_sensor.read_mm()))

The source code for this example program can be found here on github.

The modules¶

Start by importing 2 important modules:

import time
import easygopigo3 as easy

The easygopigo3 module is used for interacting with the GoPiGo3 robot, whilst the time module is generally used for delaying actions, commands, setting timers etc.

The objects¶

For interfacing with the Distance Sensor we need to instantiate an object of the easygopigo3.EasyGoPiGo3 class so in return, we can instantiate an object of the easygopigo3.DistanceSensor class. We do it like in the following code snippet.

gpg = easy.EasyGoPiGo3() # this is an EasyGoPiGo3 object
my_distance_sensor = gpg.init_distance_sensor() # this is a DistanceSensor object

Main part¶

There’s a single while loop in the entire script. The loop is for printing the values that we’re reading repeatedly. We will be using the read_mm() method for reading the distance in millimeters to the target.

while True:

    # Directly print the values of the sensor.
    print("Distance Sensor Reading (mm): " + str(my_distance_sensor.read_mm()))

Running it¶

Connect the Distance Sensor to any of the 2 "I2C" ports on the GoPiGo3 robot. After the sensor is connected, on your Raspberry Pi, open up a terminal and type in the following 2 commands.

cd ~/Desktop/GoPiGo3/Software/Python/Examples
python easy_Distance_Sensor.py

Note

See the following graphical representation as a reference to where the ports are.

Tutorials - Advanced¶

Note

Coming soon!

API Reference Point - Basic¶

Requirements¶

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

import easygopigo3

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, the GoPiGo3 repository or the GoPiGo3 package (the pip 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.

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.

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.

# we need an EasyGoPiGo3 object for instantiating sensor / actuator objects
gpg3_obj = 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

EasyGoPiGo3¶

LightSensor¶

SoundSensor¶

LoudnessSensor¶

UltrasonicSensor¶

Buzzer¶

Led¶

MotionSensor¶

ButtonSensor¶

LineFollower¶

Servo¶

DistanceSensor¶

DHTSensor¶

Warning

Coming soon!

Remote¶

API Reference Point - Advanced¶

Requirements¶

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

import easygopigo3
import gopigo3

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

You’ve followed the steps found in Getting Started guide.

You have installed either Raspbian For Robots, the GoPiGo3 repository or the GoPiGo3 package (the pip 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.

Sensor¶

DigitalSensor¶

Note

Coming soon!

AnalogSensor¶

Developer’s Guide¶

Note

Coming soon!

Our contributors¶

Matt Richardson - Github Account

Nicole Parrot - Github Account

Robert Lucian Chiriac - Github Account

John Cole - Github Account

Frequently Asked Questions¶

Note

Coming soon!

For more questions, please head over to our Dexter Industries forum.

Dexter Industries GoPiGo3 Documentation!¶

About GoPiGo3¶

Who are we and what we do.¶

What’s this documentation about.¶

Getting Started¶

Buying a GoPiGo3¶

Assembling GoPiGo3¶

Connecting to GoPiGo3¶

Program your GoPiGo3¶

Tutorials - Basic¶

Flashing an LED¶

Our goal¶

The code we analyse¶

The modules¶

The objects¶

Main part¶

Running it¶

Pushing a Button¶

Our goal¶

The code we analyse¶

The modules¶

The objects¶

Setting variables¶

Main part¶

Running it¶

Ringing a Buzzer¶

Our goal¶

The code we analyse¶

The modules¶

The objects¶

Setting variables¶

Main part¶

Running it¶

Detecting Light¶

Our goal¶

The code we analyse¶

The modules¶

The objects¶

Main part¶

Running it¶

Measuring with the Distance Sensor¶

Our goal¶

The code we analyse¶

The modules¶

The objects¶

Main part¶

Running it¶

Tutorials - Advanced¶

API Reference Point - Basic¶

Requirements¶

Hardware Ports¶

EasyGoPiGo3¶

LightSensor¶

SoundSensor¶

LoudnessSensor¶

UltrasonicSensor¶

Buzzer¶

Led¶

MotionSensor¶

ButtonSensor¶

LineFollower¶

Servo¶

DistanceSensor¶

DHTSensor¶

Remote¶

API Reference Point - Advanced¶

Requirements¶

Sensor¶

DigitalSensor¶

AnalogSensor¶

Developer’s Guide¶

Our contributors¶

Frequently Asked Questions¶

Indices and tables¶