Binary core API

From ADVACAM Wiki
Jump to navigation Jump to search

Core/basic binary (C) API introduction

The PIXet is a multi-platform software developed in ADVACAM company. It is a basic software that allows measurement control and saving of measured data with Medipix detectors. It supports Medipix2, Medipix3, Timepix and Timepix3 detectors and all the readout-devices sold by ADVACAM company such as FitPIX, AdvaPIX, WidePIX, etc. It is written in C++ language and uses multi-platform Qt libraries.

This document describes a developer interface of the PIXet software. This developer interface consists of dynamic linked library pxcore.dll (Windows) or libpxcore.so (Mac or Linux), the corresponding header file for the library pxcapi.h and few other supporting libraries (fitpix.dll, Visual Studio runtime libraries, etc.)

The core API with the pxcore library, allowing basic measurements and device settings.
Files:

  • pxcapi.h API header file
  • pxcore.dll or pxcore.so binary libraries for Windows or Linux
  • pxcore.lib static linging file for easier using on Windows (compile time only)
  • common.h common file defining basic types, constatns and usefull macros. It's not necessary, but it can be useful.

And need some auxiliary files and directories:

Requirements

Hardware

This API requires computer with x86 compatible architecture (no ARM), 64bit Windows or Linux and connected some Advacam hardware with imaging chip. Medipix3, Timepix, Timepix2, Timepix3, etc. Some functions are universal for all hardwares (pxcInitialize, pxcGetDeviceName, etc), some is specialized for only one chip type (pxcMeasureSingleFrameTpx3 is Timepix3 only).

Specialized functions have names with chip type included:

  • pxcSetTimepixCalibrationEnabled – Timepix only (no Timepix3)
  • pxcMeasureTpx3DataDrivenMode – Timepix3 only
  • pxcMeasureSingleFrameMpx3 – Medipix3 only

The attempt to use the function if compatible hardware (in initialized state) not present, end with error.
Return code is PXCERR_UNEXPECTED_ERROR.

Software

All the API functions have heads in pxcapi.h, implemented for Windows in the pxcore.dll and for linking must use the pxcore.lib in the linker settings. Implementation for Linux is in the libcore.so.
Compiled program need the pixet.ini file with proper hwlibs list inside, necessary hardware dll files (eq minipix.dll for Minipixes), optional special files (eq zestwpx.bit for Widepixes), subdirectory “factory” with default config files for all present imaging devices (eq MiniPIX-I08-W0060.xml) and the Pixet core will create subdirectory “configs” to save changed configs on exit.
See The Pixet core, additional libraries and other files
Usually, for build, just set the compiler to use 64bit and the linker to use the pxcore.lib file.

In Microsoft visual studio, while creating the C++ CLR project, it is also necessary to insert the use of WIN32 definition into the project settings (C/C++ / Preprocessor / Preprocessor definitions):

Visual Studio Project Settings
Visual Studio Project Settings

The Pixet core, additional libraries and other files

Main files:

  • pxcapi.h API header file
  • pxcore.dll or pxcore.so binary libraries for Windows or Linux
  • pxcore.lib static linging file for easier using on Windows (compile time only)

And need some auxiliary files and directories:

Where to get these files?

All need files except XML configs are located in the zip file with name like us:
PIXet_SDK_1.8.0_(Build_22b1f335)_Win.zip

Download: Advacam: Pixet Pro Software Updates

And all files except LIB files for Windows compilation are located in the Pixet directory:

All files except LIB files for Windows compilation are located in the Pixet directory
All files except LIB files for Windows compilation are located in the Pixet directory

Example of the project directory

Example of the project dirrectory
Example of the project dirrectory

On the right is a screenshot of the Windows CLR APP project directory in Visual Studio that uses Minipix Tpx3. The marked files were copied from the Advacam SDK and the "factory" directory contains the configuration XML file for the device. It is important that the name is complete, eg MiniPIX-I08-W0060.xml. This file will be used on first launch.

The directory "configs" is created when Pixet core is terminated and contains a configuration XML file with saved current settings. This file will be used on each subsequent startup and updated on each subsequent exit.

The "logs" directory is created when Pixet core is started for the first time and contains LOG files from device activity and backups of these files for the last 10 starts.

Contents of the pixet.ini file:

[hwlibs]
minipix.dll

(x64, Myform... and TPx3-1... are from the MS Visual studio project)

Don't forget to set up WIN32 and pxcore.lib in the project settings as described in the parent chapter.

Tip: How to create the Windows CLR APP:
MSDN:create-c-windows-forms-application-in-visual-studio-2017

Example of the minimalistic program directory

Example of the minimalistic project dirrectory
Example of the minimalistic project dirrectory


API Functions

Simple commandline example

Example code

This is simple example of commandline C program, whitch initializes the Pixet core and device, sets it's operation mode, measures single frame, saves the frame to some files and deinitializes the Pixet core with all the connected devices.
(Timepix3 only)

#include "pxcapi.h"

int main() {
    int rc; // return code
    
    printf("Initializing...\n");
    rc = pxcInitialize();
    printf("pxcInitialize: %d (0 is OK)\n", rc);
    
    rc = pxcSetTimepix3Mode(0, PXC_TPX3_OPM_TOATOT); // sets OPM of device with index 0
    printf("pxcSetTimepix3Mode: %d (0 is OK)\n", rc);
    
    // pxcMeasureMultipleFrames(deviceIndex, frameCount, acqTime, triggerSettings);
    rc = pxcMeasureMultipleFrames(0, 3, 1, PXC_TRG_NO);
    printf("pxcMeasureMultipleFrames: %d (0 is OK)\n", rc);
    
    // pxcSaveMeasuredFrame(deviceIndex, frameLastIndex, filename);
    rc = pxcSaveMeasuredFrame(0, 0, "testImg0.png");
    printf("pxcSaveMeasuredFrame 0: %d (0 is OK)\n", rc);
    rc = pxcSaveMeasuredFrame(0, 1, "testImg1.txt");
    printf("pxcSaveMeasuredFrame 1: %d (0 is OK)\n", rc);
    rc = pxcSaveMeasuredFrame(0, 2, "testImg2.pbf");
    printf("pxcSaveMeasuredFrame 2: %d (0 is OK)\n", rc);
    
    rc = pxcExit();
    printf("pxcExit: %d (0 is OK)\n", rc);
}

Note: If You want test it in device other than Timepix3, You can comment lines with pxcSetTimepix3Mode. But then it is not clear what will be measured.

Building using cmake on Windows with Visual Studio installed

Example of CMakeLists.txt file for compiling this using cmake (C++ file is named "minipix1.cpp"):

cmake_minimum_required(VERSION 3.10)
project(minipix1)

# include_directories(${CMAKE_SOURCE_DIR})
# link_directories(${CMAKE_SOURCE_DIR})
add_library(pxcore SHARED IMPORTED)
set_property(TARGET pxcore PROPERTY IMPORTED_LOCATION "${CMAKE_SOURCE_DIR}/pxcore.dll")
set_property(TARGET pxcore PROPERTY IMPORTED_IMPLIB  "${CMAKE_SOURCE_DIR}/pxcore.lib")
add_executable(minipix1 minipix1.cpp)
target_link_libraries(minipix1 pxcore)

Example of the Cmake building script:

rmdir /s /q build
mkdir build
cd build
cmake -DCMAKE_GENERATOR_PLATFORM=x64 .. 

msbuild /P:Configuration=Release ALL_BUILD.vcxproj 

cd .. 
copy pxcore.dll build\Release\pxcore.dll
copy minipix.dll build\Release\minipix.dll
copy pixet.ini build\Release\pixet.ini
echo build\Release\minipix1.exe > run.cmd

User can finally run the run.cmd to run the program.

Building on Linux using GCC

Example build.sh:

#!/bin/bash
gcc -o build-out minipix1.cpp -Wno-write-strings -L. -lpxcore -lminipix  -ldl -lm -lc -g

Example run.sh to run the output executable:

#!/bin/bash
LD_LIBRARY_PATH=. ./build-out
# run last compiled example

Auxiliary functions

This chapter describes auxiliary functions. There are need for normal using of the device, but it not measuring.

Start-up and end


pxcInitialize


This function initializes the Pixet software and all connected devices. This function has to be called first before any other function except pxcGetLastError.
Definition
PXCAPI int pxcInitialize(int argc = 0, char const* argv[] = NULL);

Parameters

  • argc – number of program command line arguments (optional parameter)
  • argv – command line program arguments (optional parameter)
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

int rc = pxcInitialize();


pxcExit


This function deinitializes Pixet software and all the connected devices. This function has to be called as last function before unloading the pxcore library.
Definition
PXCAPI int pxcExit();

Parameters

  • {{{1}}}
  • {{{2}}}
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

int rc = pxcExit();


pxcRefreshDevices


This function looks for newly connected devices and removed disconnected devices from the device list.
Definition
PXCAPI int pxcRefreshDevices();

Parameters

  • {{{1}}}
  • {{{2}}}
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

int rc = pxcRefreshDevices();


pxcReconnectDevice


If the device was disconnected or experienced communication problems, this function will try to reconnect the device and reinitialize it. Like as do the pxcExit and pxcInitialize, but only for one device index. The process is:
  1. Saves the device config to the “configs” directory
  2. Disconnects the device
  3. Connects the device
  4. Loads the device config
Definition
PXCAPI int pxcReconnectDevice(unsigned deviceIndex);

Parameters

  • deviceIndex - index of the device, starting from zero
  • {{{2}}}
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

int rc = pxcReconnectDevice(0); // reconnect device with index 0


Parameter Get/Set functions (direct)


Functions described in this chapter working directly, function name defines parameter name and type.

Example: Setting operation mode


 // Set the operating mode
 rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_TOATOT);
 printErrors("pxcSetTimepix3Mode", rc);

Example: List of devices with parameters


 #include <stdio.h>
 #include "pxcapi.h"
 #define CHT_Si 0
 #define CHT_CdTe 1
 char chipType = CHT_Unknown;
 int main(int argc, char const* argv[]) { // #######################################
     int rc = pxcInitialize();
     if (rc) {
         printf("Could not initialize Pixet:\n");
         printErrors("pxcInitialize", rc, ENTER_ON);
         return -1;
     }
     int connectedDevicesCount = pxcGetDevicesCount();
     printf("Connected devices: %d\n", connectedDevicesCount);
     if (connectedDevicesCount == 0) return pxcExit();
     for (unsigned devIdx = 0; (signed)devIdx < connectedDevicesCount; devIdx++) {
         char deviceName[256];
         memset(deviceName, 0, 256);
         pxcGetDeviceName(devIdx, deviceName, 256);
         char chipID[256];
         memset(chipID, 0, 256);
         pxcGetDeviceChipID(devIdx, 0, chipID, 256);
         printf("Device %d: Name %s, (first ChipID: %s)\n", devIdx, deviceName, chipID);
     }
     double bias;
     rc = pxcGetBias(devIdx, &bias);
     if (bias < 0.0) {
         if (devIdx == 0) chipType = CHT_CdTe;
         printf("Chip material detected: CdTe\n");
     } else if (bias == 0.0) {
         printf("Chip material not detected!\n");
     } else {
         if (devIdx == 0) chipType = CHT_Si;
         printf("Chip material detected: Si\n");
     }
     printf("=================================================================\n");
     
     // here can be working code (calling some example function from this manual)
     
     return pxcExit();
 }

pxcGetLastError


Returns text of last error. This function can be called even before pxcInitialize()
Definition
PXCAPI int pxcGetLastError(char* errorMsgBuffer, unsigned size);

Parameters

  • errorMsgBuffer - buffer where text will be saved
  • size - size of supplied buffer
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

char msg[200];<br> pxcGetLastError(msg, 200);<br> printf("Error msg: %s\n", msg);


Example1 (console)

#define ERRMSG_BUFF_SIZE 512
#define ENTER_ON true
#define ENTER_OFF false
// (the function used in most examples in this manual)
void printErrors(const char* fName, int rc, bool enter) {
   char errorMsg[ERRMSG_BUFF_SIZE];
   pxcGetLastError(errorMsg, ERRMSG_BUFF_SIZE);
   if (errorMsg[0]>0) {
       printf("%s %d err: %s", fName, rc, errorMsg);
   } else {
       printf("%s %d err: ---", fName, rc);
   }
   if (enter) printf("\n");
}

Now you can use it:

rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
printErrors("pxcSetTimepix3Mode", rc, ENTER_ON);

If mode set was suscessfull, result is:

pxcSetTimepix3Mode 0 err: ---

If not, you can see some as:

pxcSetTimepix3Mode -2 err: Invalid device index


Example2 (Windows CLR)

const unsigned cErrBufSize = 512;
// primary use to show function name, return code, last error message
bool errorToList(const char* fName, int rc) {
    char errorMsg[cErrBufSize];
    char cMsg[cErrBufSize];
    String^ eMsg;
    pxcGetLastError(errorMsg, cErrBufSize);
    if (rc!=0) {
        sprintf(cMsg, "%s %d err: %s", fName, rc, errorMsg);
        eMsg = gcnew String(errorMsg);
    } else {
        sprintf(cMsg, "%s %d err: ---", fName, rc);
    };
    String^ sMsg = gcnew String(cMsg);
    listMessages->Items->Add(sMsg);
    return (rc!=0);
}

Now you can use it:

rc = pxcSetTimepix3Mode(deviceIndex, PXC_TPX3_OPM_EVENT_ITOT);
if (printErrorToList("pxcSetTimepix3Mode", rc)) return rc;

pxcGetDevicesCount


This function returns number of connected and initialized devices.
Definition
PXCAPI int pxcGetDevicesCount();

Parameters

  • {{{1}}}
  • {{{2}}}
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
Number of devices, otherwise the return value is a PXCERR_XXX code

Note

{{{Not}}}

Warning

{{{War}}}

Example

printf("Connected devices count: %d\n", pxcGetDevicesCount());


pxcListNetworkDevices


Search for available network devices and store basic information about it to arrary.
Definition
PXCAPI int pxcListNetworkDevices(NetworkDevInfo* devInfos, unsigned* size);

Parameters

  • devInfos - Pointer to array of NetworkDevInfo{char ip[15]; char name[20]; int serial;} structures
  • size - [in] Pointer to size of the devInfo (number of elements) / [out] Value overwritten by the number of devices found
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
Returns 0 if OK or PXCERR_BUFFER_SMALL if the number of devices exceeded the size of the array (the array is still filled and *size is set)

Note

{{{Not}}}

Warning

{{{War}}}

Example

NetworkDevInfo ndi[10];<br>
unsigned size = 10;<br>
<br>
int rc = pxcListNetworkDevices(ndi, &size);<br>
printf("Network dev list:\n");
for (int i=0; (rc==0 && i<size) || (rc<0 && i<10); i++) printf("  IP: %s, Name: %s, Serial: %d\n", ndi[i].ip, ndi[i].name, ndi[i].serial);<br>
printf("Devices found: %d\n", *size);<br>
if (rc<0) printf("Warning: Number of devs exceeded the array size\n");



pxcGetDeviceName


This function returns the full name of the selected device.
Definition
PXCAPI int pxcGetDeviceName((unsigned deviceIndex, char* nameBuffer, unsigned size);

Parameters

  • deviceIndex - index of the device, starting from zero
  • nameBuffer - buffer where the name of the device will be saved. Cannot be NULL
  • size - size of the supplied name buffer
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

char name[100];<br> pxcGetDeviceName(deviceIndex, name, 100);<br> printf("Dev %d name: %s\n", deviceIndex, msg);


pxcGetDeviceChipCount


This function returns number of chips in the device.
Definition
PXCAPI int pxcGetDeviceChipCount(unsigned deviceIndex);

Parameters

  • deviceIndex - index of the device, starting from zero
  • {{{2}}}
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
Number of chips if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

printf("Dev %d has chip count: %d\n", deviceIndex, pxcGetDeviceChipCount(deviceIndex));


pxcGetDeviceChipID


This function returns the ID of chip of the detector connected to the readout device.
Definition
PXCAPI int pxcGetDeviceChipID((unsigned deviceIndex, unsigned chipIndex, char* chipIDBuffer, unsigned size);

Parameters

  • deviceIndex - index of the device, starting from zero
  • chipIndex – index of the chip in the device, starting from zero
  • chipIDBuffer - buffer where the chipID of the detector will be saved. Cannot be NULL
  • size - size of the supplied chipID buffer
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

char id[50];<br> pxcGetDeviceChipID(deviceIndex, 0, id, 50);<br> printf("Chip 0 of dev %d have ID: %s\n", deviceIndex, msg);


pxcGetDeviceSerial


This function returns the devise serial number.
Definition
PXCAPI int pxcGetDeviceSerial(unsigned deviceIndex);

Parameters

  • deviceIndex - index of the device, starting from zero
  • {{{2}}}
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
Serial number (>0) if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

printf("Dev %d has serial number: %d\n", deviceIndex, pxcGetDeviceSerial(deviceIndex));


pxcGetDeviceDimmensions


This function gets pixel width and height of the device.
Definition
PXCAPI int pxcGetDeviceDimmensions(unsigned deviceIndex, unsigned *w, unsigned *h);

Parameters

  • deviceIndex - index of the device, starting from zero
  • w – pointer to unsigned variable where the width of the device will be returned
  • h – pointer to unsigned variable where the height of the device will be returned
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

unsigned w, h;<br>
int rc = pxcGetDeviceDimmensions(deviceIndex, &w, &h);<br>
if (rc==0) printf("Width: %d, Height %d [px]\n", w, h);<br>
else printf("pxcGetDeviceDimmensions failed, code %d\n", rc);


pxcGetBias


This function gets the bias voltage (high voltage) of the sensor chip.
Definition
PXCAPI int pxcGetBias(unsigned deviceIndex, double* bias);

Parameters

  • deviceIndex – index of the device, starting from zero
  • bias – pointer to double variable where current bias will be returned
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

double bias;<br>
int rc = pxcGetBias(deviceIndex, &bias);<br>
if (rc==0) printf("Bias: %f V\n", bias);<br>
else printf("pxcGetBias failed, code %d\n", rc);


pxcGetBiasRange


This function gets the range of the allowed minimal and maximal bias values.
Definition
PXCAPI int pxcGetBiasRange(unsigned deviceIndex, double* minBias, double* maxBias);

Parameters

  • deviceIndex - index of the device, starting from zero
  • minBias – pointer to double variable where minimum allowed bias will be returned
  • maxBias – pointer to double variable where maximum allowed bias will be returned
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

double min, max;<br>
int rc = pxcGetBiasRange(deviceIndex, &min, &max);<br>
if (rc==0) printf("Bias min: %f, max: %f V\n", min, max);<br>
else printf("pxcGetBiasRange failed, code %d\n", rc);


pxcSetBias


This function sets the high voltage (bias) of the detector.
Definition
PXCAPI int pxcSetBias(unsigned deviceIndex, double bias);

Parameters

  • deviceIndex - index of the device, starting from zero
  • bias – high voltage in volts (limits and polarity depending on the device configuration, see: pxcGetBiasRange)
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

int rc = pxcSetBias(0, -350); // set bias -350 V to device with idx 0


pxcGetThreshold


This function gets the threshold of the detector. Output value is normally in keV, but if the device not properly configurated, output is didital DAC value.
Definition
PXCAPI int pxcGetThreshold(unsigned deviceIndex, unsigned thresholdIndex, double* threshold);

Parameters

  • deviceIndex - index of the device, starting from zero
  • thresholdIndex – for all except Medipix3 always 0, for Medipix3 index of corresponding threshold starting from zero
  • threshold – pointer to double variable where threshold will be saved. The value is several keVs with decimals or from 0 to a some power of two (depending of device DAC bits depth).
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

double thl;<br>
int rc = pxcGetThreshold(deviceIndex, &thl);<br>
if (rc==0) printf("Threshold: %f\n", thl);<br>
else printf("pxcGetThreshold failed, code %d\n", rc);


pxcGetThresholdRange


This function gets the allowed range of values for threshold. Output values are normally in keV, but if the device not properly configurated, output is didital DAC value.
Definition
PXCAPI int pxcGetThresholdRange(unsigned deviceIndex, int thresholdIndex, double* minThreshold, double* maxThreshold);

Parameters

  • deviceIndex - index of the device, starting from zero
  • thresholdIndex – for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
  • minThreshold – pointer to double variable where the minimal allowed threshold will be returned
  • maxThreshold – pointer to double variable where the maximal allowed threshold will be returned
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

double min, max;<br>
int rc = pxcGetThresholdRange(deviceIndex, &min, &max);<br>
if (rc==0) printf("Threshold range - min: %f, max: %f\n", min, max);<br>
else printf("pxcGetThresholdRange failed, code %d\n", rc);


pxcSetThreshold


This function sets the threshold of the detector in KeV.
Definition
PXCAPI int pxcSetThreshold(unsigned deviceIndex, unsigned thresholdIndex, double threshold);

Parameters

  • deviceIndex - index of the device, starting from zero
  • thresholdIndex - for Timepix and Timepix3 always 0, for Medipix3 index of corresponding threshold starting from zero
  • threshold – detector threshold in keV.
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

Too low thl value cause many noising pixels with all related problems.

Example

int rc = pxcSetThreshold(1, 0, 4.5); // set threshold with idx 0 on device with idx 1 to the 4.5 keV.


pxcGetDAC


This function gets a single DAC value of the detector.
Definition
PXCAPI int pxcGetDAC(unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short* value);

Parameters

  • deviceIndex – index of the device, starting from zero
  • chipIndex – index of the chip, starting from zero
  • dacIndex – index of the DAC, starting from zero
  • value – pointer to output value be stored
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

unsigned short val;<br>
int rc = pxcGetDAC(deviceIndex, chipIndex, dacIndex, &val);<br>
if (rc==0) printf("Input value of DAC with idx %d, on chip with idx %d, of device with idx %d is: %d\n", deviceIndex, chipIndex, dacIndex, val);<br>
else printf("pxcGetDAC failed, code %d\n", rc);


pxcSetDAC


This function sets a single DAC value of the detector.
Definition
PXCAPI int pxcSetDAC(unsigned deviceIndex, unsigned chipIndex, unsigned dacIndex, unsigned short value);

Parameters

  • deviceIndex – index of the device, starting from zero
  • chipIndex – index of the chip, starting from zero
  • dacIndex – index of the DAC, starting from zero
  • value – new DAC value
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

{{{Not}}}

Warning

{{{War}}}

Example

int rc = pxcSetDAC(0, 1, 2, 123); // set DAC with idx 3 on chip with idx 2 on device with idx 1 to the 123.


pxcGetTimepixClock


This function gets the current value of measurement clock for Timepix detector (in MHz).
Definition
PXCAPI int pxcGetTimepixClock(unsigned deviceIndex, double* clock);

Parameters

  • deviceIndex – index of the device, starting from zero
  • clock – pointer to double variable where the clock will be saved
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.

Warning

{{{War}}}

Example

double val;<br>
int rc = pxcGetTimepixClock(deviceIndex, &val);<br>
if (rc==0) printf("Timepix clock: %f MHz\n", val);<br>
else printf("pxcGetTimepixClock failed, code %d\n", rc);


pxcSetTimepixClock


This function sets the value of measurement clock for Timepix detector (in MHz). Not all values are possible, the result will be the closest possible frequency.
Definition
PXCAPI int pxcSetTimepixClock(unsigned deviceIndex, double clock);

Parameters

  • deviceIndex – index of the device, starting from zero
  • clock – desired value of the measurement clock for Timepix detector
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

Only for the Timepix devices, not usable on Timepix3 and other TimepixN. Timepix3 has a fixed clock of 40 MHz. Timepix2 has other clocks managenment.

Warning

{{{War}}}

Example

int rc = pxcSetTimepixClock(deviceIndex, 25.0);


pxcGetTimepixMode


This function gets the current value of the Timepix mode (Counting, Energy,…)
Definition
PXCAPI int pxcGetTimepixMode(unsigned deviceIndex);

Parameters

  • deviceIndex – index of the device, starting from zero
  • {{{2}}}
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
Timepix mode if successful, otherwise the return value is a PXCERR_XXX code.
Timepix mode can be:
PXC_TPX_MODE_MEDIPIX – counting mode
PXC_TPX_MODE_TOT – energy mode
PXC_TPX_MODE_TIMEPIX – timepix mode if successful.
Otherwise the return value is a PXCERR_XXX code.

Note

Only for the Timepix devices, not usable on Timepix3 and other TimepixN.

Warning

{{{War}}}

Example

int rc = pxcGetTimepixMode(deviceIndex);<br>
if (rc>=0) printf("Mode of dev. idx %d is: %d\n", rc);<br>
else printf("pxcGetTimepixMode failed, code %d\n", rc);


pxcSetTimepixMode


This function sets the value of Timepix mode.
Definition
PXCAPI int pxcSetTimepixMode(unsigned deviceIndex, int mode);

Parameters

  • deviceIndex – index of the device, starting from zero
  • mode – new value of the Timepix mode. One of the values:
PXC_TPX_MODE_MEDIPIX – counting mode
PXC_TPX_MODE_TOT – energy mode
PXC_TPX_MODE_TIMEPIX – timepix mode
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

Only for the Timepix devices, not usable on Timepix3 and other TimepixN.

Warning

{{{War}}}

Example

int rc = pxcSetTimepixMode(0, PXC_TPX_MODE_MEDIPIX); // set dev 0 to mode counting alias MEDIPIX


pxcSetTimepixCalibrationEnabled


This function enables or disables the calibration of Timepix ToT counts to energy in keV
Definition
PXCAPI int pxcSetTimepixCalibrationEnabled(unsigned deviceIndex, bool enabled);

Parameters

  • deviceIndex – index of the device, starting from zero
  • enabled – if the calibration is enabled or disable
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Note

Only for the Timepix devices, not usable on Timepix3 and other TimepixN.

Warning

{{{War}}}

Example

int rc = pxcSetTimepixCalibrationEnabled(0, true); // enable ToT calibration to keVs on device with idx 0


pxcIsTimepixCalibrationEnabled


This function returns if the calibration of Timepix ToT counts to energy in keV is enabled.
Definition
PXCAPI int pxcIsTimepixCalibrationEnabled(unsigned deviceIndex);

Parameters

  • deviceIndex – index of the device, starting from zero
  • {{{2}}}
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if disabled, greater than 0 enabled, negative value a PXCERR_XXX code

Note

Only for the Timepix devices, not usable on Timepix3 and other TimepixN.

Warning

{{{War}}}

Example

int rc = pxcIsTimepixCalibrationEnabled(0);<br>
if (rc>=0) printf("Calibration of dev0 is %s\n", (rc==0) ? "disabled" : "enabled");<br>
else printf("pxcIsTimepixCalibrationEnabled failed, code %d\n", rc);



Definition
PXCAPI int ();

Parameters

(no pars)
  • {{{2}}}
  • {{{3}}}
  • {{{4}}}
  • {{{5}}}
  • {{{6}}}
  • {{{7}}}
  • {{{8}}}
Return value
0 if successful, otherwise the return value is a PXCERR_XXX code.

Warning

{{{War}}}


Related

Pixet SDK