OPT3101 library for Arduino

Version: 1.0.1
Release date: 2020-11-17
www.pololu.com

Summary

This is a library that helps interface with the OPT3101 time-of-flight-based distance sensor from Texas Instruments.

Supported platforms

This library is designed to work with the Arduino IDE version 1.8.x or later; we have not tested it with earlier versions. This library should support any Arduino-compatible board, including the Pololu A-Star controllers.

Getting started

Hardware

An OPT3101 carrier can be purchased from Pololu's website. Before continuing, careful reading of the product page is recommended.

Make the following connections between the Arduino and the OPT3101 board:

5V Arduino boards

(including Arduino Uno, Leonardo, Mega; Pololu A-Star 32U4)

Arduino   OPT3101 board
-------   -------------
     5V - VIN
    GND - GND
    SDA - SDA
    SCL - SCL

3.3V Arduino boards

(including Arduino Due)

Arduino   OPT3101 board
-------   -------------
    3V3 - VIN
    GND - GND
    SDA - SDA
    SCL - SCL

Software

You can use the Library Manager in the Arduino software (IDE) to install this library:

1. In the Arduino IDE, open the "Sketch" menu, select "Include Library", then "Manage Libraries...".
2. Search for "OPT3101".
3. Click the OPT3101 entry in the list.
4. Click "Install".

If this does not work, you can manually install the library:

1. Download the latest release archive from GitHub and decompress it.
2. Rename the folder "opt3101-arduino-master" to "OPT3101".
3. Move the "OPT3101" folder into the "libraries" directory inside your Arduino sketchbook directory. You can view your sketchbook location by opening the "File" menu and selecting "Preferences" in the Arduino IDE. If there is not already a "libraries" folder in that location, you should make the folder yourself.
4. After installing the library, restart the Arduino IDE.

Examples

Several example sketches are available that show how to use the library You can access them from the Arduino IDE by opening the "File" menu, selecting "Examples", and then selecting "OPT3101". If you cannot find these examples, the library was probably installed incorrectly and you should retry the installation instructions above.

Library reference

• OPT3101()
  Constructor for the OPT3101 class.

• void setAddress(uint8_t new_addr)
  Configures the library to use a different I²C address (7-bit) to communicate with the OPT3101. The address you provide here must match the configuration of your hardware. The library uses an address of 0x58 by default.

• uint8_t getAddress()
  Returns the current I²C address.

• uint8_t getLastError()
  Returns a non-zero error code if there was an error communicating with the OPT3101. Every function in this library that communicates with the OPT3101 sets the error code returned by this function to zero on success or non-zero error code if it fails.

• void resetAndWait()
  Resets the OPT3101 and then waits for the INIT_LOAD_DONE bit to be 1.

• void writeReg(uint8_t reg, uint32_t value)
  Writes the given value to the an OPT3101 register. The OPT3101 registers are 24-bit, so the upper 8 bits of value are ignored.

• uint32_t readReg(uint8_t reg);
  Reads an OPT3101 register and returns the value read.

• void init();
  Initializes and configures the sensor. This includes calling resetAndWait() and configureDefault().

• void configureDefault();
  Configures the sensor with some default settings. This includes calling setMonoshotMode() and setFrameTiming(512).

• void setChannel(uint8_t channel);
  Configures the sensor to use the specified channel. This determines which set of infrared LEDs will be turned on while taking a reading. Valid arguments are:

  • 0 for TX0
  • 1 for TX1
  • 2 for TX2
  • OPT3101ChannelAutoSwitch to automatically cycle through all channels

• void nextChannel();
  This convenience method configures the sensor to use the channel that comes numerically after the last channel that was sampled (according to the channelUsed member).

• void setBrightness(OPT3101Brightness brightness)
  Sets the OPT3101 to use the specified LED brightness. Valid arguments are:

  • OPT3101Brightness::Low (0)
  • OPT3101Brightness::High (1)
  • OPT3101Brightness::Adaptive (255) Low brightness mode only works well for nearby objects. High brightness mode works for a wide range of distances, but objects that are too reflective or too close can cause the sensor to saturate, meaning that it fails to measure a distance. Adaptive mode automatically uses low or high brightness depending on how much reflected light the sensor is seeing.

• void setMonoshotMode();
  Configures the sensor to use monoshot mode, which means it only turns on the LEDs and takes measurements when we request it to. This function is called by configureDefault() which is called by init() so most applications will not need to use it directly.

• void setContinuousMode();
  Configures the sensor to use continuous mode, where it automatically takes readings as long as the timing generator is enabled.

• void setFrameTiming(uint16_t subFrameCount);
  Configures the OPT3101 to average the specified number of sub-frames. Each frame of the OPT3101 (i.e. sample) consists of a certain number of sub-frames which take 0.25 ms each. The OPT3101 averages the results from these subframes together. Choosing a high number here makes the samples take longer, but could give increased accuracy. subFrameCount can be any power of 2 between 1 and 4096, but it should be at least 2 if you are using adaptive brightness.

• void enableTimingGenerator();
  Enables the timing generator by setting the TG_EN bit to 1. This is automatically called by startSample() so most applications will not need to use it directly.

• void disableTimingGenerator();
  Disables the timing generator by setting the TG_EN bit to 0.

• void enableDataReadyOutput(uint8_t gpPin);
  Configures one of the GPIO pins of the OPT3101 to be used as a data ready output which drives high when a new reading is available. Valid arguments are 1 for GP1 and 2 for GP2.

• void startSample();
  Tells the sensor to start taking a sample. The sensor will start emitting light from its LEDs according to the previosuly-specified settings. This calls enableTimingGenerator() if that has not been done already.

• bool isSampleDone();
  Returns true if enough time has elapsed so that the sample started by startSample() is expected to be complete. This function only uses Arduino timing functions; it does not communicate with the OPT3101, and does not report any errors using getLastError().

• void readOutputRegs();
  Reads the sensor's output registers and updates the data in the following member variables: channelUsed, brightnessUsed, i, q, amplitude, phase, distanceMillimeters, ambient, temperature.

• void sample();
  This calls startSample(), then delays until the sample is complete, then calls readOutputRegs() to read the results from the sample.

• Sample results:

  • uint8_t channelUsed
    The channel used in the last sample. The library ensures that this number will be 0, 1, or 2.
  • OPT3101Brightness brightnessUsed;
    The brightness used in the last sample. This will either be OPT3101Brightness::Low (0) or OPT3101Brightness::High (1).
  • uint16_t ambient;
    The level of ambient light detected in the last sample. The OPT3101 uses this internally to adjust its readings.
  • uint16_t temperature;
    The temperature measured during the last sample. The OPT3101 uses this internally to adjust its readings.
  • int32_t i, q;
    These two numbers come from reading the IPHASE_XTALK and QPHASE_XTALK registers from the OPT3101 while IQ_READ_DATA_SEL is 2. They represent a measurement of the reflected infrared light, and its decomposition into two signals: a signal that is in phase with the emitted wave (i) and a signal that is 90 degrees out of phase (q).
  • uint16_t amplitude;
    The intensity of the reflected light measured in the last sample. The lower the amplitude, the less reliable the phase/distance readings will be. An amplitude of 65535 (0xFFFF) indicates that the sensor was saturated by receiving too much light. If this happens, phase and distanceMillimeters will both be 0.
  • int16_t phase;
    This is the distance measured by the OPT3101 in the last sample, in units of 0.228723 mm. This is read from the PHASE_OUT register.
  • int16_t distanceMillimeters;
    This is the distance measured by the OPT3101 in the last sample, converted to millimeters. Please note that it is normal for this reading—and all the other readings documented here—to have noise, even when your system is not moving. The noise is typically lower for objects that are closer to the sensor or more reflective.

Version history

• 1.0.1 (2020-11-17): Added calls to Serial.begin in the examples.
• 1.0.0 (2020-08-19): Original release.