Yoctopuce Yocto-RangeFinder User manual

Yocto-RangeFinder, User's guide

Table of contents
1. Introduction 1..............................................................................................................................
1.1. Safety Information 2.................................................................................................................
2. Presentation 3.............................................................................................................................
2.1. Common elements 3................................................................................................................
2.2. Specific elements 4..................................................................................................................
2.3. Optional accessories 5............................................................................................................
3. Working principle and limitations 7................................................................................
3.1. Ambient light 7.........................................................................................................................
3.2. Color and reflectivity of the detected objects 7........................................................................
3.3. Workings behind a protective glass 7......................................................................................
3.4. Working modes 8.....................................................................................................................
3.5. Temperature variations 8.........................................................................................................
3.6. Hardware calibration procedures 8..........................................................................................
4. First steps 13...............................................................................................................................
4.1. Prerequisites 13.......................................................................................................................
4.2. Testing USB connectivity 14....................................................................................................
4.3. Localization 15.........................................................................................................................
4.4. Test of the module 15..............................................................................................................
4.5. Configuration 15......................................................................................................................
5. Assembly and connections 17..........................................................................................
5.1. Fixing 17..................................................................................................................................
5.2. Moving the sensor away 18.....................................................................................................
5.3. USB power distribution 19.......................................................................................................
6. Programming, general concepts 21................................................................................
6.1. Programming paradigm 21......................................................................................................
6.2. The Yocto-RangeFinder module 23.........................................................................................
6.3. Module control interface 24.....................................................................................................
6.4. RangeFinder function interface 25...........................................................................................
6.5. LightSensor function interface 26............................................................................................
6.6. Temperature function interface 28...........................................................................................

6.7. DataLogger function interface 29.............................................................................................
6.8. What interface: Native, DLL or Service ? 30............................................................................
6.9. Programming, where to start? 32.............................................................................................
7. Using the Yocto-RangeFinder in command line 33................................................
7.1. Installing 33..............................................................................................................................
7.2. Use: general description 33.....................................................................................................
7.3. Control of the RangeFinder function 34...................................................................................
7.4. Control of the module part 34..................................................................................................
7.5. Limitations 35...........................................................................................................................
8. Using Yocto-RangeFinder with JavaScript / EcmaScript 37.............................
8.1. Blocking I/O versus Asynchronous I/O in JavaScript 37..........................................................
8.2. Using Yoctopuce library for JavaScript / EcmaScript 2017 38.................................................
8.3. Control of the RangeFinder function 40...................................................................................
8.4. Control of the module part 43..................................................................................................
8.5. Error handling 46.....................................................................................................................
9. Using Yocto-RangeFinder with PHP 47........................................................................
9.1. Getting ready 47......................................................................................................................
9.2. Control of the RangeFinder function 47...................................................................................
9.3. Control of the module part 49..................................................................................................
9.4. HTTP callback API and NAT filters 52.....................................................................................
9.5. Error handling 55.....................................................................................................................
10. Using Yocto-RangeFinder with C++ 57......................................................................
10.1. Control of the RangeFinder function 57.................................................................................
10.2. Control of the module part 59................................................................................................
10.3. Error handling 62...................................................................................................................
10.4. Integration variants for the C++ Yoctopuce library 62............................................................
11. Using Yocto-RangeFinder with Objective-C 65.....................................................
11.1. Control of the RangeFinder function 65.................................................................................
11.2. Control of the module part 67................................................................................................
11.3. Error handling 69...................................................................................................................
12. Using Yocto-RangeFinder with Visual Basic .NET 71........................................
12.1. Installation 71.........................................................................................................................
12.2. Using the Yoctopuce API in a Visual Basic project 71...........................................................
12.3. Control of the RangeFinder function 72.................................................................................
12.4. Control of the module part 74................................................................................................
12.5. Error handling 76...................................................................................................................
13. Using Yocto-RangeFinder with C# 77.........................................................................
13.1. Installation 77.........................................................................................................................
13.2. Using the Yoctopuce API in a Visual C# project 77...............................................................
13.3. Control of the RangeFinder function 78.................................................................................
13.4. Control of the module part 80................................................................................................
13.5. Error handling 82...................................................................................................................
14. Using Yocto-RangeFinder with Delphi 85.................................................................
14.1. Preparation 85.......................................................................................................................
14.2. Control of the RangeFinder function 85.................................................................................
14.3. Control of the module part 87................................................................................................

14.4. Error handling 90...................................................................................................................
15. Using the Yocto-RangeFinder with Python 91.......................................................
15.1. Source files 91.......................................................................................................................
15.2. Dynamic library 91.................................................................................................................
15.3. Control of the RangeFinder function 91.................................................................................
15.4. Control of the module part 93................................................................................................
15.5. Error handling 95...................................................................................................................
16. Using the Yocto-RangeFinder with Java 97.............................................................
16.1. Getting ready 97....................................................................................................................
16.2. Control of the RangeFinder function 97.................................................................................
16.3. Control of the module part 99................................................................................................
16.4. Error handling 101.................................................................................................................
17. Using the Yocto-RangeFinder with Android 103...................................................
17.1. Native access and VirtualHub 103.........................................................................................
17.2. Getting ready 103..................................................................................................................
17.3. Compatibility 103...................................................................................................................
17.4. Activating the USB port under Android 104...........................................................................
17.5. Control of the RangeFinder function 106...............................................................................
17.6. Control of the module part 108..............................................................................................
17.7. Error handling 113.................................................................................................................
18. Advanced programming 115............................................................................................
18.1. Event programming 115........................................................................................................
18.2. The data logger 118...............................................................................................................
18.3. Sensor calibration 120...........................................................................................................
19. Firmware Update 125............................................................................................................
19.1. The VirtualHub or the YoctoHub 125.....................................................................................
19.2. The command line library 125................................................................................................
19.3. The Android application Yocto-Firmware 125........................................................................
19.4. Updating the firmware with the programming library 126......................................................
19.5. The "update" mode 128.........................................................................................................
20. Using with unsupported languages 129....................................................................
20.1. Command line 129.................................................................................................................
20.2. VirtualHub and HTTP GET 129.............................................................................................
20.3. Using dynamic libraries 131...................................................................................................
20.4. Porting the high level library 134...........................................................................................
21. High-level API Reference 135..........................................................................................
21.1. General functions 136............................................................................................................
21.2. Module control interface 166.................................................................................................
21.3. RangeFinder function interface 229.......................................................................................
21.4. Temperature function interface 294.......................................................................................
21.5. LightSensor function interface 357........................................................................................
21.6. DataLogger function interface 414.........................................................................................
21.7. Recorded data sequence 458................................................................................................
21.8. Measured value 472..............................................................................................................
22. Troubleshooting 479.............................................................................................................
22.1. Where to start? 479...............................................................................................................

22.2. Linux and USB 479................................................................................................................
22.3. ARM Platforms: HF and EL 480.............................................................................................
22.4. Powered module but invisible for the OS 480........................................................................
22.5. Another process named xxx is already using yAPI 480.........................................................
22.6. Disconnections, erratic behavior 480.....................................................................................
22.7. Damaged device 480.............................................................................................................
23. Characteristics 483................................................................................................................
Blueprint 485...................................................................................................................................
Index 487.............................................................................................................................................

1. Introduction
The Yocto-RangeFinder is a 58x20mm module enabling you to detect the presence of objects up to
one or two meters away depending on conditions, and to evaluate the distance of the closest object.
This module is based on a "ToF" (Time of Light) technology. The sensor emits laser pulses and
measures the time they take to come back to the sensor after reflection against an obstacle. The
Yocto-RangeFinder can also measure its own temperature, in order to determine when a new
calibration is required, and estimate the ambient light.
This small and relatively cheap module, using a quite harmless laser, does not pretend to be a true
telemeter that you could use to measures distances with a millimeter accuracy. Its accuracy is
limited, and the detection range depends on the environment. You can find tables describing the
expected accuracy depending on the surrounding conditions in the section called Working principles
and limitations of this user's guide.
The Yocto-RangeFinder module
The Yocto-RangeFinder is intended to be used as laboratory equipment, or as industrial process-
control equipment, but also for similar applications in domestic and commercial environments 1.
Yoctopuce thanks you for buying this Yocto-RangeFinder and sincerely hopes that you will be
satisfied with it. The Yoctopuce engineers have put a large amount of effort to ensure that your
Yocto-RangeFinder is easy to install anywhere and easy to drive from a maximum of programming
languages. If you are nevertheless disappointed with this module, do not hesitate to contact
Yoctopuce support2.
1 i.e. the scope of IEC 61010-1:2010 international standard
2 [email protected]
www.yoctopuce.com 1

1.1. Safety Information
Caution: The Yocto-RangeFinder is not certified for use in hazardous locations,
explosive environments, or life-threatening applications.
Caution: The Yocto-RangeFinder is not certified for use in medical
environments or life-support applications.
1. Introduction
2 www.yoctopuce.com

2. Presentation
1: Micro-B USB socket 5: ToF Laser sensor
2: Yocto-button 6: Temperature sensor
3: Yocto-led 7: Pad for Picoflex connector
4: Detection led
2.1. Common elements
All Yocto-modules share a number of common functionalities.
USB connector
Yoctopuce modules all come with a micro-B USB socket. The corresponding cables are not the most
common, but the sockets are the smallest available.
Warning: the USB connector is simply soldered in surface and can be pulled out if the USB plug acts
as a lever. In this case, if the tracks stayed in position, the connector can be soldered back with a
good iron and using flux to avoid bridges. Alternatively, you can solder a USB cable directly in the
1.27mm-spaced holes near the connector.
Yocto-button
The Yocto-button has two functionalities. First, it can activate the Yocto-beacon mode (see below
under Yocto-led). Second, if you plug in a Yocto-module while keeping this button pressed, you can
www.yoctopuce.com 3

then reprogram its firmware with a new version. Note that there is a simpler UI-based method to
update the firmware, but this one works even in case of severely damaged firmware.
Yocto-led
Normally, the Yocto-led is used to indicate that the module is working smoothly. The Yocto-led then
emits a low blue light which varies slowly, mimicking breathing. The Yocto-led stops breathing when
the module is not communicating any more, as for instance when powered by a USB hub which is
disconnected from any active computer.
When you press the Yocto-button, the Yocto-led switches to Yocto-beacon mode. It starts flashing
faster with a stronger light, in order to facilitate the localization of a module when you have several
identical ones. It is indeed possible to trigger off the Yocto-beacon by software, as it is possible to
detect by software that a Yocto-beacon is on.
The Yocto-led has a third functionality, which is less pleasant: when the internal software which
controls the module encounters a fatal error, the Yocto-led starts emitting an SOS in morse 1. If this
happens, unplug and re-plug the module. If it happens again, check that the module contains the
latest version of the firmware, and, if it is the case, contact Yoctopuce support2.
Current sensor
Each Yocto-module is able to measure its own current consumption on the USB bus. Current supply
on a USB bus being quite critical, this functionality can be of great help. You can only view the
current consumption of a module by software.
Serial number
Each Yocto-module has a unique serial number assigned to it at the factory. For Yocto-RangeFinder
modules, this number starts with YRNGFND1. The module can be software driven using this serial
number. The serial number cannot be modified.
Logical name
The logical name is similar to the serial number: it is a supposedly unique character string which
allows you to reference your module by software. However, in the opposite of the serial number, the
logical name can be modified at will. The benefit is to enable you to build several copies of the same
project without needing to modify the driving software. You only need to program the same logical
name in each copy. Warning: the behavior of a project becomes unpredictable when it contains
several modules with the same logical name and when the driving software tries to access one of
these modules through its logical name. When leaving the factory, modules do not have an assigned
logical name. It is yours to define.
2.2. Specific elements
The sensor
The Yocto-RangeFinder is based on a VL53L0X sensor manufactured by ST Microelectronics. It
contains a laser coupled to an infrared light detector. This laser is conformed to the "LASER CLASS
1" security limits and does not present any particular danger, as long as its normal beam is not
altered, either by optical devices or otherwise. This sensor does not require any specific
maintenance, but make sure that it stays clean.
The detection led
The detection led signals when the Yocto-RangeFinder has detected an object less than one meter
away.
1 short-short-short long-long-long short-short-short
2 [email protected]
2. Presentation
4 www.yoctopuce.com