Qwiic dToF Imager (TMF882X) Hookup Guide

Introduction

The SparkFun Qwiic dToF Imager - TMF8820/TMF8821 are a direct time-of-flight (dToF) sensors that includes single modular package with associated Vertical Cavity Surface Emitting Laser (VCSEL) from AMS. The dToF device is based on Single Photon Avalanche Photodiode (SPAD), time-to-digital converter (TDC) and histogram technology and achieves 5000 mm detection range. Due to its lens on the SPAD, the TMF8820 supports 3x3 multizone output data while the TMF8821 supports 3x3, 4x4, and 3x6 multizone output data. The lens on each dToF Imager provides a very wide, dynamically adjustable, field of view. A multi-lens-array (MLA) inside the package above the VCSEL widens up the FoI (field of illumination). All processing of the raw data is performed on-chip and the TMF8820/TMF8821 provide distance information together with confidence values on its I²C interface. The high performance on-chip optical filter blocks most of the ambient light, and enables distance measurements in dark and sunlight environments.

These sensors are great for projects that such as distance measurement for camera autofocus - Laser Detect Autofocus - LDAF (mobile phone), presence detection (computing and communication), object detection and collision avoidance (robotics), and light curtain (industrial).

added to your cart!

SparkFun Qwiic dToF Imager - TMF8820

In stock SEN-19036

The SparkFun Qwiic dToF TMF8820 Imager is a direct time-of-flight sensor that includes a single modular package with an assoc…

$19.95

Favorited Favorite 7

Wish List

added to your cart!

SparkFun Qwiic Mini dToF Imager - TMF8820

In stock SEN-19218

The SparkFun Qwiic Mini dToF TMF8820 Imager is a direct time-of-flight sensor that includes a single modular package with an …

$20.50

Favorited Favorite 7

Wish List

added to your cart!

SparkFun Qwiic dToF Imager - TMF8821

In stock SEN-19037

The SparkFun Qwiic dToF TMF8821 Imager is a direct time-of-flight sensor that includes a single modular package with an assoc…

$20.95

1

Favorited Favorite 8

Wish List

added to your cart!

SparkFun Qwiic Mini dToF Imager - TMF8821

In stock SEN-19451

The SparkFun Qwiic Mini dToF TMF8821 Imager is a direct time-of-flight sensor that includes a single modular package with an …

$21.50

Favorited Favorite 8

Wish List

Required Materials

To follow along with this tutorial, you will need the following materials. You may not need everything though depending on what you have. Add it to your cart, read through the guide, and adjust the cart as necessary. Note that the following wishlist includes the RedBoard Artemis and the TMF8821. Depending on your application, you can adjust the cart for a different processor board or sensor version.

Suggested Reading

If you aren't familiar with the Qwiic system, we recommend reading here for an overview.

Qwiic Connect System

We would also recommend taking a look at the following tutorials if you aren't familiar with them.

Hardware Overview

First, let's check out some of the characteristics of the TMF8820 and TMF8821 we're dealing with, so we know what to expect out of the board. Below is a comparison table for both sensors taken from the datasheet. Both are the pretty much the same except for the zone operation. Typically, the each board is powered at 3.3V via the Qwiic connector.

The layout for both the Qwiic dToF Imagers standard and mini sizes are the same. The only difference is the IC that is populated on the boards. The boards can be distinguished by the solder blob on the top side of the board. Below shows the image of the TMF8820 populated boards for the standard and mini size.

Qwiic dToF Imager - TMF8820/TMF8821 - Label	Qwiic Mini dToF Imager - TMF8820/TMF8821 - Label

Illuminator and Receiver

The TMF8820 and TMF8821 consists of an illuminator (VCSEL + MLA) and receiver (lens + SPADs). The illuminator emits a infrared laser at a frequency of 940nm. By taking a smartphone camera or DSLR out, you should be able to see the IR through the illuminator by aiming the camera at an angle when the board is powered and running the example code! The internal processor (ARM M0+ ®) executes the ams algorithm to calculate the target distance of the object.

The orientation of the TMF8820/8821 IC's illuminator (VCSEL + MLA) and receiver (lens + SPAD) can be referenced by the IC's polarity marker. You'll need to orient the board based on the marker for your project's needs. While the image below shows the TMF8820, this applies to both the TMF8820 and TMF8821 when using a 3x3 SPAD. The TMF8820 is limited to only a 3x3 SPAD.

TMF8820 - IC	TMF8820 - IC	3x3 SPAD Reference spad_map_id=1 (3x3 mode, 33°x32° FoV)

Below are SPAD map configurations for the 3x3 modes taken from the datasheet. Note that the datasheet recommends that users use the checkerboard SPAD masks for high ambient light conditions.

The orientation of the TMF8821 IC's illuminator (VCSEL + MLA) and receiver (lens + SPAD) can be reference by the IC's polarity marker. You'll need to orient the board based on the marker for your project's needs. The image below shows the TMF8821 and only applies to TMF8821 when using a 4x4 and 3x6 SPAD. The TMF8821 can support a 3x3, 4x4, or 3x6 SPAD. Make sure to configure the IC to set the size of the SPAD.

TMF8821 - IC	TMF8821 - IC	TMF8821 - 4x4 SPAD Reference spad_map_id=7 (4x4 mode, 41°x52° FoV)

Below are SPAD map configurations for the 4x4 and 3x6 modes taken from the datasheet. These configurations are possible with the TMF8821.

Broken Out Pins

The pins that are broken out are listed out as follows. Note that the pins are rearranged for the Mini version. Most likely you will be using the Qwiic cable to access the sensor. However, you can still solder header pins or wires to the PTHs.

Qwiic dToF Imager - TMF8820/TMF8821 - Breakout Pins	Qwiic Mini dToF Imager - TMF8820/TMF8821 - Breakout Pins

Qwiic and I²C

The breakout boards include 2x Qwiic connectors to easily access the I²C data lines and power. Note that the standard size uses the right angle Qwiic connecgtors The Qwiic ecosystem is made for fast prototyping by removing the need for soldering. All you need to do is plug a Qwiic cable into the Qwiic connector and voila! The I²C address for each sensor is 0x41 as stated earlier.

Qwiic dToF Imager - TMF8820/TMF8821	Qwiic Mini dToF Imager - TMF8820/TMF8821

LED

The power LED will light up when the board is powered. To disable, cut the trace on the back of the board.

Qwiic dToF Imager - TMF8820/TMF8821 - LED	Qwiic Mini dToF Imager - TMF8820/TMF8821 - LED

Jumper

There are two jumpers on the back of the board. For more information on modifying the jumpers, check out our tutorial on working with jumper pads and PCB traces.

• I²C - This three way jumper labeled I²C connects two 2.2kΩ pull-up resistors to the I²C data lines by default. If you have many devices on your I²C data lines, then you may consider cutting these.
• LED - This connects to the power LED by default. Cut the trace to disable the LED.

Qwiic dToF Imager - TMF8820/TMF8821 - Jumpers	Qwiic Mini dToF Imager - TMF8820/TMF8821 - Jumpers

Board Dimensions

The Qwiic dToF Imager TMF8820/TMF8821 use the standard Qwiic size 1.0"x1.0". The mini uses versions has a footprint that is half the size 0.5" x 1.0".

Qwiic dToF Imager - TMF8820/TMF8821 - Board Dimensions	Qwiic Mini dToF Imager - TMF8820/TMF8821 - Board Dimensions

Hardware Hookup

The following Arduino-compatible processor boards are compatible with the Qwiic dToF TMF8820/TMF8821.

• Artemis
• SAMD21/51
• ESP32
• Teensy
• STM32
• nRF52840

To connect your Qwiic dToF Imager, insert a Qwiic cable between an Arduino-compatible development board and the sensor. Then insert the associated cable for power and programming the microcontroller. In this case, we used the RedBoard Artemis and a USB type C cable. If you're going to be soldering to the through hole pins, then just attach lines to power, ground, and the I²C data lines to the microcontroller of your choice. Make sure to orient the sensor with respect to the TMF8820/TMF8821's SPADs and your application. In this case, the sensor was rotated 90° counterclockwise for reference.

For the Qwiic Mini versions, you would follow the same steps to connect to the sensor. The only difference is that the board is smaller. The image below shows the RedBoard Artemis connecting to the sensor. However, you could use an Arduino-compatible development board that has a smaller form factor. Make sure to orient the sensor with respect to the TMF8820/TMF8821's SPADs and your application.

Software Installation

The SparkFun TMF882X dToF Arduino library can be downloaded with the Arduino library manager by searching 'SparkFun TMF882X dToF Arduino Library' or you can grab the zip here from the GitHub repository to manually install:

Arduino Examples

Below are a few examples that are highlighted from the Arduino library.

Example 1: Basic

The following example uses the RedBoard Artemis. However, you could also use any Arduino-compatible microcontroller listed earlier in this tutorial if it has enough memory.

After installing the library, open the sketch in Arduino: File > Examples > SparkFun Qwiic TMF882X Arduino Library > Example-01_Basic. The following code was copied from the Arduino Library for your convenience. If you have not already, select your Board (in this case the RedBoard Artemis), and associated COM port. Upload the code to the board.

language:c
/*

  Example-01_Basic.ino

  This demo shows a basic use of a TMF882X device. The device is connected to, 
  and a single reading is taken for each loop iteration. 

  Supported Boards:

   SparkFun Qwiic dToF Imager - TMF8820        https://www.sparkfun.com/products/19036
   SparkFun Qwiic Mini dToF Imager - TMF8820   https://www.sparkfun.com/products/19218
   SparkFun Qwiic Mini dToF Imager - TMF8821   https://www.sparkfun.com/products/19451
   SparkFun Qwiic dToF Imager - TMF8821        https://www.sparkfun.com/products/19037

  Written by Kirk Benell @ SparkFun Electronics, April 2022

  Repository:
     https://github.com/sparkfun/SparkFun_Qwiic_TMF882X_Arduino_Library

  Documentation:
     https://sparkfun.github.io/SparkFun_Qwiic_TMF882X_Arduino_Library/

  SparkFun code, firmware, and software is released under the MIT License(http://opensource.org/licenses/MIT).
*/

#include "SparkFun_TMF882X_Library.h" //http://librarymanager/All#SparkFun_Qwiic_TMPF882X

SparkFun_TMF882X  myTMF882X;

// Structure to hold the measurement results - this is defined by the TMF882X SDK.

static struct tmf882x_msg_meas_results myResults;

void setup()
{

    delay(1000);
    Serial.begin(115200);
    Serial.println("");

    Serial.println("In setup");
    Serial.println("==============================");

    // Initialize the TMF882X device
    if(!myTMF882X.begin())
    {
        Serial.println("Error - The TMF882X failed to initialize - is the board connected?");
        while(1);
    }else
        Serial.println("TMF882X started.");

    // The device is now ready for operations
}

void loop()
{
    delay(2000);

    // get a Measurement
    if(myTMF882X.startMeasuring(myResults))
    {
        // print out results
        Serial.println("Measurement:");
        Serial.print("     Result Number: "); Serial.print(myResults.result_num);
        Serial.print("  Number of Results: "); Serial.println(myResults.num_results);       

        for (int i = 0; i < myResults.num_results; ++i) 
        {
            Serial.print("       conf: "); Serial.print(myResults.results[i].confidence);
            Serial.print(" distance mm: "); Serial.print(myResults.results[i].distance_mm);
            Serial.print(" channel: "); Serial.print(myResults.results[i].channel);
            Serial.print(" sub_capture: "); Serial.println(myResults.results[i].sub_capture);   

        }
        Serial.print("     photon: "); Serial.print(myResults.photon_count);    
        Serial.print(" ref photon: "); Serial.print(myResults.ref_photon_count);
        Serial.print(" ALS: "); Serial.println(myResults.ambient_light); Serial.println();

    }

}

Open the Arduino Serial Monitor set to 115200 baud. Place an object like your finger or a flat, rigid object in front of the dToF Imager's IC. You should see something similar in the output below. The readings show a high confidence value [.confidence values are between 0 and 255, with 255 being the highest] and the distance measurements in millimeters [.distance_mm] for each channel [.channel]. The output also provides information about the total photons received [.photon_count], reference photon [.ref_photon_count], and tutorial ambient light [.ambient_light]received by the channels.

Try positioning the object so that channel 1 through 3 is covered and close to the TMF8820/TMF8821. In this case, we used a piece of cardboard to partially cover the sensor. Make sure to orient the board with respect to the SPADs as shown in the image below to easily view the changes in the output.

With the Serial Monitor still open, you should see something similar to the output below. You will notice that the sensor was able to detect an object over channels 1 through 3 with a high confidence. The values for the other channels that were not covered by the cardboard showed a low confidence and longer distance values, which were close to the distance between the top of my desk and the ceiling (i.e. 12 feet). The TMF8820/TMF8821 may not display a result if the SPAD does not receive a reflected pulse.

Example 5: Verbose

With the library installed, open the sketch in Arduino: File > Examples > SparkFun Qwiic TMF882X Arduino Library > Example-05_Verbose. The following code was copied from the Arduino Library for your convenience. If you have not already, select your Board (in this case the RedBoard Artemis), and associated COM port. Upload the code to the board.

language:c
/*

  Example-05_Verbose.ino

  The TMF882X Arduino library uses the TMF882X Software Development Kit (SDK) from
  AMS to interface with the sensor. 

  The AMS SDK is able to print out informational messages during normal operation, as 
  well as debug messages. This example shows how to enable those messages and direct 
  them to a Serial device for output.

  Supported Boards:

   SparkFun Qwiic dToF Imager - TMF8820        https://www.sparkfun.com/products/19036
   SparkFun Qwiic Mini dToF Imager - TMF8820   https://www.sparkfun.com/products/19218
   SparkFun Qwiic Mini dToF Imager - TMF8821   https://www.sparkfun.com/products/19451
   SparkFun Qwiic dToF Imager - TMF8821        https://www.sparkfun.com/products/19037

  Written by Kirk Benell @ SparkFun Electronics, April 2022

  Repository:
     https://github.com/sparkfun/SparkFun_Qwiic_TMF882X_Arduino_Library

  Documentation:
     https://sparkfun.github.io/SparkFun_Qwiic_TMF882X_Arduino_Library/

  SparkFun code, firmware, and software is released under the MIT License(http://opensource.org/licenses/MIT).
*/

#include "SparkFun_TMF882X_Library.h"    //http://librarymanager/All#SparkFun_Qwiic_TMPF882X

SparkFun_TMF882X  myTMF882X;

static struct tmf882x_msg_meas_results myResults;

void setup()
{

    delay(1000);
    Serial.begin(115200);
    Serial.println("");

    Serial.println("In setup");
    Serial.println("==============================");

    // The underlying TMF882X SDK can output a wide variety of information during 
    // normal operation. It's very verbose.
    //
    // Enable this output as part of this demo.
    //
    // Pass in our output device - Serial

    myTMF882X.setOutputDevice(Serial);

    // Enable Info messages
    myTMF882X.setInfoMessages(true);

    // Enable Debug mode. Set this before calling begin to get initialization debug 
    // information.

    myTMF882X.setDebug(true);

    if(!myTMF882X.begin())
    {
        Serial.println("Error - The TMF882X failed to initialize - is the board connected?");
        while(1);
    }else
        Serial.println("TMF882X started.");


}

void loop()
{
    delay(2000);

    // get a myResultsurment
    if(myTMF882X.startMeasuring(myResults))
    {
        // print out results
        Serial.println("Measurement:");
        Serial.print("     Result Number: "); Serial.print(myResults.result_num);
        Serial.print("  Number of Results: "); Serial.println(myResults.num_results);       

        for (uint32_t i = 0; i < myResults.num_results; ++i) 
        {
            Serial.print("       conf: "); Serial.print(myResults.results[i].confidence);
            Serial.print(" distance mm: "); Serial.print(myResults.results[i].distance_mm);
            Serial.print(" channel: "); Serial.print(myResults.results[i].channel);
            Serial.print(" sub_capture: "); Serial.println(myResults.results[i].sub_capture);   

        }
        Serial.print("     photon: "); Serial.print(myResults.photon_count);    
        Serial.print(" ref photon: "); Serial.print(myResults.ref_photon_count);
        Serial.print(" ALS: "); Serial.println(myResults.ambient_light); Serial.println();

    }

}

Open the Arduino Serial Monitor set to 115200 baud. The output is similar to the Basic example. However, there is additional information displayed. This information is useful for those debugging with the TMF8820 or TMF8821. The measurements were taken when an object was covering the IC completely.

Example 8: Factory Calibration

This example is suggested when placing the TMF8820 and TMF8821 its final application and when adjusting the SPAD mask selection. As suggested in the datasheet under 7.3 Calibration, "the calibration test shall be done in a housing with minimal ambient light and no target within 40 cm in field of view of the TMF8820/21."

With the library installed, open the sketch in Arduino: File > Examples > SparkFun Qwiic TMF882X Arduino Library > Example-08_FactoryCal. The following code was copied from the Arduino Library for your convenience. If you have not already, select your Board (in this case the RedBoard Artemis), and associated COM port. Upload the code to the board.

language:c
/*

  Example-08_FactoryCal.ino

  This example shows how to peform a Factory Calibration on the connected 
  TMF882X device. Details on the calibration and it's use are contained in
  the TMF882X datasheet.

  Supported Boards:

   SparkFun Qwiic dToF Imager - TMF8820        https://www.sparkfun.com/products/19036
   SparkFun Qwiic Mini dToF Imager - TMF8820   https://www.sparkfun.com/products/19218
   SparkFun Qwiic Mini dToF Imager - TMF8821   https://www.sparkfun.com/products/19451
   SparkFun Qwiic dToF Imager - TMF8821        https://www.sparkfun.com/products/19037

  Written by Kirk Benell @ SparkFun Electronics, April 2022

  Repository:
     https://github.com/sparkfun/SparkFun_Qwiic_TMF882X_Arduino_Library

  Documentation:
     https://sparkfun.github.io/SparkFun_Qwiic_TMF882X_Arduino_Library/

  SparkFun code, firmware, and software is released under the MIT License(http://opensource.org/licenses/MIT).
*/


#include <SparkFun_TMF882X_Library.h>    //http://librarymanager/All#SparkFun_Qwiic_TMPF882X

SparkFun_TMF882X  myTMF882X;

void setup()
{

    delay(1000);
    Serial.begin(115200);
    Serial.println("");

    Serial.println("In setup");
    Serial.println("==============================");

    if(!myTMF882X.begin())
    {
        Serial.println("Error - The TMF882X failed to initialize - is the board connected?");
        while(1){}
    }else
        Serial.println("TMF882X started.");


    Serial.println();
    Serial.println("Performing a Factory Calibration.");
    Serial.println();
    // Perform a factory calibration of the connected device.

    // First set some config parameters to support the calibration
    struct tmf882x_mode_app_config tofConfig;
    if (!myTMF882X.getTMF882XConfig(tofConfig)) 
    {
        Serial.println("Error - unable to get device configuration.");
        while(1){}
    }

    // Change the APP configuration
    //  - set the reporting period to 500 milliseconds
    //  - set the iterations to 4,000,000 (4M) to perform factory calibration
    tofConfig.report_period_ms = 500;
    tofConfig.kilo_iterations = 4000;

    if (!myTMF882X.setTMF882XConfig(tofConfig)) 
    {
        Serial.println("Error - unable to set device configuration.");
        while(1){}
    }

    struct tmf882x_mode_app_calib factoryCal;

    // Peform the calibration
    if (!myTMF882X.factoryCalibration(factoryCal)) 
    {
        Serial.println("Error - Factory Calibration Failed.");
        while(1){}
    }

    // Output the calibration
    Serial.println("Calibration Complete"); 
    Serial.println();
    Serial.print("Calibration Data Length: ");
    Serial.println(factoryCal.calib_len);

    Serial.println("Calibration Data:");
    for (int i = 0; i < factoryCal.calib_len; i++)
    {
        Serial.print("   "); Serial.print(factoryCal.data[i]);

        if ( (i + 1) % 16 == 0 )
            Serial.println();
    }
    Serial.println();

}

void loop()
{
    delay(2000);

    // Nothing - just here for the calibration example
}

Open the Arduino Serial Monitor set to 115200 baud. You will see an output similar to the image below. You will need to follow the datasheet to calibrate the sensor properly.

Example 9: SPAD Map

With the library installed, open the sketch in Arduino: File > Examples > SparkFun Qwiic TMF882X Arduino Library > Example-09_SPADMap. The following code was copied from the Arduino Library for your convenience. If you have not already, select your Board (in this case the RedBoard Artemis), and associated COM port. Upload the code to the board.

language:c
/*

  Example-09_SPADMap.ino

  The Optical performance of the TMF882X is controled by a SPAD (Single Photon
  Avalanche Photodiode) Map. 

  SPAD Maps are set using a SPAD Map ID, which are detailed in the TMF882X datasheet.

  This example shows how to determine the current SPAD Map on the device and change 
  it to a desired map.

  Supported Boards:

   SparkFun Qwiic dToF Imager - TMF8820        https://www.sparkfun.com/products/19036
   SparkFun Qwiic Mini dToF Imager - TMF8820   https://www.sparkfun.com/products/19218
   SparkFun Qwiic Mini dToF Imager - TMF8821   https://www.sparkfun.com/products/19451
   SparkFun Qwiic dToF Imager - TMF8821        https://www.sparkfun.com/products/19037

  Written by Kirk Benell @ SparkFun Electronics, April 2022

  Repository:
     https://github.com/sparkfun/SparkFun_Qwiic_TMF882X_Arduino_Library

  Documentation:
     https://sparkfun.github.io/SparkFun_Qwiic_TMF882X_Arduino_Library/

  SparkFun code, firmware, and software is released under the MIT License(http://opensource.org/licenses/MIT).
*/

#include <SparkFun_TMF882X_Library.h>    //http://librarymanager/All#SparkFun_Qwiic_TMPF882X

static struct tmf882x_msg_meas_results myResults;


SparkFun_TMF882X  myTMF882X;

// What SPAD map to change to

#define NEW_SPAD_MAP 2

void setup()
{

    delay(1000);
    Serial.begin(115200);
    Serial.println("");

    Serial.println("In setup");
    Serial.println("==============================");

    if(!myTMF882X.begin())
    {
        Serial.println("Error - The TMF882X failed to initialize - is the board connected?");
        while(1){}
    }else
        Serial.println("TMF882X started.");


    // Let's change the SPAD map in use on this device.
    //
    // Get the current SPAD Map ID
    int spadMap =  myTMF882X.getCurrentSPADMap();
    Serial.println();
    Serial.print("Current SPAD Map ID: ");
    Serial.println(spadMap);

    // Now switch
    Serial.println("Switching SPAD Map to ID 2 - 3x3 Macro 1 off center");
    Serial.println();

    if (!myTMF882X.setCurrentSPADMap(NEW_SPAD_MAP))
    {
        Serial.println("Error -  Failed to set the SPAD Map - halting");
        while(1){}
    }

    // Let's make sure it worked
    spadMap =  myTMF882X.getCurrentSPADMap();

    if(spadMap != NEW_SPAD_MAP)
    {
        Serial.println("Error -  Failed to set the SPAD Map - halting");
        while(1){}
    }

    Serial.print("The new SPAD Map ID: ");
    Serial.println(spadMap);

    // Now set some config parameters to support the spad map
    struct tmf882x_mode_app_config tofConfig;

    if (!myTMF882X.getTMF882XConfig(tofConfig)) 
    {
        Serial.println("Error - unable to get device configuration.");
        while(1){}
    }

    // Change the APP configuration
    //  - set the reporting period to 500 milliseconds
    tofConfig.report_period_ms = 500;

    if (!myTMF882X.setTMF882XConfig(tofConfig)) 
    {
        Serial.println("Error - unable to set device configuration.");
        while(1){}
    }

}

void loop()
{
    delay(2000);

    // get a myResultsurment
    if(myTMF882X.startMeasuring(myResults))
    {
        // print out results
        Serial.println("Measurement:");
        Serial.print("     Result Number: "); Serial.print(myResults.result_num);
        Serial.print("  Number of Results: "); Serial.println(myResults.num_results);       

        for (int i = 0; i < myResults.num_results; ++i) 
        {
            Serial.print("       conf: "); Serial.print(myResults.results[i].confidence);
            Serial.print(" distance mm: "); Serial.print(myResults.results[i].distance_mm);
            Serial.print(" channel: "); Serial.print(myResults.results[i].channel);
            Serial.print(" sub_capture: "); Serial.println(myResults.results[i].sub_capture);   

        }
        Serial.print("     photon: "); Serial.print(myResults.photon_count);    
        Serial.print(" ref photon: "); Serial.print(myResults.ref_photon_count);
        Serial.print(" ALS: "); Serial.println(myResults.ambient_light); Serial.println();

    }
}

This example allows you to select the operating mode of the SPAD. The datasheet under "8.5.17 SPAD_MAP_ID Register" provides a list of acceptable values and modes. Note that certain values are reserved and zone configurations may not be available to use for the TMF8820 (i.e. limited to 3x3) or TMF8821 (i.e. limited to 3x3, 4x4, 3x6).

Once uploaded, open the Arduino Serial Monitor at 115200 baud and cover channels 1 through 3. The spad_map_id was changed to 2. The readings are similar to example 1 when the SPAD was using the default 3x3 Normal Mode. However, SPAD uses a different FOV and slightly offset.

If you have a TMF8821, try adjusting the SPAD to 4x4 normal mode with a 41°x52° FoV by changing spad_map_id to 7 (i.e. change the line #define NEW_SPAD_MAP 2 to #define NEW_SPAD_MAP 7). Then upload the code to the board.

Open the Arduino Serial Monitor at 115200 baud and try to cover channels 9 through 16. You will see an output similar to the image below indicating that the respective channels were covered.

Example 11: Histogram

With the library installed, open the sketch in Arduino: File > Examples > SparkFun Qwiic TMF882X Arduino Library > Example-11_Histogram. The following code was copied from the Arduino Library for your convenience. If you have not already, select your Board (in this case the RedBoard Artemis), and associated COM port. Upload the code to the board.

language:c
/*

  Example-11_Histogram.ino

  This example shows how to enable and recieve raw histogram data from the 
  connected TMF882X device

  Supported Boards:

   SparkFun Qwiic dToF Imager - TMF8820        https://www.sparkfun.com/products/19036
   SparkFun Qwiic Mini dToF Imager - TMF8820   https://www.sparkfun.com/products/19218
   SparkFun Qwiic Mini dToF Imager - TMF8821   https://www.sparkfun.com/products/19451
   SparkFun Qwiic dToF Imager - TMF8821        https://www.sparkfun.com/products/19037

  Written by Kirk Benell @ SparkFun Electronics, April 2022

  Repository:
     https://github.com/sparkfun/SparkFun_Qwiic_TMF882X_Arduino_Library

  Documentation:
     https://sparkfun.github.io/SparkFun_Qwiic_TMF882X_Arduino_Library/

  SparkFun code, firmware, and software is released under the MIT License(http://opensource.org/licenses/MIT).
*/

#include "SparkFun_TMF882X_Library.h"  //http://librarymanager/All#SparkFun_Qwiic_TMPF882X

SparkFun_TMF882X  myTMF882X;

#define NUMBER_OF_SAMPLES_TO_TAKE  4

int nSample = 0;

// For our histogram printout 
#define MAX_BIN_LEN 128

// Define our histogram callback function

void onHistogramCallback(struct tmf882x_msg_histogram *myHistogram)
{

    nSample++;

    Serial.print("Histogram Number: ");
    Serial.println(nSample);

    uint8_t zone_count = 0;
    for (int tdc_idx = 0; tdc_idx < myHistogram->num_tdc; ++tdc_idx) 
    {
        // Histogram tag for zones, #HLONG01,#HLONG02....
        Serial.println();
        Serial.print("#HLONG");
        Serial.print(zone_count++);

        for (int bin_idx = 0; bin_idx < myHistogram->num_bins; ++bin_idx) {

            Serial.print((unsigned long)myHistogram->bins[tdc_idx][bin_idx]);

            if ((bin_idx + 1) == MAX_BIN_LEN) 
            {
                Serial.println();
                Serial.print("#HLONG");
                Serial.print(zone_count++);

            } else if ((bin_idx + 1) % MAX_BIN_LEN != 0)
                Serial.print(",");
        }
    }
    Serial.println();
}

void setup()
{

    delay(500);
    Serial.begin(115200);
    Serial.println("");


    if(!myTMF882X.begin())
    {
        Serial.println("Error - The TMF882X failed to initialize - is the board connected?");
        while(1){}
    }

    // set our call back function that handles histograms
    myTMF882X.setHistogramHandler(onHistogramCallback);

    // Set our delay between samples  - 1 second - note it's in ms
    myTMF882X.setSampleDelay(1000);

    // First config parameter to enable output of histogram data.

    struct tmf882x_mode_app_config tofConfig;
    if (!myTMF882X.getTMF882XConfig(tofConfig)) 
    {
        Serial.println("Error - unable to get device configuration.");
        while(1){}
    }

    // Change the APP configuration
    //  - set the reporting period to 500 milliseconds
    //  - Enable Histogram mode
    tofConfig.report_period_ms = 500;
    tofConfig.histogram_dump = 1;

    if (!myTMF882X.setTMF882XConfig(tofConfig)) 
    {
        Serial.println("Error - unable to set device configuration.");
        while(1){}
    }
}

void loop()
{
    delay(2000);

    // get a measurment
    // Have the sensor take 4 measurements, the results are sent to the above callback

    Serial.println("---------------------------------------------------------");    
    Serial.print("Taking "); 
    Serial.print(NUMBER_OF_SAMPLES_TO_TAKE);
    Serial.println(" data samples."); 
    Serial.println();

    nSample=0;
    myTMF882X.startMeasuring(NUMBER_OF_SAMPLES_TO_TAKE);

    Serial.println("---------------------------------------------------------\n\n");    

}

Open the Arduino Serial Monitor at 115200 baud to view the raw histogram data for your TMF8820 and TMF8821. Note that the example code is currently set to take a 4 data samples at a time. You should see an output similar to the image below if you are covering the sensor.

More Examples!

This tutorial highlights a few examples listed in the Arduino Library to get you started. Additional examples can be found in the library.

Troubleshooting

Resources & Going Further

Now that you've successfully got your Qwiic dToF Imager up and running, it's time to incorporate it into your own project! For more information, check out the resources below:

• SparkFun Qwiic dToF Imager - TMF8820
  • Schematic (PDF)
  • Eagle Files (ZIP)
  • Board Dimensions (PDF)
• SparkFun Qwiic Mini dToF Imager - TMF8820
  • Schematic (PDF)
  • Eagle Files (ZIP)
  • Board Dimensions (PDF)
• SparkFun Qwiic dToF Imager - TMF8821
  • Schematic (PDF)
  • Eagle Files (ZIP)
  • Board Dimensions (PDF)
• SparkFun Qwiic Mini dToF Imager - TMF8821
  • Schematic (PDF)
  • Eagle Files (ZIP)
  • Board Dimensions (PDF)
• TMF882X
  • Datasheet (PDF)
  • Driver User Guide (PDF)
  • Host Driver Communication (PDF)
• Arduino Library
  • API Reference
• GitHub Hardware Repo
• SFE Product Showcase

Need some inspiration for your next project? Check out some of these other tutorials using sensors.