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 processcontrol 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
support@yoctopuce.com
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
support@yoctopuce.com
2. Presentation
4 www.yoctopuce.com
2.3. Optional accessories
The accessories below are not necessary to use the Yocto-RangeFinder module but might be useful
depending on your project. These are mostly common products that you can buy from your favorite
hacking store. To save you the tedious job of looking for them, most of them are also available on the
Yoctopuce shop.
Screws and spacers
In order to mount the Yocto-RangeFinder module, you can put small screws in the 2.5mm assembly
holes, with a screw head no larger than 4.5mm. The best way is to use threaded spacers, which you
can then mount wherever you want. You can find more details on this topic in the chapter about
assembly and connections.
Micro-USB hub
If you intend to put several Yoctopuce modules in a very small space, you can connect them directly
to a micro-USB hub. Yoctopuce builds a USB hub particularly small for this purpose (down to
20mmx36mm), on which you can directly solder a USB cable instead of using a USB plug. For more
details, see the micro-USB hub information sheet.
YoctoHub-Ethernet, YoctoHub-Wireless and YoctoHub-GSM
You can add network connectivity to your Yocto-RangeFinder, thanks to the YoctoHub-Ethernet, the
YoctoHub-Wireless and the YoctoHub-GSM which provides repectiveley Ethernet, WiFi and GSM
connectivity. All of them can drive up to three devices and behave exactly like a regular computer
running a VirtualHub.
1.27mm (or 1.25mm) connectors
In case you wish to connect your Yocto-RangeFinder to a Micro-hub USB or a YoctoHub without
using a bulky USB connector, you can use the four 1.27mm pads just behind the USB connector.
There are two options.
You can mount the Yocto-RangeFinder directly on the hub using screw and spacers, and connect it
using 1.27mm board-to-board connectors. To prevent shortcuts, it is best to solder the female
connector on the hub and the male connector on the Yocto-RangeFinder.
You can also use a small 4-wires cable with a 1.27mm connector. 1.25mm works as well, it does not
make a difference for 4 pins. This makes it possible to move the device a few inches away. Don't put
it too far away if you use that type of cable, because as the cable is not shielded, it may cause
undesirable electromagnetic emissions.
Enclosure
Your Yocto-RangeFinder has been designed to be installed as is in your project. Nevertheless,
Yoctopuce sells enclosures specifically designed for Yoctopuce devices. These enclosures have
removable mounting brackets and magnets allowing them to stick on ferromagnetic surfaces. More
details are available on the Yoctopuce web site 3. The suggested enclosure model for your YoctoRangeFinder is the $SPECBOX$.
3
http://www.yoctopuce.com/EN/products/category/enclosures
2. Presentation
www.yoctopuce.com 5
You can install your Yocto-RangeFinder in an optional enclosure
Picoflex connectors and flexible ribbon cable
If you intend to move the sensor away from the Yocto-RangeFinder module using a pluggable cable,
you will need 4-wire ribbon cable of 1.27mm pitch, and Picoflex connectors.4 You can find more
details on this topic in the chapter about assembly and connections.
4
Header Molex ref 90325-3004 or 90325-0004, available from most electronic components suppliers (www.mouser.com,
www.digikey.com, www.farnell.com, www.distrelec.ch...). To be used with connectors ref 90327-3304 or 90327-0304.
2. Presentation
6 www.yoctopuce.com
3. Working principle and limitations
The Yocto-RangeFinder emits laser pulses and measures the time that they take to come back to the
sensor after their reflection against an obstacle. Time intervals for such a measure are so short that
the sensor uses indirect physical principles to evaluate them. Therefore, a number of external
perturbations can hinder the measure.
3.1. Ambient light
As long as it does not hide the reflection of the emitted laser pulses, the ambient light does not
perturb the workings of the sensor. But naturally, the infrared laser reflection in a bright outside
environment is much harder to detect than reflection in an inside environment that is poor in infrared.
Generally speaking, the maximal detection distance is reduced by a factor of two outside (sunlight
about 5000 lux), and accuracy is reduced by half. If the infrared sensor is saturated by a strong
radiation, the measure can even prove impossible.
3.2. Color and reflectivity of the detected objects
The sensor is designed to estimate the distance of objects independently from their color and their
reflectivity. However, these parameters have an influence on the quantity of reflected light, and
therefore on the maximal detection range and on the accuracy. A light object (white 88%) is typically
detected at a distance almost twice as far as a dark object (gray 17%), and with a twice as good an
accuracy.
3.3. Workings behind a protective glass
Even if it is transparent to infrared light, a protection glass necessarily creates glints which interferes
with the measure. In presence of glints, the sensor is faced with two simultaneous reflections to be
measured: an intentional reflection, and a parasitic reflection. It is unfortunately impossible to directly
filter the parasitic reflection. However, you can counter the measure bias that it introduces through a
material calibration of the sensor. Its process is described below.
Even if you perform the calibration with the greatest care, it cannot do anything against the fact the
radiations reflected against the glass are not going to reach the object of which you want to measure
the distance. The presence of glass has therefore also as side effect to decrease the maximal
detection distance and the measure accuracy. To limit this negative effect, you must absolutely use
the thinnest and the most transparent glass possible, and above all to press it against the sensor.
The more space between the sensor and the glass, the more the reflections hinder the measure.
www.yoctopuce.com 7
3.4. Working modes
Depending on its use, you can configure the Yocto-RangeFinder to maximize accuracy (by
measuring on a longer period), the maximal distance (by increasing sensitivity to low reflections), or
the measure frequency. The default behavior is a compromise that you can use for standard
applications. Here is an estimate of expected sensor performances, in its different working modes:
Default mode characteristics
Measuring frequency: about 25 Hz
Maximal detection distance: 1.2m (inside, white target)
Expected accuracy:
Conditions Distance Standard deviation
Light target, inside 120cm 4%
Dark target, inside 70cm 7%
Light target, outside 60cm 7%
Dark target, outside 40cm 12%
High accuracy mode characteristics
Measuring frequency: about 5 Hz
Maximal detection distance: 1.2m (inside, white target)
Expected accuracy: < 3%
Long distance mode characteristics
Measuring frequency: about 25 Hz
Maximal detection distance: 2m (inside, white target)
Expected accuracy:
Conditions Distance Standard deviation
Light target inside 200cm 6%
Dark target inside 70cm 7%
High frequency mode characteristics
Measuring frequency: 30 Hz
Maximal detection distance: 1.2m (inside, white target)
Expected accuracy: 5%
3.5. Temperature variations
The distance sensor uses a detection principle which is sensitive to the temperature. You can
counter this sensitivity with a simple automatic sensor re-calibration process, which does not require
any external intervention. In order to avoid perturbing measure linearity, the Yocto-RangeFinder does
not trigger this calibration automatically. It is equipped with a temperature sensor which allows you to
decide when to trigger this calibration when the temperature difference since the latest calibration
reaches 8 degrees Celsius.
The next section describes using hardware calibration procedures.
3.6. Hardware calibration procedures
Calibration procedures described in the following paragraphs are specific to the VL53L0CXV0DH/1
sensor in the Yocto-RangeFinder and act directly on its detection principle. You must not mistake
3. Working principle and limitations
8 www.yoctopuce.com
them with software calibration which you can perform a posteriori on the measures of all Yoctopuce
sensors.
Calibration for temperature variations
To ensure proper operation of the sensor, you must run an automatic calibration process when the
temperature varies of more than 8°C. The Yocto-RangeFinder includes a temperature sensor located
right next to the distance sensor, allowing you to detect temperature variations and to run this
calibration if needed.
To know the current temperature, you must call the get_currentTemperature() method. To
know the latest calibration temperature, you must call the
get_hardwareCalibrationTemperature() method. When the two are too far apart, you
must call the triggerTemperatureCalibration() method:
YRangeFinder rf = YRangeFinder.FirstRangeFinder();
Double currTemp = rf.get_currentTemperature();
Double calibTemp = rf.get_hardwareCalibrationTemperature();
if (Math.abs(currTemp - calibTemp) > 8.0) {
rf.triggerTemperatureCalibration();
}
You do not need to put a target in front of the sensor to perform a temperature calibration.
Calibration to compensate reflections on a protection glass
Reflections caused by a protection glass introduce several types of biases in the measure. They can
be compensated only in applying the calibration procedures described below, in the given order.
These calibrations do not need to be repeated as long as the glass does not change position (this
calibration is relatively stable with regards to external conditions). But do not forget that even the best
calibration cannot compensate a too low signal/noise ratio. It is therefore critical to reduce as much
as possible the distance between the glass and the sensor, and to use the most transparent and
thinnest glass possible.
Before you start the calibration process, start by asserting that the sensor receives enough signal to
work. Even without calibration, at a relatively short distance, the sensor should be able to correctly
detect an object. If it is not the case, it means that the signal is too perturbed and you must either
move the glass closer to the sensor, or use a thinner glass, or most likely both. In good conditions,
the value measured by the sensor compared to the actual distance should conform to the following
graph:
The effect of an intervening glass on the distance measure, without calibration
Note the three areas of this graph: in the area close to the sensor, the measured value varies in
parallel to the distance of the object. In the median area, the measured value keeps on growing with
the distance, but the actual distance is more and more under-estimated. In the most distant area, the
measured value decreases, so that it is in no case possible to measure a distance, even after
calibration.
3. Working principle and limitations
www.yoctopuce.com 9
As a calibration target, we used the JJC GC-3 color balance card deck.
Phase 1: photon detector calibration
The aim of this calibration is to measure the level of ambient light (behind the glass), without any
particular reflection. Do not put the target directly against the glass for this calibration, nor any
specific light source.
To run the calibration, call the triggerSpadCalibration() method.
This calibration is almost instantaneous.
Phase 2: offset calibration
The aim of this calibration is to correct the measure offset (fixed offset) introduced by the laser going
through the glass. This calibration must be performed with a white target, positioned at a known
distance from the sensor, close enough from the sensor (linear area), ideally at about 100mm if the
glass allows it. We recommend that you redo a temperature calibration right before running an offset
calibration.
To run the calibration , call the triggerOffsetCalibration() method, giving as parameter
the distance of the target in millimeters or in inches, depending on the module configuration.
This calibration takes about half a second.
Phase 3: cross-talk calibration
The aim of this calibration is to correct the non-linearity introduced in the measure because of the
interferences between reflections against the glass and reflections against the measured object.
Ideally, this calibration must be performed with a gray target, positioned at a known distance from the
sensor, in the measure area where the interference effect is the strongest, that is at 80% to 90% of
the maximal measurable distance.
To run this calibration, call the triggerXTalkCalibration() method, and pass as parameters
the distance of the target in millimeters or in inches, depending on the module configuration.
This calibration may take 5 to 10 seconds. The detection led blinks during calibration.
Phase 4: testing et saving the results
When calibration has been performed, the module should provide correct measures, independently
of the color of the object, as long as it is detected. If it is not the case, it is probably because
calibration did not occur in good distance conditions. In this case you must determine usable
distances with the selected glass again, drawing the measured distance graph (without calibration)
depending on the actual distance of a target.
For the result of calibration to be kept after the module restarts, you must save the computed
parameters in the Yocto-RangeFinder flash memory. To do so, you must call the module
saveToFlash() method.
YRangeFinder rf = YRangeFinder.FirstRangeFinder();
rf.get_module().saveToFlash();
Calibrating with the command line library
If you want to perform calibration once and for all, without writing you own piece of code, you can use
our command line library, which you can download from www.yoctopuce.com in the Support section.
The corresponding commands are the following, naturally in positioning the corresponding targets
and in replacing distances depending on the target actual positions:
YRangeFinder any triggerSpadCalibration
YRangeFinder any triggerTemperatureCalibration
YRangeFinder any triggerOffsetCalibration 100
YRangeFinder any triggerXTalkCalibration 700
3. Working principle and limitations
10 www.yoctopuce.com
To check the current measure:
YRangeFinder any get_currentValue
And to save the current calibration in the module flash memory, add -s in any command, for example:
YRangeFinder -s any get_currentValue
3. Working principle and limitations
www.yoctopuce.com 11
12 www.yoctopuce.com
4. First steps
By design, all Yoctopuce modules are driven the same way. Therefore, user's guides for all the
modules of the range are very similar. If you have already carefully read through the user's guide of
another Yoctopuce module, you can jump directly to the description of the module functions.
4.1. Prerequisites
In order to use your Yocto-RangeFinder module, you should have the following items at hand.
A computer
Yoctopuce modules are intended to be driven by a computer (or possibly an embedded
microprocessor). You will write the control software yourself, according to your needs, using the
information provided in this manual.
Yoctopuce provides software libraries to drive its modules for the following operating systems:
Windows, Mac OS X, Linux, and Android. Yoctopuce modules do not require installing any specific
system driver, as they leverage the standard HID driver1 provided with every operating system.
Windows versions currently supported are: Windows XP, Windows 2003, Windows Vista, Windows
7, Windows 8 and Windows 10. Both 32 bit and 64 bit versions are supported. Yoctopuce is
frequently testing its modules on Windows 7 and Windows 10.
Mac OS X versions currently supported are: 10.9 (Maverick), 10.10 (Yosemite), 10.11 (El Capitan)
and 10.12 (Sierra). Yoctopuce is frequently testing its modules on Mac OS X 10.11.
Linux kernels currently supported are the 2.6 branch, the 3.0 branch and the 4.0 branch. Other
versions of the Linux kernel, and even other UNIX variants, are very likely to work as well, as Linux
support is implemented through the standard libusb API. Yoctopuce is frequently testing its modules
on Linux kernel 3.19.
Android versions currently supported are: Android 3.1 and later. Moreover, it is necessary for the
tablet or phone to support the Host USB mode. Yoctopuce is frequently testing its modules on
Android 4.x on a Nexus 7 and a Samsung Galaxy S3 with the Java for Android library.
A USB cable, type A-micro B
USB connectors exist in three sizes: the "standard" size that you probably use to connect your
printer, the very common mini size to connect small devices, and finally the micro size often used to
1
The HID driver is the one that takes care of the mouse, the keyboard, etc.
www.yoctopuce.com 13
connect mobile phones, as long as they do not exhibit an apple logo. All USB modules manufactured
by Yoctopuce use micro size connectors.
The most common USB 2 connectors: A, B, Mini B, Micro A, Micro B.
2
To connect your Yocto-RangeFinder module to a computer, you need a USB cable of type A-micro
B. The price of this cable may vary a lot depending on the source, look for it under the name USB A
to micro B Data cable. Make sure not to buy a simple USB charging cable without data connectivity.
The correct type of cable is available on the Yoctopuce shop.
You must plug in your Yocto-RangeFinder module with a USB cable of type A - micro B.
If you insert a USB hub between the computer and the Yocto-RangeFinder module, make sure to
take into account the USB current limits. If you do not, be prepared to face unstable behaviors and
unpredictable failures. You can find more details on this topic in the chapter about assembly and
connections.
4.2. Testing USB connectivity
At this point, your Yocto-RangeFinder should be connected to your computer, which should have
recognized it. It is time to make it work.
Go to the Yoctopuce web site and download the Virtual Hub software3. It is available for Windows,
Linux, and Mac OS X. Normally, the Virtual Hub software serves as an abstraction layer for
languages which cannot access the hardware layers of your computer. However, it also offers a
succinct interface to configure your modules and to test their basic functions. You access this
interface with a simple web browser4. Start the Virtual Hub software in a command line, open your
preferred web browser and enter the URL http://127.0.0.1:4444. The list of the Yoctopuce modules
connected to your computer is displayed.
2
Although they existed for some time, Mini A connectors are not available anymore http://www.usb.org/developers/
Deprecation_Announcement_052507.pdf
3
www.yoctopuce.com/EN/virtualhub.php
4
The interface is tested on Chrome, FireFox, Safari, Edge et IE 11.
4. First steps
14 www.yoctopuce.com
Module list as displayed in your web bowser.
4.3. Localization
You can then physically localize each of the displayed modules by clicking on the beacon button.
This puts the Yocto-led of the corresponding module in Yocto-beacon mode. It starts flashing, which
allows you to easily localize it. The second effect is to display a little blue circle on the screen. You
obtain the same behavior when pressing the Yocto-button of the module.
4.4. Test of the module
The first item to check is that your module is working well: click on the serial number corresponding
to your module. This displays a window summarizing the properties of your Yocto-RangeFinder.
Properties of the Yocto-RangeFinder module.
This window allows you, among other things, to play with your module to check that it is working
properly, detection values are indeed displayed in real time.
4.5. Configuration
When, in the module list, you click on the configure button corresponding to your module, the
configuration window is displayed.
Yocto-RangeFinder module configuration.
4. First steps
www.yoctopuce.com 15
Firmware
The module firmware can easily be updated with the help of the interface. Firmware destined for
Yoctopuce modules are available as .byn files and can be downloaded from the Yoctopuce web site.
To update a firmware, simply click on the upgrade button on the configuration window and follow the
instructions. If the update fails for one reason or another, unplug and re-plug the module and start
the update process again. This solves the issue in most cases. If the module was unplugged while it
was being reprogrammed, it does probably not work anymore and is not listed in the interface.
However, it is always possible to reprogram the module correctly by using the Virtual Hub software
5
in command line 6.
Logical name of the module
The logical name is a name that you choose, which allows you to access your module, in the same
way a file name allows you to access its content. A logical name has a maximum length of 19
characters. Authorized characters are A..Z, a..z, 0..9, _, and -. If you assign the same logical name
to two modules connected to the same computer and you try to access one of them through this
logical name, behavior is undetermined: you have no way of knowing which of the two modules
answers.
Luminosity
This parameter allows you to act on the maximal intensity of the leds of the module. This enables
you, if necessary, to make it a little more discreet, while limiting its power consumption. Note that this
parameter acts on all the signposting leds of the module, including the Yocto-led. If you connect a
module and no led turns on, it may mean that its luminosity was set to zero.
Logical names of functions
Each Yoctopuce module has a serial number and a logical name. In the same way, each function on
each Yoctopuce module has a hardware name and a logical name, the latter can be freely chosen by
the user. Using logical names for functions provides a greater flexibility when programming modules.
The Yocto-RangeFinder module has three functions:
• "rangeFinder", corresponding to the distance measure.
• "lightSensor", corresponding to the ambient light estimate.
• "temperature", corresponding to the temperature measure of the sensor itself, needed to
determine when a new calibration is required.
5
www.yoctopuce.com/EN/virtualhub.php
6
More information available in the virtual hub documentation
4. First steps
16 www.yoctopuce.com
5. Assembly and connections
This chapter provides important information regarding the use of the Yocto-RangeFinder module in
real-world situations. Make sure to read it carefully before going too far into your project if you want
to avoid pitfalls.
5.1. Fixing
While developing your project, you can simply let the module hang at the end of its cable. Check only
that it does not come in contact with any conducting material (such as your tools). When your project
is almost at an end, you need to find a way for your modules to stop moving around.
Examples of assembly on supports
The Yocto-RangeFinder module contains 2.5mm assembly holes. You can use these holes for
screws. The screw head diameter must not be larger than 4.5mm or they will damage the module
circuits. Make sure that the lower surface of the module is not in contact with the support. We
recommend using spacers, but other methods are possible. Nothing prevents you from fixing the
module with a glue gun; it will not be good-looking, but it will hold.
If your intend to screw your module directly against a conducting part, for example a metallic frame,
insert an isolating layer in between. Otherwise you are bound to induce a short circuit: there are
naked pads under your module. Simple insulating tape should be enough.
www.yoctopuce.com 17
5.2. Moving the sensor away
The Yocto-RangeFinder module is designed so that you can split it into two parts, allowing you to
move away the sensor from the command sub-module. You can split the module by simply breaking
the circuit. However, you can obtain better results if you use a good pincer, or cutting pliers. When
you have split the sub-modules, you can sandpaper the protruding parts without risk.
The Yocto-RangeFinder module is designed so that you can split it into two parts.
Wiring under the modules once separated.
Once the module is split into two, you must rewire the sub-modules. You can connect the submodules by soldering simple electric wires, but you can obtain a better result with 1.27 pitch ribbon
cable. Consider using solid copper cables, rather than threaded ones: solid copper cables are
somewhat less flexible, but much easier to solder.
Moving the sensor away with a ribbon cable.
You can also use ribbon cables with Picoflex connectors. You will obtain a somewhat larger system,
but Picoflex headers are much easier to solder than ribbon cable. Moreover, you can disassemble
the result.
Moving the sensor with Picoflex connectors.
Warning: divisible Yoctopuce modules very often have very similar connection systems.
Nevertheless, sub-modules from different models are not all compatible. If you connect your YoctoRangeFinder sub-module to another type of module, such as a Yocto-Temperature for instance, it
will not work, and you run a high risk of damaging your equipment.
5. Assembly and connections
18 www.yoctopuce.com
5.3. USB power distribution
Although USB means Universal Serial BUS, USB devices are not physically organized as a flat bus
but as a tree, using point-to-point connections. This has consequences on power distribution: to
make it simple, every USB port must supply power to all devices directly or indirectly connected to it.
And USB puts some limits.
In theory, a USB port provides 100mA, and may provide up to 500mA if available and requested by
the device. In the case of a hub without external power supply, 100mA are available for the hub itself,
and the hub should distribute no more than 100mA to each of its ports. This is it, and this is not
much. In particular, it means that in theory, it is not possible to connect USB devices through two
cascaded hubs without external power supply. In order to cascade hubs, it is necessary to use selfpowered USB hubs, that provide a full 500mA to each subport.
In practice, USB would not have been as successful if it was really so picky about power distribution.
As it happens, most USB hub manufacturers have been doing savings by not implementing current
limitation on ports: they simply connect the computer power supply to every port, and declare
themselves as self-powered hub even when they are taking all their power from the USB bus (in
order to prevent any power consumption check in the operating system). This looks a bit dirty, but
given the fact that computer USB ports are usually well protected by a hardware current limitation
around 2000mA, it actually works in every day life, and seldom makes hardware damage.
What you should remember: if you connect Yoctopuce modules through one, or more, USB hub
without external power supply, you have no safe-guard and you depend entirely on your computer
manufacturer attention to provide as much current as possible on the USB ports, and to detect
overloads before they lead to problems or to hardware damages. When modules are not provided
enough current, they may work erratically and create unpredictable bugs. If you want to prevent any
risk, do not cascade hubs without external power supply, and do not connect peripherals requiring
more than 100mA behind a bus-powered hub.
In order to help controlling and planning overall power consumption for your project, all Yoctopuce
modules include a built-in current sensor that tells (with 5mA precision) the consumption of the
module on the USB bus.
5. Assembly and connections
www.yoctopuce.com 19
20 www.yoctopuce.com
6. Programming, general concepts
The Yoctopuce API was designed to be at the same time simple to use and sufficiently generic for
the concepts used to be valid for all the modules in the Yoctopuce range, and this in all the available
programming languages. Therefore, when you have understood how to drive your YoctoRangeFinder with your favorite programming language, learning to use another module, even with a
different language, will most likely take you only a minimum of time.
6.1. Programming paradigm
The Yoctopuce API is object oriented. However, for simplicity's sake, only the basics of object
programming were used. Even if you are not familiar with object programming, it is unlikely that this
will be a hinderance for using Yoctopuce products. Note that you will never need to allocate or
deallocate an object linked to the Yoctopuce API: it is automatically managed.
There is one class per Yoctopuce function type. The name of these classes always starts with a Y
followed by the name of the function, for example YTemperature, YRelay, YPressure, etc.. There is
also a YModule class, dedicated to managing the modules themselves, and finally there is the static
YAPI class, that supervises the global workings of the API and manages low level communications.
Structure of the Yoctopuce API.
The YSensor class
Each Yoctopuce sensor function has its dedicated class: YTemperature to measure the temperature,
YVoltage to measure a voltage, YRelay to drive a relay, etc. However there is a special class that
can do more: YSensor.
www.yoctopuce.com 21
The YSensor class is the parent class for all Yoctopuce sensors, and can provide access to any
sensor, regardless of its type. It includes methods to access all common functions. This makes it
easier to create applications that use many different sensors. Moreover, if you create an application
based on YSensor, it will work with all Yoctopuce sensors, even those which do no yet exist.
Programmation
In the Yoctopuce API, priority was put on the ease of access to the module functions by offering the
possibility to make abstractions of the modules implementing them. Therefore, it is quite possible to
work with a set of functions without ever knowing exactly which module are hosting them at the
hardware level. This tremendously simplifies programming projects with a large number of modules.
From the programming stand point, your Yocto-RangeFinder is viewed as a module hosting a given
number of functions. In the API, these functions are objects which can be found independently, in
several ways.
Access to the functions of a module
Access by logical name
Each function can be assigned an arbitrary and persistent logical name: this logical name is stored in
the flash memory of the module, even if this module is disconnected. An object corresponding to an
Xxx function to which a logical name has been assigned can then be directly found with this logical
name and the YXxx.FindXxx method. Note however that a logical name must be unique among all
the connected modules.
Access by enumeration
You can enumerate all the functions of the same type on all the connected modules with the help of
the classic enumeration functions FirstXxx and nextXxxx available for each YXxx class.
Access by hardware name
Each module function has a hardware name, assigned at the factory and which cannot be modified.
The functions of a module can also be found directly with this hardware name and the YXxx.FindXxx
function of the corresponding class.
Difference between Find and First
The YXxx.FindXxxx and YXxx.FirstXxxx methods do not work exactly the same way. If there is no
available module, YXxx.FirstXxxx returns a null value. On the opposite, even if there is no
corresponding module, YXxx.FindXxxx returns a valid object, which is not online but which could
become so if the corresponding module is later connected.
Function handling
When the object corresponding to a function is found, its methods are available in a classic way.
Note that most of these subfunctions require the module hosting the function to be connected in
order to be handled. This is generally not guaranteed, as a USB module can be disconnected after
the control software has started. The isOnline method, available in all the classes, is then very
helpful.
Access to the modules
Even if it is perfectly possible to build a complete project while making a total abstraction of which
function is hosted on which module, the modules themselves are also accessible from the API. In
fact, they can be handled in a way quite similar to the functions. They are assigned a serial number
at the factory which allows you to find the corresponding object with YModule.Find(). You can also
assign arbitrary logical names to the modules to make finding them easier. Finally, the YModule
class contains the YModule.FirstModule() and nextModule() enumeration methods allowing you to list
the connected modules.
6. Programming, general concepts
22 www.yoctopuce.com
Functions/Module interaction
From the API standpoint, the modules and their functions are strongly uncorrelated by design.
Nevertheless, the API provides the possibility to go from one to the other. Thus, the get_module()
method, available for each function class, allows you to find the object corresponding to the module
hosting this function. Inversely, the YModule class provides several methods allowing you to
enumerate the functions available on a module.
6.2. The Yocto-RangeFinder module
The Yocto-RangeFinder module provides one instance of the RangeFinder function, corresponding
to the range finder sensor, one instance of the LightSensor function, measuring the ambiant infrared
level and one instance of the Temperature function, corresponding to the temperature sensor
integrated into the device.
module : Module
attribute type modifiable ?
productName String read-only
serialNumber String read-only
logicalName String modifiable
productId Hexadecimal number read-only
productRelease Hexadecimal number read-only
firmwareRelease String read-only
persistentSettings Enumerated modifiable
luminosity 0..100% modifiable
beacon On/Off modifiable
upTime Time read-only
usbCurrent Used current (mA) read-only
rebootCountdown Integer modifiable
userVar Integer modifiable
rangeFinder1 : RangeFinder
attribute type modifiable ?
logicalName String modifiable
advertisedValue String modifiable
unit String modifiable
currentValue Fixed-point number read-only
lowestValue Fixed-point number modifiable
highestValue Fixed-point number modifiable
currentRawValue Fixed-point number read-only
logFrequency Frequency modifiable
reportFrequency Frequency modifiable
calibrationParam Calibration parameters modifiable
resolution Fixed-point number modifiable
sensorState Integer read-only
rangeFinderMode Enumerated modifiable
hardwareCalibration Range finder internal calibration parameters modifiable
currentTemperature Fixed-point number read-only
command String modifiable
lightSensor1 : LightSensor
attribute type modifiable ?
logicalName String modifiable
advertisedValue String modifiable
unit String read-only
currentValue Fixed-point number modifiable
lowestValue Fixed-point number modifiable
highestValue Fixed-point number modifiable
currentRawValue Fixed-point number read-only
6. Programming, general concepts
www.yoctopuce.com 23
logFrequency Frequency modifiable
reportFrequency Frequency modifiable
calibrationParam Calibration parameters modifiable
resolution Fixed-point number modifiable
sensorState Integer read-only
measureType Enumerated modifiable
temperature1 : Temperature
attribute type modifiable ?
logicalName String modifiable
advertisedValue String modifiable
unit String modifiable
currentValue Fixed-point number read-only
lowestValue Fixed-point number modifiable
highestValue Fixed-point number modifiable
currentRawValue Fixed-point number read-only
logFrequency Frequency modifiable
reportFrequency Frequency modifiable
calibrationParam Calibration parameters modifiable
resolution Fixed-point number modifiable
sensorState Integer read-only
sensorType Enumerated modifiable
signalValue Fixed-point number read-only
signalUnit String read-only
command String modifiable
dataLogger : DataLogger
attribute type modifiable ?
logicalName String modifiable
advertisedValue String modifiable
currentRunIndex Integer read-only
timeUTC UTC time modifiable
recording Enumerated modifiable
autoStart On/Off modifiable
beaconDriven On/Off modifiable
clearHistory Boolean modifiable
6.3. Module control interface
This interface is identical for all Yoctopuce USB modules. It can be used to control the module global
parameters, and to enumerate the functions provided by each module.
productName
Character string containing the commercial name of the module, as set by the factory.
serialNumber
Character string containing the serial number, unique and programmed at the factory. For a YoctoRangeFinder module, this serial number always starts with YRNGFND1. You can use the serial
number to access a given module by software.
logicalName
Character string containing the logical name of the module, initially empty. This attribute can be
modified at will by the user. Once initialized to an non-empty value, it can be used to access a given
module. If two modules with the same logical name are in the same project, there is no way to
determine which one answers when one tries accessing by logical name. The logical name is limited
to 19 characters among A..Z,a..z,0..9,_, and -.
6. Programming, general concepts
24 www.yoctopuce.com
Loading...