C/C++ API#

General structures#

enum class maxlab::FilterType#

Enum that represents the possible types of filters that can be selected.

Values:

enumerator FIR#

Default filter in Scope. Latency is roughly 2048 / sampling rate ms.

enumerator IIR#

Latency is roughly 10 / sampling rate ms.

struct FrameInfo#

Information about the state of a data frame.

In particular, the frame-number, the well-id and if the frame is corrupted or not.

Public Members

uint64_t frame_number = 0#

Frame number.

uint8_t well_id = 0#

Well Id on MultiWell devices.

bool corrupted = false#

If frame is corrupted or not. If corrupted, no guarantees on data contained in it.

Status maxlab::sendSequence(const char *sequenceName)#

Function to trigger sending of sequence from mxwserver to the device.

Parameters:

sequenceName – The name of the predefined maxlab.sequence.Sequence with the Python API.

Returns:

Information if call was successful and if not what kind of error happened. Please consult the definition of maxlab::Status for more infos.

enum maxlab::Status#

Enum indicating all possible error codes.

Values:

enumerator MAXLAB_OK#

All good.

enumerator MAXLAB_API_FAIL#

API response was unexpected.

enumerator MAXLAB_NO_SERVER_CONNECTION#

No connection to mxwserver

enumerator MAXLAB_LICENSE_INVALID#

No valid license.

enumerator MAXLAB_API_NO_RESPONSE#

No response from API.

enumerator MAXLAB_STREAM_ALREADY_OPENED#

Trying to open an already open stream for the second time.

enumerator MAXLAB_INCOMPATIBLE_FILTERING#

Not all filtering options are compatible with all streams.

enumerator MAXLAB_INVALID_INPUT#

Arguments passed to function are invalid.

enumerator MAXLAB_STREAM_NOT_OPENED#

Stream is not opened.

enumerator MAXLAB_NO_FRAME#

No data in the stream.

void maxlab::verifyStatus(Status status)#

Function to verify that status is maxlab::Status::MAXLAB_OK.

This function checks if status is ok and otherwise prints the error message to stdcerr and exits the execution with error code 1.

Parameters:

status –

struct SpikeEvent#

Structure used for encoding of a spike occurrence. This structure stores the frame number at which a spike is detected (typically at the maximal value of the spike), the amplitude of that spike and the channel at which this spike was detected.

Public Members

unsigned long frameNo = 0#

8 bytes - Frame number (time point) at which spike is detected.

float amp = 0#

4 bytes - Amplitude of the detected spike.

uint16_t channel = 0#

2 bytes - Channel number at which spike is detected.

unsigned char wellId = 0#

1 byte - Well id where this spike originates.

struct FilteredFrameData#

Structure to store the information obtained from the filtered data stream.

The filtered data stream contains all detected spikes at each individual frame.

Note that there will at most be a 1024 spikes (i.e. the number of readout channels), but there might be less. You thus need to make sure to never access memory that is further offset from the spikeEvents pointer than spikeCount.

Example 

...
FilteredFrameData frame;
DataStreamerFiltered_receiveNextFrame(&frame);
frame.spikeEvents[frame.spikeCount - 1]    // Valid access
frame.spikeEvents[frame.spikeCount]        // Invalid access and undefined behaviour

Public Members

uint64_t spikeCount#

How many spikes were detected, i.e. the length of the spikeEvents array.

const SpikeEvent *spikeEvents#

Pointer to the spikes.

FrameInfo frameInfo#

Information about current frame even if no spikes were detected.

struct RawFrameData#

Structure to store the information obtained from the raw data stream.

Note that there are always exactly 1024 amplitudes (i.e. the number of readout channels).

Example 

...
RawFrameData frame;
DataStreamerRaw_receiveNextFrame(&frame);
frame.amplitudes[frame.amplitudeCount - 1]    // Valid access
frame.amplitudes[frame.amplitudeCount]        // Invalid access and undefined behaviour

Public Members

FrameInfo frameInfo#

For more infos see maxlab::FrameInfo.

const float *amplitudes#

Pointer to the amplitudes array.

Public Static Attributes

static const uint64_t amplitudeCount = 1024#

Fixed size of the amplitudes pointer.

Filtered data#

Status maxlab::DataStreamerFiltered_open(FilterType filterType)#

Crates the connection to the filtered data stream.

It is recommended to use maxlab::verifyStatus to check the return of this function.

Parameters:

filterType – Specify the type of filtering you want. For more information, see maxlab::FilterType.

Returns:

Status of the initialization of the stream. Possible values are:

Status maxlab::DataStreamerFiltered_close()#

Closes the connection to the filtered data stream and restores the state of the mxwserver to the default.

Note that you should ensure to always call this function at end of you experiment and check with maxlab::verifyStatus if the closing worked correctly. If it did not, make sure to restart mxwserver before starting any new runs of doing any experiments in scope.

Returns:

Status of the closure of the stream. Possible values are:

Status maxlab::DataStreamerFiltered_receiveNextFrame(FilteredFrameData *frameData)#

Receive next frame from filtered data stream if there is one.

This function is currently blocking, i.e. it waits to receive data for 1 millisecond, if it takes longer we return maxlab::Status::MAXLAB_NO_FRAME, otherwise maxlab::Status::MAXLAB_OK.

If you receive maxlab::Status::MAXLAB_NO_FRAME it means that something is wrong (dropped frames, corrupted frames, etc.).

Parameters:

frameData – Buffer in which data can be written into.

Returns:

Status of the receiving operation. Possible values are:

Status maxlab::DataStreamerFiltered_setFilterType(FilterType filterType)#

Allows the change of filter-type while keeping the data stream open.

Parameters:

filterType – Filter type, for more information see maxlab::FilterType.

Returns:

Status of the operation. Possible values are:

FilterType maxlab::DataStreamerFiltered_getFilterType()#

Get currently set filter type.

Returns:

Filter type, for more infos, see maxlab::FilterType.

Raw data#

Status maxlab::DataStreamerRaw_open()#

Crates the connection to the raw data stream.

It is recommended to use maxlab::verifyStatus to check the return of this function.

Returns:

Status of the initialization of the stream. Possible values are:

Status maxlab::DataStreamerRaw_close()#

Closes the connection to the raw data stream and restores the state of the mxwserver to the default.

Note that you should ensure to always call this function at end of you experiment and check with maxlab::verifyStatus if the closing worked correctly. If it did not, make sure to restart mxwserver before starting any new runs of doing any experiments in scope.

Returns:

Status of the closure of the stream. Possible values are:

Status maxlab::DataStreamerRaw_receiveNextFrame(RawFrameData *frameData)#

Receive next frame from filtered data stream if there is one.

This function is currently blocking, i.e. it waits to receive data for 1 millisecond, if it takes longer we return maxlab::Status::MAXLAB_NO_FRAME, otherwise maxlab::Status::MAXLAB_OK.

If you receive maxlab::Status::MAXLAB_NO_FRAME it means that something is wrong (dropped frames, corrupted frames, etc.).

Parameters:

frameData – Buffer in which data can be written into.

Returns:

Status of the receiving operation. Possible values are: