MPPC module. Function Specifications (mppcum1a) Version 1.0. K29-B60901e

Transcription

1 K29-B60901e MPPC module Function Specifications (mppcum1a) Version 1.0

2 1 Introduction This specification document describes API needed to create application software for controlling an MPPC module. This specification document is written assuming you have experience with software development on Windows and also has an adequate understanding about USB architecture. When developing application software, we recommend checking the USB standards (USB1.1 / 2.0) by accessing the following website: [ System requirements ] Operation checks were performed for the device driver and DLL on the following system, but operation on other systems is not guaranteed. Microsoft Windows XP Professional SP3 (32 bit) OS Microsoft Windows Vista Business SP1, SP2 (32 bit) Microsoft Windows 7 Professional no SP, SP1 (32 bit/64 bit) A personal computer (PC) that meets the above system requirements must be used to operate the device driver and DLL. Although there are no other special requirements, we recommend using a PC with a high performance CPU and sufficient memory size. [ Development files ] The following DLL and function definition file are required to develop application software. Each file is contained on the CD-ROM: \Sample\ that comes with this product. mppcum1a.dll DLL for controlling an MPPC module. Copy this file into the same folder in which the application software will be stored or in the Windows system folder. mppcum1a.vb Function definition file for Visual Basic.NET. Copy this file into the project folder and add this to the project. mppcum1a.cs Function definition file for Visual C#.NET. Copy this file into the project folder and add this to the project. To allow the use of types in a namespace so that you do not have to qualify the use of a type in that namespace. Define following Using directive, if necessary. using MPPCmodule; [ Sample project files ] Project files for the sample application are included on the CD-ROM: \Sample\ that comes with this product. Use those files as references for developing your own programs. The project files were developed under the following environments..net Framework 3.5 SP1 Microsoft Visual Basic 2008 Express Edition Microsoft Visual C# 2008 Express Edition Microsoft Chart Controls for Microsoft.NET Framework 3.5 Microsoft Chart Controls Add-on for Microsoft Visual Studio 2008 * Specifications are subject to change without prior notice.

3 2 Release Notes Date Version Description November, First edition

4 3 List of Function MPPC_OpenDevice...4 MPPC_OpenTargetDevice...5 MPPC_CloseDevice...6 MPPC_CheckDevice...7 MPPC_OpenPipe...8 MPPC_ClosePipe...9 MPPC_ReadTypeNumber...10 MPPC_ReadUnitId MPPC_Initialize...12 MPPC_GetProperty...13 MPPC_SetProperty...14 MPPC_GetThreshold...15 MPPC_SetThreshold...16 MPPC_GetThresholdVoltage...17 MPPC_SetThresholdVoltage...18 MPPC_GetTemperature...19 MPPC_GetPeltierControl...20 MPPC_SetPeltierControl...21 MPPC_GetPeltierStatus...22 MPPC_GetCounterData...23 MPPC_GetCounterDataCooled...25

5 4 MPPC_OpenDevice Obtains the device handle to the MPPC module. Function MPPC_OpenDevice() As Integer System.IntPtr MPPC_OpenDevice( None INVALID_HANDLE_VALUE The target MPPC module does not exist. Other values Device handle Obtains the device handle to the MPPC module. The device handle is used to control the MPPC module. This function cannot identify the target MPPC module if two or more MPPC modules with the same vender ID and product ID are connected. When connecting two or more MPPC modules, use the MPPC_OpenTargetDevice When quitting the application you created, always use the MPPC_CloseDevice function to release the device handle that was obtained. Windows system may develop trouble if the MPPC module is disconnected from the PC without releasing the device handle.

6 5 MPPC_OpenTargetDevice Obtains the device handle to the MPPC module by specifying the unit ID (serial No.). Function MPPC_OpenTargetDevice( ByVal UnitID As String ) As Integer System.IntPtr MPPC_OpenTargetDevice( string UnitID UnitID Specify the unit ID of the target MPPC module. Unit ID is an ASCII character string (maximum of 8 bytes). INVALID_HANDLE_VALUE The target MPPC module does not exist. Other values Device handle Obtains the device handle to the MPPC module by specifying the unit ID. The device handle is used to control the MPPC module. When the unit ID is unknown, connect only one MPPC module to the PC and obtain the device handle with the MPPC_OpenDevice Then, use the MPPC_ReadUnitId function to obtain and check the device information (unit ID). When quitting the application you created, always use the MPPC_CloseDevice function to release the device handle that was obtained. Windows system may develop trouble if the MPPC module is disconnected from the PC without releasing the device handle.

7 6 MPPC_CloseDevice Releases the device handle to the MPPC module. Sub MPPC_CloseDevice( ByVal As Integer ) void MPPC_CloseDevice( System.IntPtr Specify the device handle that was obtained with the MPPC_OpenDevice function or MPPC_OpenTargetDevice None Releases the device handle obtained with the MPPC_OpenDevice function or MPPC_OpenTargetDevice Always first release the device handle when quitting the application. Windows system may develop trouble if the MPPC module is disconnected from the PC without releasing the device handle. However, the pipe handle obtained with the MPPC_OpenPipe function must be released with the MPPC _ClosePipe function before calling up this

8 7 MPPC_CheckDevice Checks the status of the connected MPPC module. Function MPPC_CheckDevice( ByVal As Integer ushort MPPC_CheckDevice( System.IntPtr Specify the device handle that was obtained with the MPPC_OpenDevice function or MPPC_OpenTargetDevice MPPC_CHECK_NORMAL MPPC module is operating normally. MPPC_CHECK_INVALID MPPC_CHECK_REMOVE MPPC module was disconnected. Checks the status of the connected MPPC module.

9 8 MPPC_OpenPipe Obtains the pipe handle to the MPPC module. Function MPPC_OpenPipe( ByVal As Integer ) As Integer System.IntPtr MPPC_OpenPipe( System.IntPtr Specify the device handle that was obtained with the MPPC_OpenDevice function or MPPC_OpenTargetDevice INVALID_HANDLE_VALUE Failed to obtain the pipe handle. Other values Pipe handle Obtains the pipe handle to the MPPC module. This pipe handle is used for data acquisition (bulk-in transfer). When quitting the application, always use the MPPC_ClosePipe function to release the pipe handle that was obtained. Windows system may develop trouble if the MPPC module is disconnected from the PC without releasing the pipe handle.

10 9 MPPC_ClosePipe Releases the pipe handle that was obtained. Sub MPPC_ClosePipe( ByVal PipeHandle As Integer ) void MPPC_ClosePipe( System.IntPtr PipeHandle PipeHandle Specify the pipe handle that was obtained with the MPPC_OpenPipe None Releases the pipe handle obtained with the MPPC_OpenPipe When quitting the application, always run this function before releasing the device handle with the MPPC_CloseDevice Windows system may develop trouble if the MPPC module is disconnected from the PC without releasing the pipe handle.

11 10 MPPC_ReadTypeNumber Obtains the type No. from the MPPC module. Function MPPC_ReadTypeNumber( ByVal As Integer, ByVal TypeNumber As System.Text.StringBuilder ushort MPPC_ReadTypeNumber( System.IntPtr, System.Text.StringBuilder TypeNumber TypeNumber Specify the leading element to the area where the MPPC module type No. is to be stored. Type No. is an ASCII character string (maximum of 16 bytes). Succeeded in obtaining the type No. Failed to obtain the type No. Obtains the type No. from the MPPC module.

12 11 MPPC_ReadUnitId Obtains the unit ID (serial No.) from the MPPC module. Function MPPC_ReadUnitID( ByVal As Integer, ByVal UnitID As System.Text.StringBuilder ushort MPPC_ReadUnitID( System.IntPtr, System.Text.StringBuilder UnitID UnitId Specify the leading element to the area where the MPPC module unit ID is to be stored. Unit ID is an ASCII character string (maximum of 8 bytes). Succeeded in obtaining the unit ID. Failed to obtain the unit ID. Obtains the unit ID from the MPPC module.

13 12 MPPC_Initialize Initializes the MPPC module. Function MPPC_Initialize( ByVal As Integer ushort MPPC_Initialize( System.IntPtr Succeeded in initializing the MPPC module. Failed to initialize the MPPC module. Initializes the MPPC module. After obtaining the device handle, initialize the MPPC module with the MPPC_Initialize The MPPC module becomes controllable after initialization.

14 13 MPPC_GetProperty Obtains the gate time and data size that are set for the MPPC module. Function MPPC_GetProperty( ByVal As Integer, ByRef GateTime As UInteger, ByRef DataSize As UShort ushort MPPC_GetProperty( System.IntPtr, out uint GateTime, out ushort DataSize GateTime Specify the variable of unsigned int type (4 bytes). The currently set gate time will be stored in this variable. DataSize Specify the variable of unsigned short type (2 bytes). The currently set data size will be stored in this variable. Succeeded in acquiring the settings. Failed to acquire the settings. Obtains the gate time and data size that are set for the MPPC module. If succeeded, the settings will be stored in the specified variable.

15 14 MPPC_SetProperty Sets the gate time and data size for the MPPC module. Function MPPC_SetProperty( ByVal As Integer, ByVal GateTime As UInteger, ByVal DataSize As UShort ushort MPPC_SetProperty( System.IntPtr, uint GateTime, ushort DataSize GateTime Specify (4 bytes) the gate time [µs]. Setting range is from 100 to 1,000,000 (100 µs to 1 second). DataSize Specify the data size (2 bytes) to be obtained. Setting range is from 1 to Succeeded in changing settings. Failed to change settings. MPPC_INVALID_VALUE Specified setting is out of range. Sets the gate time and data size to be obtained for the MPPC module. As default, the gate time is set to 1,000 µs (1 ms), and the data size to 100. In the USB communication (bulk-in transfer) with the MPPC module, the data is sent as a group in order to increase the data transfer efficiency. This is to avoid speed reduction caused by overhead. Set the data size so that the following relation is satisfied. (gate time) (data size) 20ms ( 50ms recommended)

16 15 MPPC_GetThreshold Obtains the comparator threshold level (p.e.) that is set for the MPPC module. Function MPPC_GetThreshold( ByVal As Integer, ByRef Level As UShort ushort MPPC_GetThreshold( System.IntPtr, out ushort Level Level Specify the variable of unsigned short type (2 bytes). The currently set comparator threshold (index) will be stored in this variable. Succeeded in acquiring the setting. Failed to acquire the setting. Obtains the comparator threshold (p.e.) that is set for the MPPC module. If succeeded, the setting (index) will be stored in the specified variable. Setting (index) VTH_05 (0) VTH_15 (1) VTH_25 (2) VTH_35 (3) VTH_45 (4) VTH_55 (5) VTH_65 (6) VTH_75 (7) VTH_OVER (40) Threshold level 0.5p.e. 1.5p.e. 2.5p.e. 3.5p.e. 4.5p.e. 5.5p.e. 6.5p.e. 7.5p.e. Disable

17 16 MPPC_SetThreshold Sets a comparator threshold level (p.e.) for the MPPC module. Function MPPC_SetThreshold( ByVal As Integer, ByVal Level As UShort ushort MPPC_SetThreshold( System.IntPtr, ushort Level Level Specify (2 bytes) the comparator threshold level (index). Succeeded in changing setting. Failed to change setting. MPPC_INVALID_VALUE Specified setting is out of range. Sets a comparator threshold level (p.e.) for the MPPC module. The following values can be set. Note that the counter function and comparator output will stop if the threshold is specified Disable (40). The same is true when higher than 4500 mv is set as the second argument in the MPPC_SetThresholdVoltage Setting (index) VTH_05 (0) VTH_15 (1) VTH_25 (2) VTH_35 (3) VTH_45 (4) VTH_55 (5) VTH_65 (6) VTH_75 (7) VTH_OVER (40) Threshold level 0.5p.e. 1.5p.e. 2.5p.e. 3.5p.e. 4.5p.e. 5.5p.e. 6.5p.e. 7.5p.e. Disable

18 17 MPPC_GetThresholdVoltage Obtains the comparator threshold (voltage) that is set for the MPPC module. The unit is mv. Function MPPC_GetThresholdVoltage( ByVal As Integer, ByRef Voltage As UShort ushort MPPC_GetThresholdVoltage( System.IntPtr, out ushort Voltage Voltage Specify the variable of unsigned short type (2 bytes). The currently set comparator threshold level (voltage) will be stored in this variable. Succeeded in acquiring the setting. Failed to acquire the setting. MPPC_NON_SUPPORT The MPPC module is not supported by this Obtains the comparator threshold (voltage) that is set for the MPPC module. If succeeded, the setting (mv) will be stored in the specified variable.

19 18 MPPC_SetThresholdVoltage Sets a comparator threshold level (voltage) for the MPPC module. The unit is mv. Function MPPC_SetThresholdVoltage( ByVal As Integer, ByVal Voltage As UShort ushort MPPC_SetThresholdVoltage( System.IntPtr, ushort Voltage Voltage Specify (2 bytes) the comparator threshold level (voltage). Succeeded in changing setting. Failed to change setting. MPPC_INVALID_VALUE Specified setting is out of range. Sets a comparator threshold (voltage) for the MPPC module. Setting range is from 0 to 4999 mv. Note that the counter function and comparator output will stop if the threshold is set higher than 4500 mv. The same is true when Disable (40) is specified as the second argument in the MPPC_SetThreshold

20 19 MPPC_GetTemperature Obtains temperature data from the temperature sensor installed in the MPPC module. The temperature obtained from the temperature sensor is the Internal temperature. Function MPPC_GetTemperature( ByVal As Integer, ByRef Temperature As Double ushort MPPC_GetTemperature( System.IntPtr, out double Temperature Temperature Specify the variable of double type. Temperature data will be stored in this variable. Succeeded in obtaining the temperature data. Failed to obtain the temperature data. Obtains temperature data from the temperature sensor installed in the MPPC module. If succeeded, the temperature data will be stored in the specified variable.

21 20 MPPC_GetPeltierControl Obtains the cooling control status (Enable / Disable) of the MPPC module. This function is only for cooled type MPPC modules. Function MPPC_GetPeltierControl( ByVal As Integer, ByRef ControlFlags As UShort ushort MPPC_GetPeltierControl( System.IntPtr, out ushort ControlFlag ControlFlags Specify the variable of unsigned short type (2 bytes). The cooling control status (Enable / Disable) will be stored in this variable. Succeeded in acquiring the setting. Failed to acquire the setting. MPPC_NON_SUPPORT The MPPC module is not supported by this This function is only for cooled type MPPC modules. Use this function to obtain the cooling control status (Enable / Disable) of the MPPC module. ENABLE(1) indicates the MPPC module is being cooled, and DISABLE(0) indicates the cooling is stopped.

22 21 MPPC_SetPeltierControl Sets the cooling control status (Enable / Disable) of the MPPC module. This function is only for cooled type MPPC modules. Function MPPC_SetPeltierControl( ByVal As Integer, ByVal ControlFlags As UShort ushort MPPC_SetPeltierControl( System.IntPtr, ushort ControlFlag ControlFlags Specify ENABLE(1) to start cooling or DISABLE(0) to stop cooling. Succeeded in changing setting. Failed to change setting. MPPC_INVALID_VALUE Specified setting is invalid. MPPC_NON_SUPPORT The MPPC module is not supported by this MPPC_ERROR_TEMP Internal temperature exceeded the operating temperature range. This function is only for cooled type MPPC modules. Use this function to set the cooling control status (Enable / Disable) of the MPPC module. Specify ENABLE(1) to start cooling or DISABLE(0) to stop cooling. Before starting measurement, start cooling with this If the Internal temperature is outside the operating temperature range (0 to +35 C), this function returns MPPC_ERROR_TEMP. Cooling will not start in this case.

23 22 MPPC_GetPeltierStatus Obtains the cooling status of the MPPC module. This function is only for cooled type MPPC modules. Function MPPC_GetPeltierStatus( ByVal As Integer ushort MPPC_GetPeltierStatus( System.IntPtr Cooling is stable. Failed to obtain the cooling status. MPPC_NON_SUPPORT The MPPC module is not supported by this MPPC_UNSTABLE_STATE Cooling is unstable. MPPC_PELTIER_DISABLE Cooling is stopped. MPPC_PELTIER_TIMEOUT A time-out error occurred after starting cooling. (This error will not be cleared until the power to the MPPC module is turned off.) MPPC_ERROR_MODULE An error occurred in the cooler. (This error will not be cleared until the power to the MPPC module is turned off.) MPPC_ERROR_TEMP Internal temperature exceeded the operating temperature range. This function is only for cooled type MPPC modules. Use this function to obtain the cooling status of the MPPC module. After starting cooling with the MPPC_SetPeltierControl function, check the cooling status of the MPPC module with this If the cooling is stable, will be returned. If the returned value is MPPC_UNSTABLE_STATE, the cooling temperature is not yet reached. Wait for a while and then recheck the cooling status using this If the cooling does not become stable within the specified time (approx. 2 minutes), MPPC_PELTIER_TIMEOUT will be returned. If an error occurred in the cooler, MPPC_ERROR_MODULE will be returned.

24 23 MPPC_GetCounterData Acquires data from the MPPC module. Use this function to obtain data from non-cooled type MPPC modules. Function MPPC_GetCounterData( ByVal As Integer, ByVal PipeHandle As Integer, ByVal Size As UShort, ByVal DataArea() As UInteger ushort MPPC_GetCounterData( System.IntPtr, System.IntPtr PipeHandle, ushort Size, uint[] DataArea PipeHandle Specify the pipe handle obtained with the MPPC_OpenPipe DataSize Specify the data size that was specified as DataSize with the MPPC_SetProperty DataArea Specify the leading element to the buffer (DataSize 4 bytes) where the acquired data is to be stored. Data is 4 bytes. The data read out of the MPPC module will be stored in the specified buffer. Succeeded in obtaining the data. Failed to obtain the data. MPPC_INVALID_VALUE Specified value is invalid. MPPC_NOT_UPDATED Data of the specified data size is not provided (data is being acquired). Acquires data from the MPPC module. Acquires the data equal to the data size specified with the MPPC_SetProperty function and then stores it in the specified buffer (DataArea). The data size specified as DataSize should be the same value as the size specified with the MPPC_SetProperty If a different size is specified, the acquired data is not guaranteed. In the USB communication (bulk-in transfer) with the MPPC module, the data is sent as a group in order to increase the data transfer efficiency. This is to avoid speed reduction caused by overhead. Set the data size so that the following relation is satisfied. (gate time) (data size) 20ms ( 50ms recommended)

25 24 The time needed for the MPPC_GetCounterData function to be processed (from when the function is called to when the control is returned) is about 13 to 20 ms, depending on the system environment used. This means that under the conditions not satisfying the above relation, the acquired data might be erased (overwritten by new data) in the MPPC module. [Example] If the gate time is set to 1000 µs and the data size to 50 Since 1000 µs 50 = 50 ms, new data is provided every 50 ms in the MPPC module. If no data is acquired within 50 ms after new data is updated, the data retained in the MPPC module will be erased, and new data will be provided. Because of this, the application must access the MPPC module at an interval shorter than 50 ms in order to acquire data. When data is acquired, it will be stored in the specified buffer. If new data is not provided in the MPPC module, MPPC_NOT_UPDATED will be returned. In this case, wait for a while and then recall this function to acquire data. If failed to acquire data, will be returned. The data in the specified buffer is uncertain.

26 25 MPPC_GetCounterDataCooled Acquires data from the MPPC module. Also returns an error when the cooling status becomes abnormal. Use this function to acquire data from cooled type MPPC modules. Function MPPC_GetCounterDataCooled( ByVal As Integer, ByVal PipeHandle As Integer, ByVal DataSize As UShort, ByVal Data() As UInteger ushort MPPC_GetCounterDataCooled( System.IntPtr, System.IntPtr PipeHandle, ushort Size, uint[] DataArea PipeHandle Specify the pipe handle obtained with the MPPC_OpenPipe DataSize Specify the data size that was specified as DataSize with the MPPC_SetProperty DataArea Specify the leading element to the buffer (DataSize 4 bytes) where the acquired data is to be stored. Data is 4 bytes. The data read out of the MPPC module will be stored in this buffer. Succeeded in obtaining the data. Failed to obtain the data. MPPC_INVALID_VALUE Specified value is invalid. MPPC_NOT_UPDATED Data of the specified data size is not provided (data is being acquired). MPPC_NON_SUPPORT The MPPC module is not supported by this MPPC_UNSTABLE_STATE Cooling is unstable. MPPC_PELTIER_DISABLE Cooling is stopped. MPPC_ERROR_MODULE An error occurred in the cooler. (This error will not be cleared until the power to the MPPC module is turned off.) MPPC_ERROR_TEMP Internal temperature exceeded the operating temperature range.

27 26 This function is only for cooled type MPPC modules. Acquires data from the MPPC module. Acquires the data equal to the data size specified with the MPPC_SetProperty function and then stores it in the specified buffer (DataArea). The data size specified as DataSize should be the same value as the size specified with the MPPC_SetProperty If a different size is specified, the acquired data is not guaranteed. In the USB communication (bulk-in transfer) with the MPPC module, the data is sent as a group in order to increase the data transfer efficiency. This is to avoid speed reduction caused by overhead. Set the data size so that the following relation is satisfied. (gate time) (data size) 20ms ( 50ms recommended) The time needed for the MPPC_GetCounterDataCooled function to be processed (from when the function is called to when the control is returned) is about 13 to 20 ms, depending on the system environment used. This means that under the conditions not satisfying the above relation, the acquired data might be erased (overwritten by new data) in the MPPC module. [Example] If the gate time is set to 1000 µs and the data size to 50 Since 1000 µs 50 = 50 ms, new data is provided every 50 ms in the MPPC module. If no data is acquired within 50 ms after new data is updated, the data retained in the MPPC module will be erased, and new data will be provided. Because of this, the application must access the MPPC module at an interval shorter than 50 ms in order to acquire data. When data is acquired, it will be stored in the specified buffer. If new data is not provided in the MPPC module, MPPC_NOT_UPDATED will be returned. In this case, wait for a while and then recall this function to acquire data. If failed to acquire data, will be returned. The data in the specified buffer is uncertain. If an error occurred in the cooler, MPPC_ERROR_MODULE will be returned.

28 27 Appendix A. [ Return value list ] Symbol Value Description INVALID_HANDLE_VALUE -1 The target MPPC module does not exist. 0 Normal end. 1 Abnormal end. 2 MPPC_INVALID_VALUE 3 Specified value is invalid. MPPC_NOT_UPDATED 4 Specified data size is not provided. (Data is being acquired). MPPC_NON_SUPPORT 5 MPPC module is not supported by this MPPC_UNSTABLE_STATE 11 Cooling is unstable. MPPC_PELTIER_DISABLE 12 Cooling is stopped. MPPC_PELTIER_TIMEOUT * 13 Time-out error occurred after stating cooling. MPPC_ERROR_MODULE * 14 Error occurred in the cooler. MPPC_ERROR_TEMP 15 Operating temperature range was exceeded. MPPC_CHECK_NORMAL 21 MPPC module is operating normally. MPPC_CHECK_INVALID 22 MPPC_CHECK_REMOVE 23 MPPC module is disconnected. * If MPPC_PELTIER_TIMEOUT or MPPC_ERROR_MODULE occurs, emmediately quit the application that is operating and disconnect the MPPC module from the PC. These errors will not be cleared until the power to the MPPC module is turned off.