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, or the GoPiGo3 repository.
You have the
gopigo3
package installed by typing the commandpip freeze | grep gopigo3
on your Raspberry Pi’s terminal. If the package is installed, then a string with thegopigo3==[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:
DigitalSensor
And the classes which are found at 2nd level of inheritance from this class are:
Warning
- __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 thisEasyGoPiGo3
class for setting up the GoPiGo3 robot’s pins.
- Raises
TypeError – If the
gpg
parameter is not aEasyGoPiGo3
object.
The
port
parameter can take the following string values:"AD1"
- for digital and analogpinmode
’s."AD2"
- for digital and analogpinmode
’s."SERVO1"
- for"OUTPUT"
pinmode
."SERVO2"
- for"OUTPUT"
pinmode
."I2C"
- thepinmode
is irrelevant here."SERIAL"
- thepinmode
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 theUltraSonicSensor
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
The returned string is made of the following components:
the
descriptor
’s descriptionthe
port
namethe
pin
identifierthe
portID
- seeset_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
orgopigo3.GROVE_2_2
and for interior pins (aka NC) it returnsgopigo3.GROVE_1_2
orgopigo3.GROVE_1_2
.- Return type
- 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
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
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
See more about pin modes in
__init__()
’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 anEasyGoPiGo3
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 appropriatepinmode
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.False (bool use_mutex =) – When using multiple threads/processes that access the same resource/device, mutexes should be enabled.
- Raises
TypeError – If the
gpg
parameter is not aEasyGoPiGo3
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.
- 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
- 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.