QTRSensors module

Houses QTRSensors class and associated Calibraton Data/CalibrationData class.

See qtrsensors.py by MCHobby on Github

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

See qrt-sensors-arduino by Pololu on Github (MIT License)

class QTRSensors.CalibrationData

Bases: object

as_json()

load_json(_str)

class QTRSensors.QTRSensors(pins: list[Pin], emitterPin: Pin, evenEmitterPin: Pin = None, timeout: int = 2500, maxValue: int = 4095, samples: int = 4, type=micropython.const)

Bases: object

Represents a QTR sensor array.

An instance of this class represents a QTR sensor array, consisting of one or more sensors of the same type. This could be either a single QTR sensor board or multiple boards controlled as a group.

Parameters:

pins (list[machine.Pin]) – List of machine.Pin objects representing the reflectance sensors to be read
emitterPin (machine.Pin) – machine.Pin object for the IR emitter control
evenEmitterPin (machine.Pin, optional) – machine.Pin object for the option IR emitter control of even numbered emitters. Defaults to None.
timeout (int, optional) – Timeout value in microseconds for RC (digital) sensors. Defaults to DEFAULT_TIMEOUT (2500).
maxValue (int, optional) – Maximum ADC reading value for analog sensors. Defaults to MAX_VALUE (4095).
samples (int, optional) – Number of samples to take for analog sensors. Defaults to DEFAULT_SAMPLES_PER_SENSOR (4).
type – Type of sensor used, RC (digital) or A (analog). Defaults to TYPE_RC (digital).

Raises:

ValueError – Number of pins exceeds maximum allowable
ValueError – Invalid sensor type

calibrate(mode=micropython.const)

Read the sensor for calibration.

READMODE_MANUAL is not supported

Parameters:: mode (optional) – Indicates the emitter behavior during the calibration. Defaults to READMODE_ON.

dimmable(value)

dimmingLevel(value)

emitterPin()

emitterPinCount()

emittersOff(emitters=micropython.const, wait: bool = True)

Turns the IR LEDs off. This function is mainly for use by the read() method. Since read() normally turns the emitters on and off automatically for each reading, calling this function yourself will not affect the readings unless the read mode is READMODE_MANUAL, which tells read() to leave the emitters alone.

Parameters:

emitters (optional) – Which emitters to turn off. Defaults to EMITTERS_ALL.
wait (bool, optional) – If true, this function delays to give the sensors time to turn off before returning. Otherwise, it returns immediately. Defaults to True.

emittersOn(emitters=micropython.const, wait: bool = True)

Turns the IR LEDs on.

If the sensors are dimmable and a dimming level is set, this function will apply the dimming level after turning the emitters on.

This function is mainly for use by the read() method. Since read() normally turns the emitters on and off automatically for each reading, calling this function yourself will not affect the readings unless the read mode is READMODE_MANUAL, which tells read() to leave the emitters alone.

Parameters:

emitters (optional) – Which emitters to turn off. Defaults to EMITTERS_ALL.
wait (bool, optional) – If true, this function delays to give the sensors time to turn off before returning. Otherwise, it returns immediately. Defaults to True.

emittersSelect(emitters)

Turn on selected emitters and turns off the other emitters

This function turns on the selected emitters while it waits for the other emitters to turn off. For example, emittersSelect(EMITTERS_ODD) turns on the odd-numbered emitters while turning off the even-numbered emitters. Using this method avoids unnecessary delays compared to calling emittersOff() and emittersOn() separately, but it still waits for all emitters to be in the right states before returning.

Parameters:: emitters (optional) – Which emitters to turn off. Defaults to EMITTERS_ALL.

evenEmitterPin()

oddEmitterPin()

read(mode=micropython.const)

Reads the raw sensor values.

READMODE_MANUAL is not supported.

Parameters:: mode (optional) – Indicates the emitter behavior during the calibration. Defaults to READMODE_ON.

readCalibrated(mode=micropython.const)

Reads the sensors and provides calibrated values between 0 and 1000.

READMODE_MANUAL is not supported.

Parameters:: mode (optional) – Indicates the emitter behavior during the calibration. Defaults to READMODE_ON.

readLineBlack(mode=micropython.const)

Reads the sensors, provides calibrated values, and returns an estimated black line position.

The estimate is made using a weighted average of the sensor indices multiplied by 1000, so that a return value of 0 indicates that the line is directly below sensor 0, a return value of 1000 indicates that the line is directly below sensor 1, 2000 indicates that it’s below sensor 2000, etc. Intermediate values indicate that the line is between two sensors. The formula is (where v_0 represents the value from the first sensor):

((0*v_0) + (1000*v_1) + (2000*v_2) + …) / (v_0 + v_1 + v_2 + …)

As long as your sensors aren’t spaced too far apart relative to the line, this returned value is designed to be monotonic, which makes it great for use in closed-loop PID control. Additionally, this method remembers where it last saw the line, so if you ever lose the line to the left or the right, its line position will continue to indicate the direction you need to go to reacquire the line. For example, if sensor 4 is your rightmost sensor and you end up completely off the line to the left, this function will continue to return 4000.

This function is intended to detect a black (or dark-colored) line on a white (or light-colored) background. For a white line, see readLineWhite().

Parameters:: mode (optional) – Indicates the emitter behavior during the calibration. Defaults to READMODE_ON.
Returns:: An estimate of the position of a black line under the sensors.
Return type:: int

readLineWhite(mode=micropython.const)

Reads the sensors, provides calibrated values, and returns an estimated white line position.

The estimate is made using a weighted average of the sensor indices multiplied by 1000, so that a return value of 0 indicates that the line is directly below sensor 0, a return value of 1000 indicates that the line is directly below sensor 1, 2000 indicates that it’s below sensor 2000, etc. Intermediate values indicate that the line is between two sensors. The formula is (where v_0 represents the value from the first sensor):

((0*v_0) + (1000*v_1) + (2000*v_2) + …) / (v_0 + v_1 + v_2 + …)

As long as your sensors aren’t spaced too far apart relative to the line, this returned value is designed to be monotonic, which makes it great for use in closed-loop PID control. Additionally, this method remembers where it last saw the line, so if you ever lose the line to the left or the right, its line position will continue to indicate the direction you need to go to reacquire the line. For example, if sensor 4 is your rightmost sensor and you end up completely off the line to the left, this function will continue to return 4000.

This function is intended to detect a white (or light-colored) line on a black (or dark-colored) background. For a black line, see readLineBlack().

Parameters:: mode (optional) – Indicates the emitter behavior during the calibration. Defaults to READMODE_ON.
Returns:: An estimate of the position of a black line under the sensors.
Return type:: int

resetCalibration(): Resets all calibration that has been done.

sensorPins()

setCalValues(minList: list, maxList: list, calibrationInitialized: bool, CalOn: bool = True): Sets calibration values to user-supplied presets minList: list of minimum values per sensor maxList: list of maximum values per sensor calibrationInitialized: boolean, should always be true CalOn: boolean, signifies that calibration was performed with the lights on, not off. Returns: nothing

setSamplesPerSensor(samples: int = 4)

Set the samples per sensor for analog sensors.

Parameters:: samples (int, optional) – Number of samples to be taken per read per sensor. Defaults to DEFAULT_SAMPLES_PER_SENSOR (4).

setTimeout(timeout: int = 2500)

Set the timeout value for RC (digital) sensors.

Parameters:: timeout (int, optional) – Timeout value in microseconds. Defaults to DEFAULT_TIMEOUT (2500).

setTypeAnalog(maxValue: int = 4095)

Set the sensor type to analog.

Parameters:: maxValue (int, optional) – _description_. Defaults to MAX_VALUE (4095).

setTypeRC(timeout: int = 2500)

Set the sensor type to RC (digital).

Parameters:: timeout (int, optional) – Timeout value in microseconds. Defaults to DEFAULT_TIMEOUT (2500).

timeout(value)

values()

Get the last read sensor values

Returns:: Raw or calibrated (depending if the most recently done read was read() or readCalibrated() ) sensor values.
Return type:: array[float]

QTRSensors.READMODE_MANUAL = 5: Calling read() with this mode prevents it from automatically controlling the emitters: they are left in their existing states, which allows manual control of the emitters for testing and advanced use. Calibrating and obtaining calibrated readings are not supported with this mode.

QTRSensors.READMODE_ODD_EVEN = 3: The odd-numbered sensors are read with the odd-numbered emitters on, then the even-numbered sensors are read with the even-numbered emitters on. This mode can reduce interference between adjacent sensors, especially on QTRX sensor boards. It is only usable with second-generation QTR and QTRX sensor arrays that have two emitter control pins.

QTRSensors.READMODE_ODD_EVEN_AND_OFF = 4: The odd and even sensors are read separately with the respective emitters on, then all sensors are read with emitters off and on + max − off is returned. (In other words, this mode combines OddEven and OnAndOff.)

QTRSensors.READMODE_OFF = 0: Each reading is made without turning on the infrared (IR) emitters. The reading represents ambient light levels near the sensor.

QTRSensors.READMODE_ON = 1: Each reading is made with the emitters on. The reading is a measure of reflectance.

QTRSensors.READMODE_ON_AND_OFF = 2: For each sensor, a reading is made in both the on and off states. The value returned is on + max − off, where on and off are the reading with the emitters on and off, respectively, and max is the maximum possible sensor reading. This mode can reduce the amount of interference from uneven ambient lighting.

QTRSensors.TYPE_A = 1: Analog Sensor Type

QTRSensors.TYPE_RC = 0: RC (Digital) Sensor Type