DEVELOPMENT.md

Go to the documentation of this file.

# Software development{#development}
\tableofcontents

\pre You have to install the library before to start using it. See \ref install page for details.

# Compile your project
In order to use the library, just include the CAENMCA.h header in your project:
\snippet examples.h IncludeHeader

To link your code with the library, the instructions depends on your operating system

## Linux
By default the installer puts libraries and headers into the system folders.
To use the library into your project, just add the parameter `-lCAENMCA` to the linker. For example:

``` bash
$ gcc mytest.c -lCAENMCA -o mytest
```

### Examples
An example make project is included in the source directory, under `<sourcedir>/MCALibTest`.
To get started, you may try to build it:

``` bash
$ cd <sourcedir>/MCALibTest
$ make -j3
$ ./bin/MCALibTest eth://127.0.0.1/
```

## Windows
By default the installer puts DLL files into the system folders. You may find a copy also into
your install directory, at `<installdir>/lib`.
To use the library into your project, just add the following stuff into your Visual Studio
project C/C++ properties:
* **Additional Include Directories**: `CAENMCA.h` path (by default `<installdir>/include`)

and this into the Linker properties:
* **Additional Library Directories**: `CAENMCA.lib` path (by default `<installdir>/lib/<platform>`)
* **Additional Dependencies**: `CAENMCA.lib`

### Examples
An example Visual Studio project is included in the install directory, under `<installdir>\MCALibTest`.
To get started, you may try to copy it to your user directory, and open it in Visual Studio.

\attention The path settings of the example project have been set relative to the installer default path
`C:\Program Files\CAEN\Digitizers\CAENMCA`. In case you have chosen a different location, you have to
adjust the Visual Studio project accordingly.

# Connect a device
The connection with a device in your network is established using CAEN_MCA_OpenDevice().
The function returns an handle that can be used later to interact with the system.
For example, this connects to a local instance of the Hexagon Server:
\snippet examples_board_control.c OpenDevice

Eventually, the connection should be closed by CAEN_MCA_CloseDevice(). This also free all the allocated memory:
\snippet examples_board_control.c CloseDevice

You can connect only once per device:
\startuml
    Client   ->           Device1:   CAEN_MCA_OpenDevice(...)
    Device1  --[#blue]>   Client:    Ok
    ...
    Client   ->           Device2:   CAEN_MCA_OpenDevice(...)
    Device2  --[#blue]>   Client:    Ok
    ...
    Client   ->           Device1:   CAEN_MCA_OpenDevice(...)
    Device1  --[#red]>x   Client:    Fail: no reply
    ...
    Client   ->           Device1:   CAEN_MCA_CloseDevice(...)
    Device1  --[#blue]>   Client:    Ok
    Client   ->           Device1:   CAEN_MCA_OpenDevice(...)
    Device1  --[#blue]>   Client:    Ok
\enduml

# Handles{#handles}
From [Handle](https://en.wikipedia.org/wiki/Handle_(computing)) article on Wikipedia:
> In computer programming, a handle is an abstract reference to a resource.
> Handles are used when application software references blocks of memory or objects managed
> by another system [...]. A resource handle [...]
> can be a pointer that allows access to further information.

In this library, handles are pointers to instances of abstract data types.
In a object-oriented programming analogy, they can be seen just as pointers to objects
a certain class.

Several types of handle exist, represented by the following class diagram:

\anchor handle-class-diagram
\startuml
    LIBRARY *-- DEVICE
    DEVICE *-- CHANNEL
    DEVICE *-- HVCHANNEL
    DEVICE *-- PARAMETER
    DEVICE *-- LVDSGROUP
    DEVICE *-- TRACE
    DEVICE *-- MONOUT
   DEVICE *-- DTSPECTRUM
    CHANNEL *-- PARAMETER
    CHANNEL *-- ENERGYSPECTRUM
    CHANNEL *-- MCSSPECTRUM
    HVCHANNEL *-- HVRANGE
    HVCHANNEL *-- PARAMETER
    HVRANGE *-- PARAMETER
    LVDSGROUP *-- PARAMETER
    TRACE *-- PARAMETER
    PARAMETER *-- PARAMETER
    ENERGYSPECTRUM *-- ROI
    ENERGYSPECTRUM *-- PARAMETER
    MCSSPECTRUM *-- PARAMETER
    ROI *-- PARAMETER
    MONOUT *-- PARAMETER
   DTSPECTRUM *-- PARAMETER
\enduml

## Children
The function CAEN_MCA_GetChildHandle() can be used to get handles to child objects, given a handle.
The only exception is to get the library handle, when no input handle is needed as first parameter,
and the index can be any number:
\snippet examples_handles.c Library

The handle of the device is returned by CAEN_MCA_OpenDevice(). Additionally, with the index returned by
by the last argument of that function it is possible to get the same handle using CAEN_MCA_GetChildHandle()
with the library as first argument.
Anyway, the first opened device has always index 0:
\snippet examples_handles.c Device

CAEN_MCA_GetChildHandle() can be used only for children, and not for other descendants. For example,
it is possible to get the channel handles from the device handle:
\snippet examples_handles.c GetHandle

but not from the library handle:
\snippet examples_handles.c GetHandleInvalid

For parameters, a convenient function CAEN_MCA_GetChildHandleByName() is provided, which can be used with a string
instead of a numeric index. It is implemented using hash tables, and the performances are almost identical.
Numeric indexes of parameters exist but are not published.

For example, we can get a handle to the parameter "PARAM_CH_THRESHOLD" of the Channel 0:
\snippet examples_handles.c GetHandleByName1

Note that CAEN_MCA_GetChildHandleByName() can be used also for other handle types
(except for ::CAEN_MCA_HANDLE_COLLECTION). In these cases, the index is just the literal version of the index,
except for ::CAEN_MCA_HANDLE_DEVICE, where it represents the hostname used in CAEN_MCA_OpenDevice():
\snippet examples_handles.c GetHandleByName2

## Ancestors
The function CAEN_MCA_GetAncestorHandle() can be used to get the the handle of an ancestor of the provided handle.
For example, we can get the Channel 0 handle from a parameter of the Channel 0, as well as the device handle:
\snippet examples_handles.c GetAncestorHandle1

In case no ancestor of the requested type are found, the function returns NULL:
\snippet examples_handles.c GetAncestorHandle2

# Data and Commands
Data retrieve from MCA is managed using the functions CAEN_MCA_SetData() (or its `va_list` version
CAEN_MCA_SetDataV()) and CAEN_MCA_GetData() (or its `va_list` version CAEN_MCA_GetDataV()).
The expected arguments are:
* first argument is a ::CAEN_MCA_HANDLE on which to execute the call
* second argument is an integer representing the requested type (see ::CAEN_MCA_DataType_t)
* the third argument is a 64-bit mask, with bit-meaning depending on the selected type (see \ref DataMask)
* variadic arguments, one for each bit selected in the mask.

Similarly to Data related functions, Commands are managed using the function CAEN_MCA_SendCommand()
(or its `va_list` version CAEN_MCA_SendCommandV()).
The expected arguments are:
* first argument is a ::CAEN_MCA_HANDLE on which to execute the call
* second argument is an integer representing the requested type (see ::CAEN_MCA_CommandType_t)
* the third argument is a 64-bit mask for input data, with bit-meaning depending on the selected type (see \ref CommandMask)
* the forth argument is a 64-bit mask for output data, with bit-meaning depending on the selected type (see \ref CommandMask)
* variadic arguments, one for each bit selected first in the input data mask, and then in the output data mask.

## Variadic argument order{#variadic-argument-order}
The order of the variadic arguments is specified by the order of the value of its relative mask.
For example, if the mask sets the bits with `mask = (MASK_A | MASK_B)`, where `MASK_A = 0x1`
and `MASK_B = 0x4` then you must append the variable relative to `MASK_A` first, and then the
one relative to `MASK_B`. Note that since the bitwise-OR operator is commutative, the order
in which you specify the bits of the mask does not matter at all, like in this example:
\snippet examples_board_control.c WrongOrder

## Variadic argument type{#variadic-argument-type}
The type of the variadic arguments is specified in the mask documentation: it is the type to be used
by CAEN_MCA_SetData(). In CAEN_MCA_GetData() functions, you have to pass **a pointer** to allocated memory
of that type (except for arrays).

In this examples, the same data #DATAMASK_VALUE_NUMERIC of ::CAEN_MCA_DATA_PARAMETER_VALUE
is used both with CAEN_MCA_SetData() and CAEN_MCA_GetData(). As reported in the relative documentation,
that data requires a `double` variable as argument. In the first case, pass just the variable as argument:
\snippet examples_parameters.c SetValue

In the second case, pass a pointer where to store the result:
\snippet examples_parameters.c GetValue

# Examples

## Handle collections
A special case of handles is represented by the collections. Collections are "transparent" elements of the class diagram
tree shown in the \ref handle-class-diagram "Handle class diagram". Each object has a collection for every type of
child, and every child is contained in the relative collections.
For example, the handles of type ::CAEN_MCA_HANDLE_HVCHANNEL are contained in a special collection belonging
to the handle of type ::CAEN_MCA_HANDLE_DEVICE:
\snippet examples_handles.c GetCollection

The array containing the handles of the collection, as well as its length, can be obtained
in this way:
\snippet examples_parameters.c GetCollectionInfo

## Acquisition control
To start acquisition:
\snippet examples_acquisition_control.c StartAcquisition

To stop acquisition:
\snippet examples_acquisition_control.c StopAcquisition

where `handle` can be either a device handle or a channel handle.

To set an automatic stop criteria, set the following four parameters
(if the parameter is set to zero, the stop criteria is disabled):
\snippet examples_acquisition_control.c SetStopCriteria

## HV control
To set status:
\snippet examples_hv.c SetStatus

or, alternatively:
\snippet examples_hv.c SetStatusAlternative

To get status:
\snippet examples_hv.c GetOnOff

To get extended status bitmask:
\snippet examples_hv.c GetStatus

where the meaning of each bit can be printed in this way:
\snippet examples_hv.c StatusMask

To get the active range:
\snippet examples_hv.c GetActiveRange

Once we have the active range, monitor parameters like VMon can be read:
\snippet examples_hv.c GetVMon

Note that monitor parameters can be accessed only from the currently active range.
To get information about the other ranges, get the handle of a range:
\snippet examples_hv.c GetHandle

then, use ::CAEN_MCA_DATA_HVRANGE_INFO:
\snippet examples_hv.c GetInfo

## Parameters
Parameters are values that can be set at runtime to change the behaviour and
the state of the device. The full list of the supported parameters, grouped by handle,
can be found at \ref parameters.

The list of supported parameter of a given handle can be retrieved also at runtime:
\snippet examples_parameters.c GetSupportedParameters

To get a parameter handle given its codename:
\snippet examples_parameters.c GetHandle

To get extended parameter information:
\snippet examples_parameters.c GetInfo

To get the value of parameters with type ::CAEN_MCA_PARAMETER_TYPE_RANGE:
\snippet examples_parameters.c GetValue

To set the value of parameters with type ::CAEN_MCA_PARAMETER_TYPE_RANGE:
\snippet examples_parameters.c SetValue

To get the value of parameters with type ::CAEN_MCA_PARAMETER_TYPE_LIST:
\snippet examples_parameters.c GetValueList
\note You do not have to pass a pointer to an array, but just the array!

To set the value of parameters with type ::CAEN_MCA_PARAMETER_TYPE_LIST:
\snippet examples_parameters.c SetValueList

## Save, load and delete configurations
Save the current configuration:
\snippet examples_board_control.c SaveConfiguration

Load a saved configuration:
\snippet examples_board_control.c LoadConfiguration

Delete a saved configuration:
\snippet examples_board_control.c DeleteConfiguration

Change configurations database path:
\snippet examples_board_control.c DatabasePath
NOTE: the change is not persistent, you need to set path every time the
library is reloaded. The previous database is left unchanged and not
copied to the new location.

## Registers
Read the value of a register:
\snippet examples_board_control.c ReadRegister

## Energy Spectra and ROIs
Get a spectrum handle:
\snippet examples_spectrum.c GetHandle

Get an energy spectrum:
\snippet examples_spectrum.c GetSpectrum

Set the number of bins:
\snippet examples_spectrum.c SetNBins

Spectra are saved at stop and periodically during the run. Set the auto-save period (the default is 5 seconds):
\snippet examples_spectrum.c SetPeriod

Set the remote filename where to save che spectrum:
\snippet examples_spectrum.c SetFilename

Get a ROI handle:
\snippet examples_roi.c GetHandle

Get the entries in a ROI:
\snippet examples_roi.c GetROI

Set range of a ROI:
\snippet examples_roi.c SetLow
\snippet examples_roi.c SetHigh

Clear a spectrum and its ROIs:
\snippet examples_spectrum.c ClearSpectrum

The gain stabilization can be enabled for the energy spectrum in order to compensate for possible temperature variation effects.

Enable/Disable the gain stabilizer:
\snippet examples_spectrum.c GSEnableDisable

Set the ROI used by the gain stabilizer (this ROI defines the stabilization peak):
\snippet examples_spectrum.c GSSetLow
\snippet examples_spectrum.c GSSetHigh

Set the update time for the gain stabilizer:
\snippet examples_spectrum.c GSSetTime

Reset the gain stabilizer:
\snippet examples_spectrum.c GSReset

## Enable and get waveforms
Enable waveforms:
\snippet examples_waveforms.c EnableWaveforms

Get waveforms:
\snippet examples_waveforms.c GetWaveforms

## MCS Spectra

Get a MCS spectrum handle:
\snippet examples_mcs.c GetHandle

Get a MCS spectrum:
\snippet examples_mcs.c GetSpectrum

Set the number of bins:
\snippet examples_mcs.c SetNBins

Set the dwell time:
\snippet examples_mcs.c SetDwell

Set the MCS counting mode (MCS on ICR, MCS on Ext.Signal, MCS on SCA):
\snippet examples_mcs.c SetMode

Set the MCS acquisition mode:
MCS REPLACE (replace bin contents after a sweep), MCS SUM (sum bin contents after a sweep), MCS REPLACE AND SUM (replace bin contents after first sweep, then sum) 
\snippet examples_mcs.c SetAcqMode

Enable/Disable hardware and software Dwell
\snippet examples_mcs.c EnableDisableDS
\snippet examples_mcs.c EnableDisableDH

Enable/Disable hardware and software Sweep
\snippet examples_mcs.c EnableDisableSS
\snippet examples_mcs.c EnableDisableSH

Clear a MCS spectrum:
\snippet examples_mcs.c Clear

Send a Sweep command to a MCS spectrum:
\snippet examples_mcs.c Sweep

## DT Spectra

### Introduction
This tool can be used to find the best values for the coincidence parameters (coincidence window length and coincidence delay), in order to configure the board channels to work in coincidence/anticoincidence mode.
When the DT spectrum is enabled, it is filled with the time difference DT between the timestamps of the events collected by the board channels. 
The plot is always centered in DT = 0 and its range is given by [-(Nbins/2 * DTstep), Nbins/2 * DTstep], where Nbins is the number of bins and DTstep is the time value corresponding to a single bin.

Set the number of DT spectrum bins:
\snippet examples_dt_spectrum.c DTSetNBins

Set the time interval for the DT spectrum:
\snippet examples_dt_spectrum.c DTSetTStep

Before enabling the DT spectrum, the user should set the reference channel for DT calculations:
\snippet examples_dt_spectrum.c DTSetRefCh

Enable the coincidence mode for both channels and set a big value for the coincidence window length:
\snippet examples_dt_spectrum.c DTEnableDisable

How to read the DT spectrum from the board:
\snippet examples_dt_spectrum.c DTSpectrumGet

Clear the DT spectrum:
\snippet examples_dt_spectrum.c ClearDTSpectrum

## List mode

### Introduction
This feature can be used to get a list of the events, or save it to a remote file.
An event is made of:
* timetag (in picoseconds since acquisition start)
* energy (in bins)
* a set of flags (\ref ListEventFlagsMask)

Three buffers (one per each type of data) are allocated on acquisition start with size ::DATAMASK_LIST_MAXNEVTS.
When the buffers have been filled, behaviour depends on the selected mode:
* ::CAEN_MCA_SAVEMODE_FILE_ASCII: events are written to a file in the ASCII format and buffers reset
* ::CAEN_MCA_SAVEMODE_FILE_BINARY: events are written to a file in the binary format and buffers reset
* ::CAEN_MCA_SAVEMODE_MEMORY: nothing is done until a buffer reset occurs (i.e. buffers not reset)

A reset occurs as soon as you call ::CAEN_MCA_DATA_LIST_MODE on CAEN_MCA_GetData() to get any of:
* ::DATAMASK_LIST_DATA_TIMETAG
* ::DATAMASK_LIST_DATA_ENERGY
* ::DATAMASK_LIST_DATA_FLAGS_DATAMASK

At stop, events in the buffer are written to file (if in file mode) and then freed.

A new acquisition will overwrite the existing file if the filename is not changed.

### Control
Enable or disable list mode:
\snippet examples_lists.c Enable

Set the save mode:
\snippet examples_lists.c SetMode

In case of save mode set to ::CAEN_MCA_SAVEMODE_FILE_ASCII or ::CAEN_MCA_SAVEMODE_FILE_BINARY,
this set the data to save into the remote file:
\snippet examples_lists.c SetData

Set the maximum number of events to store in the server internal buffers:
\snippet examples_lists.c SetMaxNEvts

This is an example to get and parse lists:
\snippet examples_lists.c GetLists

## Discover devices on the newtork
Find Hexagon devices on your network, a special command::CAEN_MCA_DATA_DISCOVEREDDEVICES
on CAEN_MCA_GetData() is provided:
\snippet examples_discovery.c DiscoverDevices