1. Home
  2. Knowledge Base
  3. Opensignals
  4. Quick Start
  5. OpenSignals Sensor File Specifications (.TXT Format)
  1. Home
  2. Knowledge Base
  3. Documentation
  4. Technical Notes
  5. Software
  6. OpenSignals Sensor File Specifications (.TXT Format)
  1. Home
  2. Knowledge Base
  3. biosignalsplux
  4. Sensors
  5. OpenSignals Sensor File Specifications (.TXT Format)
  1. Home
  2. Knowledge Base
  3. BITalino
  4. Sensors
  5. OpenSignals Sensor File Specifications (.TXT Format)
  1. Home
  2. Knowledge Base
  3. BITalino
  4. Software
  5. OpenSignals Sensor File Specifications (.TXT Format)
  1. Home
  2. Knowledge Base
  3. biosignalsplux
  4. Software
  5. OpenSignals Sensor File Specifications (.TXT Format)

OpenSignals Sensor File Specifications (.TXT Format)

In this article, you learn everything you need to know about the data specifications of the exported OpenSignals acquisition files in the ASCII (.TXT) format.

TXT as CSV Option

This tab-delimited .TXT file provides the same functionality as .CSV files for data export to third-party software.

You can download sample files containing real sensor data in the following article:
biosignalsplux Sensor Sample Signals Samples

Overview of OpenSignals Sensor File

OpenSignals ASCII text files have two parts, namely a Header Section and Data Section.

Header Section: Acquisition Metadata

The header section has 3 header lines, each starting with the pound (#) character, given that it is automatically ignored by ASCII text file loading functions in common scientific computing programming languages (e.g. loadtxt in Python).

The header section begins after the line with the content “# OpenSignals Text File Format” and ends after the line “# EndOfHeader”.

The second line has the metadata stored as a JSON object containing each device’s MAC address as top-level keys as shown in the following example:

# OpenSignals Text File Format
# {"00:07:80:79:6F:DB": {"sensor": ["ECG"], "device name": "00:07:80:79:6F:DB", "column": ["nSeq", "DI", "PORT1_CHN1"], "sync interval": 2, "time": "10:29:43.249", "comments": "", "device connection": "BTH00:07:80:79:6F:DB", "channels": [1], "keywords": "", "convertedValues": 0, "mode": 0, "digital IO": [0, 1], "firmware version": 773, "device": "channeller", "position": 0, "sampling rate": 1000, "label": ["PORT1_CHN1"], "resolution": [16], "date": "2018-7-5", "special": [{}, {}, {}, {}, {}, {}, {}]}}
# EndOfHeader

In a more human-readable representation, the header content is organised as follows:

For each top-level key, there is a JSON object as value, containing the acquisition settings used for that.

Device Information

Top-Level KeyDescription
deviceType of recording device used to collect the data (e.g. biosignalsplux, BITalino (r)evolution)
device nameFriendly name manually assigned by the user to the device (default: device’s MAC-address)
device connectionLogical device communication (BTH: Bluetooth, BLE: Bluetooth Low Energy)
firmware versionFirmware version of the device
positionOrder in which the block of columns corresponding to a given device appears in each line of the file (0 – First sequence of columns; 1 – Second sequence of columns; etc.), relevant for multi-device acquisitions.

Acquisition Datetime

Top-Level KeyDescription
dateDay, month and year in which the file was recorded
timeTime at which the first sample was received by the software

Acquisition Setup

Top-Level KeyDescription
sensorArray with the type of sensor connected to each analog port (e.g. as selected from the options available in the device configuration panel on OpenSignals)
channelsSet of analog inputs selected for acquisition in the recording session that generated this file (last columns of the file)
resolutionSampling resolution of each sensor channel
sampling rateSampling frequency of each sensor channel
columnMeaning of each column (left to right)
labelArray with labels manually assigned by the user to each of the analogs channels
digital IOSet of digital channels available in this device:
0 – Input
1 – Output
modeSpecifies the acquisition mode in which the device was used:
0 – Regular acquisition;
1 – Multiple synchronized devices;
2 – Started by a triggering signal
sync intervalTime interval (in seconds) at which a digital signal is sent by a “pacemaker” thread to a single device (used when the sync mode in on OpenSignals for synchronized data acquisition using multiple devices)
specialList of non-standard channels acquired (e.g. SpO2 sensors with I2C interface connected on biosignalsplux hubs).

Other Parameters

Top-Level KeyDescription
convertedValuesFormat of the sensor data in the acquisition file:
0 – Raw digital sensor values *
1 – Sensor values listed in their respective physical units

* you can find transfer functions to convert raw digital sensor values in the sensor documentation
keywordsFile key words (optional)
commentsAcquisition comments (optional)

Data Section: Acquisition Sensor Data

Sequence Number (Sample Number)

Regardless of the number of sensors used, OpenSignals files contain a sequence number series (nSeq column array in the header file) that attributes a sample/sequence number to the acquired sensor data:

# OpenSignals Text File Format. Version 1
[...]
"column": ["nSeq", "DI", "ECG"], 
[...]
# EndOfHeader

The sequential series is stored in the first column of the OpenSignals file as highlighted in the following example in bold:

# EndOfHeader
0	0	32647	
1	0	32632
2	0	32616	
3	0	32608	
4	0	32602	
5	0	32605	
...     ...     ...

Digital I/O States

Some devices, such as BITalino devices and biosignalsplux Hubs have digital input/output (I/0) channels (e.g. accessory ports) that allow you to record manual inputs from PLUX accessories (e.g. trigger buttons) or input/output synchronization signals.

The states of the digital I/O channels are recorded along with the acquired sensor data and stored in the columns in-between the Sequence Numbers and the Sensor Data.

As the number of digital I/O varies between devices, it’s important to consult the column information in the acquisition metadata to identify all available digital I/O channels, as in the following example containing only one Digital I/O channel.

# OpenSignals Text File Format. Version 1
[...]
"column": ["nSeq", "DI", "ECG"], 
[...]
# EndOfHeader

The digital I/O states are stored as follows: 0 -> no input/output signal available; 1 -> input/output signal available.

An example of the recorded states is highlighted in bold below:

# EndOfHeader
0	0	32647	
1	0	32632
2	0	32616	
3	0	32608	
4	1	32602	
5	1	32605	
...     ...     ...

Sensor Data

Sensor data is stored in the data section after the Sequence Number and Digital I/O states. The number of columns of sensor data matches the number of sensors used during the acquisition.

For instance, a single sensor acquisition using a biosignalsplux ECG results in the following header information:

# OpenSignals Text File Format. Version 1
[...]
"device": "biosignalsplux", 
"sensor": ["ECG"], 
"column": ["nSeq", "DI", "ECG"], 
[...]
# EndOfHeader

The acquisition results are listed as follows, where the first column represents the sample number (nSeq), the second column the digital I/O-state (DI) and the third-column the acquired ECG sensor values.

# EndOfHeader
0	0	32647	
1	0	32632
2	0	32616	
3	0	32608	
4	0	32602	
5	0	32605	
...     ...     ...

As previously stated, the number of columns of sensor data matches the number of sensors used during the acquisition. In an example of a multi-sensor acquisition using an ECG and an EMG sensor, the metadata would look as follows:

# OpenSignals Text File Format. Version 1
[...]
"device": "biosignalsplux", 
"sensor": ["ECG", "EMG"], 
"column": ["nSeq", "DI", "ECG", "EMG"], 
[...]
# EndOfHeader

The data section gains an additional column which lists the acquired sensor data as organised in the column metadata where the ECG data is listed in the penultimate column and the EMG data listed in the last column:

# EndOfHeader
0	0	32647	32672	
1	0	32632	32632
2	0	32616	32514
3	0	32608 	32539
4	0	32602	32616
5	0	32605	32492
...     ...     ...     ...

Raw vs. Converted Sensor Data

OpenSignals is capable of exporting both digital sensor data and sensor data converted into their respective physical units.

Digital sensor data is the result of digitisation of the analog sensor signals which results in sensor values ranging between 0 and 2^n-1 (n: sampling resolution). At a 16-bit resolution, this corresponds to sensor values between 0 and 65.535, while converted signals often have much lower ranges (e.g. -1.5mV to 1.5mV in case of an ECG signal).

Although digital values are often sufficient for further digital processing, these values are unpractical for physiological analysis.

The convertedValues parameter describes whether the presented file content is in raw digital sensor data (0, example on the left digital ECG data) or in the respective physical units (1, example on the right ECG in MV).

# OpenSignals Text File Format.
[...]
"device": "biosignalsplux", 
"sensor": ["ECG"],
"column": ["nSeq", "DI", "ECG"],
"convertedValues": 0,
[...]
# EndOfHeader
0	0	32647	
1	0	32632
2	0	32616	
3	0	32608	
4	0	32602	
5	0	32605	
...     ...     ...
# OpenSignals Text File Format.
[...]
"device": "biosignalsplux", 
"sensor": ["ECG"],
"column": ["nSeq", "DI", "ECG"],
"convertedValues": 1,
[...]
# EndOfHeader
0.0	0.0	-0.00544	
1.0	0.0	-0.00611	
2.0	0.0	-0.00683	
3.0	0.0	-0.00719	
4.0	0.0	-0.00746	
5.0	0.0	-0.00732
...     ...     ...
Updated on 24 de October de 2022

Was this article helpful?

Related Articles

Need Support?
Get one-to-one support for your Plux device or sensor from our team of biosignals experts.
Get Support