| CAEN FERS Library v1.1.4 SDK for FERS systems

Software development

Precondition
  You have to install the library before to start using it. See Installation page for details.

# Compile your project

## Header

In order to use the library, just include the FERSlib.h header in your project:

#include "FERSlib.h"
FERSlib.h
CAEN FERS Library.

## Shared library

### Windows

The Visual Studio FERSlib project is already compiled for x86_64 architecture. The FERSlib.lib is available at `.\ferslib\lib`, and must be added in your Visual Studio project settings. The corresponding shared library `ferslib.dll` is found in the path `.\FERSlib\bin\x64\Release`.

### Linux

By default `libcaenferslib.so` is installed in the system library directory: add the patht to the LD_LIBRARY_PATH and pass `-lcaenferslib` to the linker to use it.

# Develop your software

## Connect to device

To connect to a device, just call the FERS_OpenDevice() that provides the handle to the FERS module:

ret = FERS_OpenDevice(BoardPath, &handle[b]);
FERS_OpenDevice
int FERS_OpenDevice(char *path, int *handle)
Open a device (either FERS board, concentrator or offline)

The Data readout buffers for each connectd board must be initialized manually by calling FERS_InitReadout():

FERS_InitReadout(handle[b], 0, &a1);
FERS_InitReadout
int FERS_InitReadout(int handle, int ROmode, int *AllocatedSize)
Init readout for one board (allocate buffers and initialize variables)

which provides the total allocated memory for the buffers.

Eventually, FERS_CloseReadout() releases all data readout buffers and FERS_CloseDevice() close the connection:

FERS_CloseReadout(handle[b]);
FERS_CloseReadout
int FERS_CloseReadout(int handle)
De-init readoout (free buffers)
FERS_CloseDevice(handle[b]);
FERS_CloseDevice
int FERS_CloseDevice(int handle)
Cloase a device (either FERS board or concentrator)

The `BoardPath` in FERS_OpenDevice must be formed as: `[ConnType]:[Address]`. E.g.: in ethernet connection you can pass the IPv4 address

eth:192.168.50.3 ,

in usb you can use both board PID (i.e. 23475) or progressive enumeration:

usb:0 or usb:23475 ,

in TDlink you pass the DT5215 eth IP, the chain and the node the board is connected, as `eth:[DT5215_IP]:tdl:[CHAIN][NODE]`:

eth:192.168.50.125:tdl:0:1

### Log

The FERSlibLog file is enabled by default and saved in the folder where the .exe is running. User may enable other debug logging by setting the parameter `DebugLogMask` to `<0xVALUE>`, where `<0xVALUE>` can be an OR of the values in DebugLOG.

### Configure

The user can configure the FERS module setting the prameters available in CfgParam both individually by using FERS_SetParam()

FERS_SetParam(handle[b], parname, parvalue);
FERS_SetParam
int FERS_SetParam(int handle, char *param_name, char *value)
Set a parameter by name. The function assigns the value to the relevant parameter in the FERScfg stru...

or by reading a configuration file with FERS_LoadConfigFile()

ret = FERS_LoadConfigFile(cfg_file);
FERS_LoadConfigFile
int FERS_LoadConfigFile(char *filepath)
Loads a configuration file.

The parameters value is saved statically inside the library and can be retrieved with FERS_GetParam()

ret = FERS_GetParam(handle[0], parname, parvalue);
FERS_GetParam
int FERS_GetParam(int handle, char *param_name, char *value)
Get the value of a parameter. The function reads the value from the relevant parameter in the FERScfg...

The board will be configured only after calling FERS_configure()

ret = FERS_configure(handle[b], CFG_HARD);
CFG_HARD
#define CFG_HARD
Configuration Mode.
Definition: FERSlib.h:469
FERS_configure
int FERS_configure(int handle, int mode)
Configures a FERS board.

For debug, both the local parameters value and the board register value can be dump on a file by setting the `DebugLogMask` to the correct Mask in DebugLOG.

### Data acquisition

A run starts after the FERS_StartAcquisition() is called.

The data taken are decoded inside the library and available to the user by FERS_GetEvent()

ret = FERS_GetEvent(handle, &b, &dtq, &tstamp_us, &Event, &nb);
FERS_GetEvent
int FERS_GetEvent(int *handle, int *bindex, int *DataQualifier, double *tstamp_us, void **Event, int *nb)
Read and decode one event from the readout buffers. There are two readout modes: sorted or unsorted....

The event data qualifier `dtq` must be the same set in the `AcquisitionMode` parameter.

The user can cast the read event to the corresponding data type described in DataStructures So the `Event` pointer is converted in a readable format.

## Check last error

In case of error, API functions return a negative value described in FERSLIB_ErrorCodes. Extended information about the last error occurred can be retrieved using FERS_GetLastError():

char emsg[1024];
FERS_GetLastError(emsg);
FERS_GetLastError
int FERS_GetLastError(char description[1024])
Get the last message error of library.

Note
  The message is cleared after a successful call to CAEN_FELib_GetLastError().

For example, it can be used to get a detailed message of a failed call to FERS_OpenDevice():

ret = FERS_OpenDevice(BoardPath, &handle[b]);
if (ret != 0) {
char emsg[1024];
FERS_GetLastError(emsg);
printf("Can't open board: %s (ret=%d)\n", emsg, ret);
}