Yoctopuce Yocto-GPS User manual
Yocto-GPS, User's guide
Table of contents
1. Introduction 1..............................................................................................................................
1.1. Prerequisites 1.........................................................................................................................
1.2. Optional accessories 3............................................................................................................
2. Presentation 5.............................................................................................................................
2.1. Common elements 5................................................................................................................
2.2. Specific elements 6..................................................................................................................
3. First steps 9.................................................................................................................................
3.1. Localization 9...........................................................................................................................
3.2. Test of the module 9................................................................................................................
3.3. Configuration 10......................................................................................................................
4. Assembly and connections 13..........................................................................................
4.1. Fixing 13..................................................................................................................................
4.2. Antenna 13..............................................................................................................................
4.3. USB power distribution 14.......................................................................................................
5. Programming, general concepts 17................................................................................
5.1. Programming paradigm 17......................................................................................................
5.2. The Yocto-GPS module 19......................................................................................................
5.3. Module control interface 21.....................................................................................................
5.4. GPS function interface 22........................................................................................................
5.5. Latitude function interface 23...................................................................................................
5.6. Longitude function interface 24................................................................................................
5.7. Altitude function interface 25...................................................................................................
5.8. GroundSpeed function interface 26.........................................................................................
5.9. GPS function interface 27........................................................................................................
5.10. DataLogger function interface 28...........................................................................................
5.11. What interface: Native, DLL or Service ? 29..........................................................................
5.12. Programming, where to start? 31...........................................................................................
6. Using the Yocto-GPS in command line 33..................................................................
6.1. Installing 33..............................................................................................................................
6.2. Use: general description 33.....................................................................................................
6.3. Control of the Latitude function 34...........................................................................................
6.4. Control of the module part 34..................................................................................................
6.5. Limitations 35...........................................................................................................................
7. Using Yocto-GPS with JavaScript / EcmaScript 37...............................................
7.1. Blocking I/O versus Asynchronous I/O in JavaScript 37..........................................................
7.2. Using Yoctopuce library for JavaScript / EcmaScript 2017 38.................................................
7.3. Control of the Latitude function 40...........................................................................................
7.4. Control of the module part 44..................................................................................................
7.5. Error handling 46.....................................................................................................................
8. Using Yocto-GPS with PHP 49...........................................................................................
8.1. Getting ready 49......................................................................................................................
8.2. Control of the Latitude function 49...........................................................................................
8.3. Control of the module part 51..................................................................................................
8.4. HTTP callback API and NAT filters 54.....................................................................................
8.5. Error handling 57.....................................................................................................................
9. Using Yocto-GPS with C++ 59...........................................................................................
9.1. Control of the Latitude function 59...........................................................................................
9.2. Control of the module part 61..................................................................................................
9.3. Error handling 64.....................................................................................................................
9.4. Integration variants for the C++ Yoctopuce library 64..............................................................
10. Using Yocto-GPS with Objective-C 67........................................................................
10.1. Control of the Latitude function 67.........................................................................................
10.2. Control of the module part 69................................................................................................
10.3. Error handling 71...................................................................................................................
11. Using Yocto-GPS with Visual Basic .NET 73...........................................................
11.1. Installation 73.........................................................................................................................
11.2. Using the Yoctopuce API in a Visual Basic project 73...........................................................
11.3. Control of the Latitude function 74.........................................................................................
11.4. Control of the module part 75................................................................................................
11.5. Error handling 78...................................................................................................................
12. Using Yocto-GPS with C# 79............................................................................................
12.1. Installation 79.........................................................................................................................
12.2. Using the Yoctopuce API in a Visual C# project 79...............................................................
12.3. Control of the Latitude function 80.........................................................................................
12.4. Control of the module part 82................................................................................................
12.5. Error handling 84...................................................................................................................
13. Using Yocto-GPS with Delphi 87...................................................................................
13.1. Preparation 87.......................................................................................................................
13.2. Control of the Latitude function 87.........................................................................................
13.3. Control of the module part 89................................................................................................
13.4. Error handling 91...................................................................................................................
14. Using the Yocto-GPS with Python 93..........................................................................
14.1. Source files 93.......................................................................................................................
14.2. Dynamic library 93.................................................................................................................
14.3. Control of the Latitude function 93.........................................................................................
14.4. Control of the module part 95................................................................................................
14.5. Error handling 97...................................................................................................................
15. Using the Yocto-GPS with Java 99...............................................................................
15.1. Getting ready 99....................................................................................................................
15.2. Control of the Latitude function 99.........................................................................................
15.3. Control of the module part 101..............................................................................................
15.4. Error handling 103.................................................................................................................
16. Using the Yocto-GPS with Android 105.....................................................................
16.1. Native access and VirtualHub 105.........................................................................................
16.2. Getting ready 105..................................................................................................................
16.3. Compatibility 105...................................................................................................................
16.4. Activating the USB port under Android 106...........................................................................
16.5. Control of the Latitude function 108.......................................................................................
16.6. Control of the module part 110..............................................................................................
16.7. Error handling 115.................................................................................................................
17. Advanced programming 117............................................................................................
17.1. Event programming 117........................................................................................................
17.2. The data logger 120...............................................................................................................
17.3. Sensor calibration 122...........................................................................................................
18. Firmware Update 127............................................................................................................
18.1. The VirtualHub or the YoctoHub 127.....................................................................................
18.2. The command line library 127................................................................................................
18.3. The Android application Yocto-Firmware 127........................................................................
18.4. Updating the firmware with the programming library 128......................................................
18.5. The "update" mode 130.........................................................................................................
19. Using with unsupported languages 131....................................................................
19.1. Command line 131.................................................................................................................
19.2. VirtualHub and HTTP GET 131.............................................................................................
19.3. Using dynamic libraries 133...................................................................................................
19.4. Porting the high level library 136...........................................................................................
20. High-level API Reference 137..........................................................................................
20.1. General functions 138............................................................................................................
20.2. Module control interface 166.................................................................................................
20.3. GPS function interface 229....................................................................................................
20.4. Latitude function interface 275...............................................................................................
20.5. Longitude function interface 328............................................................................................
20.6. Altitude function interface 381...............................................................................................
20.7. GroundSpeed function interface 438.....................................................................................
20.8. DataLogger function interface 491.........................................................................................
20.9. Recorded data sequence 535................................................................................................
20.10. Measured value 549............................................................................................................
21. Troubleshooting 555.............................................................................................................
21.1. Linux and USB 555................................................................................................................
21.2. ARM Platforms: HF and EL 556.............................................................................................
21.3. Powered module but invisible for the OS 556........................................................................
21.4. Another process named xxx is already using yAPI 556.........................................................
21.5. Disconnections, erratic behavior 556.....................................................................................
21.6. Where to start? 556...............................................................................................................
22. Characteristics 557................................................................................................................
Blueprint 559...................................................................................................................................
Index 561.............................................................................................................................................
1. Introduction
The Yocto-GPS module is a 60x20mm module equipped with a GNSS (GPS + GLONASS) receiver
which enables you to know the position of the receiver, its travel speed, and the current time. It
requires the use of an active external antenna with a connector at the U.FL standard.
The Yocto-GPS module
Yoctopuce thanks you for buying this Yocto-GPS 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-GPS 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 support1.
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.
1.1. Prerequisites
In order to use your Yocto-GPS 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 driver2provided with every operating system.
www.yoctopuce.com 1
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
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.3
To connect your Yocto-GPS 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-GPS module with a USB cable of type A - micro B.
If you insert a USB hub between the computer and the Yocto-GPS 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.
3 Although they existed for some time, Mini A connectors are not available anymore http://www.usb.org/developers/
Deprecation_Announcement_052507.pdf
1. Introduction
2 www.yoctopuce.com
1.2. Optional accessories
The accessories below are not necessary to use the Yocto-GPS 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-GPS 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-GPS, 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.
Enclosures
Your Yocto-GPS 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 4. The suggested enclosure model for your Yocto-GPS is the
YoctoBox-Long-Thick-Transp.
You can install your Yocto-GPS in an optional enclosure
4 http://www.yoctopuce.com/EN/products/category/enclosures
1. Introduction
www.yoctopuce.com 3
4 www.yoctopuce.com
2. Presentation
1: Micro-B USB socket 3: Yocto-led
2: Yocto-button 4: Satellite reception led
5: Antenna connector
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
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.
www.yoctopuce.com 5
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-GPS
modules, this number starts with YGNSSMK1. 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 receiver
The Yocto-GPS is based on a GNSS SL869 receiver produced by Telit. It has 32 channels and can
compute up to 10 positions per second.
Satellite reception led
The green led (Fix Sat.) on the module indicates the state of the satellite reception. It stays on when
the reception is satisfactory. It blinks fast when the module searches for satellites. With an
appropriate reception, the Yocto-GPS can obtain a position in less than 35 seconds after a cold start.
Moreover, the Yocto-GPS has a small battery enabling the GPS to remember during several hours
the position of the last seen satellites, enabling a hot start in a few seconds only in most cases. In
case of a particularly degraded satellite reception, obtaining a first position can take up to 5 minutes.
The antenna connector
The Yocto-GPS needs an antenna to work. To maximize reception quality, the Yocto-GPS is
designed to work with an active external antenna (powered seamlessly in 3.3V), connected with a
1 short-short-short long-long-long short-short-short
2. Presentation
6 www.yoctopuce.com
U.FL connector. Beware, U.FL connectors are not designed to be connected/disconnected
continuously. If you plan such a scenario, use a small U.FL to SMA (female) cable and an antenna
equipped with an SMA connector.
Being active, you can deport the antenna several meters away without changing the quality of the
reception signal.
Use an SMA connector if you plan to frequently disconnect the antenna.
2. Presentation
www.yoctopuce.com 7
8 www.yoctopuce.com
3. First steps
When reading this chapter, your Yocto-GPS 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 software1. 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 browser2. 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.
Module list as displayed in your web bowser.
3.1. 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.
3.2. 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-GPS.
1 www.yoctopuce.com/EN/virtualhub.php
2 The interface is tested on Chrome, FireFox, Safari, Edge et IE 11.
www.yoctopuce.com 9
Properties of the Yocto-GPS module.
This window allows you, among other things, to play with you module to check how it is working.
Position values computed by the Yocto-GPS are displayed there in real time.
3.3. Configuration
When, in the module list, you click on the configure button corresponding to your module, the
configuration window is displayed.
Yocto-GPS module configuration.
Firmware
The module firmware can easily be updated with the help of the interface. To do so, you must
beforehand have the adequate firmware on your local disk. 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 3
in command line 4.
3 www.yoctopuce.com/EN/virtualhub.php
4 More information available in the virtual hub documentation
3. First steps
10 www.yoctopuce.com
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.
You can assign logical names to several functions of the Yocto-GPS by clicking on the corresponding
"rename" button.
The GPS function
The gps function groups all the measures computed by the module: position, ground speed, travel
direction, time, and so on... Latitude and longitude are presented as character strings with a format to
be selected between DD°MM'SS.SSS", DD°MM.MMMM, and DD.DDDDDD. You can make do with
only this function. But if you need to make calculations on the positions, or if you want to use
callbacks5, the following functions prove useful.
Latitude and Longitude functions
They enable you to obtain the current latitude and longitude in numerical format, independently of the
display format selected in the GPS function. Note, for technical reasons, the values are not given in
degrees but in millidegrees (thousandths of degree).
The Altitude function
It returns an estimate of the current altitude. Beware, altitude computations based on GPS systems
are very imprecise. Expect errors of several tens of meters.
The groundSpeed function
The Yocto-GPS can compute the ground speed, that is the horizontal speed relative to the ground.
Limitations
The Yocto-GPS has pretty standard limitations: it will lose track if any of the following limits are
exceeded:
•ITAR limits: velocity greater than 515 m/s AND altitude above 18,000 m
•altitude: 100,000 m (max) or -1500 m (min)
•velocity: 600 m/s (max)
•acceleration: 2g (max)
5 See the chapter on "Advanced programming"
3. First steps
www.yoctopuce.com 11
12 www.yoctopuce.com
4. Assembly and connections
This chapter provides important information regarding the use of the Yocto-GPS module in real-world
situations. Make sure to read it carefully before going too far into your project if you want to avoid
pitfalls.
4.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-GPS 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 packaging tape should be enough for electric insulation.
4.2. Antenna
The antenna is a key element of your system. Make sure that it is always set up in such a way as it
can "see" the largest part of the sky possible. Except in particular cases, you cannot receive good
quality GPS signals from inside. However, if you really want to try, set the antenna near a window.
www.yoctopuce.com 13
Antenna cable
The Yocto-GPS is sold with a ceramic active antenna at the end of a ten centimeter coaxial cable
ending with a U.FL connector. This type of cable is rather fragile: avoid bending it at a right angle,
you could damage it. Be particularly careful about the antenna-cable juncture.
Coaxial antenna cables are fragile: avoid bending them
U.FL connectors
Theoretically, U.FL connectors are not designed to be connected more than about 10 times. Make
sure that the U.FL plug offers a good contact: when connected, it must not be able to rotate freely
around the connector. If you plan to build a system with a removable external antenna, use a female
U.FL to SMA adaptor cable and a corresponding antenna. Almost all external antennas have an SMA
connector.
External GPS antenna usually have an SMA connector
Choosing an antenna
You do not need to use the GPS antenna delivered with the Yocto-GPS. There are many GPS
antennas on the market. You must select an active antenna: active antennas include a small
electronic amplifier limiting the loses due to the antenna cable. They are usually required when the
distance between the antenna and the GPS receiver goes above 10 centimeters or so. An active
GPS antenna is most often powered directly through the antenna cable. You can use any active GPS
antenna directly with the Yocto-GPS as long as
•it can work when powered in 3.3V
•its gain does not go above 35db.
4.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 self-
powered 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
4. Assembly and connections
14 www.yoctopuce.com
Table of contents
