Skip to content

Latest commit

 

History

History

vl53l5cx_uld

README.md

v53l5cx_uld

The uld part for the VL53L5CX time-of-flight sensor takes care of C/Rust adaptation and translation of the results from 1D vectors to 2D matrices, and enums instead of integer values.

YOU SHOULD NOT USE THIS LEVEL IN AN APPLICATION. Use the vl53l5cx API instead (which depends on us). Before that, though, read on, install the build requirements so that the higher API can be built.

Pre-reading

The build

This build is relatively complex. You can just follow the instructions below, but in case there are problems, the above map may be of help.

Requirements

clang

$ sudo apt install libclang-dev clang

bindgen

$ cargo install bindgen-cli

Note: Bindgen docs recommend using it as a library, but we prefer to use it as a command line tool.

The vendor C libary

The VL53L5CX_ULD_API (ULD C driver) is a separate download.

  1. Fetch it from the vendor (Get software > Get latest > check the license > ...)

    Note: You can "Download as a guest", after clicking the license.

  2. Unzip it to a suitable location

  3. export VL53L5CX_ULD_API={your-path}/VL53L5CX_ULD_API

Supported dev kits

The workflow has been tested on these MCUs:
esp32c6 ESP32-C6-DevKitM-01
esp32c3 ESP32-C3-DevKitC-02 with JTAG/USB wiring added

❗️ESP32-C3 has problems with long I2C transfers, in combination with the probe-rs tool. Sadly, we cannot really recommend using it. See ../../TROUBLES.md for details.

Connection to the devkit

In order to run the example(s), you need:

  • a devkit connected:

     $ probe-rs list
 The following debug probes were found:
 [0]: ESP JTAG -- 303a:1001:54:32:04:41:7D:60 (EspJtag)

  • at least one SATEL board

Wiring

Same as in ../vl53l5cx/README.md.

Only one device is needed.

Compiling

$ cargo build --release --lib

This compiles the library, and is a good place to start.

The library is fully hardware agnostic. This is something we inherit from the approach of the vendor ULD C API. Your code brings in, for example, how to drive the I2C bus. This means only tests is MCU specific.

If there are problems with the build, you may want to run the Makefile separately:

$ make manual

Running examples

There are some ULD level examples used to help development:

$ make -f Makefile.dev m3
[...]
0.870700 [INFO ] Target powered off and on again.
0.874266 [DEBUG] Ping succeeded: 0xf0,0x02
3.639815 [INFO ] Init succeeded
4.008711 [DEBUG] INT after: 24.442ms
4.024860 [INFO ] Data #0 (32°C)
4.024911 [INFO ] .target_status:    [[[SemiValid(6), SemiValid(6), SemiValid(6), SemiValid(6)], [SemiValid(6), SemiValid(6), SemiValid(6), SemiValid(6)], [SemiValid(6), SemiValid(6), SemiValid(6), SemiValid(6)], [SemiValid(6), SemiValid(6), SemiValid(6), SemiValid(6)]], [[SemiValid(6), SemiValid(6), SemiValid(6), SemiValid(6)], [SemiValid(6), SemiValid(6), SemiValid(6), SemiValid(6)], [SemiValid(6), SemiValid(6), SemiValid(6), SemiValid(6)], [SemiValid(6), SemiValid(6), SemiValid(6), SemiValid(6)]]]
4.025215 [INFO ] .targets_detected: [[2, 2, 2, 2], [2, 2, 2, 2], [2, 2, 2, 2], [2, 2, 2, 2]]
4.025322 [INFO ] .ambient_per_spad: [[1, 1, 1, 2], [1, 2, 1, 0], [1, 1, 1, 1], [0, 0, 1, 1]]
4.025446 [INFO ] .spads_enabled:    [[16128, 15872, 15104, 15872], [15104, 15104, 15872, 12800], [15616, 14848, 15616, 11264], [15360, 15360, 15872, 10240]]
4.025566 [INFO ] .signal_per_spad:  [[[137, 144, 222, 345], [154, 92, 168, 325], [120, 105, 204, 415], [112, 165, 262, 572]], [[122, 34, 26, 16], [148, 20, 12, 10], [83, 6, 16, 11], [28, 22, 26, 12]]]
4.025800 [INFO ] .range_sigma_mm:   [[[3, 2, 1, 1], [4, 3, 2, 1], [4, 3, 1, 1], [2, 2, 1, 1]], [[3, 5, 7, 9], [2, 12, 17, 12], [6, 28, 8, 12], [8, 8, 6, 13]]]
4.025994 [INFO ] .distance_mm:      [[[38, 0, 1, 0], [142, 11, 0, 0], [73, 7, 0, 0], [0, 0, 0, 0]], [[300, 202, 907, 933], [253, 1043, 808, 646], [220, 642, 708, 724], [393, 606, 642, 653]]]
4.026182 [INFO ] .reflectance:      [[[0, 0, 0, 0], [4, 0, 0, 0], [1, 0, 0, 0], [0, 0, 0, 0]], [[15, 2, 30, 19], [13, 31, 11, 6], [5, 3, 12, 8], [6, 11, 15, 8]]]
4.069097 [DEBUG] INT after: 42.756ms

Troubleshooting

See TROUBLES.md.

References

VL53L5CX

SATEL