API Reference

tmf8801

CircuitPython driver for the Adafruit TMF8801 Time of Flight Distance Sensor - 20mm to 2.5m

  • Author(s): Liz Clark

Implementation Notes

Hardware:

Software and Dependencies:

adafruit_tmf8801.tmf8801.GPIO_DISABLED = 0

GPIO is unused during capture.

adafruit_tmf8801.tmf8801.GPIO_INPUT_ACTIVE_HIGH = 2

A high level on the GPIO pauses capture.

adafruit_tmf8801.tmf8801.GPIO_INPUT_ACTIVE_LOW = 1

A low level on the GPIO pauses capture.

adafruit_tmf8801.tmf8801.GPIO_OUTPUT_HIGH = 5

The GPIO is driven high.

adafruit_tmf8801.tmf8801.GPIO_OUTPUT_LOW = 4

The GPIO is driven low.

adafruit_tmf8801.tmf8801.GPIO_OUTPUT_VCSEL = 3

The GPIO follows VCSEL timing.

adafruit_tmf8801.tmf8801.MEASUREMENT_INTERRUPTED_BY_GPIO = 2

The measurement was delayed by a GPIO input.

adafruit_tmf8801.tmf8801.MEASUREMENT_NOT_INTERRUPTED = 0

The measurement completed normally.

adafruit_tmf8801.tmf8801.RELIABILITY_LEVELS = 64

Number of distinct reliability values, from 0 (invalid) to 63 (best).

class adafruit_tmf8801.tmf8801.Result(number, distance, reliability, status, system_clock, reference_hits, object_hits)

One complete TMF8801 measurement.

number is a rolling result counter, distance is in millimeters, reliability runs from 0 (invalid) to 63 (best), status is one of the MEASUREMENT_* constants, system_clock is the sensor clock captured with the result, and reference_hits and object_hits are raw SPAD hit counts.

distance

Alias for field number 1

number

Alias for field number 0

object_hits

Alias for field number 6

reference_hits

Alias for field number 5

reliability

Alias for field number 2

status

Alias for field number 3

system_clock

Alias for field number 4

class adafruit_tmf8801.tmf8801.TMF8801(i2c: busio.I2C, address: int = _DEFAULT_ADDR)

Driver for the ams OSRAM TMF8801 Time-of-Flight distance sensor.

Parameters:

  • i2c (I2C) – The I2C bus the TMF8801 is connected to.

  • address (int) – The sensor’s I2C address. Defaults to 0x41.

Construction uploads about 11.6 kB of firmware to the sensor, which takes roughly a second and needs about 12 kB of free RAM.

property algorithm_state: bytes | None

The 11 bytes of algorithm state from the most recent result.

None until a result has been read or state is assigned. Replaying this on the next run lets the sensor skip part of its warm-up.

property algorithm_state_enabled: bool

Whether algorithm_state is sent when measuring starts.

The sensor only accepts algorithm state alongside calibration data, so this has no effect unless calibration_enabled is also set.

property calibration_data: bytes | None

The 14 bytes of stored factory calibration data.

None until factory_calibrate() runs or data is assigned. Saving these bytes and restoring them on the next run avoids recalibrating, since calibration does not survive a power cycle.

property calibration_enabled: bool

Whether calibration_data is sent when measuring starts.

chip_id

The sensor’s chip ID, which reads as 0x07 on the TMF8801.

property data_ready: bool

Whether a new measurement result is waiting to be read.

property distance: int | None

The measured distance in millimeters.

None when no result is ready or the result had a reliability of zero. Like result, reading this consumes the measurement.

factory_calibrate(timeout: float = 30.0) → bytes

Run factory calibration and store the resulting data.

Calibration should be run with the sensor pointed at empty space, with no target within about 40 cm. On success the new data is stored and calibration_enabled is turned on.

Parameters:

timeout (float) – Seconds to wait for calibration to finish.

Returns:

The 14 bytes of factory calibration data.

Raises:

RuntimeError – if calibration does not complete in time or the sensor publishes something other than calibration data.

property firmware_version: Tuple[int, int, int]

The measurement application version as (major, minor, patch).

property gpio0_mode: int

The function assigned to GPIO0 during capture.

One of GPIO_DISABLED, GPIO_INPUT_ACTIVE_LOW, GPIO_INPUT_ACTIVE_HIGH, GPIO_OUTPUT_VCSEL, GPIO_OUTPUT_LOW or GPIO_OUTPUT_HIGH.

property gpio1_mode: int

The function assigned to GPIO1 during capture.

Takes the same values as gpio0_mode.

property kilo_iterations: int

Integration iterations per measurement, in thousands.

Higher values trade measurement rate for range and accuracy. Defaults to 900, meaning 900,000 iterations.

property noise_threshold: int

Object detection noise threshold, from 0 to 255.

Zero, the default, lets the sensor use its own threshold.

property powered: bool

Whether the sensor’s CPU is powered.

Setting this to False puts the sensor into its low-power state. Setting it back to True waits for the CPU to become ready again; the uploaded firmware survives, so no reset is needed.

property repetition_period: int

Requested interval between continuous results, in milliseconds.

Defaults to 33 ms. Only used when measuring continuously.

reset() → None

Reset the sensor and reload its RAM measurement firmware.

Raises:

RuntimeError – if there is not enough free RAM for the firmware image, or if the sensor does not restart into the measurement application.

property result: Result | None

The latest complete measurement as a Result.

None if no result is ready or if the sensor is currently publishing something other than a distance result. Reading this clears the result interrupt and stores the algorithm state that comes with the result, so each measurement can only be read once.

revision_id

The sensor’s hardware revision ID.

property serial_number: int

The sensor’s 16-bit serial number.

Reading this issues a command to the sensor, so it should be read while the sensor is idle rather than mid-measurement.

start_measuring(continuous: bool = True) → None

Start distance measurements using the current configuration.

Stored calibration data and algorithm state are sent to the sensor first if they are available and enabled.

Parameters:

continuous (bool) – Measure repeatedly at repetition_period when True, or take a single measurement when False.

Raises:

RuntimeError – if the sensor does not accept the command.

status

The measurement application’s status register.

stop_measuring() → None

Stop measurements and wait for the sensor to become idle.

Raises:

RuntimeError – if the sensor does not return to its idle state.

tmf8801_firmware

TMF8801 RAM firmware image version 3.0.22.0.

Generated from main_app_3v3_k2.hex in the official ams OSRAM TMF8801_FW_v3.0.22.0 software package.

Source SHA-256: 311210096B83C129C58EF935178D4C504762B37B3CE492C03602138CAA11510F

The TMF8801 holds its measurement application in RAM, so this image must be uploaded over I2C after every reset or power cycle.

The firmware image is copyright ams OSRAM and is provided for use with TMF8801 devices. It is not covered by the MIT license of adafruit_tmf8801.