6. API DI-Sensors - Advanced¶

6.1. DistanceSensor¶

class di_sensors.distance_sensor.DistanceSensor(bus='RPI_1SW')[source]¶

Bases: object

Class for interfacing with the Distance Sensor.

__init__(bus='RPI_1SW')[source]¶

Constructor for initializing a DistanceSensor class.

Parameters: bus = "RPI_1SW" (str) – The bus to which the distance sensor is connected to. By default, it’s set to bus "RPI_1SW". Check the hardware specs for more information about the ports.
Raises: OSError – When the distance sensor is not connected to the designated bus/port. Most probably, this means the distance sensor is not connected at all.

start_continuous(period_ms=0)[source]¶

Start taking continuous measurements. Once this method is called, then the read_range_continuous() method should be called periodically, depending on the value that was set to period_ms parameter.

Parameters: period_ms = 0 (int) – The time between measurements. Can be set to anywhere between 20 ms and 5 secs.
Raises: OSError – When it cannot communicate with the device.

The advantage of this method over the simple read_range_single() method is that this method allows for faster reads. Therefore, this method should be used by those that want maximum performance from the sensor.

Also, the greater the value set to period_ms, the higher is the accuracy of the distance sensor.

read_range_continuous()[source]¶

Read the detected range while the sensor is taking continuous measurements at the set rate.

Returns: The detected range of the sensor as measured in millimeters. The range can go up to 2.3 meters.
Return type: int
Raises: OSError – When the distance sensor is not reachable or when the start_continuous() hasn’t been called before. This exception gets raised also when the user is trying to poll data faster than how it was initially set with the start_continuous() method.

Important

If this method is called in a shorter timeframe than the period that was set through start_continuous(), an OSError exception is thrown.

There’s also a timeout on this method that’s set to 0.5 secs. Having this timeout set to 0.5 secs means that the OSError gets thrown when the period_ms parameter of the start_continuous() method is bigger than 500 ms.

read_range_single(safe_infinity=True)[source]¶

Read the detected range with a single measurement. This is less precise/fast than its counterpart read_range_continuous(), but it’s easier to use.

Parameters: safe_infinity = True (boolean) – As sometimes the distance sensor returns a small value when there’s nothing in front of it, we need to poll again and again to confirm the presence of an obstacle. Setting safe_infinity to False will avoid that extra polling.
Returns: The detected range of the sensor as measured in millimeters. The range can go up to 2.3 meters.
Return type: int
Raises: OSError – When the distance sensor is not reachable.

timeout_occurred()[source]¶

Checks if a timeout has occurred on the read_range_continuous() method.

Returns: Whether a timeout has occurred or not.
Return type: bool

6.2. LightColorSensor¶

class di_sensors.light_color_sensor.LightColorSensor(sensor_integration_time=0.0048, sensor_gain=2, led_state=False, bus='RPI_1SW')[source]¶

Bases: object

Class for interfacing with the Light Color Sensor.

__init__(sensor_integration_time=0.0048, sensor_gain=2, led_state=False, bus='RPI_1SW')[source]¶

Constructor for initializing a link to the Light Color Sensor.

Parameters

sensor_integration_time = 0.0048 (float) – Time in seconds for each sample (aka the time needed to take a sample). Range is between 0.0024 and 0.6144 seconds. Use increments of 2.4 ms.
sensor_gain = di_sensors.TCS34725.GAIN_16X (int) – The gain constant of the sensor. Valid values are di_sensors.TCS34725.GAIN_1X, di_sensors.TCS34725.GAIN_4X, di_sensors.TCS34725.GAIN_16X or di_sensors.TCS34725.GAIN_60X.
led_state = False (bool) – The LED state. If it’s set to True, then the LED will turn on, otherwise the LED will stay off. By default, the LED is turned on.
bus = "RPI_1SW" (str) – The bus to which the distance sensor is connected to. By default, it’s set to bus "RPI_1SW". Check the hardware specs for more information about the ports.

Raises

OSError – When the Light Color Sensor is not reachable.
RuntimeError – When the chip ID is incorrect. This happens when we have a device pointing to the same address, but it’s not a Light Color Sensor.

set_led(value, delay=True)[source]¶

Set the LED state.

Parameters

value (bool) – If set to True, then the LED turns on, otherwise it stays off.
delay = True (bool) – When it’s set to True, the LED turns on after 2 * time_to_take_sample seconds have passed. This ensures that the next read following the LED change will be correct.

Raises

OSError – When the Light Color Sensor is not reachable.

get_raw_colors(delay=True)[source]¶

Read the sensor values.

Parameters: delay = True (bool) – Delay for the time it takes to sample. If the delay is set to be added, then we are ensured to get fresh values on every call. Used in conjuction with the set_led() method.
Returns: The RGBA values from the sensor. RGBA = Red, Green, Blue, Alpha (or Clear).
Return type: (float,float,float,float) where the range of each element is between 0 and 1.
Raises: OSError – If the Light Color Sensor can’t be reached.

6.3. InertialMeasurementUnit¶

class di_sensors.inertial_measurement_unit.InertialMeasurementUnit(bus='RPI_1SW')[source]¶

Bases: object

Class for interfacing with the InertialMeasurementUnit Sensor.

BNO055.get_calibration_status()¶

Get calibration status of the InertialMeasurementUnit Sensor.

The moment the sensor is powered, this method should be called almost continuously until the sensor is fully calibrated. For calibrating the sensor faster, it’s enough to hold the sensor for a couple of seconds on each “face” of an imaginary cube.

For each component of the system, there is a number that says how much the component has been calibrated:

System, 3 = fully calibrated, 0 = not calibrated.

Gyroscope, 3 = fully calibrated, 0 = not calibrated.

Accelerometer, 3 = fully calibrated, 0 = not calibrated.

Magnetometer, 3 = fully calibrated, 0 = not calibrated.

Returns: A tuple where each member shows how much a component of the IMU is calibrated. See the above description of the method.
Return type: (int,int,int,int)
Raises: OSError – When the InertialMeasurementUnit Sensor is not reachable.

Important

The sensor needs a new calibration each time it’s powered up.

__init__(bus='RPI_1SW')[source]¶

Constructor for initializing link with the InertialMeasurementUnit Sensor.

Parameters

bus = "RPI_1SW" (str) – The bus to which the distance sensor is connected to. By default, it’s set to bus "RPI_1SW". Check the hardware specs for more information about the ports.

Raises

RuntimeError – When the chip ID is incorrect. This happens when we have a device pointing to the same address, but it’s not a InertialMeasurementUnit Sensor.
OSError – When the InertialMeasurementUnit Sensor is not reachable.

read_euler()[source]¶

Read the absolute orientation.

Returns: Tuple of euler angles in degrees of heading, roll and pitch.
Return type: (float,float,float)
Raises: OSError – When the sensor is not reachable.

read_magnetometer()[source]¶

Read the magnetometer values.

Returns: Tuple containing X, Y, Z values in micro-Teslas units. You can check the X, Y, Z axes on the sensor itself.
Return type: (float,float,float)
Raises: OSError – When the sensor is not reachable.

read_gyroscope()[source]¶

Read the angular velocity of the gyroscope.

Returns: The angular velocity as a tuple of X, Y, Z values in degrees/s. You can check the X, Y, Z axes on the sensor itself.
Return type: (float,float,float)
Raises: OSError – When the sensor is not reachable.

read_accelerometer()[source]¶

Read the accelerometer.

Returns: A tuple of X, Y, Z values in meters/(second^2) units. You can check the X, Y, Z axes on the sensor itself.
Return type: (float,float,float)
Raises: OSError – When the sensor is not reachable.

read_linear_acceleration()[source]¶

Read the linear acceleration - that is, the acceleration from movement and without the gravitational acceleration in it.

Returns: The linear acceleration as a tuple of X, Y, Z values measured in meters/(second^2) units. You can check the X, Y, Z axes on the sensor itself.
Return type: (float,float,float)
Raises: OSError – When the sensor is not reachable.

read_gravity()[source]¶

Read the gravitational acceleration.

Returns: The gravitational acceleration as a tuple of X, Y, Z values in meters/(second^2) units. You can check the X, Y, Z axes on the sensor itself.
Return type: (float,float,float)
Raises: OSError – When the sensor is not reachable.

read_quaternion()[source]¶

Read the quaternion values.

Returns: The current orientation as a tuple of X, Y, Z, W quaternion values.
Return type: (float,float,float,float)
Raises: OSError – When the sensor is not present.

read_temperature()[source]¶

Read the temperature in Celsius degrees.

Returns: Temperature in Celsius degrees.
Return type: int
Raises: OSError – When the sensor can’t be contacted.

6.4. TempHumPress¶

class di_sensors.temp_hum_press.TempHumPress(bus='RPI_1SW')[source]¶

Bases: object

Class for interfacing with the Temperature Humidity Pressure Sensor.

__init__(bus='RPI_1SW')[source]¶

Constructor for initializing link with the Temperature Humidity Pressure Sensor.

Parameters: bus = "RPI_1SW" (str) – The bus to which the THP sensor is connected to. By default, it’s set to bus "RPI_1SW". Check the hardware specs for more information about the ports.
Raises: OSError – When the sensor cannot be reached.

get_temperature_celsius()[source]¶

Read temperature in Celsius degrees.

Returns: Temperature in Celsius degrees.
Return type: float
Raises: OSError – When the sensor cannot be reached.

get_temperature_fahrenheit()[source]¶

Read temperature in Fahrenheit degrees.

Returns: Temperature in Fahrenheit degrees.
Return type: float
Raises: OSError – When the sensor cannot be reached.

get_pressure()[source]¶

Read the air pressure in pascals.

Returns: The air pressure in pascals.
Return type: float
Raises: OSError – When the sensor cannot be reached.

get_humidity()[source]¶

Read the relative humidity as a percentage.

Returns: Percentage of the relative humidity.
Return type: float
Raises: OSError – When the sensor cannot be reached.

6.5. LineFollower¶

class di_sensors.line_follower.LineFollower(bus='RPI_1SW')[source]¶

Bases: object

Class for interfacing with the Line Follower Sensor (black board).

Important

This sensor is the replacement for the red one LineFollowerRed, which is getting retired, but we’ll still support it. The improvements of this one over the red one are:

Much faster poll rate - ~130 times a second vs the red one at ~60Hz.
More energy efficient - this one uses a minimum amount of power compared to the previous generation which tended to get hot to touch.
Sensors are much more accurate and consistent over the red ones.
Reduced overhead on the I2C line.

__init__(bus='RPI_1SW')[source]¶

Constructor for initializing an object to interface with the Line Follower Sensor (black board).

Parameters: bus = "RPI_1SW" (str) – The bus to which the Line Follower Sensor (black board) is connected to. By default, it’s set to "RPI_1SW". Check the hardware specs for more information about the ports.

read_sensors()[source]¶

Read the line follower’s values.

Returns: A 6-element tuple with line sensors 1 through 6 (from left to right with the arrow pointing forward) with values between 0 (black) and 1 (white).
Return type: tuple
Raises: OSError – When the Line Follower Sensor (black board) is not reachable.

get_manufacturer()[source]¶

Read the manufacturer of the Line Follower Sensor (black board)’s.

Returns: The name of the manufacturer.
Return type: str
Raises: OSError – When the Line Follower Sensor (black board) is not reachable.

get_board()[source]¶

Read the board name of the Line Follower Sensor (black board).

Returns: The name of the board.
Return type: str
Raises: OSError – When the Line Follower Sensor (black board) is not reachable.

get_version_firmware()[source]¶

Get the firmware version currently residing on the Line Follower Sensor (black board).

Returns: The version of the firmware.
Return type: str
Raises: OSError – When the Line Follower Sensor (black board) is not reachable.

class di_sensors.line_follower.LineFollowerRed(bus='RPI_1SW')[source]¶

Bases: object

Class for interfacing with the depreciated Line Follower Sensor (red board).

__init__(bus='RPI_1SW')[source]¶

Constructor for initializing an object to interface with the depreciated Line Follower Sensor (red board).

Parameters: bus = "RPI_1SW" (str) – The bus to which the depreciated Line Follower Sensor (red board) is connected to. By default, it’s set to "RPI_1SW". Check the hardware specs for more information about the ports.

read_sensors()[source]¶

Read the line follower’s values.

Returns: A 5-element tuple with the 1st element starting from the left of the sensor going to the right of it (check the markings on the sensor) with values between 0 (for black) and 1 (for white).
Return type: tuple
Raises: OSError – When the depreciated Line Follower Sensor (red board) is not reachable.

6.6. More …¶

If you wish to have a more granular control over the sensors’ functionalities, then you should check the following submodules of the DI-Sensors package:

di_sensors.BME280 - submodule for interfacing with the Temperature Humidity Pressure Sensor.

di_sensors.BNO055 - submodule for interfacing with the InertialMeasurementUnit Sensor.

di_sensors.TCS34725 - submodule for interfacing with the Light Color Sensor.

di_sensors.VL53L0X - submodule for interfacing with the Distance Sensor.

All these submodules that are being referenced in this section were used for creating the DistanceSensor, LightColorSensor, TempHumPress and the InertialMeasurementUnit classes.