Deepana Ishtaweera
tof library
README.md@0:1c8c01640f54, 2019-10-01 (annotated)
- Committer:
- deepanaishtaweera174
- Date:
- Tue Oct 01 12:33:27 2019 +0000
- Revision:
- 0:1c8c01640f54
hey
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| deepanaishtaweera174 | 0:1c8c01640f54 | 1 | # VL53L0X library for mbed OS 5 |
| deepanaishtaweera174 | 0:1c8c01640f54 | 2 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 3 | [](https://github.com/dbaba/vl53l0x-mbedos/releases/latest) |
| deepanaishtaweera174 | 0:1c8c01640f54 | 4 | [](https://travis-ci.org/dbaba/vl53l0x-mbedos) |
| deepanaishtaweera174 | 0:1c8c01640f54 | 5 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 6 | ## Summary |
| deepanaishtaweera174 | 0:1c8c01640f54 | 7 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 8 | This is a library for mbed OS that helps interface with ST's [VL53L0X time-of-flight distance sensor](https://www.pololu.com/product/2490). The library makes it simple to configure the sensor and read range data from it via I²C. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 9 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 10 | This project is a fork of [www.pololu.com](https://www.pololu.com/)'s [vl53l0x-arduino](https://github.com/pololu/vl53l0x-arduino). |
| deepanaishtaweera174 | 0:1c8c01640f54 | 11 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 12 | ## Supported platforms |
| deepanaishtaweera174 | 0:1c8c01640f54 | 13 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 14 | This library is designed to work with the mbed-cli v0.9.1 or later. This library should support any mbed enabled board with mbed OS 5. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 15 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 16 | ## Getting started |
| deepanaishtaweera174 | 0:1c8c01640f54 | 17 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 18 | ### Hardware |
| deepanaishtaweera174 | 0:1c8c01640f54 | 19 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 20 | A [VL53L0X carrier](https://www.pololu.com/product/2490) can be purchased from Pololu's website. Before continuing, careful reading of the [product page](https://www.pololu.com/product/2490) as well as the VL53L0X datasheet is recommended. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 21 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 22 | Make the following connections between the mbed and the VL53L0X board: |
| deepanaishtaweera174 | 0:1c8c01640f54 | 23 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 24 | #### mbed boards with [pololu VL53L0X board](https://www.pololu.com/product/2490) |
| deepanaishtaweera174 | 0:1c8c01640f54 | 25 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 26 | * internal pull-up resistors are implemented |
| deepanaishtaweera174 | 0:1c8c01640f54 | 27 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 28 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 29 | mbed VL53L0X board |
| deepanaishtaweera174 | 0:1c8c01640f54 | 30 | ------- ------------- |
| deepanaishtaweera174 | 0:1c8c01640f54 | 31 | 3V3 - VDD |
| deepanaishtaweera174 | 0:1c8c01640f54 | 32 | GND - GND |
| deepanaishtaweera174 | 0:1c8c01640f54 | 33 | SDA - SDA |
| deepanaishtaweera174 | 0:1c8c01640f54 | 34 | SCL - SCL |
| deepanaishtaweera174 | 0:1c8c01640f54 | 35 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 36 | #### mbed boards with ST VL53L0X |
| deepanaishtaweera174 | 0:1c8c01640f54 | 37 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 38 | e.g. [53L0-SATEL-I1](http://www.st.com/content/st_com/en/products/evaluation-tools/product-evaluation-tools/proximity-sensors-and-imaging-ics-eval-boards/53l0-satel-i1.html) |
| deepanaishtaweera174 | 0:1c8c01640f54 | 39 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 40 | mbed VL53L0X / 53L0-SATEL-I1 |
| deepanaishtaweera174 | 0:1c8c01640f54 | 41 | ------- ------------- |
| deepanaishtaweera174 | 0:1c8c01640f54 | 42 | 3V3 -+--+- VDD |
| deepanaishtaweera174 | 0:1c8c01640f54 | 43 | | | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 44 | <4K7>| |
| deepanaishtaweera174 | 0:1c8c01640f54 | 45 | |<4K7> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 46 | | | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 47 | SDA -+--|- SDA |
| deepanaishtaweera174 | 0:1c8c01640f54 | 48 | SCL ----+- SCL |
| deepanaishtaweera174 | 0:1c8c01640f54 | 49 | GND ------ GND |
| deepanaishtaweera174 | 0:1c8c01640f54 | 50 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 51 | ### Software |
| deepanaishtaweera174 | 0:1c8c01640f54 | 52 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 53 | Use [`mbed-cli`](https://github.com/ARMmbed/mbed-cli) to install this library. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 54 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 55 | ``` |
| deepanaishtaweera174 | 0:1c8c01640f54 | 56 | mbed add https://github.com/dbaba/vl53l0x-mbedos |
| deepanaishtaweera174 | 0:1c8c01640f54 | 57 | ``` |
| deepanaishtaweera174 | 0:1c8c01640f54 | 58 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 59 | ## ST's VL53L0X API and this library |
| deepanaishtaweera174 | 0:1c8c01640f54 | 60 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 61 | Most of the functionality of this library is based on the [VL53L0X API](http://www.st.com/content/st_com/en/products/embedded-software/proximity-sensors-software/stsw-img005.html) provided by ST (STSW-IMG005), and some of the explanatory comments in the code are quoted or paraphrased from the API source code, API user manual (UM2039), and the VL53L0X datasheet. For more explanation about the library code and how it was derived from the API, see the comments in VL53L0X.cpp. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 62 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 63 | This library is intended to provide a quicker and easier way to get started using the VL53L0X with an Arduino-compatible controller, in contrast to customizing and compiling ST's API for the Arduino. The library has a more streamlined interface, as well as smaller storage and memory footprints. However, it does not implement some of the more advanced functionality available in the API (for example, calibrating the sensor to work well under a cover glass), and it has less robust error checking. For advanced applications, especially when storage and memory are less of an issue, consider using the VL53L0X API directly. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 64 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 65 | ## Library reference |
| deepanaishtaweera174 | 0:1c8c01640f54 | 66 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 67 | * `uint8_t last_status`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 68 | The status of the last I²C write transmission. See the [`Wire.endTransmission()` documentation](http://arduino.cc/en/Reference/WireEndTransmission) for return values. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 69 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 70 | * `VL53L0X(void)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 71 | Constructor. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 72 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 73 | * `void setAddress(uint8_t new_addr)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 74 | Changes the I²C slave device address of the VL53L0X to the given value (7-bit). |
| deepanaishtaweera174 | 0:1c8c01640f54 | 75 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 76 | * `uint8_t getAddress(void)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 77 | Returns the current I²C address. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 78 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 79 | * `bool init(bool io_2v8 = true)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 80 | Iniitializes and configures the sensor. If the optional argument `io_2v8` is true (the default if not specified), the sensor is configured for 2V8 mode (2.8 V I/O); if false, the sensor is left in 1V8 mode. The return value is a boolean indicating whether the initialization completed successfully. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 81 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 82 | * `void writeReg(uint8_t reg, uint8_t value)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 83 | Writes an 8-bit sensor register with the given value. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 84 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 85 | Register address constants are defined by the regAddr enumeration type in VL53L0X.h.<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 86 | Example use: `sensor.writeReg(VL53L0X::SYSRANGE_START, 0x01);` |
| deepanaishtaweera174 | 0:1c8c01640f54 | 87 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 88 | * `void writeReg16Bit(uint8_t reg, uint16_t value)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 89 | Writes a 16-bit sensor register with the given value. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 90 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 91 | * `void writeReg32Bit(uint8_t reg, uint32_t value)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 92 | Writes a 32-bit sensor register with the given value. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 93 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 94 | * `uint8_t readReg(uint8_t reg)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 95 | Reads an 8-bit sensor register and returns the value read. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 96 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 97 | * `uint16_t readReg16Bit(uint8_t reg)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 98 | Reads a 16-bit sensor register and returns the value read. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 99 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 100 | * `uint32_t readReg32Bit(uint8_t reg)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 101 | Reads a 32-bit sensor register and returns the value read. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 102 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 103 | * `void writeMulti(uint8_t reg, uint8_t const * src, uint8_t count)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 104 | Writes an arbitrary number of bytes from the given array to the sensor, starting at the given register. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 105 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 106 | * `void readMulti(uint8_t reg, uint8_t * dst, uint8_t count)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 107 | Reads an arbitrary number of bytes from the sensor, starting at the given register, into the given array. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 108 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 109 | * `bool setSignalRateLimit(float limit_Mcps)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 110 | Sets the return signal rate limit to the given value in units of MCPS (mega counts per second). This is the minimum amplitude of the signal reflected from the target and received by the sensor necessary for it to report a valid reading. Setting a lower limit increases the potential range of the sensor but also increases the likelihood of getting an inaccurate reading because of reflections from objects other than the intended target. This limit is initialized to 0.25 MCPS by default. The return value is a boolean indicating whether the requested limit was valid. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 111 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 112 | * `float getSignalRateLimit(void)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 113 | Returns the current return signal rate limit in MCPS. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 114 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 115 | * `bool setMeasurementTimingBudget(uint32_t budget_us)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 116 | Sets the measurement timing budget to the given value in microseconds. This is the time allowed for one range measurement; a longer timing budget allows for more accurate measurements. The default budget is about 33000 microseconds, or 33 ms; the minimum is 20 ms. The return value is a boolean indicating whether the requested budget was valid. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 117 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 118 | * `uint32_t getMeasurementTimingBudget(void)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 119 | Returns the current measurement timing budget in microseconds. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 120 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 121 | * `bool setVcselPulsePeriod(vcselPeriodType type, uint8_t period_pclks)` |
| deepanaishtaweera174 | 0:1c8c01640f54 | 122 | Sets the VCSEL (vertical cavity surface emitting laser) pulse period for the given period type (`VL53L0X::VcselPeriodPreRange` or `VL53L0X::VcselPeriodFinalRange`) to the given value (in PCLKs). Longer periods increase the potential range of the sensor. Valid values are (even numbers only): |
| deepanaishtaweera174 | 0:1c8c01640f54 | 123 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 124 | Pre: 12 to 18 (initialized to 14 by default)<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 125 | Final: 8 to 14 (initialized to 10 by default) |
| deepanaishtaweera174 | 0:1c8c01640f54 | 126 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 127 | The return value is a boolean indicating whether the requested period was valid. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 128 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 129 | * `uint8_t getVcselPulsePeriod(vcselPeriodType type)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 130 | Returns the current VCSEL pulse period for the given period type. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 131 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 132 | * `void startContinuous(uint32_t period_ms = 0)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 133 | Starts continuous ranging measurements. If the optional argument `period_ms` is 0 (the default if not specified), continuous back-to-back mode is used (the sensor takes measurements as often as possible); if it is nonzero, continuous timed mode is used, with the specified inter-measurement period in milliseconds determining how often the sensor takes a measurement. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 134 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 135 | * `void stopContinuous(void)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 136 | Stops continuous mode. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 137 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 138 | * `uint8_t readRangeContinuousMillimeters(void)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 139 | Returns a range reading in millimeters when continuous mode is active. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 140 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 141 | * `uint16_t readRangeSingleMillimeters(void)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 142 | Performs a single-shot ranging measurement and returns the reading in millimeters. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 143 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 144 | * `void setTimeout(uint16_t timeout)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 145 | Sets a timeout period in milliseconds after which read operations will abort if the sensor is not ready. A value of 0 disables the timeout. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 146 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 147 | * `uint16_t getTimeout(void)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 148 | Returns the current timeout period setting. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 149 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 150 | * `bool timeoutOccurred(void)`<br> |
| deepanaishtaweera174 | 0:1c8c01640f54 | 151 | Indicates whether a read timeout has occurred since the last call to `timeoutOccurred()`. |
| deepanaishtaweera174 | 0:1c8c01640f54 | 152 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 153 | ## Version history |
| deepanaishtaweera174 | 0:1c8c01640f54 | 154 | |
| deepanaishtaweera174 | 0:1c8c01640f54 | 155 | * 1.0.0 (2016 Sep 12): Initial release for mbed OS 5 |