6. API GoPiGo3 - Advanced

6.1. Requirements

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

import easygopigo3

If you have issues importing this module, 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.

Take note that the easygopigo3 module depends on the underlying gopigo3 module. The base gopigo3 module contains lower level calls that would allow you finer control over your GoPiGo3 and its functionality is available to you once easygopigo3 is imported.

6.2. Sensor

class easysensors.Sensor(port, pinmode, gpg, use_mutex=False)[source]

Bases: object

Base class for all sensors. Can only be instantiated through the use of an EasyGoPiGo3 object.

It should only be used as a base class for any type of sensor. Since it contains methods for setting / getting the ports or the pinmode, it’s basically useless unless a derived class comes in and adds functionalities.

Variables
  • port (str) – There’re 4 types of ports - analog, digital, I2C and serial ports. The string identifiers are mapped in the following graphical representation - Hardware Ports.

  • pinmode (str) – Represents the mode of operation of a pin - can be a digital input/output, an analog input/output or even a custom mode which must defined in the GoPiGo3’s firmware.

  • pin (int) – Each grove connector has 4 pins: GND, VCC and 2 signal pins that can be user-defined. This variable specifies which pin of these 2 signal pins is used.

  • portID (int) – Depending on ports’s value, an ID is given to each port. This variable is not important to us.

  • descriptor (str) – Represents the “informal” string representation of an instantiated object of this class.

  • gpg (EasyGoPiGo3) – Object instance of the EasyGoPiGo3 class.

Note

The classes which derive from this class are the following:

And the classes which are found at 2nd level of inheritance from this class are:

Warning

  1. This class should only be used by the developers of the GoPiGo3 platform.

  2. The name of this class isn’t representative of the devices we connect to the GoPiGo3 robot - we don’t only use this class for sensors, but for any kind of device that we can connect to the GoPiGo3 robot.

__init__(port, pinmode, gpg, use_mutex=False)[source]

Constructor for creating a connection to one of the available grove ports on the GoPIGo3.

Parameters
  • port (str) – Specifies the port with which we want to communicate / interact with. The string literals we can use for identifying a port are found in the following graphical drawing : Hardware Ports.

  • pinmode (str) – The mode of operation of the pin we’re selecting.

  • gpg (easygopigo3.EasyGoPiGo3) – An instantiated object of the EasyGoPiGo3 class. We need this EasyGoPiGo3 class for setting up the GoPiGo3 robot’s pins.

Raises

TypeError – If the gpg parameter is not a EasyGoPiGo3 object.

The port parameter can take the following string values:

  • "AD1" - for digital and analog pinmode’s.

  • "AD2" - for digital and analog pinmode’s.

  • "SERVO1" - for "OUTPUT" pinmode.

  • "SERVO2" - for "OUTPUT" pinmode.

  • "I2C" - the pinmode is irrelevant here.

  • "SERIAL" - the pinmode is irrelevant here.

These ports’ locations can be seen in the following graphical representation - Hardware Ports.

The pinmode parameter can take the following string values:

  • "INPUT" - for general purpose inputs. The GoPiGo3 has 12-bit ADCs.

  • "DIGITAL_INPUT" - for digital inputs. The port can detect either 0 or 1.

  • "OUTPUT" - for general purpose outputs.

  • "DIGITAL_OUTPUT" - for digital outputs. The port can only be set to 0 or 1.

  • "US" - that’s for the UltraSonicSensor which can be bought from our shop. Can only be used with ports "AD1" and "AD2".

  • "IR" - that’s for the infrared receiver. Can only be used with ports "AD1" and "AD2".

Warning

At the moment, there’s no class for interfacing with the infrared receiver.

reconfig_bus()[source]

Sets the bus properly. Sometimes this needs to be done even after instantiation when two processes are trying to connect to the GoPiGo and one re-initialises the ports.

__str__()[source]

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

Returns

A string with a short summary of the object’s attributes.

Return type

str

The returned string is made of the following components:

  • the descriptor’s description

  • the port name

  • the pin identifier

  • the portID - see set_port() method.

Sample of returned string as shown in a terminal:

$ ultrasonic sensor on port AD1
$ pinmode OUTPUT
$ portID 3
set_pin(pin)[source]

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

Parameters

pin (int) – 1 for the exterior pin of the grove connector (aka SIG) or anything else for the interior one.

get_pin()[source]

Tells us which pin of the grove connector is used.

Returns

For exterior pins (aka SIG) it returns gopigo3.GROVE_2_1 or gopigo3.GROVE_2_2 and for interior pins (aka NC) it returns gopigo3.GROVE_1_2 or gopigo3.GROVE_1_2.

Return type

int

set_port(port)[source]

Sets the port that’s going to be used by our new device. Again, we can’t communicate with our device, because the class doesn’t have any methods for interfacing with it, so we need to create a derived class that does this.

Parameters

port (str) – The port we’re connecting the device to. Take a look at the Hardware Ports’ locations.

Apart from this graphical representation of the ports’ locations (Hardware Ports locations), take a look at the list of ports in __init__()’s description.

get_port()[source]

Gets the current port our device is connected to.

Returns

The current set port.

Return type

str

Apart from this graphical representation of the ports’ locations (Hardware Ports locations), take a look at the list of ports in __init__()’s description.

get_port_ID()[source]

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

Returns

The ID of the port we’re set to.

Return type

int

See more about port IDs in Sensor’s description.

set_pin_mode(pinmode)[source]

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

Parameters

pinmode (str) – The pin mode of the port.

See more about pin modes in __init__()’s description.

get_pin_mode()[source]

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

Returns

The pin mode of the port.

Return type

str

See more about pin modes in __init__()’s description.

set_descriptor(descriptor)[source]

Sets the object’s description.

Parameters

descriptor (str) – The object’s description.

See more about class descriptors in Sensor’s description.

6.3. DigitalSensor

Note

Coming soon!

6.4. AnalogSensor

class easysensors.AnalogSensor(port, pinmode, gpg, use_mutex=False)[source]

Bases: easysensors.Sensor

Class for analog devices with input/output capabilities on the GoPiGo3 robot. This class is derived from Sensor class, so this means this class inherits all attributes and methods.

For creating an AnalogSensor object an EasyGoPiGo3 object is needed like in the following example.

# initialize an EasyGoPiGo3 object first
gpg3_obj = EasyGoPiGo3()

# let's have an analog input sensor on "AD1" port
port = "AD1"
pinmode = "INPUT"

# instantiate an AnalogSensor object
# pay attention that we need the gpg3_obj
analogsensor_obj = AnalogSensor(port, pinmode, gpg3_obj)

# for example
# read the sensor's value as we have an analog sensor connected to "AD1" port
analogsensor_obj.read()

Warning

The name of this class isn’t representative of the type of devices we connect to the GoPiGo3 robot. With this class, both analog sensors and actuators (output devices such as LEDs which may require controlled output voltages) can be connected.

__init__(port, pinmode, gpg, use_mutex=False)[source]

Binds an analog device to the specified port with the appropriate pinmode mode.

Parameters
  • port (str) – The port to which the sensor/actuator is connected.

  • pinmode (str) – The pin mode of the device that’s connected to the GoPiGo3.

  • gpg (easygopigo3.EasyGoPiGo3) – Required object for instantiating an AnalogSensor object.

  • use_mutex = False (bool) – When using multiple threads/processes that access the same resource/device, mutexes should be enabled.

Raises

TypeError – If the gpg parameter is not a EasyGoPiGo3 object.

The available port’s for use are the following:

  • "AD1" - general purpose input/output port.

  • "AD2" - general purpose input/output port.

The ports’ locations can be seen in the following graphical representation: Hardware Ports.

Important

Since the grove connector allows 2 signals to pass through 2 pins (not concurently), we can select which pin to go with by using the set_pin() method. By default, we’re using pin 1, which corresponds to the exterior pin of the grove connector (aka SIG) and the wire is yellow.

read()[source]

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

Returns

12-bit number representing the voltage we get from the sensor. Range goes from 0V-5V.

Return type

int

Raises
  • gopigo3.ValueError – If an invalid value was read.

  • Exception – If any other errors happens.

percent_read()[source]

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

Returns

Percentage mapped to 0V-5V range.

Return type

int

write(power)[source]

Generates a PWM signal on the selected port. Good for simulating an DAC convertor - for instance an LED is a good candidate.

Parameters

power (int) – Number from 0 to 100 that represents the duty cycle as a percentage of the frequency’s period.

Tip

If the power parameter is out of the given range, the most close and valid value will be selected.

write_freq(freq)[source]

Sets the frequency of the PWM signal.

The frequency range goes from 3Hz up to 48000Hz. Default value is set to 24000Hz (24kHz).

Parameters

freq (int) – Frequency of the PWM signal.

See also

Read more about this in gopigo3.GoPiGo3.set_grove_pwm_frequency()’s description.