← network package

LSLInput

Receive data from the Lab Streaming Layer.

This node allows you to read a multi-channel stream from LSL (e.g., from an EEG device) in real time. In addition, this node can also read from a second stream that has event markers (for instance, from another application). Important: As of version 1.2, this node now synchronizes LSL stream clocks by default. If the output of this node will be streamed to disk using the Record To XDF node and you wish to retain the ground-truth timestamps then you should disable clock offset correction in this node. Important: Note that the this node does not dejitter the time stamps by default. If you do plotting or event-based processing then you must enable dejittering using the proc_dejitter parameter, or follow this node by a Dejitter Timestamps node to remove the jitter. The Lab Streaming Layer supports many different devices, such as EEG headsets, eye trackers, motion capture devices, audio, video, human-interface devices, and so on. With this node, you can read from any of these in a unified manner. On each tick of the NeuroPype scheduler, this node will output a packet that has all data from the given input stream(s) that came in since the last tick (which may be empty if there is no new data, and which may have a different length on each tick). Correspondingly, this node outputs either one or two streams depending on whether you include a marker stream. See the use_streamnames property for informatino on how these are named. The data stream channel labels will be parsed from the stream metadata. Additional metadata are typically stored in a LSL stream metadata field called desc. That information is parsed and retained in the stream properties' 'desc' field. For more information on LSL, please see the link below. More Info... Version 1.5.3

Ports/Properties

data

Data received.

• verbose name: Data
• default value: None
• port type: DataPort
• value type: Packet (can be None)
• data direction: OUT

query

LSL query string that identifies the data stream to search for. The simplest form is type='Modality' where modality can be EEG, Audio, VideoRaw, Gaze, MoCap, Control, or any other type string. The inlet will connect to an LSL stream that has its type field set to this value (and if there are multiple matches, the most recently created one of them will be connected to). If you have multiple devices with the same type on the network (e.g., possibly including playback or other users), it is recommended to make the query less broad by using the stream name, as in name='BioSemi', or starts-with(name,'BioSemi') for any stream starting with a given string (in which case you might also need to specify type='EEG' if there is a marker stream that starts with the same string. (Use Tools/LSL Streams in the Pipeline Designer to show current streams.) It is also possible to include the hostname using the 'and' keyword, as in: type='EEG' and hostname='MyLaptop1'. Other rarely-used fields include channel_count, nominal_srate, and source_id. The syntax is that of an XPath predicate, and supports many other features. If query is empty, no data streams will be found (only a marker stream if specified).

• verbose name: Query
• default value: type='EEG'
• port type: StringPort
• value type: str (can be None)

marker_query

LSL query string to find a marker stream. If non-empty, this node will try to connect to a marker stream in addition to the data stream, and once connected, the packets returned by this node will have both streams in them. The basic marker query is: type='Markers'. If there are multiple matching streams, the most recently created one of them will be connected to, but you can make it less broad by including the name of your marker stream in the query, as in: type='Markers' and name='SNAP-Markers'. You can also include the hostname if there are other machines with streams with the same name on the network (see help for the 'query' parameter for additional information on advanced syntax).

• verbose name: Marker Query
• default value:
• port type: StringPort
• value type: str (can be None)

localhost_only

Restricts the query and/or marker query to find streams originating from the local host only. Has the same effect as adding "and hostname='' to the LSL query string and/or marker query string, where is the name of the computer where this node is being run. This is useful in cases where multiple computers on the same network may be emitting a stream matching the query (i.e., same name/type).

• verbose name: Localhost Only
• default value: False
• port type: BoolPort
• value type: bool (can be None)

use_streamnames

Use the LSL stream name to name the stream in the Neuropype Packet. This applies to both the signal stream and the marker stream, if any. The stream name will be converted to lowercase, and spaces will be replaced with underscores, as per Packet stream naming convention. Also, in the unlikely event that the LSL signal and marker stream names are identical, the type will be appended to the stream name, two preserve the uniqueness of stream names in Neuropype (i.e., 'My LSL Stream' (type=EEG) will be named 'my_lsl_stream_eeg'). If False, streams in the Packet will be named after the LSL stream type, i.e., eeg or markers. Default is False for backward compatibility, but may be changed to True in a future release.

• verbose name: Use Stream Names In Packet
• default value: False
• port type: BoolPort
• value type: bool (can be None)

max_buflen

Maximum amount of data to buffer. In seconds. If more data than this remains in flight between the sender and receiver (e.g., because the network cable was unplugged, or your app was paused and stopped picking up data), then you will lose some data samples. In all other cases, the data sent will be delivered in order without omissions.

• verbose name: Maximum Buffer Length
• default value: 30
• port type: IntPort
• value type: int (can be None)

max_chunklen

Desired chunk length for transmission. In samples. This allows to override the preferred chunk size that the sender should send over the wire (if 0, the sender's preferred chunk size is used). Setting this does not guarantee that the returned packets will have this size, but it can be used as a hint to optimize transmission size, e.g., to tune network latency and overhead.

• verbose name: Desired Chunk Length
• default value: 0
• port type: IntPort
• value type: int (can be None)

max_blocklen

Maximum packet size emitted by node. This setting allows to return the data buffered in the LSL node in packets no larger than this size (in samples). IMPORTANT: if your pipeline is running at a low tick rate (e.g., 5Hz) and your data source is sending data at a high sampling rate (e.g., 5KHz) then NeuroPype would have to pick up more data per tick in order to keep up with the data stream than this limit. Therefore, if the limit is too small NeuroPype will fall behind the data stream up to the maximum buffer size and then start dropping samples. This value is mostly for internal performance optimization, but can also be used to keep subsequent nodes from stalling when a long packet would be received after a pause (instead, the graph will process the accumulated buffer in smaller chunks and remain responsive).

• verbose name: Maximum Output Packet Size
• default value: 1024
• port type: IntPort
• value type: int (can be None)

recover

Recover lost streams. Whether to attempt silent recovery of a lost LSL stream. There is usually no need to disable this feature.

• verbose name: Recover Lost Streams
• default value: True
• port type: BoolPort
• value type: bool (can be None)

channel_names

Override channel labels. If a list is provided, the channel labels of the data stream will be overridden accordingly.

• verbose name: Override Channel Labels
• default value: []
• port type: ListPort
• value type: list (can be None)

data_dtype

Optionally override the returned data type.

• verbose name: Output Value Type
• default value: float64
• port type: EnumPort
• value type: str (can be None)

nominal_rate

Override sampling rate. If set, the nominal sampling rate of the packets emitted by this node will be set to this value.

• verbose name: Override Sampling Rate
• default value: None
• port type: FloatPort
• value type: float (can be None)

diagnostics

Enable diagnostics. Can be used to monitor what kinds of data is being received from LSL, for debugging purposes.

• verbose name: Enable Diagnostics
• default value: False
• port type: BoolPort
• value type: bool (can be None)

resolve_minimum_time

Network scanning time to discover duplicate streams. If more than one stream is on the LSL network that matches the given query, this node will connect to the most recently created one of them. In order to ensure that all streams on the network have been discovered and none has been missed, the node will wait for at least this amount of time (in seconds).

• verbose name: Network Scanning Time
• default value: 0.5
• port type: FloatPort
• value type: float (can be None)

proc_clocksync

Perform automatic clock synchronization; equivalent to manually adding the time_correction() value to the received time stamps.

• verbose name: Synchronize Clocks
• default value: True
• port type: BoolPort
• value type: bool (can be None)

proc_dejitter

Remove jitter from time stamps. This will apply a smoothing algorithm to the received time stamps; the smoothing needs to see a minimum number of samples (30-120 seconds worst-case) until the remaining jitter is consistently below 1ms.

• verbose name: Dejitter Timestamps
• default value: False
• port type: BoolPort
• value type: bool (can be None)

proc_monotonize

Force the time-stamps to be monotonically ascending (only makes sense if timestamps are dejittered).

• verbose name: Ensure Timestamps Are Non-Decreasing
• default value: False
• port type: BoolPort
• value type: bool (can be None)

proc_threadsafe

Post-processing is thread- safe (same inlet can be read from by multiple threads); uses somewhat more CPU.

• verbose name: Thread-Safe Processing
• default value: False
• port type: BoolPort
• value type: bool (can be None)

omit_desc

Omit the stream description field from the output data. Even if the desc is omitted, it may still be used to build the block axes.

• verbose name: Omit Stream Description (Desc)
• default value: False
• port type: BoolPort
• value type: bool (can be None)

exclude_desc_fields

List of field names to drop from the desc metadata. Only used when omit_desc is False. 'channels' is a good field to drop because much of its information will already be preserved in the space axis.

• verbose name: Exclude Desc Fields
• default value: []
• port type: ListPort
• value type: list (can be None)

prealloc_buffer

Preallocate buffer to fetch data and reuse across fetches. This can provide a slight performance improvement.

• verbose name: Preallocate Buffer
• default value: True
• port type: BoolPort
• value type: bool (can be None)

set_breakpoint

Set a breakpoint on this node. If this is enabled, your debugger (if one is attached) will trigger a breakpoint.

• verbose name: Set Breakpoint (Debug Only)
• default value: False
• port type: BoolPort
• value type: bool (can be None)

metadata

User-definable meta-data associated with the node. Usually reserved for technical purposes.

• verbose name: Metadata
• default value: {}
• port type: DictPort
• value type: dict (can be None)