braincore/vl53l1x-rs

A Rust library for the VL531X Time-of-Flight rangefinder.

VL53L1X library for Rust on Linux

A Rust library for the VL53L1x Time-of-Flight sensor. Also, a shared library for using the VL53L1X on Linux without Rust.

Usage

extern crate vl53l1x;

pub fn main() {
    let mut vl = vl53l1x::Vl53l1x::new(1, None).unwrap();
    vl.init().unwrap();
    vl.start_ranging(vl53l1x::DistanceMode::Long).unwrap();
    loop {
        println!("Sample: {:?}", vl.read_sample());
    }
}

See examples/scan.rs for a more thorough example.

Note that if you use the sensor with 2.8 Volts (instead of the default 1.8V) you should enable the cargo feature i2c-2v8-mode, see the Datasheet (section 5.2) for more information. Most existing breakout-boards run at 2.8V (or even 3.3V) so you probably want this. You can do so by putting the following in your Cargo.toml:

[dependencies.vl53l1x]
version = "1"
features = ["i2c-2v8-mode"]

Features

• Set distance mode (short, mid, long).
• Set timing budget and inter measurement period.
• Change i2c address of device.
• Get/set region of interest to adjust field of view.
• Makefile can be used to generate static or dynamic library without Rust.
• Verified that the ST library and additions made do not leak memory using valgrind.

Approach

This compiles a C library that is then statically linked to your Rust program via the crate. The C library is based on the official ST C API. Their headers conveniently abstract away platform-specific i2c implementations into vl53l1_platform.c which I've used to implement the Linux i2c interface (linux/i2c-dev.h).

This approach differs from VL53L1X_Arduino_Library which reimplements the official library with mostly replays of i2c data stream captures. That approach results in a smaller memory footprint (good for Arduinos), but is less featured and more fragile. e.g. I've observed discrepancies in distance measurements between their library and the official. Their painstaking work is a direct result of ST not releasing an official i2c register datasheet for the device.

This approach is similar to vl53l1x-python. However, that relies on Python providing an i2c function. This library implements the i2c adapter in C and is fully self-contained, which makes it ideal for being published as a shared library libvl53l1x.

Cross Compilation

Specify a custom C-compiler and archive utility using the VL53L1X_CC and VL53L1X_AR env args. For example:

VL53L1X_CC=arm-linux-gnueabihf-gcc VL53L1X_AR=arm-linux-gnueabihf-ar cargo build

Platform

This library has only been tested on the Raspberry Pi 3 B+.

NOTE: Dynamically-Linked Library

At some point, the dynamically-linked library will be published in its own repo without Rust. For now, you can checkout the repo and run the following from the root of the repository:

make libvl53l1x_api.so

The lib will be in the build directory.

Todo

• Publish libvl53l1x for non-Rust, Linux usage.

Resources

• Datasheet

Licenses

ST's library is dual licensed with BSD and their own proprietary one. The rest is licensed under MIT.

vl53l1x-rs's Issues

Uninitialised array in VL53L1_RdDWord

In function

VL53L1_Error VL53L1_RdDWord(VL53L1_DEV Dev, uint16_t index, uint32_t *data) {
    uint8_t buf[4];
    VL53L1_ReadMulti(Dev, index, (uint8_t *)data, 4);
    *data = (buf[0] << 24) | (buf[1] << 16) | (buf[2] << 8) | buf[3];
    VL53L1_Error Status = VL53L1_ERROR_NONE;
    return Status;
}

I think that instead of

VL53L1_ReadMulti(Dev, index, (uint8_t *)data, 4);

it should be

VL53L1_ReadMulti(Dev, index, (uint8_t *)buf, 4);

because that is only thing that makes sense.

Enable 2.8V mode

Hi, thanks for writing and open-sourcing this binding!

Is there a way to activate the 2.8V mode for the Vl53l1x? It seems that by default the sensor operates in 1.8V mode and has to be switched by compiling the ST-drivers with the USE_I2C_2V8 preprocessor macro defined (see driver user manual section 2.5.9, although it says USE_I2C_2V8k there which seems to be wrong...).

This is also done e.g. in the Pololu implementation and probably makes sense as a default since most existing breakout boards assume that the sensor is used with 2.8 Volts.

Maybe this could be done using a Cargo feature and then passed on in build.rs to the Makefile?

Thanks!
Michael