briely/liblsl-rust

Rust wrapper for liblsl.

Rust bindings for the liblsl library

Safe high-level bindings for the liblsl library, the main network library of the lab streaming layer (LSL).

The lab streaming layer is a peer-to-peer pub/sub system on the local network that allows for real-time exchange of multi-channel time series (plus their meta-data) between applications and machines, with built-in cross-device time synchronization.

The most common use case is in lab spaces to make, e.g., instrument data from different pieces of hardware (e.g., sensors) accessible in real time to client programs (e.g., experimentation scripts, recording programs, stream viewers, or live processing software). One of the main features of LSL is the uniform API that allows clients to read formatted multi-channel data from many device types (such as EEG, eye tracking, audio, human interface devices, events, etc.) with the same few lines of code.

Examples

See the scripts in the examples/ folder of the git repo for the fully-commented version of the below code. Examples for other use cases can be found there too.

Sending data to LSL

use lsl;
use lsl::Pushable;

fn main() -> Result<(), lsl::Error> {
    // declare a stream and create an outlet
    let info = lsl::StreamInfo::new(
        "BioSemi", "EEG", 8, 100.0,
        lsl::ChannelFormat::Float32, "myid234365")?;
    let outlet = lsl::StreamOutlet::new(&info, 0, 360)?;

    // stream some 8-channel data
    loop {
        let sample = vec![1, 2, 3, 4, 5, 6, 7, 8];
        outlet.push_sample(&sample)?;
        std::thread::sleep(std::time::Duration::from_millis(10));
    }
}

Receiving data from LSL

use lsl;
use lsl::Pullable;

fn main() -> Result<(), lsl::Error> {

    // resolve a data stream and create an inlet to read from it
    let res = lsl::resolve_bypred("name='BioSemi' and type='EEG'", 1, lsl::FOREVER)?;
    let inl = lsl::StreamInlet::new(&res[0], 360, 0, true)?;

    // read the streaming data and print the multi-channel samples 
    loop {
        let (sample, ts): (Vec<f32>, _) = inl.pull_sample(lsl::FOREVER)?;
        println!("got {:?} at time {}", sample, ts);
    }
}

Adding as a dependency

Add a new entry to your dependencies in Cargo.toml:

[dependencies]
lsl = "0.1.1"

Add the following to your code:

use lsl;

Getting the source code

You don't need to clone this repo to use this crate, but you may still need the right C/C++ system compiler as discussed in the below section on compiling so that cargo can build the native library for you.

git clone --recurse-submodules https://github.com/labstreaminglayer/liblsl-rust

Compiling

This crate currently links against the liblsl library statically (dynamic linking against the system library, if present, is planned for a future release). To compile the crate (and the native library), you need:

• CMake 3.12 or higher. If you install that via your system's package manager (e.g., brew install cmake on MacOS if you have Homebrew or sudo apt-get install cmake on Ubuntu), this might already pull in the second dependency (the system compiler), so building may already work.
• A system compiler; on Windows MS Visual Studio 2019 (older versions might work too), on Linux build-essentials, and on MacOS XCode CLI).

With these dependencies met, the package should compile for you. The following targets have been tested with this crate so far:

* x86_64-pc-windows-msvc
* x86_64-unknown-linux-gnu
* x86_64-apple-darwin

API Documentation

Doocumentation for the most recent release can be found at docs.rs.

The lsl-sys crate

The lsl crate depends on a lower-level lsl-sys crate that provides the raw (unsafe) native library bindings. Using that crate directly is not recommended (you might as well be coding in C). These bindings are autogenerated and can be updated to a newer upstream native library version by following the instructions in that crate's readme.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the lsl crate by you, shall be licensed as MIT, without any additional terms or conditions.