Sensors¶

Buttons¶

Single Button¶

class pidevices.Button(pin_num, direction, edge='rising', bounce=200, name='', max_data_length=0)¶

A single button extends Sensor.

Parameters

pin_num (int) – BCM number of the pin.
direction (str) – Indicating the it will use pull up or pull down resistor . Could be up or down.
edge (str) – At which edge signal it will call the function. It could be rising, falling and both.
bounce (int) – The bounce time of the button. Defaults to 200ms

property pin_num¶: The bcm pin number.

property dir¶: The direction of the pull resistor.

property bounce¶: The bounce of the pull resistor.

read()¶

Read current state of button.

Returns

Represents the state of the button. 0 for not pressed: 1 for pressed.

Return type

int

when_pressed(func, *args)¶

Set a function for asynchronous call when the button is pressed.

Parameters

func (function) – The function.
*args – Arguments for the function.

wait_for_press()¶: Wait to be pressed

stop()¶: Free hardware and os resources.

class pidevices.ButtonRPiGPIO(pin_num, direction, edge='rising', bounce=200, name='', max_data_length=0)¶

A single button with rpigpio implementation extends Button.

Parameters

pin_num (int) – BCM number of the pin.
direction (str) – Indicating the it will use pull up or pull down resistor . Could be up or data:down.
edge (str) – At which edge signal it will call the function. It could be rising, falling and both.
bounce (int) – The bounce time of the button. Defaults to 200ms

start()¶: Init hardware and os resources.

class pidevices.ButtonMcp23017(pin_num, direction, edge='rising', bounce=200, bus=1, address=32, name='', max_data_length=0)¶

A single button with mcp23017 implementation extends Button.

Parameters

pin_num (int) – The module’s pin number.
direction (str) – Indicating the it will use pull up or pull down resistor . Could be up or data:down.
bounce (int) – The bounce time of the button. Defaults to 200ms

start()¶: Init hardware and os resources.

when_pressed(func, *args)¶

Set a function for asynchronous call when the button is pressed.

Parameters

func (function) – The function.
*args – Arguments for the function.

Button Array¶

class pidevices.ButtonArray(pin_nums, direction, bounce, name='', max_data_length=0)¶

An array of buttons, extends Sensor.

Parameters

pin_nums (list) – List with the gpio numbers for buttons.
direction (list|str) – Could be a list with different values per pin_num or single value.
bounce (list|int) – Could be a list with different value per pin_num or a single value.

property pin_nums¶: A list with the pin nums of the buttons

property directions¶: A list with the direction of every button.

property debounce¶: A list with the debounce time of every button.

start()¶: Init hardware and os resources.

read(button)¶

Read current state of button.

Parameters: button (int) – The number of the button.
Returns: Int with the button’s current state.
Return type: int

when_pressed(button, func, *args)¶

Set a function for asynchronous call when the button is pressed.

Parameters

button (int) – The number of the button.
func (function) – The function.
*args – Arguments for the function.

wait_for_press(b)¶

Wait to be pressed

Parameters: b (int) – The number of the button.

stop()¶: Free hardware and os resources.

add_button(pin_num, direction, bounce)¶

Add a button to the array.

Parameters: pin_num (int) – BCM number of the pin.

remove_button(button)¶

Remove a button from the array.

Parameters: button (int) – The button index.

class pidevices.ButtonArrayRPiGPIO(pin_nums, direction, bounce, name='', max_data_length=0)¶

An array of buttons, extends ButtonArray.

Parameters

pin_nums (list) – List with the gpio numbers for buttons.
direction (list|str) – Could be a list with different values per pin_num or single value.
bounce (list|int) – Could be a list with different value per pin_num or a single value.

class pidevices.ButtonArrayMcp23017(pin_nums, direction, bounce, name='', max_data_length=0)¶

An array of buttons, extends ButtonArray.

Parameters

pin_nums (list) – List with the gpio numbers for buttons.
direction (list|str) – Could be a list with different values per pin_num or single value.
bounce (list|int) – Could be a list with different value per pin_num or a single value.

enable_pressed(buttons)¶: Enable when pressed interrupts for all button

Distance sensors¶

class pidevices.DistanceSensor(name='', max_data_length=100)¶

Abstract class for distance sensors extends Sensor and a distance sensor using some common attributes.

property max_distance¶: The max distance that can be measured.

property min_distance¶: The min distance that can be measured.

HC-SR04¶

class pidevices.HcSr04(trigger_pin, echo_pin, name='', max_data_length=100)¶

HcSr04 class extends DistanceSensor

Implementation of the HC-SR04 sensor class speed of sound is 33100 + 0.6*temperature(cm/s) considering temperature = 20, speed of sound at sea level.

Hardware specs:

Operating voltage: 5V
Min distance: 2cm
Max distance: 4m

Parameters

trigger_pin (int) – BCM number of the trigger pin.
echo_pin (int) – BCM number of the echo pin.
name (str) – The optional name of the device.
max_data_length (int) – The max data of the data list.

property trigger_pin¶: Trigger pin number.

property echo_pin¶: Echo pin number.

start()¶: Initialize hardware and os resources.

stop()¶: Free hardware and os resources.

read(SAVE=False)¶

Get a distance measurment

Parameters

SAVE (boolean) – Flag for saving the measurment to the data list.

Returns

The distance in centimeters. If it return -1 it means the that: the measurment is out of the sensor’s range.

Return type

int

Raises

OutOfRange – Error when a measurment takes too long.

class pidevices.HcSr04RPiGPIO(trigger_pin, echo_pin, name='', max_data_length=100)¶

HcSr04 class extends DistanceSensor

Implementation of the HC-SR04 sensor class speed of sound is 33100 + 0.6*temperature(cm/s) considering temperature = 20, speed of sound at sea level.

Hardware specs:

Operating voltage: 5V
Min distance: 2cm
Max distance: 4m

Parameters

trigger_pin (int) – BCM number of the trigger pin.
echo_pin (int) – BCM number of the echo pin.
name (str) – The optional name of the device.
max_data_length (int) – The max data of the data list.

start()¶: Initialize hardware and os resources.

class pidevices.HcSr04Mcp23017(trigger_pin, echo_pin, bus=1, address=32, name='', max_data_length=100)¶

HcSr04 class extends DistanceSensor

UNTESTED

Implementation of the HC-SR04 sensor class speed of sound is 33100 + 0.6*temperature(cm/s) considering temperature = 20, speed of sound at sea level.

Hardware specs:

Operating voltage: 5V
Min distance: 2cm
Max distance: 4m

Parameters

trigger_pin (int) – BCM number of the trigger pin.
echo_pin (int) – BCM number of the echo pin.
name (str) – The optional name of the device.
max_data_length (int) – The max data of the data list.

start()¶: Initialize hardware and os resources.

read(SAVE=False)¶

Get a distance measurment

Parameters: SAVE (boolean) – Flag for saving the measurment to the data list.
Returns: The distance in centimeters.
Raises: OutOfRange – Error when a measurment takes too long.

vl53l1x¶

class pidevices.VL53L1X(bus=1, VL53L1X_ADDRESS=41, mode=3, name='', max_data_length=0)¶

VL53L1X ToF extends DistanceSensor. It uses this implementation.

Hardware:

voltage: 2.6V-5.5V
max_distance: 4m

The VL53L1X offers three distance modes: short, medium, and long. Long distance mode allows the longest possible ranging distance of 4 m, but the maximum range is significantly affected by ambient light. Short distance mode is mostly immune to ambient light, but the maximum ranging distance is typically limited to 1.3 m (4.4 ft). The maximum sampling rate in short distance mode is 50 Hz while the maximum sampling rate for medium and long distance modes is 30 Hz. Performance can be improved in all modes by using lower sampling rates and longer timing budgets.

First call start_ranging function and then read.

Parameters

bus (int) – The i2c bus.
VL53L1X_ADDRESS (int) – It is the i2c address of the device. Defaults to 0x29.
mode (int) – The ranging mode. Valid values 1(short), 2(medium), 3(long). Defaults to 3.

property mode¶: The distance mode of the sensor.

property bus¶: The i2c bus of the device.

property VL53L1X_ADDRESS¶: Sensor’s i2c address.

start()¶: Init hardware and os resources.

stop()¶: Free hardware and os resources.

read()¶: Get distance from VL53L1X ToF Sensor

Sharp gp2y0axxxk0f family¶

class pidevices.GP2Y0AxxxK0F(datasheet_data, adc, interval, name='', max_data_length=0)¶

Sharp gp2y0axxxk0f family of ir distance sensors extends DistanceSensor.

Parameters

datasheet_data – A 2d numpy array with the measurements from the datasheet. The array goes from max voltage to min voltage and every entry is of type voltage, cm.
adc – Instance of any adc class.
interval (float) – Interval between consecutive read.

property adc¶: Adc instance of any adc class.

start()¶: Init hardware and os resources.

read(n=1)¶

Read a measurment.

The result comes from the average of n measurments

Parameters: n (int) – The number of consecutive measurments. Defaults to 1.
Returns: The measured distance.
Raises: OutOfRange – If the measurment is out of min or max distance.

stop()¶: Free hardware and os resources.

class pidevices.GP2Y0A21YK0F(adc, name='', max_data_length=0)¶

Sharp gp2y0a21yk0f ir distance sensor extends GP2Y0AxxxK0F

Parameters: adc – Instance of any adc class.

class pidevices.GP2Y0A41SK0F(adc, name='', max_data_length=0)¶

Shaprt gp2y0a21yk0f ir distance sensor extends GP2Y0AxxxK0F

Parameters: adc – Instance of any adc class.

Line follower¶

class pidevices.LineFollower(name='', max_data_length=100)¶

Base class representing line following sensors.

property max_frequency¶: Max working frequency.

property min_dist¶: Minimum working distance.

property max_dist¶: Maximum working distance.

Cytron lss05¶

class pidevices.CytronLfLSS05(so_1, so_2, so_3, so_4, so_5, mode='dark', cal=None, max_data_length=100, name='')¶

Class representing cytron line sensor.

Parameters

so_1 (int) – BCM pin number for first ir sensor.
so_2 (int) – BCM pin number for second ir sensor.
so_3 (int) – BCM pin number for third ir sensor.
so_4 (int) – BCM pin number for fourth ir sensor.
so_5 (int) – BCM pin number for fifth ir sensor.
mode (str) – Working mode of the sensor. Valid values dark(the sensor returns one for dark line) and bright(the sesnor returns one for bright line). Defaults to dark.
cal – Calibration pin BCM number. Defaults to None for disconnected calibration pin.

property so_1¶: BCM number of 1st ir sensor.

property so_2¶: BCM number of 2nd ir sensor.

property so_3¶: BCM number of 3rd ir sensor.

property so_4¶: BCM number of 4th ir sensor.

property so_5¶: BCM number of 5th ir sensor.

property cal¶: BCM number of calibration pin.

property mode¶: Working mode of sensor. Valid value dark and bright.

start()¶

Init hardware and os resources.

Will be overloaded from specific implementations.

stop()¶: Free hardware and os resources.

read(SAVE=False)¶

Read a measurment from sensor.

Parameters

SAVE – Flag for saving measurments to the data list.

Returns

An named tuple with every sensor measurment.: The format is (so_1, so_2, so_3, so_4, so_5).

Return type

tuple

calibrate()¶: Calibrate sensor.

class pidevices.CytronLfLSS05Rpi(so_1, so_2, so_3, so_4, so_5, mode='dark', cal=None, max_data_length=100, name='')¶

Class implementing the driver of cytron line sensor using rpi.gpio implementation. Extends CytronLfLSS05

Parameters

so_1 (int) – BCM pin number for first ir sensor.
so_2 (int) – BCM pin number for second ir sensor.
so_3 (int) – BCM pin number for third ir sensor.
so_4 (int) – BCM pin number for fourth ir sensor.
so_5 (int) – BCM pin number for fifth ir sensor.
mode (str) – Working mode of the sensor. Valid values dark(the sensor returns one for dark line) and bright(the sesnor returns one for bright line). Defaults to dark.
cal – Calibration pin BCM number. Defaults to None for disconnected calibration pin.

start()¶: Init hardware and os resources.

class pidevices.CytronLfLSS05Mcp23017(so_1, so_2, so_3, so_4, so_5, mode='dark', cal=None, bus=1, address=34, max_data_length=100, name='')¶

Class implementing the driver of cytron line sensor using rpi.gpio implementation. Extends CytronLfLSS05

Parameters

so_1 (int) – Extender’s pin number for first ir sensor.
so_2 (int) – Extender’s pin number for second ir sensor.
so_3 (int) – Extender’s pin number for third ir sensor.
so_4 (int) – Extender’s pin number for fourth ir sensor.
so_5 (int) – Extender’s pin number for fifth ir sensor.
mode (str) – Working mode of the sensor. Valid values dark(the sensor returns one for dark line) and bright(the sesnor returns one for bright line). Defaults to dark.
cal – Calibration extender’s pin number. Defaults to None for disconnected calibration pin.

start()¶: Init hardware and os resources.

BME-680¶

class pidevices.BME680(bus, slave, t_oversample=1, p_oversample=0, h_oversample=0, iir_coef=0, gas_status=0, name='', max_data_length=1)¶

Class implementing BME680 sensor.

start()¶: Initialize hardware and os resources.

read(temp=True, hum=True, pres=True, gas=True)¶

Get a measurment.

Parameters

temp (bool) – Indicating if a temparature measurment will be taken.
hum (bool) – Indicating if a humidity measurment will be taken.
pres (bool) – Indicating if a pressure measurment will be taken.
gas (bool) – Indicating if a gas measurment will be taken.

stop()¶: Empty function for stopping devices, which will be overloaded.

set_idac_heat(indexes, values)¶

Set idac_heat_x registers.

Parameters

values – List with the values
indexes – List with indexes

set_heating_temp(indexes, values)¶

Set idac_heat_x registers.

Parameters

values (list) – List with the values
indexes (list) – List with indexes

set_heating_time(indexes, values)¶

Set gas wait registers.

Parameters

indexes –
values, –
multis –

set_heater_off(value)¶: Set heater of bit

IMU¶

ICM-20948¶

class pidevices.ICM_20948(bus, i2c_addr=105, name='', max_data_length=1)¶

Driver for icm 20948 imu

start()¶: Initialize hardware and os resources.

read(accel_gyro_flag=True, magne_flag=True)¶

Read measurments.

Parameters

accel_flag –
magne_flag –
gyro_flag –

bank(value)¶: Switch register self.bank.

mag_write(reg, value)¶: Write a byte to the slave magnetometer.

mag_read(reg)¶: Read a byte from the slave magnetometer.

mag_read_bytes(reg, length=1)¶: Read up to 24 bytes from the slave magnetometer.

magnetometer_ready()¶: Check the magnetometer status self._ready bit.

convert_to_degrees(x, y, z)¶

Convert magnetometer readings to degrees

Parameters

x (float) – Readings from magnetometer from the x axis.
y (float) – Readings from magnetometer from the y axis.
z (float) – Readings from magnetometer from the z axis.

Returns

Indicating the degrees of rotation.

Return type

float

set_accelerometer_sample_rate(rate=125)¶: Set the accelerometer sample rate in Hz.

set_accelerometer_full_scale(scale=16)¶: Set the accelerometer fulls cale range to +- the supplied value.

set_accelerometer_low_pass(enabled=True, mode=5)¶: Configure the accelerometer low pass filter.

set_gyro_sample_rate(rate=100)¶: Set the gyro sample rate in Hz.

set_gyro_full_scale(scale=250)¶: Set the gyro full scale range to +- supplied value.

set_gyro_low_pass(enabled=True, mode=5)¶: Configure the gyro low pass filter.

Wheel Encoders¶

class pidevices.WheelEncoder(name='', max_data_length=100)¶

Abstract class for a wheel encoders. Extends Sensor

property res¶: Resolution of the encoder.

Df Robot Wheel Encoders¶

class pidevices.DfRobotWheelEncoder(pin, name='', max_data_length=0)¶

Class implementing df robot wheel encoders. Extends WheelEncoder

Parameters: pin_num – The pin number of encoder’s signal.

property pin_num¶: The pin number of encoder’s signal.

start()¶: Initialize hardware and os resources.

read()¶

Get current state of encoder.

Returns: An integer representing the state of the encoder.

read_rpm(save=False)¶

Get rpm value of wheel.

Count until res/divisor pulses and then use the interval to compute the rounds per minute.

Parameters: save – Flag for saving the measurment to device data deque.
Returns: A number indicating the rpm value of the wheel.

stop()¶: Free hardware and os resources.

class pidevices.DfRobotWheelEncoderRpiGPIO(pin, name='', max_data_length=0)¶

Class implementing df robot wheel encoders using rpigpio library. Extends DfRobotWheelEncoder

UNTESTED

Parameters: pin_num (int) – The pin number of encoder’s signal.

start()¶: Initialize hardware and os resources.

class pidevices.DfRobotWheelEncoderMcp23017(pin, bus=1, address=32, name='', max_data_length=0)¶

Class implementing df robot wheel encoders using mcp23017 gpio extender. Extends DfRobotWheelEncoder

Parameters: pin_num – The pin number of encoder’s signal.

start()¶: Initialize hardware and os resources.

Microphone¶

class pidevices.Microphone(dev_name='mic', name='', max_data_length=0)¶

Class representing a usb microphone. Extends Sensor.

It uses pyalsaaudio library. It captures from the microphone and saves the record to a file. Currently supports only wav files. For consistent naming a udev rule has been written for identifing the device and an example asoundrc file.

Parameters: dev_name – Alsa name of the device.

property dev_name¶: The alsa name of the device.

start()¶: Initialize hardware and os resources.

read(secs, file_path=None, volume=100, file_flag=False)¶

Read data from microphone

Also set self.recording for use in a threaded environment

Parameters

secs – The time in seconds of the capture.
file_path – The file path of the file to be played. Currently it supports only wav file format.
volume – Volume percenatage

Returns

Return the path or the data in base64 format.

Raises

RuntimeError – If already recording

async_read(secs, file_path=None, volume=100, file_flag=False)¶

Async read data from microphone

Parameters

secs – The time in seconds of the capture.
file_path – The file path of the file to be played. Currently it supports only wav file format.
volume – Volume percenatage

Returns

It doesn’t return a value but it saves the recording to a file.

pause(enabled=True)¶: Pause or resume the playback.

cancel()¶: Cancel recording

stop()¶: Clean hardware and os reources.

Camera¶

class pidevices.Camera(framerate=30, resolution=Dims(width=640, height=480), name='', max_data_length=20)¶

Camera driver it uses picamera library and extends Sensor.

Parameters

framerate – The camera’s framerate defaults to 30.
resolution – Tuple that has (width, height)

property resolution¶: Camera’s resolution.

property framerate¶: Camera’s framerate.

property camera¶: Picamera object.

start()¶: Initialize hardware and os resources.

stop()¶: Free hardware and os resources.

read(batch=1, image_dims=None, image_format='rgb', save=False)¶

Take a batch of frames from camera.

Parameters

batch – The number of frames to capture
image_dims – a dims tuple or a simple tuple with width, height values
image_format – the image image_format
save – flag for appending the stream to the data deque

Returns

A deque with CameraData objects.

read_continuous(batch=1, image_dims=None, image_format='rgb')¶: Start the thread for reading continuous

stop_continuous()¶: Stop the running thread.

get_frame()¶: Return the last frame captured

ADC¶

MCP-3002¶

class pidevices.Mcp3002(port=0, device=1, v_ref=3.3, max_data_length=100, name='')¶

Mcp3002 adc implementation extends Sensor

Parameters

port – spi port.
device – spi device.
v_ref – The reference voltage. Defaults to 3.3V.

property port¶: Spi chip

property device¶: Spi device

start()¶: Initialize hardware and os resources.

stop()¶: Free hardware and os resources.

read(channel, SAVE=False)¶

Read adc value.

Parameters

channel – The adc channel. Valid values 0 and 1.
SAVE – Flag for saving to data list.

Returns

The digital value.