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.
1 [email protected]
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