Overview

Welcome to the LabAmp Parameter Tree documentation. The parameter tree represents all publicly available device settings structured in hierarchical order. These parameters are stored in the device parameter database.

The parameter name corresponds to its full path starting with the root path "/".

To change any of these settings please use the Parameter API. If a setting is not valid, a corresponding error will be returned.

Parameter properties min, max and enum can be accessed using this notation: <parameter-name>.<property-name>

To restore a device to its factory settings, please use the factory reset functionality in the user interface, via the factory reset API or by pressing the factory reset button on the back of the device.

If a parameter is channel dependent, the channel number is generally part of its name. In this document, a channel number placeholder {channel} is then used in the parameter name.

Database Information

This subtree contains all the relevant parameters concerning the database itself.

Device Information

This subtree contains all general device and version information.

Device Setup

This subtree contains all general device settings.

General parameters

Current IPv4 Settings

IPv4 Static Settings

Clock

Calibration

This subtree contains values related to calibration. All of these values are read-only.

Input Channel Settings

This subtree contains all parameters affecting the input channels. This includes sensor parameters and filters.

NOTE: $(channel) is value from (default:1) to 4.

Type

This subtree splits the sensor parameters according to the selected sensor type.

NOTE: $(channel) is value from (default:1) to 4.

Charge

Subtree containing all charge sensor parameters.

NOTE: $(channel) is value from (default:1) to 4.

IEPE

Subtree containing all IEPE sensor parameters.

NOTE: $(channel) is value from (default:1) to 4.

Voltage

Subtree containing all voltage sensor parameters.

NOTE: $(channel) is value from (default:1) to 4.

Filters

This subtree contains all filter parameters

NOTE: $(channel) is value from (default:1) to 4.

Low Pass Filter

This subtree contains all low pass filter parameters.

NOTE: $(channel) is value from (default:1) to 4.

High Pass Filter

This subtree contains all high pass filter parameters.

NOTE: $(channel) is value from (default:1) to 4.

Notch Filter

This subtree contains all notch filter parameters.

NOTE: $(channel) is value from (default:1) to 4.

Signal Mode

This subtree contains all parameters concerning Signal Mode.

NOTE: $(channel) is value from (default:1) to 4.

Virtual Channels

This subtree contains Virtual Channel settings.

NOTE: $(ch) is value from (default:1) to 2.

Generic Summation

This subtree contains settings related to the Generic Summation mode of Virtual Channels.

NOTE: $(ch) is value from (default:1) to 2.

NOTE: $(measCh) is value from (default:1) to 4.

Virtual Channel Integrator Settings

This subtree contains settings related to the Virtual Channel integrators.

NOTE: $(ch) is value from (default:1) to 2.

NOTE: $(N) is value from {1;2}.

Acceleration Compensation

This subtree contains settings related to the Accleration Compensation mode of Virtual Channels. Note that this tree can not be modified on the 5165A1 device.

NOTE: $(ch) is value from (default:1) to 2.

Signal Mode

This subtree contains all parameters concerning Virtual Channels' Signal Mode.

NOTE: $(ch) is value from (default:1) to 2.

Virtual Channel DAQ settings

This subtree contains Virtual Channel DAQ related settings.

NOTE: $(ch) is value from (default:1) to 2.

Data Acquisition (DAQ)

This subtree contains all data acquisition relevant parameters.

Recorder general settings

Recorder specific settings

This subtree contains settings related to the Recorder feature of the device.

NOTE: $(_measurementID) is value from 1 (default:1) to 1.

Signal Event Monitor - Measurement Channels

This subtree contains all parameters relevant for monitoring events from FPGA for measurement channels.

NOTE: $(thresholdCount) is value from (default:1) to 2.

NOTE: $(channel) is value from (default:1) to 4.

Signal Event Monitor - Virtual Channels

This subtree contains all parameters relevant for monitoring events from FPGA for virtual channels.

NOTE: $(thresholdCount) is value from (default:1) to 2.

NOTE: $(channel) is value from (default:1) to 2.

Analog Output

This subtree contains all parameters relevant to the analog output.

NOTE: $(channel) is value from (default:1) to 4.

Units

Following is a list of units supported by the LabAmp. The unit value is always string and exactly in the string format listed below. They are used for the Range and Sensitivity unit parameters. As the Sensitivity parameter uses a combined unit, the following notation needs to be used: <numerator-unit>/<denominator-unit> e.g. mV/kN This notation needs to be used when setting a custom sensorUnit value, not in the list. For Voltage sensor-type V/, for Charge sensor-type pC/, and for IEPE sensor-type mV/ or V/ nominator needs to be used.

_{Version: 1.2.2
Author: Gyorgy Sarvari (SGY)
Date: 22.03.2017}

• Introduction
• Acquired Data streaming (DAQ streaming)
  • Channel configuration for DAQ streaming
  • Measurement configuration
    • Measurement startTrigger
    • Measurement stopTrigger
    • Measurement signalProvider
    • Measurement pre- and postTrigger
    • Enabling measurement
      • Streaming Client Registration
      • Opening a stream
    • Specifying a port
    • Specifying scansPerFrame
      • Receiving the stream
      • Starting and stopping the measurement
      • Closing the stream
      • Unregistering the client
      • Processing the acquired data
    • Frame header
    • Event-frame
    • Data-frame
• Data Recorder
  • Overview
  • RecordSet
  • Measurement configuration
  • Starting the Data Recorder
    • Record Name
    • Repetitions
  • Starting and stopping a measurement
  • Stopping the Data Recorder
  • Exporting and processing the data
  • Data Recorder States
• Signal Monitor
  • Configuration
• Time settings
  • Setting the time manually
  • NTP synchronisation
  • PTP synchronisation

Introduction

In this document you can find information about the advanced features of your LabAmp device, along with some examples.

Acquired Data streaming (DAQ streaming)

The LabAmp 5165A.. devices provide the powerful feature of digitalizing the acquired data with high sampling rate and high precision and providing it to the user via DAQ streaming. In this section you can find information on this feature.

On high level the process of using DAQ streaming is the following:

• configuration of the requested channel(s)
• configuration of measurement
• registering a streaming client
• associating the measurement with the stream, and opening a port on the LabAmp device to start the stream
• opening the port on the client computer to receive the streamed data
• starting the measurement
• stopping the measurement
• closing the stream
• unregistering the streaming client
• processing the acquired data

Below you can find more detailed information of these steps.

Channel configuration for DAQ streaming

The requested channels can be configured through the web-based UI or using the /api/param REST API services. See details of channel configuration in the general User Manual. It is crucial to set correct values for sensor type, sensitivity and measurement ranges for the channels in order to obtain sensible data during data acquisition.

You can find information about enabling channels for DAQ in the User Manual also. On the 5165A1 device it is possible to enable maximum 2, and on the 5165A4 device to enable maximum 4 physical sensors and/or virtual channels for DAQ streaming. Physical measurement- and virtual-channels can be enabled in any arbitrary combination.

Measurement configuration

A measurement is a set of measured signal levels during the period of between a measurement start-trigger and measurement stop-trigger. The measurement can be configured using the relevant /api/daq/measurement REST API services (see REST API documentation). Note that while the parameter tree contains these settings, it is adviced to use the REST API service to change measurement configuration instead if changing the parameters directly due to their complex nature. The 5165A.. devices provide 1 measurement to configure at a time. The measurement need to be configured before opening the stream associated with the measurement. Configuring the measurement while streaming actively might result in an error in the data stream, and the stream might be terminated.

Measurement startTrigger

Measurement startTrigger can have the following values:

• request: the measurement will start when a POST request is received by the device on the /api/daq/measurement/start REST API service. (See REST API documentation)
• time: the measurement will start at a specified time. When specifying this trigger, the starting UNIX timestamp needs to be provided during the configuration in second.nanosecond form. See also the Time settings section of this guide.
• event: measurements can be started using an event provided by the 5165A.. devices' Signal Monitor feature. When specifying this trigger, the event name needs to be provided during the configuration, in the following format:

  skybase.sigmon.threshold-[THRESHOLD_NR]_[meas|virt]-[CHANNEL_NR]_[falling|rising]

where

For further information about the Signal Monitor see the Signal Monitor section of this guide.

Measurement stopTrigger

Measurement stopTriggers can have the same values as the startTriggers, and an extra one:

• duration: the measurement will stop “duration” nanoseconds after the startTrigger has fired. When specifying this stopTrigger the duration needs to be provided in nanoseconds during the configuration.

Specifying the measurement stopTrigger is mandatory.

Measurement signalProvider

The measurement signalProvider needs to be set to the static string value of “daq-provider”.

Measurement pre- and postTrigger

Using pre- and postTrigger attributes it is possible to acquire data also from a period before and/or after the start/stopTrigger would fire. The pre- and postTriggers need to be specified in nanoseconds. If not specified during configuration, the factory default 0 value is used.

Note that when using preTrigger attribute, only a limited amount of data can be obtained before the startTrigger would fire. The period that can be set as the preTrigger value depends on the configured sampling rate (the lower the sampling rate, the higher this value can be). If the preTrigger value would result in more than that can be provided by the device, the maximum possible amount of data will be provided from before the startTrigger would fire, but this period might be shorter than the specified period. No such restrictions apply to postTriggers.

Enabling measurement

The measurement needs to be enabled to use it with DAQ streaming or with the Recorder feature. Disabled measurements do not listen to start- and stopTriggers. See REST API documentation on enabling the measurement.

Measurement configuration should be applied only while the measurement is in disabled state. Configurations applied while the measurement is enabled will not take effect.

Streaming Client Registration

Before starting DAQ streaming from the 5165A.. device, a streaming client needs to be registered (see /api/daq/stream/register in REST API documentation). This will provide a unique clientId that needs to be used in the subsequent requests related to this client. It is possible to have multiple clients registered concurrently. Note that in case a clientId is not used for 60 minutes, it will be unregistered automatically.

Restarting the device will erase all previously registered streaming clients.

Opening a stream

Before connecting to a stream from the client computer, a streaming port needs to be opened on the 5165A.. device, and the measurement needs to be associated with the stream. (See /api/daq/stream/open REST API documentation). It is possible to open maximum 3 streams concurrently.

Specifying a port

It is possible to specify a port to open on the 5165A.. device for the stream. If no port is specified, or the requested port could not be opened, a random port is opened. In the response, the opened port number is always returned. Specifying the port number is optional.

Specifying scansPerFrame

It is possible to specify the number of scans received in a frame (see also “Processing the data” section of this guide) when opening a stream. If the value is not specified, the default value is used that depends on the current sampling rate. You can query the current number of scans received in a frame using the /api/daq/stream/scansperframe REST API service while a stream is in progress.

The default values are the following:

Note that it is possible to set the scansPerFrame values only higher than the default values, not lower. If the requested scansPerFrame value is too high, an error message is returned, and the stream is not opened.

Receiving the stream

After opening a stream, and receiving a port number that was opened on the 5165A.. device, the client computer needs to connect to this port using a TCP socket connection. If the port is not connected within 30 seconds after the port was opened, the port will be closed, and the stream will have to be opened again.

Note the network bandwidth requirements of high speed DAQ streaming. Each signal-level scan requires 4 bytes of data. When using DAQ streaming from one device with 4 channels enabled, using 200.000 Hz sampling rate, the required network bandwidth is 200.000 Hz x 4 channels x 4 bytes + frame header overhead ~ 40 Mbps. You can apply the above formula to your settings to get an estimation of the network bandwidth requirements for DAQ streaming.

The 5165A.. device comes with a dual port 10/100 Mbps Ethernet interface, that needs to be taken into consideration also when using DAQ streaming from multiple daisy-chained devices concurrently.

Starting and stopping the measurement

The device will start streaming binary data through the opened port after the associated measurement's startTrigger has fired. It is possible to start a measurement even before the stream would be connected, however in this case the data measured before the connection of the stream will be lost. If a startTrigger is fired without any stopTrigger between them, only the first startTrigger takes effect, the subsequent ones will be ignored. The same is true for the stopTrigger: if the stopTrigger event is received while the measurement is stopped already, it has no effect.

It is possible to repeat measurements using the same stream with firing alternating start- and stopTriggers. For example if the startTrigger is set to Signal Monitor event - rising edge, and the stopTrigger is set to duration with a value that equals to 1 second, then it is possible to receive multiple 1 second long data sections.

Note that reconfiguring the measurement triggers while streaming will terminate the stream.

Closing the stream

After the measurements are over, the stream needs to be closed on the device using the /api/daq/stream/close REST API service (see REST API documentation). After issuing the request the port will be closed on the device after all relevant data frames were flushed to the client computer, and the appropriate event frame will be inserted to the data stream (see “Processing the data” section).

Note that closing the stream on the client computer might lead to the corruption of the acquired data if done before the port would be closed on the 5165A.. device.

If the client disconnects from the port without closing the port on the LabAmp device, the port will be closed automatically immediately. It is not possible to reconnect to the same stream, it is necessary to open a new stream to continue acquiring data.

Unregistering the client

After all measurements are done, all streams closed, and the client is not necessary anymore, it is advised to unregister the client using the /api/daq/stream/unregister REST API service (see REST API documentation). If there are too many registered clients at the same time, registering new clients might not be possible until some clients are unregistered (either using the REST API service, or by waiting until the device deletes the unused clients).

Processing the acquired data

The acquired data is in binary form, that needs to be transformed programmatically to interpret it. In this section the format of the binary data is described.

The acquired data uses standard C data types, making it easy to parse with various programming languages.

The binary data consists of a series of frames. Frames contain a frame-header, and a sub-frame. There are two types of sub-frames: data-frame and event-frame. There is no padding between the elements of the frames, nor between frames.

Frame header

The basic structure of the frame header is the following:

Version: 2 bytes, unsigned short. The version of the data structure. In the current software version this value is always “1”.

Type: 2 bytes, unsigned short. The type of the current frame. Possible values:

• 0 – in case the sub-frame is an event-frame, containing a stream related event description.
• 1 – in case the sub-frame is a data-frame, containing signal-level values

Size: 4 bytes, unsigned int. The size of the whole frame in bytes, including the header and the subframe.

Sequence number: 4 bytes, unsigned int. The sequence number of the frame in the stream. The value of this field is incremented by one in each frame.

Measurement ID: 2 bytes, unsigned short. This is the ID of measurement associated with the stream and the frame. The value of this field is 1 on the 5165A.. devices.

SubType: 2 bytes, unsigned short. In case the Type of the current frame is 0 (see above) the value of this field is 0, indicating that a simple event description is contained in the sub-frame. In case the Type of the current frame is 1 (see above), the value of the SubType field is 1, indicating that the data-frame contains a UNIX timestamp.

Event-frame

The basic structure of the event-frames is the following:

Level: 1 byte, unsigned char. The level of urgency of the event. Possible values:

Facility: 1 byte, unsigned char. Value is always 0.

Code: 2 bytes, unsigned short. The code of the event. Possible values are:

Data-frame

The basic structure of the data-frames is the following:

Timestamp (second): 8 bytes, unsigned long long. The second part of the Unix timestamp of the first scan in the data-frame.

Timestamp (nanosecond): 4 bytes, unsigned int. The nanosecond part of the Unix timestamp of the first scan in the data-frame. Note that these timestamps are absolute timestamps, based on the system time of the device (see “Time settings” section of this document).

Data: 4 bytes, float. The measured signal level. The number of data fields in a frame equals the number of channels enabled for DAQ streaming multiplied by the value of scans per frame value (see above, “Opening a stream” section).

The order of the sensors in the data fields and their datatype can be obtained from the /api/daq/measurement/metadata/get REST API service. The response contains the offset of the separate channels. As an example in case measChannel3, measChannel4, and virtChannel2 are enabled, the following response might be returned by the REST API service:

{
    "result": 0,
    "metadata": {
        "version": "1.0",
        "measurement": {
            "measurementId": 1,
            "signalProvider": {
                "name": "daq-provider",
                "samplingRate": 2500.0,
                "signals": [{
                    "name": "Kistler Force Sensor",
                    "source": "Sensor-3",
                    "unit": "N",
                    "offset": 0,
                    "dataType": "FLOAT32"
                }, {
                    "name": "Kistler Acceleration Sensor",
                    "source": "Sensor-4",
                    "unit": "g",
                    "offset": 4,
                    "dataType": "FLOAT32"
                }, {
                    "name": "Combination of Sensors",
                    "source": "Virtual-Channel-2",
                    "unit": "N",
                    "offset": 8,
                    "dataType": "FLOAT32"
                }]
            }
        }
    }
}

The offset attribute of the channels shows the offset of the data in this frame, in bytes. In this example the offset of Sensor-3 is 0, meaning the Data 0 contains a measurement from this sensor. The offset of Sensor-4 is 4, so the second Data field in the frame, Data 1 contains a measurement from Sensor-4. Data 2 contains a measurement of Virtual-Channel-2 (that has an offset of 8, compared to the start of the scan). After this it starts over again: the next Data field contains a signal-level measurement of Sensor-3 again, then Sensor-4, Virtual-Channel-2, and so on.

One scan is the group of signal-levels measured on all sensors enabled for DAQ, at a given time. In the above example one scan consists of a reading from Sensor-3, Sensor-4 and Virtual-Channel-2. The next group of readings is the next scan. The number of datafields in the data-frame is

“number of enabled channels” x “scans per frame”.

The Frames contain only one timestamp, the timestamp of the very first scan in the frame. The timestamp of the following scans in the frame can be calculated easily based on the sampling rate used for acquiring the data.

Data Recorder

The Data Recorder feature provided by the 5165A.. device can be used store the output of measurements on the device temporarily and retrieve it later in CSV format.

Overview

While the main principle of the Data Recorder is identical of DAQ streaming (acquiring data with high sampling rate and timing precision), it differs on some way:

• the Data Recorder can be used to store a finite amount of data at a time (100 MB digital data on the 5165A.. device), while such restrictions don't apply when using the DAQ streaming feature
• when exporting the data, the Data Recorder pre-processes the data, and outputs an easily parsable CSV file, that can be further analyzed without converting it programmatically.
• using the Data Recorder the data can be exported from the device only after the measurement has ended, while using DAQ streaming the data is streamed in real time through the TCP socket.

In principle when the Data Recorder is enabled, it listens to the associated measurement. When the startTrigger of the measurement fires, the Data Recorder starts storing all the data in the device's internal memory until a stop condition is reached. Once the Data Recorder is stopped, the acquired data can be retrieved in CSV format, and/or the stored records (measurements) can be deleted, freeing up the memory for new records.

The feature can be useful for example when high speed Data Acquisition is required from multiple devices concurrently, and there is not sufficient available network bandwidth to retrieve the data in real time. In this case using the Data Recorder the acquired data can be kept on the device temporarily, and it can be retrieved from the devices separately after the measurements are done.

Note that in case the device is powered off before the acquired data would be exported, the data will discarded, it does not persist.

The anti-aliasing filter that is present for DAQ streaming and DAQ download is also present when using the Data Recorder feature.

It is recommended not to use high speed DAQ streaming and high speed Data Recorder feature at the same time to avoid performance problems.

Creating a Data Record consists of the following steps:

• Configuring the Measurement
• Configuring the Data Recorder
• Starting the Data Recorder
• Starting, and then stopping the measurement (even multiple times)
• Stopping the Data Recorder
• Exporting and processing the data

You can find more information about these steps below, in this section.

RecordSet

After starting the Data Recorder using the relevant REST API request, it start recording the data, called recordSet. A recordSet contains one or more repetitions (measurements) that can be exported together.

It is also possible to record multiple recordSets in the buffer by starting and stopping the Data Recorder and recording measurements without deleting existing recordSets (until there is free space in the buffer, but maximum 128).

In this section the “recordSet” and “record” terms are used interchangeably.

Measurement configuration

Just like for DAQ streaming, it is important for the Data Recorder also to have correct sensor settings set up to get sensible data. The sensor can be set up easily using the UI or the REST API services.

The Data Recorder uses the same measurement configuration as DAQ streaming, and setting up the measurement is identical to the already described process. The Data Recorder uses the same settings for measurements as the DAQ streaming feature. Refer to the measurement configuration section of this guide.

The DAQ streaming feature shares many of its settings with the Data Recorder feature. The desired sampling rate can be set on the same way as for DAQ streaming.through the UI or by /daq/samplingRate parameter using the REST API.

The channels included in the recorded data can be specified also on an identical way to the DAQ streaming feature, through the UI or REST API service. The rules are also identical: on the 5165A1 device maximum 2, on the 5165A4 device a maximum of 4 channels can be enabled to record data from. Physical measurement channels and virtual channels can be mixed arbitrarily.

Starting the Data Recorder

Initially the Data Recorder is in "Init" state, it does not record the measurement. When starting the Data Recorder, the number of repetitions of the measurement need to be specified.

Refer to the REST API documentation about setting the the maxRepetitionsCount parameter using the /api/$/record/start service.

Repetitions

The number of repetitions is a mandatory parameter (maxRepetitionsCount). When set to 0, the Data Recorder will record a maximum of 128 measurements until the buffer is full or it is stopped manually.

When it set to a positive number (between 1 and 128), the Data Recorder will store the specified number of measurement repetitions before stopping automatically. A measurement repetition is a set of signal levels between a measurement start- and stop-trigger.

As an example if the maxRepetitionsCount is set to 5, and the measurement startTrigger is set to “request”, and the stopTrigger is set to the duration of 2 seconds, then after starting the Data Recorder the service will record 5 measurement before stopping automatically: it will wait for a startTrigger event, record the data for 2 seconds, and wait for the next startTrigger – for 5 cycles.

Note that in case the maxRepetitionsCount is set to a positive number, but the amount of acquired data exceeds the available free buffer size, the Data Recorder will stop automatically.

Starting and stopping a measurement

The starting and stopping of the measurement is identical to the way described above in the DAQ streaming section.

As mentioned above, it is possible to record multiple repetitions (maximum 128) of the same measurement within the same recordSet.

Stopping the Data Recorder

The recorder stops recording when any of the stop condition is reached. The stop conditions are the following:

• the Data Recorder has recorded the specified amount of measurement repetitions
• the Data Recorder is stopped manually using the /api/$/record/stop request before the specified amount of repetitions would be recorded (see REST API documentation)
• the Data Recorder buffer is full.

Exporting and processing the data

The recorded data can be exported using the /api/$/record/download service (see REST API documentation). At a time a recordSet can be exported in CSV format, including all repetitions. The downloaded file contains the absolute timestamp of the scans (Unix timestamp, in second.nanosecond format), and the measured signal level at the corresponding timestamp in human readable form.

Note that the size of the downloaded data file might reach over 600 MB, depending on the size of the exported record.

Optionally it is possible to specify the CSV delimiter (semicolon, tab, comma) and the decimal separator character (dot, comma) during downloading the exported file. It is also possible to exclude the timestamp and/or the column header from the exported file. Refer to the REST API documentation about these options.

With each record certain metadata are stored also (current sensor and device settings) for measurement repeatability. This metadata can be downloaded as a separate file. For the metadata optionally the CSV delimiter and the decimal separator character can be specified similarly to the data exporting options.

A map is provided with timestamps in the exported metadata file – the timestamp provided is the starting timestamp of the corresponding repetition.

Since the exported data is in simple CSV format, it is easy to import and post-process it with various applications (spreadsheet applications, or numeric computational applications like MatLab or Octave, etc).

Data Recorder States

It is possible to query the current state and other general attributes of the Data Recorder through the REST API (see listRecords and status services in the REST API documentation).

Using the status REST API service it is possible to get the current state of the Data Recorder, and also the amount of available space in the buffer. It is recommended to check this state before starting a new record to ensure that the record will fit in the buffer.

The amount of data that can be acquired using the Data Recorder feature highly depends on the general DAQ settings and on the number of separate records created. The more channels and the higher sampling rates are used, the shorter period can be recorded. One signal level scan takes 4 bytes in the buffer. When one channel is selected to be used with the Data Recorder using 62500 Hz sampling rate, then

100 MB / (62500 Hz x 1 channel x 4 Bytes) ~ 400

seconds of data can be stored in the buffer. (Note that with each recordSet some extra metadata is stored also for traceability, that adds some overhead.) This formula can be used to calculate the amount of data that can be stored in the buffer, with changing the variables to the current settings.

Using the removeRecordSet REST API service it is possible to delete records from the buffer that are not necessary anymore.

Note that when the Data Recorder is in Waiting, Recording or Exporting state, it is not possible to delete the contents of the buffer. When in Exporting state it is not possible to record a new recordSet until the exporting finishes.

Sending a request to the /api/$/record/cancel REST API service will cancel the current operation, and sets the Data Recorder in Init state. Depending on the Data Recorders current state, the following operations will be performed:

If the data recorder is disabled using the parameter REST API service, the buffer's whole content will be discarded, and the recorder feature will not be usable until it is enabled again using the parameter REST API service again. The recorder feature is enabled by default.

Signal Monitor

The 5165A.. device contains a signal monitoring component that can fire when a monitored sensor's signal level reaches a configured threshold. These events can then be used to start/stop a measurement automatically on a device, or inform an event listening client (e.g.LabAmp Multi-Device-Client) about the occurred event.

Configuration

The signal monitor can be configured using the /api/param REST API services (see REST API documentation). Each channel (both physical sensors and virtual channels) can have two separate signal monitor attached (threshold-1 and threshold-2).

The relevant parameters can be found in the /signalMonitor/threshold/[THRESHOLD_NR]/[virt|meas]channel/[CHANNEL_NR] subtrees. For example the settings for threshold-1 for measChannel-3 can be found in

/signalMonitor/threshold/1/measChannel/3

subtree. The settings for threshold-2 for virtChannel-1 can be found in

/signalMonitor/threshold/2/virtChannel/1

subtree.

Each of this subtrees contains three parameters:

enabled: setting the parameter to the value “1” will enable the monitoring of the channel. Setting it to “0” will disable this monitor. type: the slope of the signal to monitor. Possible values:

value: the level of threshold. When the signal reaches this value, the relevant event will be fired. This parameter can have a value between -1 and 1. This is the ratio between the desired threshold level and the full range of the sensor.

For example if measChannel-3 has a pressure sensor with range of 15000 bar, and an event needs to be fired when the measured signal rises above 3000 bar, the following settings can be set using threshold-2:

/signalMonitor/threshold/2/measChannel/3/value → 0.2 (calculated with 3000/15000)
/signalMonitor/threshold/2/measChannel/3/type → 1 (rising edge)
/signalMonitor/threshold/2/measChannel/3/enabled → 1 (enable the signal monitoring component)

The measuring range of the sensor needs to be set up on the Sensor screen of the UI along with the sensitivity of the sensor or via the parameter API.

Note that enabling signal monitor with fast changing signals over a longer period might affect the system performance on a negative way temporarily. (E.g having 50 kHz sine wave, monitored actively with both thresholds, on both slopes, fires 200.000 events a second.) It is recommended to disable the signal monitor components when not in use to avoid accidental event-flooding.

These events configured with the signal monitor can be used as start- and stop-Triggers with measurements (see “Configuring measurements” section). The name of the events that can be set as measurement trigger follows the next format:

skybase.sigmon.threshold-[THRESHOLD_NR]_[meas|virt]-[CHANNEL_NR]_[rising|falling]

• [THRESHOLD_NR] – the number of threshold monitor to be used
• [meas|virt] – the type of channel that is monitored
• [CHANNEL_NR] – the number of channel monitored
• [rising|falling] – the slope of the signal to monitor

Continuing the previous example, if the previous configuration needs to be used as a stopTrigger for a measurement, the following event-name can be used after enabling the monitor (threshold-2, measChannel-3, rising slope):

skybase.sigmon.threshold-2_meas-3_rising

Note the small difference between the settings of the signal monitor and the acceptable start- and stopTrigger event names for measurements. As described above, it is possible to set 3 values for the “type” parameter of the signal monitor: 0 – falling, 1 – rising, 2 – both. When the value “2” is used, it means that the monitor will fire both “rising” and “falling” events, when they occur. For the measurements it is possible to set one type of event at a time – either falling or rising. (But the start- and stopTriggers can be different events: it is possible to set up rising event as startTrigger and falling event as the stopTrigger – even from different signal monitors.)

Time settings

LabAmp device supports time synchronisation over the network using NTP or PTP protocol.

Setting the time manually

It is possible to set the time manually on the device using either the web-based UI, or the /api/clock/set REST API (see REST API documentation). Note that this way of setting the time provides no accuracy of synchronisation between devices.

NTP synchronisation

It is possible to use an NTP (Network Time Protocol) server for time synchronisation. It is possible to set this mode using the web-based UI or the REST API (see REST API documentation). Note that when entering the NTP server address as a domain name, a DNS server needs to be set up in the network settings too. When using DHCP (dynamic IP) network configuration, the DNS server is expected to be received from the DHCP server. When using static IP configuration, the DNS server's IP needs to be set up manually.

You can check the synchronisation status through the web-based UI or using the /api/clock/ntp/status/get REST API service (see REST API documentation).

NTP synchronisation provides better synchronisation accuracy between devices than setting the time manually, but the time difference between devices might still be a couple of milliseconds. Therefore this mode should not be used when intending to retrieve and merge the DAQ-data from multiple synchronized devices.

Nevertheless this mode can be used to first synchronize all devices to the world clock, especially when no external clock master is available in the network.

PTP synchronisation

When using synchronised DAQ streaming using multiple LabAmp devices, it is recommended to use PTP (Precision Time Protocol) time synchronisation on all involved devices, as this provides the highest level of time synchronisation accuracy amongst the available settings.

The 5165A.. device has an implementation of PTPv2 (also known as IEEE 1588-2008 standard). Below this standard will be referred to as simply PTP.

PTP synchronisation can be enabled through the web-based UI or using the REST API (see REST API documentation). After enabling this option the device will look for a PTP grandmaster on the local network to synchronise with. After the PTP grandmaster was found, it might take up to 5 minutes (typically 90 seconds) for the devices to synchronise successfully with the PTP grandmaster. In case no PTP grandmaster was found on the network, a 5165A.. device will act as a PTP grandmaster.

Note that the 5165A.. devices have no battery powered RTC, and the system time is reset after powering off the device, so initially the system time might be incorrect on the device until a successful synchronisation with an NTP server/PTP grandmaster, or until setting the time manually. When using the device as a PTP grandmaster, it is recommended to synchronise the time beforehand with an NTP server, or setting the time manually.

When using the device with PTP time synchronisation mode, it is important that the network configuration has to support PTP. If the switches/routers used with the 5165A.. device don't support PTP, the devices need to be daisy-chained (one 5165A.. device connected to the network, the second one connected to the first device, and so on), otherwise the PTP synchronisation might be unsuccessful, and/or the the synchronisation level might lose accuracy. Nevertheless long daisy chains (more than 10 devices) might affect the synchronization accuracy and should be avoided.

When using PTP synchronisation with daisy-chained devices the PTP master connect should be connected to Ethernet 1 port on the device, and the slave 5165A.. device should be connected to the first device's Ethernet 2 port.

_{Version: 1.2.2
Author: Gyorgy Sarvari (SGY)
Date: 22.03.2017}

• Introduction
• about
  • /api/about
• clock
  • /api/clock/ntp/status/get
  • /api/clock/timezone/set
  • /api/clock/ptp/status/get
  • /api/clock/ntp/settings/set
  • /api/clock/timezone/get
  • /api/clock/settings/get
  • /api/clock/syncmode/set
  • /api/clock/time/get
  • /api/clock/ptp/settings/set
  • /api/clock/timezone/list
  • /api/clock/time/set
  • /api/clock/status/get
• control
  • /api/ctrl/factoryreset
  • /api/ctrl/identify
• daq
  • /api/daq/start
  • /api/daq/status
  • /api/daq/device/metadata/get
  • /api/daq/stop
  • /api/daq/download/{guid-key}
• measurement
  • /api/daq/measurement/metadata/get
  • /api/daq/measurement/enabled/get
  • /api/daq/measurement/configuration/set
  • /api/daq/measurement/start-trigger/set
  • /api/daq/measurement/signal-provider/set
  • /api/daq/measurement/signal-provider/get
  • /api/daq/measurement/count/get
  • /api/daq/measurement/start
  • /api/daq/measurement/status/get
  • /api/daq/measurement/stop
  • /api/daq/measurement/enabled/set
  • /api/daq/measurement/stop-trigger/get
  • /api/daq/measurement/start-trigger/get
  • /api/daq/measurement/configuration/get
  • /api/daq/measurement/stop-trigger/set
• monitor
  • /api/$/monitor/set
  • /api/$/monitor/get
• param
  • /api/param/export
  • /api/param/import
  • /api/param/get
  • /api/param/set
  • /api/param/changes/{index}
• record
  • /api/$/record/listRecords
  • /api/$/record/cancel
  • /api/$/record/stop
  • /api/$/record/remove
  • /api/$/record/start
  • /api/$/record/download/data
  • /api/$/record/status
  • /api/$/record/download/metadata
• signal
  • /api/$/signal/get
  • /api/$/signal/reset
• status
  • /api/$/status/channel
  • /api/$/status/led
• stream
  • /api/daq/stream/register
  • /api/daq/stream/protocol-version
  • /api/daq/stream/close
  • /api/daq/stream/status
  • /api/daq/stream/scansPerFrame
  • /api/daq/stream/unregister
  • /api/daq/stream/list
  • /api/daq/stream/open
• system
  • /api/$/system/channels
• teds
  • /api/teds/status
  • /api/teds/userText/set
  • /api/teds/data/get

Introduction

Your Kistler 5165A.. device provides an extensive set of REST API services to control all the features conveniently. On this page you can find a description of these services, and also examples of the usage.

/api/param/

All functionality needed for device parameterization and getting information about device param (set, get, validate, poll for changes).

/api/daq/

Provides access to data acquisition and measurement controls.

/api/ctrl/

Provides access to device control.

/api/clock/

Provides access to system-time related settings and information.

/api/about

Provides access to basic information about the device.

/api/update

Provides access to firmware update on the device.

/api/$/status

Provides access to to the current channel statuses the device.

/api/$/signal

Provides access to the current signal levels on the device, and also option to reset arithmetic calculations.

/api/$/monitor

Provides access to LED colors/channel statuses, and to current signal values. DEPRECATED

/api/teds

Provides access to data stored on TEDS capable sensors.

/api/$/record

Provides access to the recorder feature of the device.

/api/about

Retrieves all relevant information This API provides the means to get some general information of the device .

Examples

TX: curl http://IP_ADDRESS/api/about
RX: {"result": 0, "about": { "softwareVersion": "2015-04-21_08-03(2592)", "platformVersion" : "2747", "bootloaderVersion": "1.1.0 ", "hardwareVersion": "120111", "fpgaVersion": "20150420", "serialNumber": "1234567890" } }

Summary

/api/clock/ntp/status/get

Returns list of available timezones Gets the current NTP sync status. NTP status code can be:

• "disabled": NTP synchronisation is disabled
• "nosync": device is not synchronised with NTP server. Device will continously retry to synchronise.
• "sync": device is synchronised with NTP server

Summary

/api/clock/timezone/set

Sets the timezone Sets the timezone of the system clock. This interface uses the parameter manager interface to set the parameter. Clients could also use the parameter manager interfaces directly. The timezone needs to be one of the zones retrieved from the timezone/list service.

Summary

/api/clock/ptp/status/get

Gets PTP sync status Gets the current PTP sync status. PTP status code can be:

• "disabled": PTP is not running.
• "unsynchronized": The role of the device (PTP Slave or Grandmaster) is not determined. This can happen for a few seconds after boot-up or a network reconfiguration.
• "master": System acts as a PTP Grandmaster.
• "slaveNosync": System acts as a PTP Slave. Time information is not inside the range of specified system qualities.
• "slaveSync": System acts as a PTP Slave. Correct time information is provided by PTP.

SyncE status code can be:

• "forceOff": SyncE is forced off.

  The values for "gmIdentity", "clockIdentity" and "portStates" are strings of the format defined in the PTP data set.

  The value for "offsetFromMaster" is an integer and provides the estimated synchronisation offset in nano seconds.

Summary

/api/clock/ntp/settings/set

Sets the NTP Server list Sets the NTP Server list. This interface uses the API param to set the parameter. Clients could also use the parameter manager interfaces directly.

Summary

/api/clock/timezone/get

Gets the timezone Returns the current timezone.

Examples

TX: curl http://IP_ADDRESS/api/clock/timezone/get
RX: { "result": 0, "timezone": "Europe/Paris" }

Summary

/api/clock/settings/get

Gets clock system settings Gets the current settings for the clock system.

Summary

/api/clock/syncmode/set

Sets the synchronization mode Sets the synchronization mode. This interface uses the API param to set the parameter. Clients could also use the parameter manager interfaces directly.

The values for "syncmode" can be:

• "disabled": All synchronisation protocols are disabled. The time is set manually on the device.
• "ntpOnly": Only NTP synchronisation is enabled.
• "ptpOnly": Only PTP synchronisation is enabled.

Summary

/api/clock/time/get

Gets current system time Returns the current system time. Either returns the current system time in the configured local timezone, when format = "local" or returns the current system time in UTC, when format = "utc".

Summary

/api/clock/ptp/settings/set

Sets the PTP specific configuration. Sets the PTP specific configuration. This interface uses the API param to set the parameter. Clients could also use the parameter manager interfaces directly. A valid request specifies each parameter in the Body Request. Specifying "manualUTCOffset" parameter is required only when "source" is "manual".

The Value of "domain" is integer from range 0..127. Only devices belonging to the same domain would synchronize together.

The value for "ptpProfile" can be one of the following:

• "auto: Starts with the delay request-response mechanism (E2E) and switches to the peer delay mechanism (P2P) if peer delay request messages are received.
• "requestResponse": Delay Request-Response Default PTP profile 00-1B-19-00-01-00 (E2E mechanism).
• "peerToPeer": Peer-to-Peer Default PTP profile 00-1B-19-00-02-00 (P2P mechanism).

The value for "ptpTransport" can be one of the following:

• "Ethernet: Network transport for PTP is IEEE 802.3/Ethernet.
• "UDP_IPv4": Network transport for PTP is UDP over IPv4.

The value for "syncE" can be one of the following:

• "forceOff": Synchronous Ethernet forced off.

The value of priority1 and priority2 ranges from 0..255, while 0 is the highest priority and 255 is the lowest one.

The value for "utcOffset"."source" can be one of the following:

• "tzdata: use tzdata database to obtain UTC offset
• "userDefined": user defined value provided in "utcOffset"

Summary

/api/clock/timezone/list

Returns list of available timezones Returns a list of available timezones installed on the system when orderby = "none". Returns a list of available timezones installed on the system ordered by region : country : zone, when orderby = "region".

Summary

/api/clock/time/set

Sets the time Sets the current date and/or time of the system using ISO-8601 time string. Date, Time, or both can be specified. Use T separator if specifying both date and time. Use Z suffix to indicate supplied time is UTC, otherwise local time is assumed. If the time can not be set because of a time source conflict, then the error "conflicting_time_source" is returned. It is not possible to set the time menually when the device is in PTP slave mode, or in NTP synchronization mode.

Summary

/api/clock/status/get

Gets clock service status Gets the current service status. Service status can be:

• "configuring": Service is initializing, recovering from error or applying changes to the settings
• "ready": Running mode does reflect actual parameter values and service is operating normally

Summary

/api/ctrl/factoryreset

Reset the device to factory setting This service resets all parameter settings to the factory default values and reboots the device. This has the same effect as pressing the factory reset button on the device for 2 seconds.

Summary

/api/ctrl/identify

Cause the device to activate its physical identification mechanism. NOTE: This method currently cannot return anything but success.

Examples

TX: curl --data "" http://IP_ADDRESS/api/ctrl/identify

RX: { "result": 0 }

Summary

/api/daq/start

Returns acquired data in file as chunked download. Registers a DAQ Download session ID that can be used with the /api/daq/download service to obtain the file. The scanLimit parameter is the number of scans returned in the downloaded file. If its value is 0, the number of returned scan is unlimited (till a /daq/stop request is sent).

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/daq/start -d '{ "scanLimit": 1000}'

RX: { "result": 0, "key": "1414bad3-1120-40be-b0c3-51d6353f96b6" }

Summary

/api/daq/status

Returns the current status for the daq process. The "scans" Count is the current number of scans acquired when this method is called. This can be used to control a progress bar.

The "status" conditions represents the state of the data acquisition process. Possible values are:

The "lastError" conditions indicates the last error that occurred during the data acquisition process. Possible values are:

Examples

TX: curl -v -X GET http://IP_ADDRESS/api/daq/status
RX: { "result": 0, "lastError": 0, "scans": 1024, "status": 1 }

Summary

/api/daq/device/metadata/get

Gets metadata of the device Returns the basic attributes of the DAQ subsystem.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/device/metadata/get -d '{ }'
RX: { "result": 0 } and metadata (see schema)

Summary

/api/daq/stop

Stops the downloading process for the given guid-key. The stop is ignored if data acquisition is not running

The user must supply the correct guid-key as provided when started. If the key is missing, or does not match with the current acquisition process, an error is returned. This prevents a second client from stopping a data acquisition process.

TX: curl -v -X POST http://IP_ADDRESS/api/daq/stop -d '{ "key": "1414bad3-1120-40be-b0c3-51d6353f96b6" }

RX: { "result": 0 }

Summary

/api/daq/download/{guid-key}

Returns acquired data in file as chunked download The full url download path requires the guid-key returned from the api/daq/start call. An optional query string parameter ?filename=filename specifies the save-as file name. If omitted the file is downloaded with the guid-key as the filename. Error conditions are returned via the /api/daq/status method.

NOTE: This download will not stop until a stop condition is reached. Stop conditions are for example:

• A '/api/daq/stop' command is issued (this is the normal use case)

• A pre-defined scan count has been reached

• Connection to requesting client is lost or has been closed

• Device memory is full resulting from data being acquired faster than it can be transmitted to client

Examples

TX: curl -v -X GET http://IP_ADDRESS/api/daq/download/1414bad3-1120-40be-b0c3-51d6353f96b6 -o test.csv

RX: chunked file download

Summary

/api/daq/measurement/metadata/get

Gets metadata of the specific measurement Returns the metadata for the specified measurement (channels in the measurement, channel data, their offset in the resulting binary data that can be acquired using DAQ streaming/binary DAQ download. There are only signals, which are enabled (enabled: true). Offset is calculated according to order of signal in scan and the byte size of signal data type (FLOAT32 = 4 bytes).

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/device/metadata/get -d '{ }'
RX: { "result": 0 } and metadata (see schema)

Summary

/api/daq/measurement/enabled/get

Enables the measurement Returns the "enabled" status of the specified measurement.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/enabled/get -d '{ "measurementId" : 1 }'
RX: { "result" : 0, "enabled" : false }

Summary

/api/daq/measurement/configuration/set

Sets configuration for the measurement Set the whole measurement configuration in one request. Note that this is equivalent to setting the separate attributes one by one.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/configuration/set -d '{ "measurementId" : 4, "startTrigger" : { "triggerUpon" : "event", "event" : "request", "preTrigger" : 4 }, "stopTrigger" : { "triggerUpon" : "duration", "duration": 8000, "postTrigger" : 4000 }, "signal-provider" : "daq-provider", "enabled" : true }'
RX: { "result" : 0 }

Summary

/api/daq/measurement/start-trigger/set

Sets start trigger The property triggerUpon should be set to the one of time, event, or request. According to this value, the property time or event is required. The property pre-trigger equals 0 if omitted. See also the user guide's section about measurements.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/start-trigger/set -d '{ "measurementId" : 1, "triggerUpon" : "event", "event": "skybase.sigmon.threshold-1_meas-1_falling", "preTrigger" : 16 }'
RX: { "result" : 0 }

Summary

/api/daq/measurement/signal-provider/set

Sets signal provider Set the signal-provider for the measurement. Note that the value of the signal-provider on the 5165A.. device is always "daq-provider".

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/signal-provider/set -d '{ "measurementId" : 1, "signalProvider" : "daq-provider" }'
RX: { "result" : 0 }

Summary

/api/daq/measurement/signal-provider/get

Gets signal provider Returns the current signal-provider associated with the specified measurement.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/signal-provider/get -d '{ "measurementId" : 1 }'
RX: { "result" : 0, "signalProvider" : "daq-provider" }

Summary

/api/daq/measurement/count/get

Number of possible measurements The number of available measurement configurations on the device.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/count/get -d '{ }'
RX: { "result" : 0, "measurementConfigurationsCount" : 1 }

Summary

/api/daq/measurement/start

Starts the measurement Starts the measurement when the measurement's startTrigger is set to "request". The time field in the body is optional. When set, the measurement will start at the specified timestamp. If omitted, the measurement will start immediately. Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/start -d '{ "measurementId" : 1 }'
RX: { "result" : 0 }

Summary

/api/daq/measurement/status/get

Returns status of given measurement Returns status of given measurement - whether the measurement is running or not, and a timestamp of the last status change

measurementId is an ID number of the measurement the status of which the user wants to know.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/status/get -d '{ "measurementId": 1}'
RX: {"result":0,"status":{"measurementId" : 1, "enabled" : true, "running" : false, "timestamp" : "1470902766.637592000", "signalProvider" : "daq-provider"}}

Summary

/api/daq/measurement/stop

Stops the measurement Stops the measurement when the measurement's stopTrigger is set to "request". Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/stop -d '{ "measurementId" : 2 }'
RX: { "result" : 0 }

Summary

/api/daq/measurement/enabled/set

Enables the measurement Sets the "enabled" status of the measurement.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/enabled/set -d '{ "measurementId" : 1, "enabled" : "true" }'
RX: { "result" : 0 }

Summary

/api/daq/measurement/stop-trigger/get

Gets stop trigger Returns the currently set stopTrigger for the specified measurement along with the postTrigger time in nanoseconds.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/stop-trigger/get -d '{ "measurementId" : 1 }'
RX: { "triggerUpon" : "duration", "postTrigger" : 4, "duration" : 8000, "result" : 0}

Summary

/api/daq/measurement/start-trigger/get

Get start trigger Returns the currently set startTrigger for the specified measurement ID along with the preTrigger time in nanoseconds.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/start-trigger/get -d '{ "measurementId" : 1 }'
RX: { "triggerUpon" : "request", "preTrigger" : 16, "result" : 0}

Summary

/api/daq/measurement/configuration/get

Gets configuration for the measurement Returns the whole measurement configuration.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/configuration/get -d '{ "measurementId" : 1}'
RX: { "result" : 0, "signalProvider" : "daq-provider", "enabled" : true, "startTrigger" : { "triggerUpon" : "request", "preTrigger" : 16}, "stopTrigger" : { "triggerUpon" : "event", "postTrigger" : 12, "event" : "skybase.sigmon.threshold-1_meas-1_rising"}}

Summary

/api/daq/measurement/stop-trigger/set

Sets stop trigger The property triggerUpon should be set to the one of time, event, duration, or request. According to this value, the property time, event, or duration is required. The property postTrigger equals 0 if omitted.

Examples

TX: curl -X POST http://IP_ADDRESS/api/daq/measurement/stop-trigger/set -d '{ "measurementId" : 1, "triggerUpon" : "duration", "duration": 1000000, "postTrigger" : 16000 }'
RX: { "result" : 0 }

Summary

/api/$/monitor/set

Resets the arithmetic calculations for the channels. Note that this service is deprecated, and might be removed from future software releases. We recommend you not to develop new software depending on this service, and consider migrating your existing applications to use the /api/$/signal and /api/$/status REST API services

This method can be used to reset the arithmetic calculations (min/max/ampl) values for the channels. The format of the string that needs to be sent to reset the arithmetic calculations is the following: signal/measChannel/[CHANNEL_NUMBER]/reset where CHANNEL_NUMBER is the number of channel that's min/max/ampl values need to be reset.

The value for the request should be always "1".

This service can't be used to reset the calculations for Virtual Channels.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/signal/reset -d '{"values":[{"name":"signal/measChannel/1/reset","value":"1"},{"name":"signal/measChannel/2/reset","value":"1"},{"name":"signal/measChannel/3/reset","value":"1"},{"name":"signal/measChannel/4/reset","value":"1"}]}'

RX: {"result":0}

Summary

/api/$/monitor/get

Returns the current signal levels and LED/channel statuses. Note that this service is deprecated, and might be removed from future software releases. We recommend you not to develop new software depending on this service, and consider migrating your existing applications to use the /api/$/signal and /api/$/status REST API services

This method can be used to get the current signal values and LED colors, even multiple ones and types with one request. The format of requesting a signal value is the following:

signal/measChannel/[CHANNEL_NUMBER]/[SIGNAL_TYPE]

where the [CHANNEL_NUMBER] is an integer, corresponding the requested channel number, and [SIGNAL_TYPE] is one of the following values: min, max, live, rms, ampl

The format for requesting the LED status is the following:

[CHANNEL_TYPE]/[CHANNEL_NUMBER]/LEDstatus

where [CHANNEL_TYPE] is either "measChannel" or "output", and the [CHANNEL_NUMBER] is an integer corresponding to the number of the requested channel.

When requesting LED status, the following values might be returned:

Note that this REST API service does not support querying data from Virtual Channels.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/monitor/get -d '{"values":["signal/measChannel/1/live","measChannel/1/LEDstatus"]}'

RX: { "result": 0, "values":[ {"name": "signal/measChannel/1/live", "value": "-0.000959"}, {"name": "measChannel/1/LEDstatus", "value": "1"} ]}

Summary

/api/param/export

Export parameters, applying filters. INFO: Requests can also be made using multipart/form-data for file-download of the results. The type and filter (as semi-colon separate list) are form parameters, filename is also specified as a form parameter. The response will contain a content-disposition for file download.

NOTE: The type must be an integer value:

0 = json

1 = pretty json

2 = XML

3 = pretty XML

The filter is an array of filter strings. Each filter must begin with a '+' or '-', followed by a valid path in the parameter tree. If the filter starts with '-', the given branch will be omitted from the export, along with all childnodes. If the filter starts with '+', the whole branch will be included in the export, along with the child nodes. The filters can be combined. In the below example the whole tree is excluded from the export, except the /deviceSetup/net/if0/ipv4 branch, that is added as an extra filter. If no filter is given, the whole tree is exported.

Examples

TX: curl -X POST http://IP_ADDRESS/api/param/export \ -d '{ "type": 3, "filter": ["-/", "+/deviceSetup/net/if0/ipv4"] }'

RX:

<pe:ParameterExport xmlns:pe="http://libparamDB/XSD/ParamExport.xsd" pe:version="2">
 <pe:header>
   <pe:timeOfExport>Thu Jan 22 05:22:18 2015</pe:timeOfExport>
   <pe:serialNumber>123456</pe:serialNumber>
   <pe:type>5165A4</pe:type>
   <pe:deviceName>LabAmp Room 222</pe:deviceName>
   <pe:softwareVersion>516XAX-V1.2.0</pe:softwareVersion>
   <pe:schemaMajor>1</pe:schemaMajor>
   <pe:schemaMinor>0</pe:schemaMinor>
   <pe:version>2</pe:version>
 </pe:header>
 <pe:settings>
   <pe:path pe:name="deviceSetup">
     <pe:path pe:name="net">
       <pe:path pe:name="if0">
         <pe:path pe:name="ipv4">
           <pe:param pe:name="mode">1</pe:param>
           <pe:path pe:name="static">
             <pe:param pe:name="address">IP_ADDRESS</pe:param>
             <pe:param pe:name="gateway">IP_ADDRESS</pe:param>
             <pe:param pe:name="mask">IP_ADDRESS</pe:param>
           </pe:path>
         </pe:path>
       </pe:path>
     </pe:path>
   </pe:path>
 </pe:settings>
 <pe:signature>
   <pe:type>SHA256</pe:type>
   <pe:header>F05B3938BE2442FBED25D3C675B60952DF3D1096D1DD0959604D2C6A937E7206</pe:header>
   <pe:settings>25BA4B96E1892AE6210C5FA96178BA7F6A22E1BEF36F6BF1EF4F5C657E9D9424</pe:settings>
 </pe:signature>    </pe:ParameterExport>

Summary

/api/param/import

Import parameters, applying filters. NOTE: The type must be an integer value:

0, 1 = json

2, 3 = pretty XML

When specifying filter(s) in the request only the specified parameters will be imported. This is useful for example to avoid importing network settings when it is not desired.

The filter is an array of filter strings. Each filter must begin with a '+' or '-'. When using the '+' prefix for a parameter tree, that given tree will be imported from the data string. Using '-' prefix will exclude the prefixed tree from the import. It is possible to combine filters even in the same tree. For example the filter ["-/", "+/deviceInformation/deviceName"] will exclude every parameters from the import string, except for the "/deviceInformation/deviceName" parameter.

Examples

TX: curl --digest -X POST http://IP_ADDRESS/api/param/import -d '{ "type": 0, "filter": [""], "data":"{\"header\":{\"signature\": {\"type\":\"SHA256\",\"hash\":\"3CCFD8F87AC8391A190FCA0C2E0843D2FA028ED4381D62757F37309397F899FF\"},\"data\":{\"serialNumber\":\"C12345\",\"type\":\"Type 5556\",\"deviceName\":\"SkyBoard\",\"softwareVersion\":\"0.1.0.0\",\"schemaMajor\":\"1\",\"schemaMinor\":\"0\",\"version\":\"3\"}},\"settings\":{\"signature\":{\"type\":\"SHA256\",\"hash\":\"E3A75A218FACDA9CEA0B8AFB7A4C0592D60ECD805F3530F959D1062A47B1FB2C\"},\"data\":{\"amp\":{\"chan1\":{\"calfactor\":\"10\",\"fso\":\"10\",\"lpfilter\":\"1\",\"range\":\"100\",\"sensitivity\":\"84\",\"timeconstant\":\"2\",\"overload\":\"0\"}}}}}" }' -c cookie.txt -b cookie.txt RX: { "result": 0 }

Summary

/api/param/get

Returns value(s) of the parameters listed in <parameter list>. This method can be used to query parameters and properties. Properties are addressed using the syntax parameter.property. See also parameter documentation.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/param/get -d '{"params":["/output/2/voltageP1"]}'

RX: { "params":[ {"name": "output/2/voltageP1", "value": "0"} ]}

TX: curl -v -X POST http://IP_ADDRESS/api/param/get -d '{"params":["/signalMonitor/threshold/1/virtChannel/1/enabled","/virtChannel/1/accComp/forceChannel"]}'

RX: { "params":[ {"name": "/signalMonitor/threshold/1/virtChannel/1/enabled", "value": "1"}, {"name": "/virtChannel/1/accComp/forceChannel", "value": "3"} ]}

Summary

/api/param/set

Sets parameters in to the values defined in the same list. Examples

TX: curl -v -X POST http://IP_ADDRESS/api/param/set -d '{"params":[{"name":"/deviceSetup/net/if0/ipv4/static/address","value":"192.168.123.33"}]}'

RX: { "result": 0 }

TX: curl -v -X POST http://IP_ADDRESS/api/param/set -d '{"params":[{"name":"/deviceSetup/net/if0/ipv4/static/address","value":"192.168.123.33"}, {"name":"/deviceSetup/net/if0/ipv4/static/mask","value":"255.255.255.0"}]}'

RX: { "result": 0 }

Summary

/api/param/changes/{index}

Returns the changes since the last call. Suitable for long polling clients. This method is used to monitor changes to parameters on the system. The index is an integer value and represents a short lived, incremental state of the system. Requesting an index value less than the current index will result in an immediate response that will contain the current index and optionally an array of parameters that have recently changed. Changes are persisted for a limited time so this call can return different results for the same index value. If the index is omitted, the server returns the current index with no changes. If the index is equal to the current index, the system will wait until there are changes pending or until the long poll times out.

Examples

TX: curl -v -X GET http://IP_ADDRESS/api/param/changes

RX: { "index": 1, "changes": [ ] }

TX: curl -v -X GET http://IP_ADDRESS/api/param/changes/1

RX: { "index": 2, "changes": ["/measChannel/1/sensor/type/selected"] }

Summary

/api/$/record/listRecords

Lists data about the content of the buffer. This method can be used to retreve data about the current content of the recorder buffer, including the length, name, repetition count, status and starting time of the meaurement. If there were no problems encountered during recording the measurement, the state of the repetition will be "OK". Otherwise a short description is displayed about the encountered problem (e.g timeskew, configuration change during recording)

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/record/listRecords -d '{"recorderId":1}'

RX: {"result": 0,"data": {"recorderId": 1,"records": [{"repetitions": [{"duration": "1.999460000","repetition": 1,"size": 3207328,"status": "ERROR: DAQ Subsystem configuration changed","time": "1486574307.545610022"}],"setId": 0},{"repetitions": [{"duration": "2.520000","repetition": 1,"size": 1608608,"status": "OK","time": "1486574519.616720022"}],"setId": 1}]}}

Summary

/api/$/record/cancel

Cancels the current Data Recorder operation. This method can be used to cancel the current Data Recorder operation. In case it is called while in Recording state, the currently recorded recordSet will be discarded. If called during exporting the data, the exporting process will be stopped. After calling this method the Data Recorder will return to "Init" state.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/record/cancel -d '{"recorderId":1}'

RX: {"result":0}

Summary

/api/$/record/stop

Stops the Data Recorder. This method can be used to stop the Data Recorder manually. Note that in case the Data Recorder has already recorded the number of measurements specified with maxRepetitionsCount, it will stop automatically. This method can be used to stop the Data Recorder manually before the Data Recorder would record the specified number of measurements, or in case of unlimited number of measurements, to stop before the buffer would be full.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/record/stop -d '{"recorderId":1}'

RX: {"result":0}

Summary

/api/$/record/remove

Removes the specified recordSet from the buffer. This method can be used to remove recordSets from the buffer. Note that removing a recordSet will dicard all of the recordSets recorded data and metadata also, and it will not be able to retrieve this data after removal.

If the "setId" parameter is not present in the request, all records will be deleted for the Data Recorder.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/record/remove -d '{"recorderId":1, "setId":3}'

RX: {"result":0}

Summary

/api/$/record/start

Starts the recorder. This method can be used to start the recorder feature. The "name" field is optional. If the maxRepetitionsCount is 0 or negative, the number of measurements recorded is only limited by the available buffer size.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/record/start -d '{"recorderId":1,"maxRepetitionsCount":2}'

RX: {"result":0}

TX: curl -v -X POST http://IP_ADDRESS/api/$/record/start -d '{"recorderId":1,"maxRepetitionsCount":-2}'

RX: {"result":0}

Summary

/api/$/record/download/data

Exports a recordset. This method can be used to retrieve the recorded data in csv format. It returns a content-disposition response.

Examples

TX: wget --content-disposition http://IP_ADDRESS/api/$/record/download/data?recorderId=1&setId=2&fileName=record.csv

RX: content-disposition file

Summary

/api/$/record/status

Returns the current status of the recorder. This method can be used to retrieve basic status information about the recorder, including buffer information also.

The state of the recorder might be one of the following:

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/record/status -d '{"recorderId":1}'

RX: {"result":0,"data":{"state":"Init","totalCapacity":104857600,"totalSize":25754640,"usage":"24.56%"}}

Summary

/api/$/record/download/metadata

Exports the metadata for a recordSet. This method can be used to retrieve the recorded metadata for an existing recordSet in csv format. It returns a content-disposition response.

Examples

TX: wget --content-disposition http://IP_ADDRESS/api/$/record/download/metadata?recorderId=1&setId=2&fileName=record_metadata.csv

RX: content-disposition file

Summary

/api/$/signal/get

Returns the current signal values for the requested channel(s). This method can be used to acquire the current live signal value a channel, along with the minimum and maximum values since the last arithmetic reset performed on the channel. Beside these the current RMS and amplitude values are returned also. The method can be used for input channels and for virtual channels too.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/signal/get -d '{"type":"SENSOR","channels":[1]}'

RX: {"result":0,"data":{"type":"SENSOR","items":[{"channel":1,"live":[-0.0010463169310242],"max":[5.6459264755249],"min":[-5.6382536888123],"ampl":[0.00726527692145],"rms":[0.00087193085346371]}]}}

Summary

/api/$/signal/reset

Resets the arithmetic calculations for the channels. This method can be used to reset the arithmetic calculations (min/max/ampl) values for the channels.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/signal/reset -d '{"type":"VIRTUAL","channels":[1]}'

RX: {"result":0}

TX: curl -v -X POST http://IP_ADDRESS/api/$/signal/reset -d '{"type":"SENSOR","channels":[1,3,4]}'

RX: {"result":0}

Summary

/api/$/status/channel

Returns the current channel statuses. This method can be used to query the statuses of the different Input, Output and Virtual Channels. Note that certain statuses are channel type specific. The meaning of the statuses are the following:

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/status/channel -d '{"type":"SENSOR","channels":[1]}'

RX: {"result":0,"data":{"type":"SENSOR","items":[{"channel":1,"status":"OK"]}}

TX: curl -v -X POST http://IP_ADDRESS/api/$/status/channel -d '{"type":"OUTPUT","channels":[3,4]}'

RX: {"result":0,"data":{"type":"OUTPUT","items":[{"channel":3,"status":"OFF"},{"channel":4,"status":"OR_OUTPUT"}]}}

Summary

/api/$/status/led

Returns the current LED statuses. This method can be used to query the device's current LED statuses, operating modes and colors.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/status/led -d '{"type":"SENSOR","channels":[1]}'

RX: {"result":0,"data":{"type":"SENSOR","items":[{"channel":1,"color":"CYAN","blinkColor":"BLACK","operatingMode":"ON"}]}}

TX: curl -v -X POST http://IP_ADDRESS/api/$/status/led -d '{"type":"OUTPUT","channels":[3,4]}'

RX: {"result":0,"data":{"type":"OUTPUT","items":[{"channel":3,"color":"YELLOW","blinkColor":"BLACK","operatingMode":"FAST_BLINKING"},{"channel":4,"color":"RED","blinkColor":"BLACK","operatingMode":"ON"}]}}

Summary

/api/daq/stream/register

Registers a client Generates a unique identifier for a client which is used to keep track of its state in subsequent API calls.

Summary

/api/daq/stream/protocol-version

Gets protocol version Gets protocol version of daqstream service.

Summary

/api/daq/stream/close

Closes the stream Closes a port for DAQ Stream.

Summary

/api/daq/stream/status

Gets a status of the stream Retrieves a status of DAQ Stream for given client. The status in the response body may be on of the following:

Summary

/api/daq/stream/scansPerFrame

Gets scan count per frame Gets scan count per frame. measurementId is an id of measurement, which is streamed in the stream given by streamId. Note that this API should be called during an active measurement only.

Summary

/api/daq/stream/unregister

Unregisters the client Unregisters client from DAQ Streaming service. The unregistration is done automatically if the client is non-active for more than 24 hours. However, unregistration should be done explicitly by the client.

Summary

/api/daq/stream/list

Gets a list of active streams List all active DAQ Streams for given registered client.

Summary

/api/daq/stream/open

Retrieves status Opens a data port for DAQ Stream. The stream is closed automatically if there is no established connection in 30 seconds. Error already_waiting means that the connection from the previous call of open is still waiting for a connection from client. Error no_open_stream is usually caused by situation when port is set in a request, but the port is not available.

Summary

/api/$/system/channels

Returns basic system properties. This method can be used to get the number of input, output and virtual channels on the device.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/status/channel -d ''

RX: {"result":0,"data":{"input":4,"virtual":2,"output":4}}

Summary

/api/teds/status

Returns the current TEDS sensor status on all inputs. This method can be used to get the current TEDS sensor statuses on all input channels. The following values might be returned:

Examples

TX: curl -v -X GET http://IP_ADDRESS/api/teds/status

RX: {"result":0,"status":[{"channel":"1","status":"NONE"},{"channel":"2","status":"AVAILABLE"},{"channel":"3","status":"NONE"},{"channel":"4","status":"BUSY"}]}

Summary

/api/teds/userText/set

Writes an arbitrary text to the userText field of the TEDS sensor. This method allows the modification of TEDS sensors' UserText field, with a maximum 50 characters long text. The TEDS template needs to support the UserText field.

Note: if the text is longer than 50 characters, then it will be truncated to 50 characters by removed the last characters. Modifying TEDS data might take up to 30 seconds.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/teds/userText/set -d '{"channel":1, "text":"arbitrary text"}'

RX: {"result":0,"data":{"channel":1, "text":"arbitrary text"}}

Summary

/api/teds/data/get

Returns all TEDS data read from the TEDS capable sensor. This method can be used to query the data stored on the TEDS sensor.

Examples

TX: curl -v -X POST http://IP_ADDRESS/api/$/teds/data/get -d '{"channel":1}'

RX: {"result":0,"channel":1,"data":[{"name":"Manufacturer","value":"Kistler"},{"name":"Model","value":"8763"},{"name":"Version_letter","value":"B"},{"name":"Version_number","value":"36"},{"name":"TEMPLATE","value":"0"},{"name":"CalDate","value":"2013-10-15"},{"name":"Sens@Ref","value":"0.001113", "unit":"V/(m/s²)"},{"name":"Reffreq","value":"99.083542", "unit":"Hz"},{"name":"TF_HP_S","value":"0.099911", "unit":"Hz"},{"name":"Sign","value":"positive"},{"name":"Direction","value":"x"},{"name":"MeasID","value":"1"},{"name":"User Text","value":"LabAmp-Team"}]}

TX: curl -v -X POST http://IP_ADDRESS/api/$/teds/data/get -d '{"channel":9}'

RX: {"result":1,"error":{"namespace":"labamp","reason":"invalid_argument","detail":"channel 9 doesn't exist"}}

Summary