4. On Library & Hardware

4.1. Requirements

Before you check the API for the DI-Sensors, please make sure you have the DI-Sensors package installed. You can do this by checking with pip by typing the following command.

pip show DI-Sensors

Or you can check by trying to import the package in a Python console the following way:

import di_sensors

If there’s nothing to be shown when pip show-ing or you get an import error on the di_sensors package, then please check the Getting Started section and follow the instructions.

4.2. Hardware interface

Instantiating the 4 sensors in Python is a matter of choosing the right bus. Thus, there are 4 buses to choose from, depending on the context:

• The "RPI_1SW" bus - this can be used along all 5 platforms we have (the GoPiGo3, GoPiGo, BrickPi3, GrovePi & PivotPi). This bus corresponds to the "I2C" port.

• The "RPI_1" bus - this bus can be used along all 5 platforms we have (the GoPiGo3, GoPiGo, BrickPi3, GrovePi & PivotPi). Does not correspond to the "I2C" port.

• The "GPG3_AD1"/"GPG3_AD2" buses - these buses can only be used on the GoPiGo3 platform. The advantage of using these ones is that the interface between the Raspberry Pi and the sensor is more stable. These buses correspond to the "AD1" and "AD2" ports of the GoPiGo3.

Important

These notations for ports ("RPI_1SW", "RPI_1", "GPG3_AD1" and "GPG3_AD2") are only required for classes that don’t start with the Easy word, specifically for:

• DistanceSensor

• InertialMeasurementUnitSensor

• LightColorSensor

• TempHumPress

If you choose to use a sensor library that starts with the Easy word, you can use the same notations as those used and mentioned in the GoPiGo3’s documentation, such as:

• "I2C" instead of "RPI_1SW".

• "AD1/AD2" instead of "GPG3_AD1/GPG3_AD2".

Also, you may notice that for the "I2C" port we only support the "RPI_1SW", which is a software implementation for the I2C so that the hardware one can be avoided. The problem with the hardware implementation (the "RPI_1" bus) is that it’s riddled with bugs and if you don’t want your application to crash, use the software implemented one. The software implemented driver for the I2C is as fast the HW one and it doesn’t take much CPU time at all.

For seeing where the "AD1"/"AD2" are located on the GoPiGo3, please check the GoPiGo3’s documentation.

4.3. Library Structure

4.3.1. Classes Short-List

The classes that are more likely to be of interest are graphically displayed shortly after this. In this graphic you can also notice inheritance links between different classes. We can notice 3 groups of classes:

• Those that start with the Easy word in them and are easier to use and may provide some high-level functionalities.

• Those that don’t start with the Easy word and yet are related to those that are. These are generally intented for power users.

• Those that look like they might represent a model number (that belong to modules such as di_sensors.VL53L0X, di_sensors.BME280, etc). These are intented for those who want to extend the functionalities of our library and are not documented here.

Note

Since this is an interactive graphic, you can click on the displayed classes and it’ll take you to the documentation of a given class, if provided.

4.3.2. Functions Short-List

Here’s a short summary of all classes and methods. There’s a list going on for each class. We first start off by listing the Easy classes/methods and then we end up showing the classes/methods for power users. In this short summary, we’re not covering the low-level classes that are not even documented in this documentation.

4.3.2.1. Easy - TempHumPress

di_sensors.easy_temp_hum_press.EasyTHPSensor([...])	Class for interfacing with the Temperature Humidity Pressure Sensor.
di_sensors.easy_temp_hum_press.EasyTHPSensor.__init__([...])	Constructor for initializing link with the Temperature Humidity Pressure Sensor.
di_sensors.easy_temp_hum_press.EasyTHPSensor.safe_celsius()	Read temperature in Celsius degrees.
di_sensors.easy_temp_hum_press.EasyTHPSensor.safe_fahrenheit()	Read temperature in Fahrenheit degrees.
di_sensors.easy_temp_hum_press.EasyTHPSensor.safe_pressure()	Read the air pressure in pascals.
di_sensors.easy_temp_hum_press.EasyTHPSensor.safe_humidity()	Read the relative humidity as a percentage.

4.3.2.2. Easy - Light & Color

di_sensors.easy_light_color_sensor.EasyLightColorSensor([...])	Class for interfacing with the Light Color Sensor.
di_sensors.easy_light_color_sensor.EasyLightColorSensor.__init__([...])	Constructor for initializing a link to the Light Color Sensor.
di_sensors.easy_light_color_sensor.EasyLightColorSensor.translate_to_hsv(...)	Standard algorithm to switch from one color system (RGB) to another (HSV).
di_sensors.easy_light_color_sensor.EasyLightColorSensor.safe_raw_colors()	Returns the color as read by the Light Color Sensor.
di_sensors.easy_light_color_sensor.EasyLightColorSensor.safe_rgb()	Detect the RGB color off of the Light Color Sensor.
di_sensors.easy_light_color_sensor.EasyLightColorSensor.guess_color_hsv(...)	Determines which color in_color parameter is closest to in the known_colors list.

4.3.2.3. Easy - Distance

di_sensors.easy_distance_sensor.EasyDistanceSensor([...])	Class for the Distance Sensor device.
di_sensors.easy_distance_sensor.EasyDistanceSensor.__init__([...])	Creates a EasyDistanceSensor object which can be used for interfacing with a distance sensor.
di_sensors.easy_distance_sensor.EasyDistanceSensor.read_mm()	Reads the distance in millimeters.
di_sensors.easy_distance_sensor.EasyDistanceSensor.read()	Reads the distance in centimeters.
di_sensors.easy_distance_sensor.EasyDistanceSensor.read_inches()	Reads the distance in inches.

4.3.2.4. Easy - IMU

di_sensors.easy_inertial_measurement_unit.EasyIMUSensor([...])	Class for interfacing with the InertialMeasurementUnit Sensor.
di_sensors.easy_inertial_measurement_unit.EasyIMUSensor.__init__([...])	Constructor for initializing link with the InertialMeasurementUnit Sensor.
di_sensors.easy_inertial_measurement_unit.EasyIMUSensor.reconfig_bus()	Use this method when the InertialMeasurementUnit Sensor becomes unresponsive but it's still plugged into the board.
di_sensors.easy_inertial_measurement_unit.EasyIMUSensor.safe_calibrate()	Once called, the method returns when the magnetometer of the InertialMeasurementUnit Sensor gets fully calibrated.
di_sensors.easy_inertial_measurement_unit.EasyIMUSensor.safe_calibration_status()	Returns the calibration level of the magnetometer of the InertialMeasurementUnit Sensor.
di_sensors.easy_inertial_measurement_unit.EasyIMUSensor.convert_heading(...)	This method takes in a heading in degrees and return the name of the corresponding heading.
di_sensors.easy_inertial_measurement_unit.EasyIMUSensor.safe_read_euler()	Read the absolute orientation.
di_sensors.easy_inertial_measurement_unit.EasyIMUSensor.safe_read_magnetometer()	Read the magnetometer values.
di_sensors.easy_inertial_measurement_unit.EasyIMUSensor.safe_north_point()	Determines the heading of the north point.

4.3.2.5. Easy - Line Follower

di_sensors.easy_line_follower.EasyLineFollower([...])	Higher-level of abstraction class for either the LineFollower or LineFollowerRed.
di_sensors.easy_line_follower.EasyLineFollower.__init__([...])	Initialize a class to interface with either the LineFollower or the LineFollowerRed.
di_sensors.easy_line_follower.EasyLineFollower.set_calibration(color)	Calibrate the sensor for the given color and save the values to file.
di_sensors.easy_line_follower.EasyLineFollower.get_calibration(color)	Read the calibration values from the disk for the given color.
di_sensors.easy_line_follower.EasyLineFollower.read([...])	Read the sensors' values from either line follower.
di_sensors.easy_line_follower.EasyLineFollower.position_01()	Same as calling read() method like read("bivariate").
di_sensors.easy_line_follower.EasyLineFollower.position_bw()	Same as calling read() method like read("bivariate-str").
di_sensors.easy_line_follower.EasyLineFollower.position()	Returns a string telling to which side the black line that we're following is located.
di_sensors.easy_line_follower.EasyLineFollower.position_val()	Same as calling read() method like read("weighted-avg").

4.3.2.6. TempHumPress

di_sensors.temp_hum_press.TempHumPress([bus])	Class for interfacing with the Temperature Humidity Pressure Sensor.
di_sensors.temp_hum_press.TempHumPress.__init__([bus])	Constructor for initializing link with the Temperature Humidity Pressure Sensor.
di_sensors.temp_hum_press.TempHumPress.get_temperature_celsius()	Read temperature in Celsius degrees.
di_sensors.temp_hum_press.TempHumPress.get_temperature_fahrenheit()	Read temperature in Fahrenheit degrees.
di_sensors.temp_hum_press.TempHumPress.get_pressure()	Read the air pressure in pascals.
di_sensors.temp_hum_press.TempHumPress.get_humidity()	Read the relative humidity as a percentage.
di_sensors.temp_hum_press.TempHumPress.get_humidity()	Read the relative humidity as a percentage.

4.3.2.7. Light & Color

di_sensors.light_color_sensor.LightColorSensor([...])	Class for interfacing with the Light Color Sensor.
di_sensors.light_color_sensor.LightColorSensor.__init__([...])	Constructor for initializing a link to the Light Color Sensor.
di_sensors.light_color_sensor.LightColorSensor.set_led(value)	Set the LED state.
di_sensors.light_color_sensor.LightColorSensor.get_raw_colors([delay])	Read the sensor values.

4.3.2.8. Distance

di_sensors.distance_sensor.DistanceSensor([bus])	Class for interfacing with the Distance Sensor.
di_sensors.distance_sensor.DistanceSensor.__init__([bus])	Constructor for initializing a DistanceSensor class.
di_sensors.distance_sensor.DistanceSensor.start_continuous([...])	Start taking continuous measurements.
di_sensors.distance_sensor.DistanceSensor.read_range_continuous()	Read the detected range while the sensor is taking continuous measurements at the set rate.
di_sensors.distance_sensor.DistanceSensor.read_range_single([...])	Read the detected range with a single measurement.
di_sensors.distance_sensor.DistanceSensor.timeout_occurred()	Checks if a timeout has occurred on the read_range_continuous() method.

4.3.2.9. IMU

di_sensors.inertial_measurement_unit.InertialMeasurementUnit([bus])	Class for interfacing with the InertialMeasurementUnit Sensor.
di_sensors.inertial_measurement_unit.InertialMeasurementUnit.__init__([bus])	Constructor for initializing link with the InertialMeasurementUnit Sensor.
di_sensors.inertial_measurement_unit.InertialMeasurementUnit.read_euler()	Read the absolute orientation.
di_sensors.inertial_measurement_unit.InertialMeasurementUnit.read_magnetometer()	Read the magnetometer values.
di_sensors.inertial_measurement_unit.InertialMeasurementUnit.read_gyroscope()	Read the angular velocity of the gyroscope.
di_sensors.inertial_measurement_unit.InertialMeasurementUnit.read_accelerometer()	Read the accelerometer.
di_sensors.inertial_measurement_unit.InertialMeasurementUnit.read_linear_acceleration()	Read the linear acceleration - that is, the acceleration from movement and without the gravitational acceleration in it.
di_sensors.inertial_measurement_unit.InertialMeasurementUnit.read_gravity()	Read the gravitational acceleration.
di_sensors.inertial_measurement_unit.InertialMeasurementUnit.read_quaternion()	Read the quaternion values.
di_sensors.inertial_measurement_unit.InertialMeasurementUnit.read_temperature()	Read the temperature in Celsius degrees.

4.3.2.10. Line Follower Black/Red

di_sensors.line_follower.LineFollower([bus])	Class for interfacing with the Line Follower Sensor (black board).
di_sensors.line_follower.LineFollower.__init__([bus])	Constructor for initializing an object to interface with the Line Follower Sensor (black board).
di_sensors.line_follower.LineFollower.read_sensors()	Read the line follower's values.
di_sensors.line_follower.LineFollower.get_manufacturer()	Read the manufacturer of the Line Follower Sensor (black board)'s.
di_sensors.line_follower.LineFollower.get_board()	Read the board name of the Line Follower Sensor (black board).
di_sensors.line_follower.LineFollower.get_version_firmware()	Get the firmware version currently residing on the Line Follower Sensor (black board).

di_sensors.line_follower.LineFollowerRed([bus])	Class for interfacing with the depreciated Line Follower Sensor (red board).
di_sensors.line_follower.LineFollowerRed.__init__([bus])	Constructor for initializing an object to interface with the depreciated Line Follower Sensor (red board).
di_sensors.line_follower.LineFollowerRed.read_sensors()	Read the line follower's values.