Hioki TM6101 Measuring Library Instruction Manual

Instruction Manual
HIOKI TM6101A985-02
TM6101 Measuring Library
May 2021 Revised edition 2 TM6101A985-02 21-05H
EN
HIOKI TM6101A985-02

Contents

Chapter 1 Overview .................................................................................. 5
Chapter 2 Using the Measuring Library .................................................... 5
2.1 Installing the Library .................................................................................................................... 5
2.2 Using the Library ......................................................................................................................... 5
Chapter 3 Controlling the TM6101 ........................................................... 6
3.1 Overall Process ............................................................................................................................ 6
3.2 Opening the Instrument .............................................................................................................. 7
3.3 Closing the Instrument ................................................................................................................ 7
3.4 Setting Measurement Conditions ............................................................................................... 8
Normal Measurement Mode Settings ............................................................................................... 8
AC Measurement Mode Settings ..................................................................................................... 9
External I/O Settings ........................................................................................................................ 9
Calculation Settings .......................................................................................................................... 9
3.5 Dark Measurement ..................................................................................................................... 10
Performing Dark Measurement for the Current Integration Time and Sensitivity Range ............... 10
Performing Dark Measurement for All Integration Times and Sensitivity Ranges .......................... 11
3.6 Reference Value Correction ...................................................................................................... 12
Performing Chromaticity Correction ............................................................................................... 12
Performing Illuminance, Luminous Intensity, and Luminous Flux Correction ................................ 12
3.7 Making Measurements .............................................................................................................. 14
Making Measurements Using the Synchronous Function .............................................................. 14
Making Measurements Using the Asynchronous Function ............................................................ 15
3.8 Acquiring Measurement Results .............................................................................................. 18
Measurement Results That Can Be Acquired ................................................................................ 18
Chapter 4 Library Function Reference ................................................... 19
4.1 Connection Functions ............................................................................................................... 19
TmOpenDevice ........................................................................................................................... 19
TmOpenDeviceBySerial ............................................................................................................. 19
TmCloseDevice .......................................................................................................................... 20
4.2 Measurement Conditions .......................................................................................................... 21
TmSetMeasMode ....................................................................................................................... 21
TmGetMeasMode ....................................................................................................................... 21
TmSetIntegralTime ..................................................................................................................... 22
TmGetIntegralTime ..................................................................................................................... 22
TmSetSensitivity ......................................................................................................................... 23
TmGetSensitivity ......................................................................................................................... 23
HIOKI TM6101A985-02
TmSetAverageNum .................................................................................................................... 24
TmGetAverageNum .................................................................................................................... 24
TmSetTrigType ........................................................................................................................... 24
TmGetTrigType ........................................................................................................................... 24
TmSetTrigDelay .......................................................................................................................... 25
TmGetTrigDelay.......................................................................................................................... 25
TmSetTrigTimeout ...................................................................................................................... 25
TmGetTrigTimeout ...................................................................................................................... 25
TmSetAutoRange ....................................................................................................................... 26
TmGetAutoRange ....................................................................................................................... 27
TmSetAutoRangeLevel .............................................................................................................. 27
TmGetAutoRangeLevel .............................................................................................................. 27
TmSetAcMode ............................................................................................................................ 28
TmGetAcMode ............................................................................................................................ 28
TmSetRefIlluminant .................................................................................................................... 28
TmGetRefIlluminant .................................................................................................................... 29
TmSetLightDistance ................................................................................................................... 29
TmGetLightDistance ................................................................................................................... 29
TmSetExtIoIndexOutpTime ........................................................................................................ 29
TmGetExtIoIndexOutpTime ........................................................................................................ 30
TmSetMeasSettingAll ................................................................................................................. 30
TmGetMeasSettingAll ................................................................................................................. 30
TmInitializeMeasSettings ............................................................................................................ 31
4.3 Measurement Execution ........................................................................................................... 32
TmMeasExec .............................................................................................................................. 32
TmMeasExecAsync .................................................................................................................... 33
TmGetMeasStatus ...................................................................................................................... 34
TmGetStandbyStatus .................................................................................................................. 34
TmCancelMeas ........................................................................................................................... 35
TmExecDarkMeas ...................................................................................................................... 35
TmExecDarkMeasAsync ............................................................................................................ 36
4.4 Reference Value Correction ...................................................................................................... 38
TmGetDarkAll ............................................................................................................................. 37
TmSetDarkAll .............................................................................................................................. 37
TmResetDark .............................................................................................................................. 37
TmExecChromaticityCorrect ....................................................................................................... 38
TmExecChromaticityCorrectByFile ............................................................................................. 39
TmGetChromaticityCorrectValue ................................................................................................ 39
HIOKI TM6101A985-02
TmSetChromaticityCorrectValue ................................................................................................ 39
TmResetChromaticityCorrect ..................................................................................................... 40
TmExecIlluminanceCorrect ........................................................................................................ 40
TmGetIlluminanceCorrectValue .................................................................................................. 41
TmSetIlluminanceCorrectValue .................................................................................................. 41
TmResetIlluminanceCorrect ....................................................................................................... 41
TmExecLuminousFluxCorrect .................................................................................................... 41
TmGetLuminousFluxCorrectValue ............................................................................................. 42
TmSetLuminousFluxCorrectValue .............................................................................................. 42
TmResetLuminousFluxCorrect ................................................................................................... 42
TmExecLuminousIntensityCorrect .............................................................................................. 42
TmGetLuminousIntensityCorrectValue ....................................................................................... 43
TmSetLuminousIntensityCorrectValue ....................................................................................... 43
TmResetLuminousIntensityCorrect ............................................................................................ 43
TmGetUserCorrectData .............................................................................................................. 44
TmSetUserCorrectData .............................................................................................................. 44
4.5 Acquiring Measurement Results .............................................................................................. 45
TmGetIlluminanceValue .............................................................................................................. 45
TmGetLuminousIntensityValue ................................................................................................... 45
TmGetLuminousFluxValue ......................................................................................................... 45
TmGetTristimulusValues ............................................................................................................. 45
TmGetChromaticityValue_xy ...................................................................................................... 46
TmGetChromaticityValue_uv ...................................................................................................... 46
TmGetCorrelatedColorTemperature ........................................................................................... 46
TmGetSpecialColorRenderingIndex ........................................................................................... 46
TmGetGeneralColorRenderingIndex .......................................................................................... 47
TmGetDominantWaveLength ..................................................................................................... 47
TmGetMeasResultAll .................................................................................................................. 47
TmGetDetectLevel ...................................................................................................................... 48
4.6 Acquiring the Instrument Status .............................................................................................. 49
TmGetSerialNo ........................................................................................................................... 49
4.7 Structures ................................................................................................................................... 51
TmCheckDevice ......................................................................................................................... 49
TmGetLastError .......................................................................................................................... 50
Measurement conditions structure ............................................................................................. 51
Reference value correction value structure ................................................................................ 52
Measurement results structure ................................................................................................... 53
HIOKI TM6101A985-02

Chapter 1 Overview

HIOKI TM6101A985-02
The measuring library consists of Windows software designed for use with the TM6101 LED Optical Meter. It can be used on a computer running Windows to develop software for controlling the TM6101.
Operating environment
Supported operating systems Windows 7 (32bit/64bit), Windows 8 (32bit/64bit),
Windows 10 (32bit/64bit)
Supported development environments Visual Studio 2017, 2019 (Visual C++, Visual Basic,
Visual C#)
Note
Use a computer on which the target operating system operates properly. The software may not operate with sufficient speed in some operating environments. The measuring library includes C-language header files. When using the library in a
development environment other than C, for example with Visual Basic, you will need to create function declarations as necessary.

Chapter 2 Using the Measuring Library

2.1 Installing the Library

Install the software as described in “Chapter 2 Measurement Preparations” of the TM6101 LED
Optical Meter Instruction Manual. You will need to install both the driver software and the PC application in order to make use of the measuring library.

2.2 Using the Library

A “Library” folder will be created in the folder into which the software was installed as described in the
Instruction Manual. Copy the files in the “Library” folder to the location of your choice in your
development environment.
HiLedMeas.dll DLL software HiLedMeas.lib Library file Tm6101Api.h Library header file
Note The above files, driver software, and PC application software may only be redistributed for the purpose of controlling the TM6101. When distributing software you have developed, include the above files and the included installer as necessary.
HIOKI TM6101A985-02

Chapter 3 Controlling the TM6101

3.1 Overall Process

Open the instrument.
Use an open function to acquire a device number for the connected instrument.
Set measurement conditions.
Set measurement conditions with the measurement condition configuration function. You can either use functions that set individual measurement conditions or a function that sets all the measurement conditions at once.
Perform dark measurement. If dark correction if not performed, you will not be able to obtain
normal measured values. Be sure to perform dark measurement before making measurements.
Perform reference value correction. In this process, the instrument’s sensitivity is corrected based on
reference light source spectral data and photometric values that you provide. Perform reference value correction as necessary.
Perform measurement.
Measure the target light source and perform color calculations.
Acquire the measurement results.
Close the instrument.
Acquire the measurement results.
Close the instrument.

3.2 Opening the Instrument

long TmOpenDevice();
Opens a TM6101 and acquires a device number. When multiple instruments are connected to the computer, it is not possible to specify a particular device to open.
long TmOpenDeviceBySerial(char* pSerial);
Opens the TM6101 specified using a serial number (a 9-digit string) and acquires a device number.
long TmCloseDevice(long lDeviceId);
Closes the TM6101 with the specified device number.
HIOKI TM6101A985-02
In order to control the instrument, it is first necessary to use an open function to open it. When the open function executes successfully, it will return at least one device number. Once the instrument has been opened, the assigned device number is used to control it.
When the instrument is opened, all measurement conditions will be initialized. Additionally, if a given instrument is closed and then reopened, it may be assigned a different device number, and all measurement conditions will be initialized.
Note Immediately after the AC adapter and USB cable are connected to the instrument after turning on the
computer’s power supply, the main unit’s power indicator will turn red. When the instrument is
opened, the power indicator will change from red to green, and when the instrument is closed, it will
change back to red.
The device number acquired when opening the instrument can only be used within the same process. The same TM6101 cannot be opened at the same time from multiple processes.
Open functions

3.3 Closing the Instrument

Use the close function to close the instrument once you have completed all control operations. Once an instrument has been closed, the device number acquired with the open function can no longer be used.
Note
When the instrument is closed, its power indicator will change from green to red.
Close function
HIOKI TM6101A985-02

3.4 Setting Measurement Conditions

Before making measurements with the TM6101, it is necessary to set measurement conditions such as the integration time, sensitivity, and average times. It is also possible to set all the measurement conditions at once by specifying a measurement condition structure.
The current measurement conditions can be acquired using measurement condition acquisition functions.
The instrument can be reverted to the measurement conditions in effect when it was opened using the measurement condition initialization function.
Note
Measurement condition configuration functions cannot be used while the instrument is in the measurement standby state. The TmGetStandbyStatus function, described below, can be used to detect whether the instrument is in the measurement standby state.
The following measurement conditions must be set:

Normal Measurement Mode Settings

The TM6101 can make measurements in either of two measurement modes: normal measurement mode or AC measurement mode. The instrument is set to normal measurement mode when it is opened.
Measurement mode Set to normal measurement mode. Integration time 0.1 / 0.5 / 1 / 2 / 4 / 8 / 10 / 16.6 / 20 / 33.3 / 40 ms Sensitivity range High / Low Average times 1 to 100 Auto-ranging OFF / Integration time auto-ranging / Sensitivity auto-ranging Auto-ranging level 1% to 99%
Note
When auto-ranging is enabled, the auto-ranging function will be disabled when making measurements under the following conditions:
AC measurement mode External trigger Dark measurement

AC Measurement Mode Settings

HIOKI TM6101A985-02
When making measurements in AC measurement mode, configure the following settings:
Measurement mode Set to AC measurement mode. AC drive settings Measurement range (range 1 to 3) Power supply frequency (60/50 Hz)
Average times (1 to 100) *AC drive settings (measurement range, power supply frequency, and average times) are set together with the TmSetAcMode function.

External I/O Settings

Trigger type OFF / External trigger ON (rising edge) / External trigger ON
(falling edge) Trigger delay 0 to 1,000 ms Trigger timeout 10,000 to 1,000,000 ms Index output time 1 to 100 ms
Note
When not using an external trigger, the trigger delay and trigger timeout settings are disabled.

Calculation Settings

Reference light CIE daylight / Blackbody radiation / Automatic selection *Used in calculating the color rendering index. Measuring distance 0.01 to 10.00 m
*Used in measuring luminous intensity values.
10
HIOKI TM6101A985-02

3.5 Dark Measurement

Dark-corrected measurement results are obtained by performing dark measurement before making measurements. If dark correction if not performed, you will not be able to obtain normal measured values. Be sure to perform dark measurement before making measurements. The average times can be set when performing dark measurement (average times: 1 to 100).
Note
Be sure to affix the included cap before performing dark measurement.
Either of two methods can be used to perform dark measurement: it can be performed for the current integration time and sensitivity range, or for all integration times and sensitivity ranges.

Performing Dark Measurement for the Current Integration Time and Sensitivity Range

This approach takes less time to complete, but dark measurement values are cleared whenever the integration time, sensitivity range, or measurement mode is changed. Additionally, dark measurement values are cleared when measurement is performed using auto-ranging.
Dark measurement is performed using the TmExecDarkMeas function. The function does not return until dark measurement is complete.
11
Start dark
measurement
Acquire
measurement state
Measurement
complete?
TmExecDarkMeasAsync function
TmGetMeasStatus function
End dark measurement
Yes
No
HIOKI TM6101A985-02

Performing Dark Measurement for All Integration Times and Sensitivity Ranges

By calling the function once, dark measurement is performed while automatically switching the integration time and sensitivity range. The operation takes some time to complete since dark measurement is performed for all integration times and sensitivity ranges.
When using this approach, there is no need to repeat dark measurement, even if the integration time, sensitivity range, or measurement mode is changed. Dark measurement results remain valid until the instrument is turned off. When enabling auto-ranging, perform dark measurement for all integration times and sensitivity ranges.
The library provides functions for acquiring all dark correction data, setting all dark correction data, and reverting the instrument to its state before dark measurement was performed.
Dark measurement is performed using either a synchronous or asynchronous function.
(1) Performing dark measurement using the synchronous function
Dark measurement is performed using the TmExecDarkMeas function. The function does not return until dark measurement is complete.
(2) Performing dark measurement using the asynchronous function
Dark measurement is performed using the TmExecDarkMeasAsync function. The function returns immediately, but it is necessary to monitor the measurement status with the TmGetMeasStatus until dark measurement completes.
Example of dark measurement performed using the asynchronous function
12
HIOKI TM6101A985-02

3.6 Reference Value Correction

In this process, the instrument’s sensitivity is corrected based on reference light source spectral data
and photometric values that you provide. Reference value correction should be performed as necessary. Reference value correction results are valid until the instrument is closed using the close function. In addition to functions for performing reference value correction, the library includes functions for acquiring reference value correction data, setting reference value correction data, and reverting the instrument to its state before reference value correction was performed.

Performing Chromaticity Correction

1. Measure the spectral characteristics of the light source for which chromaticity correction is to be performed using a standard instrument (spectral-type measuring instrument) and prepare the corresponding measurement results. You will need spectral measurement results at a 5 nm interval from 380 nm to 780 nm.
2. Measure the light source for which chromaticity correction is to be performed with the TM6101.
For more information about the measurement procedure, see “3.7 Making Measurements”
below.
3. Perform chromaticity correction using one of the chromaticity correction functions. The measurement results from step (2) above (from the preceding step) will be subject to correction.
When using TmExecChromaticityCorrect, specify the spectral measurement results as the
function argument.
When using TmExecChromaticityCorrectByFile, specify the name of the file in which the spectral
measurement results were saved as the function argument. For more information about the file format, see “2.8 Using Correction Functions” in the TM6101 LED Optical Meter Instruction Manual.

Performing Illuminance, Luminous Intensity, and Luminous Flux Correction

1. Measure the correction target light source with the TM6101. For more information about the measurement procedure, see “3.7 Making Measurements” below.
2. Perform correction using the appropriate correction function, specifying the correction target reference value as the function argument. The measurement results from step (1) above (from the preceding step) will be subject to correction.
To perform illuminance correction, use TmExecIlluminanceCorrect. To perform luminous intensity correction, use TmExecLuminousIntensityCorrect. To perform luminous flux correction, use TmExecLuminousFluxCorrect.
Example of reference value correction:
TmExecChromaticityCorrect function TmExecIlluminanceCorrect function TmExecLuminousIntensityCorrect function TmExecLuminousFluxCorrect function
To measurement or other process
Open the device
Perform reference value
correction
Acquire reference value
correction data
Set measurement
conditions
Perform dark
measurement
Measure the
correction target
light source
TmGetChromaticityCorrectValue function TmGetIlluminanceCorrectValue function TmGetLuminousIntensityCorrectValue function TmGetLuminousFluxCorrectValue function
Save reference
value correction
data
To measurement or other process
Open the device
Set reference value
correction data
Set measurement
conditions
Perform dark
measurement
TmSetChromaticityCorrectValue function TmSetIlluminanceCorrectValue function TmSetLuminousIntensityCorrectValue function TmSetLuminousFluxCorrectValue function
HIOKI TM6101A985-02
13
Example restoration of reference value correction data:
*Reference value correction data should be acquired and saved as necessary, for example when it will be necessary to restore correction data the next time the instrument is turned on. Processing to save reference value correction data must be implemented by the customer (for example, by saving data to a file, etc.).
14
End measurement
Open the device
Make measurement
Set measurement
conditions
Perform dark
measurement
TmMeasExec function
Acquire
measurement results
Resume
measurement?
Yes
No
HIOKI TM6101A985-02

3.7 Making Measurements

Measurement is performed using either a synchronous or asynchronous measurement function. Once measurement is complete, the measurement results can be acquired using a measurement results acquisition function.
Note
When the external trigger is enabled, external trigger monitoring is started by executing the measurement function. Once measurement using the external trigger is complete, external trigger monitoring is cancelled. To start measurement using the external trigger again, execute the measurement function again.

Making Measurements Using the Synchronous Function

Measurements are made using the TmMeasExec function. The function does not return until measurement is complete and the instrument is in the measurement standby state. The instrument enters the measurement standby state when external I/O measurement complete output changes to OFF. When the external trigger is enabled, external trigger monitoring is started by executing the TmMeasExec function. The function does not return until either measurement completes following external trigger input or the timeout time elapses.
Example use of the synchronous function:
15
HIOKI TM6101A985-02

Making Measurements Using the Asynchronous Function

Since the asynchronous function returns immediately when measurement starts, other processing can be performed while the instrument is making measurements. When the external trigger is enabled, external trigger monitoring is started by executing the TmMeasExec function. While the external trigger is being monitored, the monitoring state can be cancelled (i.e., the instrument can be set to the measurement standby state) by calling the TmCancelMeas function. Once the TmMeasExecAsync function returns, the measurement status must be monitored with the TmGetMeasStatus and TmGetStandbyStatus functions. The following procedure is used to make measurements using the asynchronous function:
1. Start measurement with the TmMeasExecAsync function. The function will return as soon as
the instrument starts measurement. *If auto-ranging is enabled, the function will not return until auto-ranging processing completes.
2. Acquire the measurement status with the TmGetMeasStatus function. The TmGetMeasStatus
function should be repeatedly called until measurement completes. If a value of 0xFFFFFFFF is specified as the timeout time argument, the TmGetMeasStatus function will not return until measurement completes. Since measurement processing is performed internally by the TmGetMeasStatus function, be sure to verify the completion of measurement with the TmGetMeasStatus function.
3. Once measurement completes, the measurement results can be acquired using the library’s
measurement results acquisition functions. Additionally, since measurement by the sensor will have completed by this time, processing such as positioning the next measurement target can be performed.
4. Detect whether the instrument is in the measurement standby state with the
TmGetStandbyStatus function. If the instrument is in the measurement standby state, measurement can be started with the TmMeasExecAsync function. If a value of 0xFFFFFFFF is specified as the timeout time argument, the TmGetStandbyStatus function will not return until the instrument enters the measurement standby state.
Note
Once measurement starts, measurement conditions cannot be set until measurement completes and the instrument enters the measurement standby state. Do not use the measurement condition configuration functions until you verify that the instrument has entered the measurement standby state.
16
Measurement complete
Open the device
Start measurement
Set measurement
conditions
Perform dark
measurement
TmMeasExecAsync function
Acquire
measurement results
Resume
measurement?
Yes
No
Acquire measurement
status
Detect measurement
standby state
Measurement
complete?
Measurement
standby state?
Yes
No
Yes
No
TmGetMeasStatus function
TmGetStandbyStatus function
HIOKI TM6101A985-02
Example use of asynchronous function:
The following diagram illustrates the timing of instrument and library function operation. For more
detailed information about instrument operation timing, see “4.2 Timing Chart” in the TM6101 LED
Optical Meter Instruction Manual.
TM6101 operation timing:
TmGetMeasStatus
function
TmGetStandbyStatus
function
TM6101 internal operation Asynchronous functions
External trigger monitoring start
External trigger input
Measurement time
INDEX pulse width
Trigger delay
Measurement complete output ON
Measurement complete output OFF
Measurement start
*The next measurement can be performed once the function returns.
*If external trigger use is disabled, measurement starts.
Other functions
Measurement standby state
Measurement standby state
TmMeasExecAsync
function
Measurement results acquisition functions can be used.
Configuration functions can be used.
HIOKI TM6101A985-02
17
* Due to communications time requirements, it takes approximately 2 ms from the time the TmMeasExecAsync function is called until external trigger monitoring starts. Once the TmMeasExecAsync function returns, external trigger monitoring will already have started.
* Similarly, it takes approximately 2 ms from the time measurement completes until the TmGetMeasStatus function returns, and approximately 2 ms from the time measurement complete output turns OFF until the TmGetStandbyStatus function returns (when in the standby state after setting the timeout argument to 0xFFFFFFFF).
* The exact amount of time required for communications varies with factors such as the computer’s processing capability and the operating environment being used.
* When making measurements using the TmMeasExec function (a synchronous function), the function returns when measurement complete output changes to OFF.
Loading...
+ 40 hidden pages