# Rust bindings for the liblsl library
Safe high-level bindings for the `liblsl` library, the main network library of
the [lab streaming layer](https://github.com/sccn/labstreaminglayer) (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/](https://github.com/labstreaminglayer/liblsl-rust/tree/main/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
```rust
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
```rust
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`:
```toml
[dependencies]
lsl = "0.1.1"
```
Add the following to your code:
```rust
use lsl;
```
## Getting the source code
```
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](https://cmake.org/download/) 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](https://brew.sh/) 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](https://visualstudio.microsoft.com/) 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](https://docs.rs/lsl).
#### The [lsl-sys](https://crates.io/crates/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](https://github.com/labstreaminglayer/liblsl-rust/blob/main/lsl-sys/README.md).
## 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.