ams TMD3725 EVM Evaluation Kit User Guide

: June 6, 2024
: ams

User guide
TMD3725 EVM
TMD3725 ALS, Color and Proximity Sensor Evaluation Kit
Version 1.3

TMD3725

The TMD3725 device features advanced proximity measurement, color sense (RGBC+IR), and digital ambient light sensing (ALS). The package has been designed to accommodate a “single hole” aperture approach. The slim module incorporates an IR LED and factory-calibrated LED driver.

Initial hardware setup

The software should be installed prior to connecting any hardware to the computer. Follow the instructions found in the Quick Start Guide (QSG). This will load the required driver for the USB interface and also the control software and graphical user interface (GUI).
The hardware consists of the EVM Controller v2.1a or v2.1c, the TMD3725 EVM daughterboard and a USB interface cable. When the USB cable is connected, the green LED should flash indicating that power is being received via the USB interface, and the controller board processor is running. If the green LED does not flash, check the USB cable connections; unplug the USB cable and try again. If the green LED still does not flash, check the PC for USB error messages. See the Resources section at the end of this document for additional assistance.

Establishing basic functionality

The software should be started selecting ams->TMD3725 EVM->TMD3725_EVM command in the Windows menu or by double clicking the TMD3725.exe file from the installation directory. The default installation directory, depending on the device and the operating system you are using, is:
C:\Program Files\ams\TMD3725EVM Windows 32 bit operating systems
C:\Program Files (x86)\ams\TMD3725EVM Windows 64 bit operating systems
A different install path may be selected by the user. When started, the TMD3725 window will open on the PC.
The balance of this document identifies and describes the controls available on the GUI. In combination with the TMD3725 datasheet, the QSG and application notes available on the ams website, www.ams.com. There should be enough information to allow evaluation of the TMD3725 device.

TMD3725 EVM graphical user interface (GUI)

2.1 Software overview
On successful initialization, the software displays a main window, containing controls pertinent to the connected device. If the software detects an error, it will display an error window.
If “Device not found or is unsupported” appears, verify that the correct daughterboard is properly connected to the motherboard. If “Cannot connect to EVM board” appears, verify the USB cable is connected. A green LED on the EVM Controller will flash to indicate that the USB cable is connected and providing power to the system.
If the EVM board is disconnected from the USB bus while the program is running it will display an error message and then terminate. Reconnect the EVM board and restart the program.

The main window for the TMD3725 is shown below.

Clicking on the red “X” will close the window and terminate the application.

The checkboxes near the top of the window power on the chip and enable the ALS function. The ALS tab contains controls for the remaining functions and displays status and data from the device as it operates.
If the default LUX EQ XML file (TMD3725_luxeq.xml) is found in the system default documents directory ( %USERPROFILE%\Documents , also known as My Documents), then the file will be loaded, the Lux coefficients changed and a dialog displaying the new coefficients will be displayed, notifying you that coefficients have been automatically loaded that override the default open-air coefficients. This allows storing a special set of coefficients that will be automatically loaded and used.

Please see the LUX EQ XML section below for details.

2.1.1 Device ID Information
The lower left corner of the window displays the ID number of the EVM motherboard, identifies the device being used and displays the ID of the device.
2.1.2 Log Status and Control Information
The lower right corner of the window contains status information and controls for the logging function:

This section contains two text boxes that are stored in the log file data and used to build the file name for the log file. If you change the data in these fields, the new values will be stored with all new log data. The default log file name will be based on these values at the time the log file is written. If nothing is entered in these boxes they default to a period (“.”).

The Count value displayed is a count of the number of samples currently in the log buffer.
The Elapsed Time value indicates the elapsed time since data logging was started.
The final field in this section controls the number of log samples that will be collected before logging is automatically stopped and the log data is stored. If the count of log entries reaches the amount shown in this field, the program will stop the logging function and pop up a window asking for a file name to save the collected data.

LUX EQ XML

The TMD3725 ALS supplies information that is used to calculate LUX (unit of illumination) and CCT (correlated color temperature). The LUX Equation for the TMD3725 uses a combination of data from the sensor and various coefficients to calculate the LUX value. The EVM GUI is preconfigured with coefficients suitable for an open-air configuration.
When the TMD3725 sensor is placed behind glass, different coefficients may be necessary to calculate the LUX value. Lux Coefficients can be loaded and saved as well as displayed from the System Menu.
The format of the LUX EQ XML file is an XML file and must contain all the required LUX EQ elements to be loaded. The format of the file follows the standard XML ormat and is as follows:

<?xml version=”1.0″ encoding=”utf-8″?>
<!– Device:TMD3725 Saved:6/5/2017 12:32:19 PM –>

If you are experiencing trouble loading a LUX EQ XML file, this may indicate a problem with the file format. Generally, you can manually load the file (see the System Menus section below) and confirm both the location and format of the file are correct. Another useful trick is to save the current coefficients to a LUX EQ XML file in the default documents directory and edit it with a text editor, such as notepad. This will help in creating a properly formatted file.

2.1.4 System Menus

At the top of the window there are three pull-down menus labeled “File”, “Log”, and “Help”. The File menu provides basic application-level control. The Log menu is used to control the logging function, and the Help menu provides version and copyright information for the application.

File `Menu`

The File menu contains the following functions:

The Reread Registers function forces the program to re-read all of the control registers from the device and display them on the screen. This does not read the status and ALS or PROX result registers, because those registers are continually read while the program is running.
The Lux Coefficients menu item pulls up a sub-menu that allows you to Save, Load and Display the coefficients used to calculate LUX and CCT.
Click on the Exit command to close the main window and terminate the application. If you have unsaved log entries, you will be prompted to save them. You can press ‘Yes’ to be prompted to save the log to a file, ‘No’ to exit without saving the log, or press ‘Cancel’ to not exit. If you press ‘Yes’ and saving the log to a file is cancelled or failed then the application will not exit and will return to normal state.

The Lux Coefficients sub-menu is used to Save, Load or Display the coefficients used to calculate LUX and CCT. For additional information concerning the LUXEQ XML usage, please refer to the LUX EQ XML section above.

The Load function opens a dialog that allows you to select a LUXEQ XML file that contains the LUXEQ Coefficients used to calculate LUX and CCT. If necessary, navigate to the directory that contains the LUXEQ XML file you wish to load, select the LUXEQ XML file and press the Open button to load, or the Cancel button to abort.

The Save function opens a dialog that allows you to enter a file name that the current LUXEQ Coefficients will be saved to. If necessary, navigate to the directory that you want the file to be saved into, enter the file name, and press the Save button to save the LUXEQ coefficients to a LUXEQ XML file, or the Cancel button to abort.

The Display function opens a dialog that displays the current LUXEQ Coefficients.

The Log menu is used to control the logging function and to save the log data to a file. Log data is accumulated in memory until it is discarded or written to a data file.

Click Start Logging to start the logging function. Each time the program polls the ALS information from the device, it will create a new log entry showing the raw data values, the calculated lux value, the values of various control registers, and the values entered by the user into the text fields near the bottom right corner of the window.
Click Stop Logging to stop the logging function. Once logging is stopped, the data can be written to a file, or you can continue collecting additional data by clicking Start Logging again.
The Log a Single Entry command will cause logging to be start, collect one single entry, and immediately stop again. This function is not available when logging is already running.
Click Clear Log to discard any data that has already been collected. If there is data in memory, which has not been saved to disk, this function will display a prompt asking if you to verify that it is
OK to discard the data. If the log is running when this function is clicked, the log will continue running after the existing data is discarded.
Click Save Log to save the collected log data to a data file. This will stop the logging function, if it is active, and display a file dialog box for you to specify where to store the ogged data. The default file name, as described above, will be displayed, but you may change the file name if you wish.

The Help menu contains a single function; About.

The About function displays a dialog box showing the version and copyright information for the TMD3725 program.

Click the OK button to close this window and continue.

System Level Controls

Immediately below the top menu bar there are three checkboxes that are used to control the system level functions of the TMD3725 device.
The Power-On checkbox controls the PON function of the TMD3725. When this box is checked, the power is on and the device can operate. When this box is unchecked, the power is off and the device will not operate (The control registers can still be written, but the device will not function).

The ALS Enable checkbox controls the ADC_EN function of the TMD3725. When this box is checked, the device will collect and report ALS data as programmed. When this box is unchecked, the ALS functions will not operate.

“ALS” Tab

The main portion of the screen contains a tab labeled ALS. The controls in this tab are divided into 3 sections, each performing a separate function.

ALS Controls

The left side of the ALS tab contains controls to set various ALS settings.

The ATIME control sets the time of the ALS integration. ATIME can be adjusted in 2.81ms steps.
This register functions as a count-up value such that ATIME=0 is the minimum integration time (2.81ms) and ATIME=255 is the maximum integration time (719.36ms).
The AGAIN control is a pulldown menu which lets you select the analog gain of the ALS/Color sensor. The values that can be chosen are 1x, 4x, 16x, and 64x.
The WEN checkbox controls the ALS Wait feature. When this box is checked, the values for WTIME and WLONG are used to determine the time between ALS cycles. When this box is unchecked, there is no wait period between ALS cycles and the values of WTIME and WLONG are ignored.
The WTIME control sets the time to wait between ALS cycles. WTIME can be adjusted in 2.81ms steps. This register functions as a count-up value such that WTIME=0 is the minimum wait time (2.81ms) and WTIME=255 is the maximum wait time (719.36ms).
The WLONG checkbox controls sets the WTIME factor. When this box is checked, the wait time between ALS cycles is extended by a factor of 12x.

ALS Output Data

The top right corner of the ALS tab displays the data that is output by the device.
CDATA displays the Clear Channel data count.
RDATA displays the Red Channel data count.
GDATA displays the Green Channel data count.
BDATA displays the Blue Channel data count.
Lux displays the calculated lux.
CCT displays the calculated correlated color temperature.

ALS Data Plot

The remaining portion of the ALS tab is used to display a running plot of the collected ALS values and calculated Lux & CCT values. The last 350 values are collected and plotted on the graph. As additional values are added, the old values will be deleted from the left side of the graph. ****The Enable Plot checkbox activates the plotting function. Data will only be plotted when this box is checked.
The Clear, Red, Green, Blue and Lux checkboxes control which values will be displayed on the plot. Only the checked values will be displayed.
Click the Clear Plot button to discard the current data and continue plotting the new data. Note if the Clear Plot button is clicked while the plot is disabled, the data is discarded, but the actual plot will not be updated until the plot function is re-enabled.
The Scale of the Y-axis of the plot can be adjusted by clicking on the small up and down arrows at the top left corner of the plot. The scale can be set to any power of 2 from 64 through 65536.

“Prox” Tab

The main portion of the screen contains a tab labeled Prox. The controls in this tab are divided into 3 sections, each performing a separate function.

Prox Controls

The left side of the Prox tab contains controls to set various Prox settings.
The PPULSE controls the maximum number of pulses used for each prox cycle. To avoid saturating the prox sensor, the Automatic Pulse Control (APC) feature of the device may reduce the number of pulses in real-time. The maximum number of pulses selected, which is one more than the value in the register (PPULSE = 0 → 1 pulse), is displayed immediately to the right of the box.
The PPULSE_LEN control sets the width of all IR LED pulses within the proximity cycle. Longer pulses result in increased proximity range and typically result in less electrical noise generated in the analog front end.
The PGAIN control is a pulldown menu that lets you select the analog gain of the proximity IR sensor. The values that can be chosen are 1x, 2x, 4x and 8x.
The PLDRIVE control sets the drive strength of the IR LED current. Values are approximate; actual current through LED is factory trimmed to normalize IR intensity. The values range from 0 (6mA LED Current) to 31 (192mA LED Current).
The HW Prox Averaging control is a pulldown menu that lets you defines the number of ADC samples collected and averaged during a cycle, which become the proximity result. The values range from 0 (Disabled) to 7 (128 samples) where each value is the exponent of 2 (2 value ).
The PTIME control sets the duration of 1 Prox Sample, which is (PRATE + 1)*88µs. The POFFSET control sets the magnitude that adjusts PDATA to remove crosstalk from the proximity data. The values range from -255 to 255.
The Cal button triggers the sensor’s proximity offset calibration sequence.
The Auto Offset Adjust checkbox causes the POFFSET value to be decremented if PDATA ever becomes zero.

Prox Output Data

The top right corner of the Prox tab displays the data that is output by the device.
PDATA displays the Proximity ADC channel data count.
StDev displays the standard deviation of the last 32 PDATA samples.

Prox Data Plot

The remaining portion of the Prox tab is used to display a running plot of the collected PROX values. The last 350 values are collected and plotted on the graph. As additional values are added, the old values will be deleted from the left side of the graph.

The Enable Plot checkbox activates the plotting function. Data will only be plotted when this box is checked.
Click the Clear Plot button to discard the current data and continue plotting the new data. Note, if the Clear Plot button is clicked while the plot is disabled, the data is discarded, but the actual plot will not be updated until the plot function is re-enabled.
The Scale of the Y-axis of the plot can be adjusted by clicking on the small up and down arrows at the top left corner of the plot. The scale can be set to any power of 2 from 64 through 65536.

Resources

TMD3725 datasheet
TMD3725 EVM Quick Start Guide (QSG)
Designer’s Notebooks

For additional information regarding the TMD3725, please refer to the datasheet. For information regarding the installation of the TMD3725 EVM host application software please refer to the TMD3725 EVM Quick Start Guide.
Designer’s Notebooks dealing with various aspects of optical measurement and optical easurement applications are available. All content is available on the ams website www.ams.com.